SYSTEM 문

SYSTEM 문

SYSTEM 문은 사전(dictionary) 리로드, 캐시 정리, 복제본 관리, 백그라운드 merge/move/fetch 제어, 뷰 새로고침 관리 등 ClickHouse 서버의 다양한 시스템 수준 작업을 수행해요. 대부분의 명령은 선택적으로 ON CLUSTER cluster_name을 지원해요.

출처: 문서

본문

SYSTEM RELOAD EMBEDDED DICTIONARIES

모든 내부 사전(Internal dictionaries)을 리로드해요. 기본적으로 내부 사전은 비활성화돼 있어요. 내부 사전 업데이트 결과와 관계없이 항상 Ok.를 반환해요.

SYSTEM RELOAD DICTIONARIES

SYSTEM RELOAD DICTIONARIES 쿼리는 LOADED 상태인 사전(예: 이전에 성공적으로 로드된 사전, system.dictionaries의 status 열 참고)을 리로드해요. 기본적으로 사전은 지연(lazy) 로드되며(dictionaries_lazy_load 참고), 시작 시 자동으로 로드되는 대신 dictGet 함수를 사용하거나 ENGINE = Dictionary인 테이블에서 SELECT를 사용해 처음 접근할 때 초기화돼요.

Syntax (구문)

SYSTEM RELOAD DICTIONARIES [ON CLUSTER cluster_name]

SYSTEM RELOAD DICTIONARY

사전의 상태(LOADED / NOT_LOADED / FAILED)와 관계없이 사전 dictionary_name을 완전히 리로드해요. 사전 업데이트 결과와 관계없이 항상 Ok.를 반환해요.

SYSTEM RELOAD DICTIONARY [ON CLUSTER cluster_name] dictionary_name

사전의 상태는 system.dictionaries 테이블을 조회해 확인할 수 있어요.

SELECT name, status FROM system.dictionaries;

SYSTEM UNLOAD DICTIONARY

사전 상태가 LOADED이면 사전 dictionary_name을 언로드해 메모리를 해제해요. 사전은 다시 필요할 때 지연 리로드돼요.

SYSTEM UNLOAD DICTIONARY dictionary_name

사전의 상태는 system.dictionaries 테이블을 조회해 확인할 수 있어요.

SELECT name, status FROM system.dictionaries;

SYSTEM UNLOAD DICTIONARIES

SYSTEM UNLOAD DICTIONARIES 쿼리는 LOADED 상태인 모든 사전(이전에 성공적으로 로드된 사전)을 언로드해요.

SYSTEM UNLOAD DICTIONARIES

SYSTEM RELOAD FUNCTIONS

구성 파일에서 등록된 모든 실행 가능한 사용자 정의 함수(executable user defined functions) 또는 그중 하나를 리로드해요.

Syntax (구문)

SYSTEM RELOAD FUNCTIONS [ON CLUSTER cluster_name]
SYSTEM RELOAD FUNCTION [ON CLUSTER cluster_name] function_name

SYSTEM RELOAD ASYNCHRONOUS METRICS

모든 비동기 메트릭(asynchronous metrics)을 다시 계산해요. 비동기 메트릭은 asynchronous_metrics_update_period_s 설정을 기반으로 주기적으로 업데이트되므로, 이 문으로 수동 업데이트하는 것은 보통 필요하지 않아요.

SYSTEM RELOAD ASYNCHRONOUS METRICS [ON CLUSTER cluster_name]

SYSTEM CLEAR|DROP DNS CACHE

ClickHouse의 내부 DNS 캐시를 지워요. 인프라를 변경할 때(다른 ClickHouse 서버나 사전이 사용하는 서버의 IP 주소를 변경) 이 명령이 필요한 경우가 있어요(오래된 ClickHouse 버전의 경우). 더 편리한(자동) 캐시 관리를 위해서는 disable_internal_dns_cache, dns_cache_max_entries, dns_cache_update_period 매개변수를 참고해요.

SYSTEM CLEAR|DROP MARK CACHE

마크 캐시(mark cache)를 지워요.

SYSTEM CLEAR|DROP PRIMARY INDEX CACHE

MergeTree 테이블의 기본 키를 메모리에 보관하는 기본 인덱스 캐시를 지워요. 그 크기는 서버 수준 설정 primary_index_cache_size로 구성돼요.

SYSTEM CLEAR|DROP ICEBERG METADATA CACHE

iceberg 메타데이터 캐시를 지워요.

SYSTEM CLEAR|DROP AVRO SCHEMA CACHE

AvroConfluent 형식이 사용하는 URL별 Confluent Schema Registry 캐시를 지워요. 이는 스키마 가져오기 캐시(id → schema)와 스키마 등록 캐시(subject + schema → id)를 모두 삭제해서, 이후 읽기와 쓰기가 레지스트리 서버로 돌아가도록 해요. 레지스트리 쪽에서 스키마가 삭제되거나 다시 쓰였을 때, 또는 테스트에서 레지스트리의 멱등성(idempotency)을 확인할 때 유용해요.

SYSTEM DROP PARQUET METADATA CACHE

parquet 메타데이터 캐시를 지워요.

SYSTEM CLEAR|DROP PAIMON METADATA CACHE

파싱된 Paimon 메타데이터 파일(manifest lists와 manifests)의 메모리 내 캐시를 지워요.

SYSTEM CLEAR|DROP POINT IN POLYGON CACHE

pointInPolygon 함수가 사용하는 전처리된 상수 폴리곤의 캐시를 지워요. 구성된 크기 제한(point_in_polygon_cache_size 서버 설정)은 그대로 두므로, 이후에도 캐시는 계속 항목을 받아들여요. 캐시를 비활성화하려면 대신 point_in_polygon_cache_size를 0으로 설정해요.

SYSTEM CLEAR|DROP TEXT INDEX CACHES

텍스트 인덱스의 tokens, header, postings 캐시를 지워요. 이 캐시 중 하나를 개별적으로 삭제하려면 다음을 실행할 수 있어요.

