ALTER TABLE ... PARTITION

파티션과 관련해서 다음 연산들을 사용할 수 있어요.

출처: 문서

본문

DETACH PARTITION|PART — 파티션 또는 파트를 detached 디렉터리로 이동시키고 잊어버려요.
DROP PARTITION|PART — 파티션 또는 파트를 삭제해요.
DROP DETACHED PARTITION|PART — detached에서 파트 또는 파티션의 모든 파트를 삭제해요.
FORGET PARTITION — 비어 있는 파티션의 메타데이터를 ZooKeeper에서 삭제해요.
ATTACH PARTITION|PART — detached 디렉터리에서 테이블로 파티션 또는 파트를 추가해요.
ATTACH PARTITION FROM — 데이터 파티션을 한 테이블에서 다른 테이블로 복사하고 추가해요.
REPLACE PARTITION — 데이터 파티션을 한 테이블에서 다른 테이블로 복사하고 교체해요.
MOVE PARTITION TO TABLE — 데이터 파티션을 한 테이블에서 다른 테이블로 이동해요.
CLEAR COLUMN IN PARTITION — 파티션 안의 특정 컬럼의 값을 초기화해요.
CLEAR INDEX IN PARTITION — 파티션 안의 지정된 보조 인덱스를 초기화해요.
FREEZE PARTITION — 파티션의 백업을 만들어요.
UNFREEZE PARTITION — 파티션의 백업을 제거해요.
FETCH PARTITION|PART — 다른 서버에서 파트 또는 파티션을 다운로드해요.
MOVE PARTITION|PART — 파티션/데이터 파트를 다른 디스크나 볼륨으로 이동해요.
UPDATE IN PARTITION — 조건에 따라 파티션 안의 데이터를 업데이트해요.
DELETE IN PARTITION — 조건에 따라 파티션 안의 데이터를 삭제해요.
REWRITE PARTS — 테이블(또는 특정 파티션)의 파트를 완전히 다시 써요.

DETACH PARTITION|PART

ALTER TABLE table_name [ON CLUSTER cluster] DETACH PARTITION|PART partition_expr

지정된 파티션의 모든 데이터를 detached 디렉터리로 이동해요. 서버는 분리된 데이터 파티션을 존재하지 않는 것처럼 잊어버립니다. ATTACH 쿼리를 실행하기 전까지 서버는 이 데이터에 대해 알지 못해요.

예시:

ALTER TABLE mt DETACH PARTITION '2020-11-21';
ALTER TABLE mt DETACH PART 'all_2_2_0';

파티션 표현식을 설정하는 방법은 How to set the partition expression 섹션을 참고하세요.

쿼리가 실행된 후에는 detached 디렉터리의 데이터에 대해 원하는 것을 할 수 있어요 — 파일 시스템에서 삭제하거나 그냥 남겨 둘 수 있습니다.

이 쿼리는 복제됩니다 — 모든 리플리카의 detached 디렉터리로 데이터를 이동해요. 이 쿼리는 leader 리플리카에서만 실행할 수 있다는 점에 주의하세요. 리플리카가 leader인지 확인하려면 system.replicas 테이블에 SELECT 쿼리를 실행하세요. 또는 모든 리플리카에서 DETACH 쿼리를 실행하는 것이 더 간단한데요 — (여러 leader가 허용되므로) leader 리플리카를 제외한 모든 리플리카가 예외를 던지게 됩니다.

DROP PARTITION|PART

ALTER TABLE table_name [ON CLUSTER cluster] DROP PARTITION|PART partition_expr

테이블에서 지정된 파티션을 삭제해요. 이 쿼리는 파티션을 비활성(inactive)으로 표시하고, 대략 10분 후에 데이터를 완전히 삭제합니다.

파티션 표현식을 설정하는 방법은 How to set the partition expression 섹션을 참고하세요.

이 쿼리는 복제됩니다 — 모든 리플리카에서 데이터를 삭제해요.

예시:

ALTER TABLE mt DROP PARTITION '2020-11-21';
ALTER TABLE mt DROP PART 'all_4_4_0';

DROP DETACHED PARTITION|PART

ALTER TABLE table_name [ON CLUSTER cluster] DROP DETACHED PARTITION|PART ALL|partition_expr

detached에서 지정된 파트 또는 지정된 파티션의 모든 파트를 제거해요. 파티션 표현식을 설정하는 방법에 대한 자세한 내용은 How to set the partition expression 섹션을 참고하세요.

FORGET PARTITION

