CHECK TABLE

ClickHouse의 CHECK TABLE 쿼리는 특정 테이블이나 그 파티션에 대한 검증 검사를 수행하는 데 사용돼요. 체크섬과 기타 내부 데이터 구조를 확인하여 데이터의 무결성을 보장합니다.

특히 실제 파일 크기를 서버에 저장된 예상 값과 비교해요. 파일 크기가 저장된 값과 일치하지 않으면 데이터가 손상된 것입니다. 이는 예를 들어 쿼리 실행 중 시스템 크래시로 인해 발생할 수 있어요.

CHECK TABLE 쿼리는 테이블의 모든 데이터를 읽고 일부 리소스를 점유하여 리소스 집약적일 수 있어요. 이 쿼리를 실행하기 전에 성능 및 리소스 사용에 대한 잠재적 영향을 고려하세요. 이 쿼리는 시스템 성능을 향상시키지 않으며, 무엇을 하고 있는지 확신이 없다면 실행하지 않아야 해요.

출처: 문서

본문

Syntax

쿼리의 기본 문법은 다음과 같아요.

CHECK TABLE table_name [PARTITION partition_expression | PART part_name] [FORMAT format] [SETTINGS check_query_single_value_result = (0|1) [, other_settings]]

table_name: 확인하고 싶은 테이블의 이름을 지정해요.
partition_expression: (선택) 테이블의 특정 파티션을 확인하려면 이 표현식으로 파티션을 지정할 수 있어요.
part_name: (선택) 테이블의 특정 파트를 확인하려면 문자열 리터럴로 파트 이름을 지정할 수 있어요.
FORMAT format: (선택) 결과의 출력 형식을 지정할 수 있어요.
SETTINGS: (선택) 추가 설정을 허용해요.

(선택): check_query_single_value_result: 이 설정은 출력이 상세(0)인지 요약(1)인지 제어해요. 다른 설정도 적용할 수 있어요. 결과에 결정론적 순서가 필요하지 않다면, 쿼리를 빠르게 하려고 max_threads를 1보다 큰 값으로 설정할 수 있어요.

쿼리 응답은 check_query_single_value_result 설정의 값에 따라 달라져요. check_query_single_value_result = 1인 경우 단일 행을 가진 result 컬럼만 반환됩니다. 이 행의 값은 무결성 검사가 통과하면 1, 데이터가 손상되었으면 0이에요.

check_query_single_value_result = 0이면 쿼리는 다음 컬럼을 반환해요.

part_path: 데이터 파트 또는 파일 이름의 경로를 나타내요.
is_passed: 이 파트에 대한 검사가 성공하면 1, 그렇지 않으면 0을 반환해요.
message: 오류 또는 성공 메시지 같은 검사와 관련된 추가 메시지.

CHECK TABLE 쿼리는 다음 테이블 엔진을 지원해요.

다른 테이블 엔진의 테이블에 수행하면 NOT_IMPLEMENTED 예외가 발생합니다.

*Log 계열의 엔진은 실패 시 자동 데이터 복구를 제공하지 않아요. CHECK TABLE 쿼리를 사용해 데이터 손실을 시기적절하게 추적하세요.

Examples

기본적으로 CHECK TABLE 쿼리는 일반적인 테이블 검사 상태를 보여줘요.

CHECK TABLE test_table;

┌─result─┐
│      1 │
└────────┘

각 개별 데이터 파트에 대한 검사 상태를 보려면 check_query_single_value_result 설정을 사용할 수 있어요.

또한, 테이블의 특정 파티션을 확인하려고 PARTITION 키워드를 사용할 수 있어요.

CHECK TABLE t0 PARTITION ID '201003'
FORMAT PrettyCompactMonoBlock
SETTINGS check_query_single_value_result = 0

┌─part_path────┬─is_passed─┬─message─┐
│ 201003_7_7_0 │         1 │         │
│ 201003_3_3_0 │         1 │         │
└──────────────┴───────────┴─────────┘

마찬가지로 PART 키워드를 사용해 테이블의 특정 파트를 확인할 수 있어요.

CHECK TABLE t0 PART '201003_7_7_0'
FORMAT PrettyCompactMonoBlock
SETTINGS check_query_single_value_result = 0