• SYSTEM CLEAR TEXT INDEX TOKENS CACHE,
• SYSTEM CLEAR TEXT INDEX HEADER CACHE, 또는
• SYSTEM CLEAR TEXT INDEX POSTINGS CACHE

SYSTEM CLEAR|DROP INDEX MARK CACHE

보조(데이터 스킵핑) 인덱스의 마크 캐시를 지워요.

SYSTEM CLEAR|DROP INDEX UNCOMPRESSED CACHE

보조(데이터 스킵핑) 인덱스의 압축되지 않은 블록 캐시를 지워요.

SYSTEM CLEAR|DROP MMAP CACHE

메모리 매핑된 파일의 캐시를 지워요.

SYSTEM CLEAR|DROP PAGE CACHE

사용자 공간 페이지 캐시, 즉 ClickHouse가 기본 스토리지에서 읽은 데이터의 자체 메모리 내 캐시를 지워요.

SYSTEM CLEAR|DROP VECTOR SIMILARITY INDEX CACHE

벡터 유사도 인덱스 캐시를 지워요.

SYSTEM CLEAR|DROP CONNECTIONS CACHE

나가는 연결에 사용되는 HTTP 연결 풀의 캐시를 지워요.

SYSTEM CLEAR|DROP S3 CLIENT CACHE

S3 클라이언트의 캐시를 지워요.

SYSTEM PREWARM MARK CACHE

mark cache에 테이블의 마크를 로드해요. 보조 인덱스 마크도 index mark cache에 로드돼요.

SYSTEM PREWARM MARK CACHE [ON CLUSTER cluster_name] [db.]table

SYSTEM PREWARM PRIMARY INDEX CACHE

primary index cache에 MergeTree 테이블의 기본 인덱스를 로드해요.

SYSTEM PREWARM PRIMARY INDEX CACHE [ON CLUSTER cluster_name] [db.]table

SYSTEM CLEAR|DROP DISK METADATA CACHE

지정된 디스크의 메타데이터 캐시를 지워요.

SYSTEM DROP DISK METADATA CACHE <disk_name>

SYSTEM SYNC FILESYSTEM CACHE

ClickHouse의 파일시스템 캐시 메모리 내 상태를 디스크에 실제로 존재하는 캐시 파일과 조정(reconcile)하고, 각 캐시 파일 세그먼트의 cache_name, path, 다운로드된 size를 반환해요. 선택적인 캐시 이름은 작업을 단일 캐시로 제한해요.

SYSTEM SYNC FILESYSTEM CACHE ['<cache_name>']

SYSTEM CLEAR|DROP DISTRIBUTED CACHE

SYSTEM CLEAR|DROP DISTRIBUTED CACHE는 ClickHouse Cloud에서만 사용할 수 있어요. 분산 캐시를 삭제해요. CONNECTIONS를 사용하면 분산 캐시 서버에 대한 캐시된 연결만 삭제하거나, 서버 식별자를 전달해 단일 서버를 대상으로 할 수 있어요.

SYSTEM DROP DISTRIBUTED CACHE [CONNECTIONS | 'server_id']

SYSTEM DROP REPLICA

ReplicatedMergeTree 테이블의 죽은(dead) 복제본은 다음 구문으로 삭제할 수 있어요.

SYSTEM DROP REPLICA 'replica_name' FROM TABLE database.table;
SYSTEM DROP REPLICA 'replica_name' FROM DATABASE database;
SYSTEM DROP REPLICA 'replica_name';
SYSTEM DROP REPLICA 'replica_name' FROM ZKPATH '/path/to/table/in/zk';

쿼리는 ZooKeeper의 ReplicatedMergeTree 복제본 경로를 제거해요. 복제본이 죽었고 더 이상 테이블이 없어 DROP TABLE로는 ZooKeeper에서 해당 메타데이터를 제거할 수 없을 때 유용해요. 비활성/오래된 복제본만 삭제하며, 로컬 복제본은 삭제할 수 없어요. 로컬 복제본은 DROP TABLE을 사용해요. DROP REPLICA는 어떤 테이블도 삭제하지 않으며 디스크에서 데이터나 메타데이터를 제거하지 않아요. 첫 번째 것은 database.table 테이블의 'replica_name' 복제본 메타데이터를 제거해요. 두 번째는 데이터베이스의 모든 복제 테이블에 대해 같은 작업을 해요. 세 번째는 로컬 서버의 모든 복제 테이블에 대해 같은 작업을 해요. 네 번째는 테이블의 다른 모든 복제본이 삭제되었을 때 죽은 복제본의 메타데이터를 제거하는 데 유용해요. 테이블 경로를 명시적으로 지정해야 해요. 테이블 생성 시 ReplicatedMergeTree 엔진의 첫 번째 인자로 전달된 경로와 같아야 해요.

SYSTEM DROP DATABASE REPLICA

Replicated 데이터베이스의 죽은 복제본은 다음 구문으로 삭제할 수 있어요.

SYSTEM DROP DATABASE REPLICA 'replica_name' [FROM SHARD 'shard_name'] FROM DATABASE database;
SYSTEM DROP DATABASE REPLICA 'replica_name' [FROM SHARD 'shard_name'];
SYSTEM DROP DATABASE REPLICA 'replica_name' [FROM SHARD 'shard_name'] FROM ZKPATH '/path/to/table/in/zk';

SYSTEM DROP REPLICA와 유사하지만, DROP DATABASE를 실행할 데이터베이스가 없을 때 ZooKeeper에서 Replicated 데이터베이스 복제본 경로를 제거해요. ReplicatedMergeTree 복제본은 제거하지 않으므로, 필요하다면 SYSTEM DROP REPLICA도 실행해야 할 수 있어요. 샤드와 복제본 이름은 데이터베이스 생성 시 Replicated 엔진 인자에 지정된 이름이에요. 또한 이 이름들은 system.clusters의 database_shard_name과 database_replica_name 열에서 얻을 수 있어요. FROM SHARD 절이 없으면 replica_name은 shard_name|replica_name 형식의 전체 복제본 이름이어야 해요.

