ALTER TABLE 쿼리는 테이블 설정이나 데이터를 수정합니다:
대부분의
ALTER TABLE 쿼리는 *MergeTree, Merge, Distributed 테이블에서만 지원됩니다.ALTER SQL 문은 뷰를 수정합니다:
다음
ALTER SQL 문은 역할 기반 접근 제어와 관련된 엔터티를 수정합니다:
뮤테이션
ALTER 쿼리는 “뮤테이션”이라는 메커니즘으로 구현되며, 대표적인 예로 ALTER TABLE … DELETE 및 ALTER TABLE … UPDATE가 있습니다. 이는 MergeTree 테이블의 머지와 유사한 비동기 백그라운드 프로세스로, 파트의 새로운 “뮤테이션된” 버전을 생성합니다.
*MergeTree 테이블에서 뮤테이션은 전체 데이터 파트를 다시 써서 실행됩니다.
원자성은 보장되지 않습니다. 준비가 완료되는 즉시 기존 파트가 뮤테이션된 파트로 대체되므로, 뮤테이션 도중 실행을 시작한 SELECT 쿼리에서는 이미 뮤테이션된 파트의 데이터와 아직 뮤테이션되지 않은 파트의 데이터를 함께 보게 됩니다.
뮤테이션은 생성 순서에 따라 완전히 정렬되며, 각 파트에 그 순서대로 적용됩니다. 또한 뮤테이션은 INSERT INTO 쿼리와 부분적인 순서 관계를 가집니다. 즉, 뮤테이션이 제출되기 전에 테이블에 삽입된 데이터는 뮤테이션되지만, 그 이후에 삽입된 데이터는 뮤테이션되지 않습니다. 참고로 뮤테이션은 어떤 방식으로도 삽입을 차단하지 않습니다.
뮤테이션 쿼리는 뮤테이션 항목이 추가된 직후 즉시 반환됩니다(복제된 테이블의 경우 ZooKeeper에, 복제되지 않은 테이블의 경우 파일 시스템에 추가됩니다). 뮤테이션 자체는 시스템 프로필 설정을 사용해 비동기적으로 실행됩니다. 뮤테이션의 진행 상황은 system.mutations 테이블을 사용해 추적할 수 있습니다. 성공적으로 제출된 뮤테이션은 ClickHouse 서버가 재시작되더라도 계속 실행됩니다. 제출된 뮤테이션은 롤백할 수 없지만, 어떤 이유로 뮤테이션이 멈춘 경우 KILL MUTATION 쿼리로 취소할 수 있습니다.
완료된 뮤테이션 항목은 즉시 삭제되지 않습니다(보존되는 항목 수는 finished_mutations_to_keep 스토리지 엔진 매개변수로 결정됩니다). 오래된 뮤테이션 항목은 삭제됩니다.
ALTER 쿼리의 동기성
ALTER 쿼리가 동기식으로 수행됩니다. 복제된 테이블에서는 쿼리가 적절한 작업에 대한 지시만 ZooKeeper에 추가하고, 실제 작업은 가능한 한 빨리 수행됩니다. 다만, 쿼리는 이러한 작업이 모든 레플리카에서 완료될 때까지 기다릴 수 있습니다.
뮤테이션을 생성하는 ALTER 쿼리(예: UPDATE, DELETE, MATERIALIZE INDEX, MATERIALIZE PROJECTION, MATERIALIZE COLUMN, APPLY DELETED MASK, APPLY PATCHES, CLEAR STATISTIC, MATERIALIZE STATISTIC 등이 있으나 이에 국한되지는 않음)의 동기성은 mutations_sync 설정으로 정의됩니다.
메타데이터만 수정하는 다른 ALTER 쿼리의 경우 alter_sync 설정을 사용해 대기 동작을 설정할 수 있습니다.
비활성 레플리카가 모든 ALTER 쿼리를 실행할 때까지 얼마나 오래 기다릴지(초 단위)는 replication_wait_for_inactive_replica_timeout 설정으로 지정할 수 있습니다.
모든
ALTER 쿼리에서 alter_sync = 2이고 일부 레플리카가 replication_wait_for_inactive_replica_timeout 설정에 지정된 시간보다 오래 비활성 상태로 남아 있으면 UNFINISHED 예외가 발생합니다.하나의 테이블에서 동시 ALTER 할당
ALTER 문을 짧은 간격으로 연속 제출하면 CANNOT_ASSIGN_ALTER(코드 517) 오류가 발생할 수 있습니다. 레플리카가 이전 ALTER 중 일부를 아직 적용하지 않은 경우(메타데이터 버전이 공통 메타데이터보다 뒤처진 경우) 복제 경로에서 이 오류가 발생합니다. 서버는 레플리카가 “still not applied some of previous alters” 또는 “Probably too many alters executing concurrently” 상태라고 표시할 수 있습니다. 이전 ALTER가 이미 할당된 후에도 이 상태가 계속될 수 있습니다. 이는 일반적인 동시 메타데이터 ALTER / 뮤테이션 관련 상태이며, 뮤테이션 전용 SQL 문에만 국한되지 않습니다. 일반적인 동시 메타데이터 변경(ADD / DROP / MODIFY 등)에서도 동일한 재시도 가능한 코드가 발생할 수 있습니다(예를 들어 tests/queries/0_stateless/03518_alter_logical_race.sh에서 다루는 재시도 경로를 참조하십시오).
경합을 방지하는 방법:
- 문법에서 허용하는 경우 독립적인 메타데이터 작업을 하나의 다중 절
ALTER로 결합하십시오(예: 여러ADD INDEX절). ALTER문을 순차적으로 실행하고, 이전ALTER가 레플리카에 적용될 때까지 코드 517 오류 발생 시 재시도하십시오.- 뮤테이션을 생성하는
ALTER의 경우, 다음 작업을 제출하기 전에mutations_sync또는system.mutations의is_done과 같은 문서화된 확인 수단을 사용하여 이전 뮤테이션이 완료될 때까지 기다리십시오.
MATERIALIZE INDEX 절 함께 사용하기
ALTER에 여러 MATERIALIZE INDEX 절을 포함할 수 있습니다. 현재 트리에서 다루는 사례는 여러 ADD INDEX 절과 해당 새 인덱스에 대한 MATERIALIZE INDEX를 하나의 SQL 문에 함께 지정하는 것입니다(tests/queries/0_stateless/02911_add_index_and_materialize_index.sql 참고). 이렇게 ADD INDEX와 MATERIALIZE INDEX를 함께 사용하는 형식은 AlterCommand 세그먼트와 MutationCommand 세그먼트를 혼합하므로, DatabaseReplicated는 이를 QUERY_IS_PROHIBITED와 함께 거부합니다(InterpreterAlterQuery::validateReplicatedDatabaseSegments). 일반(DatabaseReplicated가 아닌) 데이터베이스에서는 02911 예시가 유효합니다. DatabaseReplicated에서는 메타데이터 변경과 구체화 뮤테이션을 별도 SQL 문으로 실행하십시오.
현재 구현에서는 뮤테이션을 준비할 때 각 MATERIALIZE INDEX 절을 테이블 메타데이터 스냅샷을 기준으로 해석합니다. 따라서 이미 존재하는 인덱스에 대해 구체화만 수행하는 여러 절 형식도 동일한 준비 경로를 따릅니다(뮤테이션만 포함하므로 하나의 세그먼트에 유지됩니다). 이 정확한 형식은 아직 별도의 stateless 테스트로 검증되지 않았습니다. 이러한 테스트가 추가되기 전까지는 별도로 보장되는 계약이 아니라 현재 구현 동작으로 간주하십시오.
순서대로 뮤테이션을 적용해야 한다면, SQL 문마다 MATERIALIZE INDEX를 하나씩 실행하고 mutations_sync로 완료를 기다릴 수 있습니다.