ALTER TABLE table_name FORGET PARTITION partition_expr

비어 있는 파티션에 대한 모든 메타데이터를 ZooKeeper에서 제거해요. 파티션이 비어 있지 않거나 알 수 없으면 쿼리가 실패해요. 반드시 다시는 사용되지 않을 파티션에 대해서만 실행하세요.

파티션 표현식을 설정하는 방법은 How to set the partition expression 섹션을 참고하세요.

예시:

ALTER TABLE mt FORGET PARTITION '20201121';

ATTACH PARTITION|PART

ALTER TABLE table_name ATTACH PARTITION|PART partition_expr

detached 디렉터리에서 테이블로 데이터를 추가해요. 전체 파티션의 데이터 또는 별도의 파트에 대한 데이터를 추가할 수 있어요. 예시:

ALTER TABLE visits ATTACH PARTITION 201901;
ALTER TABLE visits ATTACH PART 201901_2_2_0;

파티션 표현식을 설정하는 방법에 대한 자세한 내용은 How to set the partition expression 섹션을 참고하세요.

이 쿼리는 복제됩니다. 리플리카-개시자(replica-initiator)는 detached 디렉터리에 데이터가 있는지 확인해요. 데이터가 있으면 쿼리는 데이터 무결성을 확인합니다. 모든 것이 올바르면 쿼리는 데이터를 테이블에 추가해요.

attach 명령을 받은 비개시자(non-initiator) 리플리카가 자기 detached 폴더에서 올바른 체크섬을 가진 파트를 찾으면, 다른 리플리카에서 가져오지 않고 그 데이터를 연결합니다. 올바른 체크섬을 가진 파트가 없으면 해당 파트를 가진 리플리카에서 데이터가 다운로드돼요.

한 리플리카의 detached 디렉터리에 데이터를 넣고 ALTER ... ATTACH 쿼리로 모든 리플리카의 테이블에 추가할 수 있어요.

ATTACH PARTITION FROM

ALTER TABLE table2 [ON CLUSTER cluster] ATTACH PARTITION partition_expr FROM table1

이 쿼리는 데이터 파티션을 table1에서 table2로 복사해요.

다음에 유의하세요.

데이터는 table1과 table2 어디에서도 삭제되지 않아요.
table1은 임시 테이블일 수 있어요.

쿼리가 성공적으로 실행되려면 다음 조건을 충족해야 해요.

두 테이블은 동일한 구조여야 해요.
두 테이블은 동일한 파티션 키, 동일한 order by 키, 동일한 기본 키를 가져야 해요.
두 테이블은 동일한 storage policy를 가져야 해요.
소스 파트가 비적응(non-adaptive) 인덱스 세분성(granularity)을 가지면, 두 테이블은 동일한 index_granularity를 가져야 해요. 그런 파트는 마크별 행 수를 저장하지 않으므로, 대상 테이블의 값을 사용해 마크를 해석해요.
대상 테이블은 소스 테이블의 모든 인덱스와 프로젝션을 포함해야 해요. 대상 테이블에서 enforce_index_structure_match_on_partition_manipulation 설정이 활성화되어 있으면 인덱스와 프로젝션이 동일해야 해요. 그렇지 않으면 대상 테이블은 소스 테이블의 인덱스와 프로젝션의 상위 집합(superset)을 가질 수 있어요.

REPLACE PARTITION

ALTER TABLE table2 [ON CLUSTER cluster] REPLACE PARTITION partition_expr FROM table1

이 쿼리는 데이터 파티션을 table1에서 table2로 복사하고 table2의 기존 파티션을 교체해요. 이 연산은 원자적(atomic)입니다.

다음에 유의하세요.

데이터는 table1에서 삭제되지 않아요.
table1은 임시 테이블일 수 있어요.

쿼리가 성공적으로 실행되려면 다음 조건을 충족해야 해요.

두 테이블은 동일한 구조여야 해요.
두 테이블은 동일한 파티션 키, 동일한 order by 키, 동일한 기본 키를 가져야 해요.
두 테이블은 동일한 storage policy를 가져야 해요.
소스 파트가 비적응 인덱스 세분성을 가지면, 두 테이블은 동일한 index_granularity를 가져야 해요. 그런 파트는 마크별 행 수를 저장하지 않으므로, 대상 테이블의 값을 사용해 마크를 해석해요.
대상 테이블은 소스 테이블의 모든 인덱스와 프로젝션을 포함해야 해요. 대상 테이블에서 enforce_index_structure_match_on_partition_manipulation 설정이 활성화되어 있으면 인덱스와 프로젝션이 동일해야 해요. 그렇지 않으면 대상 테이블은 소스 테이블의 인덱스와 프로젝션의 상위 집합을 가질 수 있어요.