SYSTEM CLEAR|DROP UNCOMPRESSED CACHE

압축되지 않은 데이터 캐시를 지워요. 압축되지 않은 데이터 캐시는 쿼리/사용자/프로필 수준 설정 use_uncompressed_cache로 활성화/비활성화돼요. 그 크기는 서버 수준 설정 uncompressed_cache_size로 구성할 수 있어요.

SYSTEM CLEAR|DROP COMPILED EXPRESSION CACHE

컴파일된 표현식 캐시를 지워요. 컴파일된 표현식 캐시는 쿼리/사용자/프로필 수준 설정 compile_expressions으로 활성화/비활성화돼요.

SYSTEM CLEAR|DROP QUERY CONDITION CACHE

쿼리 조건 캐시를 지워요.

SYSTEM CLEAR|DROP ENCRYPTION HEADERS CACHE

암호화 헤더 캐시를 지워요. 이 캐시는 암호화된 파일의 앞부분에서 읽은 암호화 헤더를 보관하며, 실험적인 use_reader_executor 읽기 경로가 이를 다시 읽지 않도록 하는 데 사용해요. 그 크기는 encryption_header_cache_size 서버 설정으로 구성돼요.

SYSTEM CLEAR|DROP QUERY CACHE

SYSTEM CLEAR QUERY CACHE;
SYSTEM CLEAR QUERY CACHE TAG '<tag>'

query cache를 지워요. 태그가 지정되면 지정된 태그를 가진 쿼리 캐시 항목만 삭제돼요.

SYSTEM CLEAR|DROP FORMAT SCHEMA CACHE

format_schema_path에서 로드된 스키마의 캐시를 지워요. 지원되는 대상:

• Protobuf: 가져온 Protobuf 메시지 정의를 메모리에서 제거해요.
• Files: format_schema_source가 query로 설정되었을 때 생성된, format_schema_path에 로컬로 저장된 캐시된 스키마 파일을 삭제해요.

참고: 대상이 지정되지 않으면 두 캐시가 모두 지워져요.

SYSTEM CLEAR|DROP FORMAT SCHEMA CACHE [FOR Protobuf/Files]

SYSTEM FLUSH LOGS

버퍼링된 로그 메시지를 시스템 테이블(예: system.query_log)로 플러시해요. 대부분의 시스템 테이블은 기본 플러시 간격이 7.5초이므로 주로 디버깅에 유용해요. 메시지 큐가 비어 있어도 시스템 테이블을 생성해요.

SYSTEM FLUSH LOGS [ON CLUSTER cluster_name] [log_name|[database.table]] [, ...]

모든 것을 플러시하고 싶지 않다면, 개별 로그의 이름이나 대상 테이블을 전달해 하나 이상의 개별 로그를 플러시할 수 있어요.

SYSTEM FLUSH LOGS query_log, system.query_views_log;

SYSTEM RELOAD CONFIG

ClickHouse 구성을 리로드해요. 구성이 ZooKeeper에 저장된 경우 사용돼요. SYSTEM RELOAD CONFIG는 ZooKeeper에 저장된 USER 구성을 리로드하지 않고, users.xml에 저장된 USER 구성만 리로드한다는 점에 유의해요. 모든 USER 구성을 리로드하려면 SYSTEM RELOAD USERS를 사용해요.

SYSTEM RELOAD CONFIG [ON CLUSTER cluster_name]

SYSTEM RELOAD USERS

users.xml, 로컬 디스크 접근 스토리지, 복제된(ZooKeeper의) 접근 스토리지를 포함한 모든 접근 스토리지를 리로드해요.

SYSTEM RELOAD USERS [ON CLUSTER cluster_name]

SYSTEM SHUTDOWN

ClickHouse를 정상적으로 종료해요(예: service clickhouse-server stop / kill {$pid_clickhouse-server}).

SYSTEM KILL

ClickHouse 프로세스를 중단해요(예: kill -9 {$ pid_clickhouse-server}).

SYSTEM INSTRUMENT

ENABLE_XRAY=1로 ClickHouse가 빌드되어 있을 때 사용 가능한 LLVM의 XRay 기능을 사용해 계측 지점(instrumentation points)을 관리해요. 이는 소스 코드를 수정하지 않고 최소한의 오버헤드로 프로덕션에서 디버깅하고 프로파일링할 수 있게 해줘요. 계측 지점이 추가되지 않으면 200개 이상의 명령어로 구성된 함수의 프롤로그와 에필로그에 인접 주소로의 추가 점프만 추가되므로 성능 저하는 무시할 수 있어요.

SYSTEM INSTRUMENT ADD

새 계측 지점을 추가해요. 계측된 함수는 system.instrumentation 시스템 테이블에서 확인할 수 있어요. 같은 함수에 여러 핸들러를 추가할 수 있으며, 추가된 순서대로 실행돼요. 계측할 함수는 system.symbols 시스템 테이블에서 수집할 수 있어요. 함수에 추가할 수 있는 핸들러의 종류는 세 가지예요.

Syntax (구문)

SYSTEM INSTRUMENT ADD FUNCTION HANDLER [ARGUMENTS]

여기서 FUNCTION은 QueryMetricLog::startQuery 같은 함수 또는 함수의 부분 문자열이고, 핸들러는 다음 중 하나예요.

LOG

함수의 ENTRY 또는 EXIT에서 인자로 제공된 텍스트와 스택 트레이스를 출력해요.

SYSTEM INSTRUMENT ADD 'QueryMetricLog::startQuery' LOG ENTRY 'this is a log printed at entry'
SYSTEM INSTRUMENT ADD 'QueryMetricLog::startQuery' LOG EXIT 'this is a log printed at exit'

SLEEP

ENTRY 또는 EXIT에서 고정된 초 단위 만큼 잠들어요.

SYSTEM INSTRUMENT ADD 'QueryMetricLog::startQuery' SLEEP ENTRY 0.5

또는 공백으로 구분된 min과 max를 제공하여 균일 분포의 임의 초 단위만큼 잠들어요.

SYSTEM INSTRUMENT ADD 'QueryMetricLog::startQuery' SLEEP ENTRY 0 1