┌─part_path────┬─is_passed─┬─message─┐
│ 201003_7_7_0 │         1 │         │
└──────────────┴───────────┴─────────┘

파트가 존재하지 않으면 쿼리는 오류를 반환한다는 점에 유의하세요.

CHECK TABLE t0 PART '201003_111_222_0'

DB::Exception: No such data part '201003_111_222_0' to check in table 'default.t0'. (NO_SUCH_DATA_PART)

Receiving a ‘Corrupted’ Result

면책 조항: 여기 설명된 절차(데이터 디렉터리에서 파일을 직접 수동으로 조작하거나 제거하는 것을 포함)는 실험 또는 개발 환경에서만 사용하기 위한 것이에요. 프로덕션 서버에서는 시도하지 마세요. 데이터 손실이나 기타 의도하지 않은 결과를 초래할 수 있어요.

기존 체크섬 파일을 제거해요.

rm /var/lib/clickhouse-server/data/default/t0/201003_3_3_0/checksums.txt

CHECK TABLE t0 PARTITION ID '201003'
FORMAT PrettyCompactMonoBlock
SETTINGS check_query_single_value_result = 0

┌─part_path────┬─is_passed─┬─message──────────────────────────────────┐
│ 201003_7_7_0 │         1 │                                          │
│ 201003_3_3_0 │         1 │ Checksums recounted and written to disk. │
└──────────────┴───────────┴──────────────────────────────────────────┘

checksums.txt 파일이 없으면 복원될 수 있어요. 특정 파티션에 대한 CHECK TABLE 명령 실행 중에 다시 계산되어 다시 작성되며, 상태는 여전히 'is_passed = 1'로 보고됩니다.

CHECK ALL TABLES 쿼리로 존재하는 모든 (Replicated)MergeTree 테이블을 한 번에 확인할 수 있어요.

CHECK ALL TABLES
FORMAT PrettyCompactMonoBlock
SETTINGS check_query_single_value_result = 0

┌─database─┬─table────┬─part_path───┬─is_passed─┬─message─┐
│ default  │ t2       │ all_1_95_3  │         1 │         │
│ db1      │ table_01 │ all_39_39_0 │         1 │         │
│ default  │ t1       │ all_39_39_0 │         1 │         │
│ db1      │ t1       │ all_39_39_0 │         1 │         │
│ db1      │ table_01 │ all_1_6_1   │         1 │         │
│ default  │ t1       │ all_1_6_1   │         1 │         │
│ db1      │ t1       │ all_1_6_1   │         1 │         │
│ db1      │ table_01 │ all_7_38_2  │         1 │         │
│ db1      │ t1       │ all_7_38_2  │         1 │         │
│ default  │ t1       │ all_7_38_2  │         1 │         │
└──────────┴──────────┴─────────────┴───────────┴─────────┘

개별 테이블의 무결성이 아니라 전체 데이터베이스의 건강 상태를 확인하려면 CHECK DATABASE 쿼리를 사용하세요. 이는 주로 DataLakeCatalog 엔진을 가진 데이터베이스를 위한 것으로, 외부 카탈로그에 접근할 수 있는지 확인해요.

If the Data Is Corrupted

테이블이 손상된 경우 손상되지 않은 데이터를 다른 테이블로 복사할 수 있어요. 이렇게 하려면:

손상된 테이블과 동일한 구조의 새 테이블을 만든다. 이를 위해 CREATE TABLE <new_table_name> AS <damaged_table_name> 쿼리를 실행해요.
다음 쿼리를 단일 스레드로 처리하려고 max_threads 값을 1로 설정한다. 이를 위해 SET max_threads = 1 쿼리를 실행해요.
INSERT INTO <new_table_name> SELECT * FROM <damaged_table_name> 쿼리를 실행한다. 이 요청은 손상된 테이블의 손상되지 않은 데이터를 다른 테이블로 복사해요. 손상된 부분 이전의 데이터만 복사됩니다.
max_threads 값을 재설정하려고 clickhouse-client를 다시 시작한다.

더 알아보기 (Learn more)

CHECK DATABASE