MOVE PARTITION TO TABLE

ALTER TABLE table_source [ON CLUSTER cluster] MOVE PARTITION partition_expr TO TABLE table_dest

이 쿼리는 데이터 파티션을 table_source에서 table_dest로 이동시키고 table_source의 데이터를 삭제해요.

쿼리가 성공적으로 실행되려면 다음 조건을 충족해야 해요.

두 테이블은 동일한 구조여야 해요.
두 테이블은 동일한 파티션 키, 동일한 order by 키, 동일한 기본 키를 가져야 해요.
두 테이블은 동일한 storage policy를 가져야 해요.
두 테이블은 동일한 엔진 계열(복제 또는 비복제)이어야 해요.
소스 파트가 비적응 인덱스 세분성을 가지면, 두 테이블은 동일한 index_granularity를 가져야 해요. 그런 파트는 마크별 행 수를 저장하지 않으므로, 대상 테이블의 값을 사용해 마크를 해석해요.
대상 테이블은 소스 테이블의 모든 인덱스와 프로젝션을 포함해야 해요. 대상 테이블에서 enforce_index_structure_match_on_partition_manipulation 설정이 활성화되어 있으면 인덱스와 프로젝션이 동일해야 해요. 그렇지 않으면 대상 테이블은 소스 테이블의 인덱스와 프로젝션의 상위 집합을 가질 수 있어요.

CLEAR COLUMN IN PARTITION

ALTER TABLE table_name [ON CLUSTER cluster] CLEAR COLUMN column_name IN PARTITION partition_expr

파티션 안의 지정된 컬럼의 모든 값을 초기화해요. 테이블 생성 시 DEFAULT 절이 지정되었다면, 이 쿼리는 컬럼 값을 지정된 기본값으로 설정합니다.

예시:

ALTER TABLE visits CLEAR COLUMN hour in PARTITION 201902

FREEZE PARTITION

ALTER TABLE table_name [ON CLUSTER cluster] FREEZE [PARTITION partition_expr] [WITH NAME 'backup_name']

이 쿼리는 지정된 파티션의 로컬 백업을 만들어요. PARTITION 절이 생략되면 모든 파티션의 백업을 한 번에 만듭니다.

전체 백업 과정은 서버를 중지하지 않고 수행됩니다.

old-styled 테이블의 경우 파티션 이름의 접두사(예: 2019)를 지정할 수 있다는 점에 유의하세요 — 그러면 해당하는 모든 파티션에 대한 백업이 만들어집니다. 파티션 표현식을 설정하는 방법은 How to set the partition expression 섹션을 참고하세요.

실행 시점에 데이터 스냅샷을 위해 쿼리는 테이블 데이터에 대한 하드링크를 만들어요. 하드링크는 /var/lib/clickhouse/shadow/N/... 디렉터리에 배치되는데, 여기서:

/var/lib/clickhouse/는 config에 지정된 ClickHouse 작업 디렉터리예요.
N은 백업의 증분 번호(incremental number)예요.
WITH NAME 파라미터가 지정되면 증분 번호 대신 'backup_name' 파라미터 값이 사용돼요.

테이블 데이터 저장을 위해 데이터 저장용 디스크 집합을 사용한다면, shadow/N 디렉터리가 각 디스크에 나타나며 PARTITION 표현식과 일치하는 데이터 파트를 저장해요.

백업 안에는 /var/lib/clickhouse/와 동일한 디렉터리 구조가 만들어져요. 쿼리는 모든 파일에 대해 chmod를 수행해 쓰기를 금지합니다.

백업을 만든 후에는 /var/lib/clickhouse/shadow/에서 원격 서버로 데이터를 복사하고, 그 다음 로컬 서버에서 삭제할 수 있어요. ALTER t FREEZE PARTITION 쿼리는 복제되지 않는다는 점에 유의하세요. 이 쿼리는 로컬 서버에만 로컬 백업을 만들어요.

이 쿼리는 거의 즉시 백업을 만듭니다(단, 먼저 해당 테이블에 대한 현재 쿼리가 실행을 마칠 때까지 기다려요).

ALTER TABLE t FREEZE PARTITION는 데이터만 복사하지 테이블 메타데이터는 복사하지 않아요. 테이블 메타데이터를 백업하려면 /var/lib/clickhouse/metadata/database/table.sql 파일을 복사하세요.