PROFILE

함수의 ENTRY와 EXIT 사이에 소요된 시간을 측정해요. 프로파일링 결과는 system.trace_log에 저장되며 Chrome Event Trace Format으로 변환할 수 있어요.

SYSTEM INSTRUMENT ADD 'QueryMetricLog::startQuery' PROFILE

SYSTEM INSTRUMENT REMOVE

다음으로 단일 계측 지점을 제거해요.

SYSTEM INSTRUMENT REMOVE ID

ALL 키워드로 모두 제거해요.

SYSTEM INSTRUMENT REMOVE ALL

서브쿼리의 ID 집합으로 제거해요.

SYSTEM INSTRUMENT REMOVE (SELECT id FROM system.instrumentation WHERE handler = 'log')

또는 주어진 function_name과 일치하는 모든 계측 지점을 제거해요.

SYSTEM INSTRUMENT REMOVE 'QueryMetricLog::startQuery'

계측 지점 정보는 system.instrumentation 시스템 테이블에서 수집할 수 있어요.

Managing Distributed Tables (분산 테이블 관리)

ClickHouse는 distributed 테이블을 관리할 수 있어요. 사용자가 이 테이블에 데이터를 삽입하면 ClickHouse는 먼저 클러스터 노드로 보내야 할 데이터의 큐를 만든 뒤 비동기로 전송해요. STOP DISTRIBUTED SENDS, FLUSH DISTRIBUTED, START DISTRIBUTED SENDS 쿼리로 큐 처리를 관리할 수 있어요. 또한 distributed_foreground_insert 설정으로 분산 데이터를 동기적으로 삽입할 수도 있어요.

SYSTEM STOP DISTRIBUTED SENDS

분산 테이블에 데이터를 삽입할 때 백그라운드 데이터 분배를 비활성화해요.

SYSTEM STOP DISTRIBUTED SENDS [db.]<distributed_table_name> [ON CLUSTER cluster_name]

prefer_localhost_replica이 활성화(기본값)된 경우 로컬 샤드로의 데이터는 어쨌든 삽입돼요.

SYSTEM FLUSH DISTRIBUTED

ClickHouse가 클러스터 노드로 데이터를 동기적으로 보내도록 강제해요. 노드를 사용할 수 없으면 ClickHouse는 예외를 발생시키고 쿼리 실행을 중지해요. 모든 노드가 다시 온라인이 될 때까지 쿼리를 재시도할 수 있어요. SETTINGS 절로 일부 설정을 재정의할 수도 있는데, 이는 max_concurrent_queries_for_all_users나 max_memory_usage 같은 일시적인 제한을 피하는 데 유용할 수 있어요.

SYSTEM FLUSH DISTRIBUTED [db.]<distributed_table_name> [ON CLUSTER cluster_name] [SETTINGS ...]

각 보류 중인 블록은 초기 INSERT 쿼리의 설정으로 디스크에 저장되므로, 때로 설정을 재정의하고 싶을 수 있어요.

SYSTEM START DISTRIBUTED SENDS

분산 테이블에 데이터를 삽입할 때 백그라운드 데이터 분배를 활성화해요.

SYSTEM START DISTRIBUTED SENDS [db.]<distributed_table_name> [ON CLUSTER cluster_name]

SYSTEM STOP LISTEN

지정된 포트와 지정된 프로토콜로 서버에 대한 소켓을 닫고 기존 연결을 정상적으로 종료해요. 다만 해당 프로토콜 설정이 clickhouse-server 구성에 지정되지 않았다면 이 명령은 효과가 없어요.

SYSTEM STOP LISTEN [ON CLUSTER cluster_name] [QUERIES ALL | QUERIES DEFAULT | QUERIES CUSTOM | TCP | TCP WITH PROXY | TCP SECURE | HTTP | HTTPS | MYSQL | GRPC | POSTGRESQL | PROMETHEUS | CUSTOM 'protocol']

• CUSTOM 'protocol' 수정자가 지정되면 서버 구성의 protocols 섹션에 정의된 지정된 이름의 커스텀 프로토콜이 중지돼요.
• QUERIES ALL [EXCEPT .. [,..]] 수정자가 지정되면 EXCEPT 절로 지정되지 않은 한 모든 프로토콜이 중지돼요.
• QUERIES DEFAULT [EXCEPT .. [,..]] 수정자가 지정되면 EXCEPT 절로 지정되지 않은 한 모든 기본 프로토콜이 중지돼요.
• QUERIES CUSTOM [EXCEPT .. [,..]] 수정자가 지정되면 EXCEPT 절로 지정되지 않은 한 모든 커스텀 프로토콜이 중지돼요.

SYSTEM START LISTEN

지정된 프로토콜에서 새 연결이 설정되도록 허용해요. 다만 지정된 포트와 프로토콜의 서버가 SYSTEM STOP LISTEN 명령으로 중지되지 않았다면 이 명령은 효과가 없어요.

SYSTEM START LISTEN [ON CLUSTER cluster_name] [QUERIES ALL | QUERIES DEFAULT | QUERIES CUSTOM | TCP | TCP WITH PROXY | TCP SECURE | HTTP | HTTPS | MYSQL | GRPC | POSTGRESQL | PROMETHEUS | CUSTOM 'protocol']

Managing MergeTree Tables (MergeTree 테이블 관리)

ClickHouse는 MergeTree 테이블의 백그라운드 프로세스를 관리할 수 있어요.

SYSTEM STOP MERGES

MergeTree 계열 테이블의 백그라운드 merge를 중지할 수 있게 해줘요.

SYSTEM STOP MERGES [ON CLUSTER cluster_name] [ON VOLUME <volume_name> | [db.]merge_tree_family_table_name]

이전에 모든 MergeTree 테이블에 대해 merge가 중지된 경우에도 DETACH / ATTACH 테이블은 그 테이블에 대한 백그라운드 merge를 시작해요.

SYSTEM START MERGES

MergeTree 계열 테이블의 백그라운드 merge를 시작할 수 있게 해줘요.

SYSTEM START MERGES [ON CLUSTER cluster_name] [ON VOLUME <volume_name> | [db.]merge_tree_family_table_name]

SYSTEM STOP TTL MERGES

MergeTree 계열 테이블에 대해 TTL expression에 따라 오래된 데이터를 삭제하는 백그라운드 작업을 중지할 수 있게 해줘요. 테이블이 존재하지 않거나 테이블이 MergeTree 엔진이 아니어도 Ok.를 반환해요. 데이터베이스가 존재하지 않으면 오류를 반환해요.

SYSTEM STOP TTL MERGES [ON CLUSTER cluster_name] [[db.]merge_tree_family_table_name]

SYSTEM START TTL MERGES

MergeTree 계열 테이블에 대해 TTL expression에 따라 오래된 데이터를 삭제하는 백그라운드 작업을 시작할 수 있게 해줘요. 테이블이 존재하지 않아도 Ok.를 반환해요. 데이터베이스가 존재하지 않으면 오류를 반환해요.

SYSTEM START TTL MERGES [ON CLUSTER cluster_name] [[db.]merge_tree_family_table_name]

SYSTEM STOP MOVES

MergeTree 계열 테이블에 대해 TO VOLUME 또는 TO DISK 절이 있는 TTL 테이블 표현식에 따라 데이터를 이동하는 백그라운드 작업을 중지할 수 있게 해줘요. 테이블이 존재하지 않아도 Ok.를 반환해요. 데이터베이스가 존재하지 않으면 오류를 반환해요.

SYSTEM STOP MOVES [ON CLUSTER cluster_name] [[db.]merge_tree_family_table_name]

SYSTEM START MOVES

MergeTree 계열 테이블에 대해 TO VOLUME 및 TO DISK 절이 있는 TTL 테이블 표현식에 따라 데이터를 이동하는 백그라운드 작업을 시작할 수 있게 해줘요. 테이블이 존재하지 않아도 Ok.를 반환해요. 데이터베이스가 존재하지 않으면 오류를 반환해요.

SYSTEM START MOVES [ON CLUSTER cluster_name] [[db.]merge_tree_family_table_name]

SYSTEM UNFREEZE

지정된 이름의 동결(frozen) 백업을 모든 디스크에서 지워요. 개별 파트의 unfreezing에 대한 자세한 내용은 ALTER TABLE table_name UNFREEZE WITH NAME을 참고해요.

SYSTEM UNFREEZE WITH NAME <backup_name>

SYSTEM WAIT LOADING PARTS

테이블의 비동기 로딩 중인 모든 데이터 파트(오래된 데이터 파트)가 로드될 때까지 기다려요.

SYSTEM WAIT LOADING PARTS [ON CLUSTER cluster_name] [db.]merge_tree_family_table_name

Managing ReplicatedMergeTree Tables (ReplicatedMergeTree 테이블 관리)

ClickHouse는 ReplicatedMergeTree 테이블의 백그라운드 복제 관련 프로세스를 관리할 수 있어요.

SYSTEM STOP FETCHES

ReplicatedMergeTree 계열 테이블의 삽입된 파트에 대한 백그라운드 fetch를 중지할 수 있게 해줘요. 테이블 엔진과 관계없이, 테이블이나 데이터베이스가 존재하지 않아도 항상 Ok.를 반환해요.

SYSTEM STOP FETCHES [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name]

SYSTEM START FETCHES

ReplicatedMergeTree 계열 테이블의 삽입된 파트에 대한 백그라운드 fetch를 시작할 수 있게 해줘요. 테이블 엔진과 관계없이, 테이블이나 데이터베이스가 존재하지 않아도 항상 Ok.를 반환해요.

SYSTEM START FETCHES [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name]

SYSTEM STOP REPLICATED SENDS

ReplicatedMergeTree 계열 테이블의 새로 삽입된 파트에 대한 클러스터 내 다른 복제본으로의 백그라운드 전송을 중지할 수 있게 해줘요.

SYSTEM STOP REPLICATED SENDS [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name]

SYSTEM START REPLICATED SENDS

ReplicatedMergeTree 계열 테이블의 새로 삽입된 파트에 대한 클러스터 내 다른 복제본으로의 백그라운드 전송을 시작할 수 있게 해줘요.

SYSTEM START REPLICATED SENDS [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name]

SYSTEM STOP REPLICATION QUEUES

ReplicatedMergeTree 계열 테이블에 대해 Zookeeper에 저장된 복제 큐에서 백그라운드 fetch 작업을 중지할 수 있게 해줘요. 가능한 백그라운드 작업 유형은 merges, fetches, mutation, ON CLUSTER 절이 있는 DDL 문이에요.

SYSTEM STOP REPLICATION QUEUES [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name]

SYSTEM START REPLICATION QUEUES

ReplicatedMergeTree 계열 테이블에 대해 Zookeeper에 저장된 복제 큐에서 백그라운드 fetch 작업을 시작할 수 있게 해줘요. 가능한 백그라운드 작업 유형은 merges, fetches, mutation, ON CLUSTER 절이 있는 DDL 문이에요.

SYSTEM START REPLICATION QUEUES [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name]

SYSTEM STOP PULLING REPLICATION LOG

ReplicatedMergeTree 테이블에서 복제 로그의 새 항목을 복제 큐로 로드하는 것을 중지해요.

SYSTEM STOP PULLING REPLICATION LOG [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name]

SYSTEM START PULLING REPLICATION LOG

SYSTEM STOP PULLING REPLICATION LOG를 취소해요.

SYSTEM START PULLING REPLICATION LOG [ON CLUSTER cluster_name] [[db.]replicated_merge_tree_family_table_name]

SYSTEM SYNC REPLICA

ReplicatedMergeTree 테이블이 클러스터의 다른 복제본과 동기화될 때까지 기다리되, receive_timeout 초를 넘지 않아요.

SYSTEM SYNC REPLICA [ON CLUSTER cluster_name] [db.]replicated_merge_tree_family_table_name [IF EXISTS] [STRICT | LIGHTWEIGHT [FROM 'srcReplica1'[, 'srcReplica2'[, ...]]] | PULL]