백업에서 데이터를 복원하려면 다음을 수행해요.

테이블이 없으면 만든다. 쿼리를 확인하려면 .sql 파일을 사용한다(그 안의 ATTACH를 CREATE로 바꾼다).
백업 안의 data/database/table/ 디렉터리에서 /var/lib/clickhouse/data/database/table/detached/ 디렉터리로 데이터를 복사한다.
ALTER TABLE t ATTACH PARTITION 쿼리를 실행해 데이터를 테이블에 추가한다.

백업에서 복원하는 데 서버를 중지할 필요는 없어요.

이 쿼리는 파트를 병렬로 처리하며, 스레드 수는 max_threads 설정으로 조절됩니다.

백업 및 데이터 복원에 대한 자세한 내용은 "Backup and Restore in ClickHouse" 섹션을 참고하세요.

UNFREEZE PARTITION

ALTER TABLE table_name [ON CLUSTER cluster] UNFREEZE [PARTITION 'part_expr'] WITH NAME 'backup_name'

디스크에서 지정된 이름을 가진 frozen 파티션을 제거해요. PARTITION 절이 생략되면 모든 파티션의 백업을 한 번에 제거합니다.

CLEAR INDEX IN PARTITION

ALTER TABLE table_name [ON CLUSTER cluster] CLEAR INDEX index_name IN PARTITION partition_expr

이 쿼리는 CLEAR COLUMN과 유사하게 동작하지만, 컬럼 데이터 대신 인덱스를 초기화해요.

FETCH PARTITION|PART

ALTER TABLE table_name [ON CLUSTER cluster] FETCH PARTITION|PART partition_expr FROM 'path-in-zookeeper'

다른 서버에서 파티션을 다운로드해요. 이 쿼리는 복제 테이블에서만 동작합니다.

이 쿼리는 다음을 수행해요.

지정된 샤드에서 파티션|파트를 다운로드한다. 'path-in-zookeeper'에는 ZooKeeper에서 샤드까지의 경로를 지정해야 해요.
그런 다음 쿼리는 다운로드한 데이터를 table_name 테이블의 detached 디렉터리에 넣는다. 데이터를 테이블에 추가하려면 ATTACH PARTITION|PART 쿼리를 사용해요.

예를 들어:

FETCH PARTITION

ALTER TABLE users FETCH PARTITION 201902 FROM '/clickhouse/tables/01-01/visits';
ALTER TABLE users ATTACH PARTITION 201902;

FETCH PART

ALTER TABLE users FETCH PART 201901_2_2_0 FROM '/clickhouse/tables/01-01/visits';
ALTER TABLE users ATTACH PART 201901_2_2_0;

다음에 유의하세요.

ALTER ... FETCH PARTITION|PART 쿼리는 복제되지 않아요. 파트 또는 파티션을 로컬 서버의 detached 디렉터리에만 배치해요.
ALTER TABLE ... ATTACH 쿼리는 복제돼요. 모든 리플리카에 데이터를 추가해요. 데이터는 한 리플리카에서는 detached 디렉터리에서 추가되고, 다른 리플리카에서는 인접한 리플리카에서 추가됩니다.

다운로드 전에 시스템은 파티션이 존재하고 테이블 구조가 일치하는지 확인해요. 가장 적절한 리플리카가 정상 리플리카 중에서 자동으로 선택됩니다.

이 쿼리는 ALTER TABLE이라고 불리지만, 테이블 구조를 변경하지 않고 테이블에서 사용 가능한 데이터를 즉시 변경하지도 않아요.

MOVE PARTITION|PART

MergeTree 엔진 테이블의 파티션 또는 데이터 파트를 다른 볼륨이나 디스크로 이동해요. Using Multiple Block Devices for Data Storage를 참고하세요.

ALTER TABLE table_name [ON CLUSTER cluster] MOVE PARTITION|PART partition_expr TO DISK|VOLUME 'disk_name'

ALTER TABLE t MOVE 쿼리:

복제되지 않아요. 리플리카마다 서로 다른 storage policy를 가질 수 있기 때문이에요.
지정된 디스크나 볼륨이 구성되어 있지 않으면 오류를 반환해요. storage policy에 지정된 데이터 이동 조건을 적용할 수 없을 때도 오류를 반환합니다.
이동할 데이터가 백그라운드 프로세스, 동시 ALTER TABLE t MOVE 쿼리 또는 백그라운드 데이터 병합의 결과로 이미 이동된 경우 오류를 반환할 수 있어요. 이 경우 사용자는 추가 작업을 수행해서는 안 됩니다.