이 문을 실행한 후 [db.]replicated_merge_tree_family_table_name은 공통 복제 로그에서 명령을 자체 복제 큐로 가져오고, 쿼리는 복제본이 가져온 모든 명령을 처리할 때까지 기다려요. 다음 수정자가 지원돼요.

• IF EXISTS(25.6부터 사용 가능)를 사용하면 테이블이 존재하지 않아도 쿼리가 오류를 던지지 않아요. 이는 클러스터에 새 복제본을 추가할 때 유용한데, 이미 클러스터 구성의 일부이지만 여전히 테이블을 생성하고 동기화하는 과정에 있을 때 유용해요.
• STRICT 수정자가 지정되면 쿼리는 복제 큐가 비워질 때까지 기다려요. STRICT 버전은 복제 큐에 새 항목이 계속 나타나면 성공하지 못할 수 있어요.
• LIGHTWEIGHT 수정자가 지정되면 쿼리는 GET_PART, ATTACH_PART, DROP_RANGE, REPLACE_RANGE, DROP_PART 항목이 처리되기만을 기다려요. 추가로 LIGHTWEIGHT 수정자는 선택적인 FROM 'srcReplicas' 절을 지원하는데, 'srcReplicas'는 쉼표로 구분된 원본 복제본 이름 목록이에요. 이 확장은 지정된 원본 복제본에서 시작되는 복제 작업에만 집중함으로써 더 목표 지향적인 동기화를 가능하게 해요.
• PULL 수정자가 지정되면 쿼리는 ZooKeeper에서 새 복제 큐 항목을 가져오지만, 어떤 것이 처리되기를 기다리지는 않아요.

SYNC DATABASE REPLICA

지정된 replicated database가 해당 데이터베이스의 DDL 큐에서 모든 스키마 변경을 적용할 때까지 기다려요.

Syntax (구문)

SYSTEM SYNC DATABASE REPLICA replicated_database_name;

SYSTEM RESTART REPLICA

ReplicatedMergeTree 테이블에 대해 Zookeeper 세션의 상태를 다시 초기화할 수 있게 해줘요. 현재 상태를 Zookeeper(진리의 소스)와 비교하고 필요하면 Zookeeper 큐에 작업을 추가해요. ZooKeeper 데이터 기반 복제 큐의 초기화는 ATTACH TABLE 문과 같은 방식으로 발생해요. 짧은 시간 동안 테이블은 모든 작업에 사용할 수 없어요.

SYSTEM RESTART REPLICA [ON CLUSTER cluster_name] [db.]replicated_merge_tree_family_table_name

SYSTEM RESTORE REPLICA

데이터가 [어쩌면] 존재하지만 Zookeeper 메타데이터가 유실된 경우 복제본을 복원해요. 읽기 전용 ReplicatedMergeTree 테이블에서만 동작해요. 다음 후에 쿼리를 실행할 수 있어요.

• ZooKeeper root / 유실.
• 복제본 경로 /replicas 유실.
• 개별 복제본 경로 /replicas/replica_name/ 유실.

복제본은 로컬에서 찾은 파트를 연결(attach)하고 그 정보를 Zookeeper로 보내요. 메타데이터 유실 전에 복제본에 존재하던 파트는 오래되지 않았다면 다른 복제본에서 다시 가져오지 않아요(즉 복제본 복원이 네트워크를 통해 모든 데이터를 다시 다운로드하는 것을 의미하지는 않아요). 모든 상태의 파트는 detached/ 폴더로 이동돼요. 데이터 유실 전에 활성 상태(커밋된)였던 파트는 연결돼요.

SYSTEM RESTORE DATABASE REPLICA

데이터가 [어쩌면] 존재하지만 Zookeeper 메타데이터가 유실된 경우 복제본을 복원해요.

Syntax (구문)

SYSTEM RESTORE DATABASE REPLICA repl_db [ON CLUSTER cluster]

Example (예제)

CREATE DATABASE repl_db
ENGINE=Replicated("/clickhouse/repl_db", shard1, replica1);

CREATE TABLE repl_db.test_table (n UInt32)
ENGINE = ReplicatedMergeTree
ORDER BY n PARTITION BY n % 10;

-- zookeeper_delete_path("/clickhouse/repl_db", recursive=True) <- root loss.

SYSTEM RESTORE DATABASE REPLICA repl_db;

Syntax (구문)

SYSTEM RESTORE REPLICA [db.]replicated_merge_tree_family_table_name [ON CLUSTER cluster_name]

대체 구문:

SYSTEM RESTORE REPLICA [ON CLUSTER cluster_name] [db.]replicated_merge_tree_family_table_name

Example (예제) 여러 서버에 테이블 생성. ZooKeeper에서 복제본의 메타데이터가 유실된 후 테이블은 메타데이터가 없어 읽기 전용으로 연결돼요. 마지막 쿼리는 모든 복제본에서 실행해야 해요.

CREATE TABLE test(n UInt32)
ENGINE = ReplicatedMergeTree('/clickhouse/tables/test/', '{replica}')
ORDER BY n PARTITION BY n % 10;

INSERT INTO test SELECT * FROM numbers(1000);

-- zookeeper_delete_path("/clickhouse/tables/test", recursive=True) <- root loss.

SYSTEM RESTART REPLICA test;
SYSTEM RESTORE REPLICA test;

다른 방법:

SYSTEM RESTORE REPLICA test ON CLUSTER cluster;

SYSTEM RESTART REPLICAS

모든 ReplicatedMergeTree 테이블에 대해 Zookeeper 세션 상태를 다시 초기화할 수 있게 해줘요. 현재 상태를 Zookeeper(진리의 소스)와 비교하고 필요하면 Zookeeper 큐에 작업을 추가해요.

SYSTEM CLEAR|DROP FILESYSTEM CACHE

파일시스템 캐시를 내릴 수 있게 해줘요.

SYSTEM CLEAR FILESYSTEM CACHE [ON CLUSTER cluster_name]

SYSTEM SYNC FILE CACHE

너무 무겁고 오용 가능성이 있어요. sync syscall을 수행해요.

SYSTEM SYNC FILE CACHE [ON CLUSTER cluster_name]

SYSTEM LOAD PRIMARY KEY

주어진 테이블 또는 모든 테이블의 기본 키를 로드해요.

SYSTEM LOAD PRIMARY KEY [db.]name

SYSTEM LOAD PRIMARY KEY

SYSTEM UNLOAD PRIMARY KEY

주어진 테이블 또는 모든 테이블의 기본 키를 언로드해요.

SYSTEM UNLOAD PRIMARY KEY [db.]name

SYSTEM UNLOAD PRIMARY KEY

Managing Refreshable Materialized Views (새로고침 가능한 Materialized View 관리)

Refreshable Materialized Views가 수행하는 백그라운드 작업을 제어하는 명령들이에요. 사용하는 동안 system.view_refreshes를 주시해요.

SYSTEM STOP [REPLICATED] VIEW, STOP VIEWS

주어진 뷰 또는 모든 새로고침 가능한 뷰의 주기적 새로고침을 비활성화해요. 새로고침이 진행 중이면 그것도 취소해요. 뷰가 Replicated 또는 Shared 데이터베이스에 있다면 STOP VIEW는 현재 복제본에만 영향을 주고, STOP REPLICATED VIEW는 모든 복제본에 영향을 줘요. 중지된 상태는 서버 재시작 후에도 유지되지 않아요. 재시작 후 뷰는 구성된 새로고침 일정을 재개해요. Replicated 또는 Shared 데이터베이스에서 SYSTEM STOP VIEW는 현재 복제본에만 영향을 줘요. 모든 복제본에서 새로고침을 중지하려면 SYSTEM STOP REPLICATED VIEW를 사용해요.

SYSTEM STOP VIEW [db.]name

SYSTEM STOP VIEWS

SYSTEM START [REPLICATED] VIEW, START VIEWS

주어진 뷰 또는 모든 새로고침 가능한 뷰의 주기적 새로고침을 활성화해요. 즉각적인 새로고침은 트리거되지 않아요. 뷰가 Replicated 또는 Shared 데이터베이스에 있다면 START VIEW는 STOP VIEW의 효과를 되돌리고, START REPLICATED VIEW는 STOP REPLICATED VIEW의 효과를 되돌려요. START VIEW는 PAUSE VIEW의 효과도 되돌려요.

SYSTEM START VIEW [db.]name

SYSTEM START VIEWS

SYSTEM PAUSE VIEW, PAUSE VIEWS

주어진 뷰 또는 모든 새로고침 가능한 뷰의 주기적 새로고침을 비활성화해요. SYSTEM STOP VIEW와 달리 SYSTEM PAUSE VIEW는 이미 진행 중인 새로고침을 중단하지 않아요. 실행 중인 새로고침은 끝나도록 허용되고, 그 이후의 새로고침만 막혀요. SYSTEM START VIEW 또는 SYSTEM START VIEWS로 되돌릴 수 있어요. 일시 중지된 상태는 서버 재시작 후에도 유지되지 않아요. 재시작 후 뷰는 구성된 새로고침 일정을 재개해요. Replicated 또는 Shared 데이터베이스에서 SYSTEM PAUSE VIEW는 현재 복제본에만 영향을 줘요.

SYSTEM PAUSE VIEW [db.]name

SYSTEM PAUSE VIEWS

SYSTEM REFRESH VIEW

주어진 뷰의 즉각적인 예정 외(out-of-schedule) 새로고침을 트리거해요.

SYSTEM REFRESH VIEW [db.]name

SYSTEM WAIT VIEW

실행 중인 새로고침이 완료되기를 기다려요. 새로고침이 실행 중이지 않으면 즉시 반환돼요. 최신 새로고침 시도가 실패하면 오류를 보고해요. 새로고침 가능한 materialized view를 (EMPTY 키워드 없이) 만든 직후 초기 새로고침이 완료되기를 기다리는 데 사용할 수 있어요. 뷰가 Replicated 또는 Shared 데이터베이스에 있고 다른 복제본에서 새로고침이 실행 중이면 그 새로고침이 완료되기를 기다려요.

SYSTEM WAIT VIEW [db.]name

SYSTEM CANCEL VIEW

현재 복제본에서 주어진 뷰에 대한 새로고침이 진행 중이면 중단하고 취소해요. 그렇지 않으면 아무것도 하지 않아요.

SYSTEM CANCEL VIEW [db.]name

Managing Background Activity (백그라운드 활동 관리)

엔진에 구애받지 않는(engine-agnostic) 명령들로, 단일 테이블 또는 서버의 모든 그러한 테이블의 백그라운드 활동을 한 번에 제어해요. 이는 다음을 다룹니다.

• Refreshable materialized views(주기적 새로고침), 그리고
• 외부 소스에서 지속적으로 소비하는 스트리밍 테이블 엔진: Kafka, RabbitMQ, NATS, S3Queue, AzureQueue.