예시:

ALTER TABLE hits MOVE PART '20190301_14343_16206_438' TO VOLUME 'slow'
ALTER TABLE hits MOVE PARTITION '2019-09-01' TO DISK 'fast_ssd'

UPDATE IN PARTITION

지정된 파티션에서 지정된 필터링 표현식과 일치하는 데이터를 조작해요. mutation으로 구현됩니다.

Syntax:

ALTER TABLE [db.]table [ON CLUSTER cluster] UPDATE column1 = expr1 [, ...] [IN PARTITION partition_expr] WHERE filter_expr

Example

-- using partition name
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION 2 WHERE p = 2;

-- using partition id
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION ID '2' WHERE p = 2;

DELETE IN PARTITION

지정된 파티션에서 지정된 필터링 표현식과 일치하는 데이터를 삭제해요. mutation으로 구현됩니다.

Syntax:

ALTER TABLE [db.]table [ON CLUSTER cluster] DELETE [IN PARTITION partition_expr] WHERE filter_expr

Example

-- using partition name
ALTER TABLE mt DELETE IN PARTITION 2 WHERE p = 2;

-- using partition id
ALTER TABLE mt DELETE IN PARTITION ID '2' WHERE p = 2;

REWRITE PARTS

모든 새 설정을 사용해 파트를 처음부터 다시 써요. 테이블 수준 설정(예: use_const_adaptive_granularity)이 기본적으로 새로 쓰여진 파트에만 적용되기 때문에 이것이 의미가 있어요.

Example

ALTER TABLE mt REWRITE PARTS;
ALTER TABLE mt REWRITE PARTS IN PARTITION 2;

How to Set Partition Expression

ALTER ... PARTITION 쿼리에서 파티션 표현식을 여러 가지 방법으로 지정할 수 있어요.

system.parts 테이블의 partition 컬럼 값으로 지정한다. 예: ALTER TABLE visits DETACH PARTITION 201901.
ALL 키워드를 사용한다. DROP/DETACH/ATTACH/ATTACH FROM에서만 사용할 수 있어요. 예: ALTER TABLE visits ATTACH PARTITION ALL.
테이블 파티셔닝 키 튜플과 (타입이) 일치하는 표현식 또는 상수의 튜플로 지정한다. 단일 요소 파티셔닝 키의 경우 표현식을 tuple (...) 함수로 감싸야 해요. 예: ALTER TABLE visits DETACH PARTITION tuple(toYYYYMM(toDate('2019-01-25'))).
파티션 ID를 사용한다. 파티션 ID는 파일 시스템과 ZooKeeper에서 파티션 이름으로 사용되는 파티션의 문자열 식별자(가능하면 사람이 읽을 수 있는)예요. 파티션 ID는 PARTITION ID 절에 작은따옴표로 지정해야 해요. 예: ALTER TABLE visits DETACH PARTITION ID '201901'.
ALTER ATTACH PART 및 DROP DETACHED PART 쿼리에서 파트 이름을 지정하려면 system.detached_parts 테이블의 name 컬럼 값을 가진 문자열 리터럴을 사용한다. 예: ALTER TABLE visits ATTACH PART '201901_1_1_0'.

파티션을 지정할 때 따옴표를 사용하는 것은 파티션 표현식의 타입에 따라 달라져요. 예를 들어 String 타입의 경우 이름을 따옴표(')로 지정해야 합니다. Date 및 Int* 타입은 따옴표가 필요 없어요.

위의 모든 규칙은 OPTIMIZE 쿼리에도 적용됩니다. 비파티션 테이블을 최적화할 때 유일한 파티션을 지정해야 한다면 PARTITION tuple() 표현식을 설정하세요. 예:

OPTIMIZE TABLE table_not_partitioned PARTITION tuple() FINAL;

IN PARTITION은 ALTER TABLE 쿼리의 결과로 UPDATE 또는 DELETE 표현식이 적용될 파티션을 지정해요. 새 파트는 지정된 파티션에서만 생성됩니다. 이렇게 해서, 테이블이 많은 파티션으로 나뉘고 특정 데이터만 점진적으로 업데이트하면 되는 경우 IN PARTITION은 부하를 줄이는 데 도움이 돼요.

ALTER ... PARTITION 쿼리의 예시는 테스트 00502_custom_partitioning_local 및 00502_custom_partitioning_replicated_zookeeper에서 확인할 수 있어요.

ALTER TABLE ... PARTITION