새로고침 가능한 materialized view의 경우 각 동사는 Managing Refreshable Materialized Views의 해당 SYSTEM ... VIEW 명령의 별칭이에요. SYSTEM STOP [db.]name은 정확히 SYSTEM STOP VIEW [db.]name처럼 동작하고, 나머지도 마찬가지예요. 테이블별 형식과 와일드카드 형식은 백그라운드 활동이 없는 테이블을 다루는 방식이 달라요. 테이블별 형식(SYSTEM STOP [db.]table)은 명명된 테이블이 스트리밍 엔진도 새로고침 가능한 materialized view도 아니면 오류를 던져요. 와일드카드 형식은 그러한 테이블을 조용히 건너뛰므로 항상 실행해도 안전해요. STOP과 CANCEL은 최대한 빨리 소비를 중단해요. Kafka, RabbitMQ, NATS의 경우 소스에서 읽기는 중지하지만 이미 시작된 insert는 중단하지 않아요. materialized views에 이미 쓰여지고 있는 블록은 여전히 끝나고 커밋돼요. S3Queue와 AzureQueue는 단일 파이프라인에서 읽기와 삽입을 수행해요. 중복 제거가 활성화(기본값)되면 insert도 취소되고 파일은 나중에 다시 처리돼요. 중복 제거가 비활성화되면 진행 중인 배치는 (위 엔진들처럼) 끝나고 커밋되어 행 중복을 피해요. 읽었지만 아직 커밋되지 않은 데이터는 나중에 다시 소비되므로 손실되지 않아요. 유일한 예외는 core NATS( JetStream 없이)인데, 재전송할 수 없어서 이를 버려요. PAUSE는 실행 중인 insert를 중단하지 않으므로 보통 아무것도 잃지 않아요. core NATS가 예외예요. 일시 중지는 소비를 멈추고 이미 받았지만 아직 삽입하지 않은 메시지를 버리며, core NATS는 이를 재전송할 수 없어요. 이 상태들 중 어느 것도 서버 재시작 후에 유지되지 않아요. 재시작 후 새로고침 가능한 뷰는 구성된 일정을 재개해요.

SYSTEM STOP

백그라운드 활동을 멈추고 중지된 상태로 유지해요. 지금 실행 중인 것을 중단시키고 SYSTEM START까지 더 아무것도 실행하지 않아요. PAUSE + CANCEL과 동등해요.

SYSTEM STOP [db.]table
SYSTEM STOP ALL BACKGROUND

SYSTEM START

이전 SYSTEM STOP 또는 SYSTEM PAUSE를 되돌려 활동을 재개해요. 어떤 활동도 중단하지 않아요.

SYSTEM START [db.]table
SYSTEM START ALL BACKGROUND

SYSTEM PAUSE

추가 백그라운드 활동을 막되, 지금 실행 중인 것은 먼저 끝내도록 해요.

SYSTEM PAUSE [db.]table
SYSTEM PAUSE ALL BACKGROUND

SYSTEM CANCEL

미래 활동을 막지 않고 지금 실행 중인 활동만 중단해요. 테이블은 일정에 따라 계속 새로고침하거나 소비해요. 진행 중인 활동이 없으면 아무것도 하지 않아요.

SYSTEM CANCEL [db.]table
SYSTEM CANCEL ALL BACKGROUND

SYSTEM REFRESH

예정 외의 추가 사이클을 한 번 실행해요. 스트리밍 테이블에서는 테이블이 중지되거나 일시 중지된 상태여도 즉시 한 번 실행돼요. 새로고침 가능한 materialized view에서는 SYSTEM REFRESH VIEW처럼 동작해요. 뷰가 중지되면 새로고침이 기억되고 SYSTEM START가 풀어주면 한 번 실행돼요.

SYSTEM REFRESH [db.]table
SYSTEM REFRESH ALL BACKGROUND

Privileges (권한)

각 명령은 대상 엔진의 권한을 요구해요. 새로고침 가능한 materialized view에는 SYSTEM VIEWS, 스트리밍 테이블에는 SYSTEM STREAMING ENGINES가 필요해요. 둘 다 SYSTEM BACKGROUND의 자식이므로, SYSTEM BACKGROUND를 부여하면 모든 그러한 테이블의 백그라운드 활동을 제어할 수 있어요. ALL BACKGROUND 형태는 사용자가 제어하도록 허용된 테이블에만 적용되며 나머지는 조용히 건너뛰어요.

SYSTEM FLUSH OBJECT STORAGE QUEUE

주어진 S3Queue 또는 AzureQueue 테이블이 주어진 파일을 처리하거나 영구적으로 실패할 때까지 블록해요. 파일이 이미 처리되었다면 즉시 반환돼요. 파일이 영구적으로 실패하면(모든 재시도 소진) 오류를 발생시켜요.

SYSTEM FLUSH OBJECT STORAGE QUEUE [db.]table_name PATH 'path'

SYSTEM ENABLE|DISABLE FAILPOINT

Fail points는 테스트를 위해 필요 시 결함(오류, 지연, 또는 실행 중인 스레드의 일시 중지)을 주입할 수 있는 서버 코드의 이름이 붙은 위치예요. 이들은 현재 상태와 함께 system.fail_points 테이블에 나열돼요.

SYSTEM ENABLE FAILPOINT name
SYSTEM DISABLE FAILPOINT name
SYSTEM DISABLE ALL FAILPOINTS
SYSTEM WAIT FAILPOINT name [PAUSE|RESUME]
SYSTEM NOTIFY FAILPOINT name

SYSTEM ENABLE FAILPOINT는 단일 fail point를 장전(arm)하고, SYSTEM DISABLE FAILPOINT는 이를 해제하며 그 위에 막힌 모든 스레드를 재개하고, 활성화되지 않았다면 no-op이에요. SYSTEM DISABLE ALL FAILPOINTS는 모든 fail point를 한 번에 비활성화하고 일시 중지 가능한 것에 막힌 모든 스레드를 재개해요. 이름을 취하지 않으며 멱등적이므로, 테스트 하니스는 이전 테스트가 어떤 fail point를 활성화했는지 몰라도 아무것도 주입하지 않는 상태로 서버를 되돌릴 수 있어요. fail point 지원이 없는 빌드에서는 그 문이 성공하고 아무것도 하지 않아요. SYSTEM WAIT FAILPOINT ... PAUSE는 주어진 일시 중지 가능한 fail point에 스레드가 일시 중지될 때까지(또는 fail point가 비활성화될 때까지) 블록하고, ... RESUME은 일시 중지된 스레드가 재개될 때까지 블록하며, SYSTEM NOTIFY FAILPOINT는 fail point를 비활성화하지 않고 일시 중지된 스레드를 재개해요. Fail points는 노드 로컬 상태이므로, 이 문들 중 어떤 것도 ON CLUSTER를 받지 않아요. 모두 SYSTEM FAILPOINT 권한이 필요해요.

더 알아보기 (Learn more)

• DROP TABLE
• ALTER TABLE ... UNFREEZE
• ReplicatedMergeTree