Pular para o conteúdo principal
A consulta CHECK TABLE no ClickHouse é usada para realizar uma verificação em uma tabela específica ou em suas partições. Ela garante a integridade dos dados ao verificar os checksums e outras estruturas internas de dados. Em particular, ela compara os tamanhos reais dos arquivos com os valores esperados armazenados no servidor. Se os tamanhos dos arquivos não corresponderem aos valores armazenados, isso significa que os dados estão corrompidos. Isso pode ser causado, por exemplo, por uma falha do sistema durante a execução da consulta.
A consulta CHECK TABLE pode ler todos os dados da tabela e reter alguns recursos, o que a torna intensiva em termos de recursos. Considere o possível impacto no desempenho e no uso de recursos antes de executar esta consulta. Esta consulta não melhora o desempenho do sistema, e você não deve executá-la se não tiver certeza do que está fazendo.

​
Sintaxe

A sintaxe básica da consulta é a seguinte: 
CHECK TABLE table_name [PARTITION partition_expression | PART part_name] [FORMAT format] [SETTINGS check_query_single_value_result = (0|1) [, other_settings]]
  • table_name: Especifica o nome da tabela que você quer verificar.
  • partition_expression: (Opcional) Se você quiser verificar uma partição específica da tabela, pode usar esta expressão para especificá-la.
  • part_name: (Opcional) Se você quiser verificar uma parte específica da tabela, pode adicionar um literal de string para especificar o nome da parte.
  • FORMAT format: (Opcional) Permite especificar o formato de saída do resultado.
  • SETTINGS: (Opcional) Permite definir configurações adicionais.
    • (Opcional): check_query_single_value_result: Essa configuração controla se a saída será detalhada (0) ou resumida (1).
    • Outras configurações também podem ser aplicadas. Se você não precisar de uma ordem determinística para os resultados, pode definir max_threads como um valor maior que um para acelerar a consulta.
A resposta da consulta depende do valor da configuração check_query_single_value_result. No caso de check_query_single_value_result = 1, apenas a coluna result, com uma única linha, é retornada. O valor nessa linha é 1 se a verificação de integridade for aprovada e 0 se os dados estiverem corrompidos. Com check_query_single_value_result = 0, a consulta retorna as seguintes colunas:
  • part_path: Indica o caminho para a parte de dados ou o nome do arquivo.
    • is_passed: Retorna 1 se a verificação dessa parte for bem-sucedida; caso contrário, retorna 0.
    • message: Quaisquer mensagens adicionais relacionadas à verificação, como erros ou mensagens de sucesso.
A consulta CHECK TABLE oferece suporte aos seguintes motores de tabela: Executá-la em tabelas com outros motores de tabela gera uma exceção NOT_IMPLEMENTED. Os motores da família *Log não oferecem recuperação automática de dados em caso de falha. Use a consulta CHECK TABLE para detectar perda de dados rapidamente.

​
Exemplos

Por padrão, a consulta CHECK TABLE mostra o status geral da verificação da tabela:
Query
CHECK TABLE test_table;
Response
┌─result─┐
│      1 │
└────────┘
Se você quiser ver o status da verificação de cada parte de dados separadamente, pode usar a configuração check_query_single_value_result. Além disso, para verificar uma partição específica da tabela, você pode usar a palavra-chave PARTITION.
Query
CHECK TABLE t0 PARTITION ID '201003'
FORMAT PrettyCompactMonoBlock
SETTINGS check_query_single_value_result = 0
Response
┌─part_path────┬─is_passed─┬─message─┐
│ 201003_7_7_0 │         1 │         │
│ 201003_3_3_0 │         1 │         │
└──────────────┴───────────┴─────────┘
Da mesma forma, você também pode verificar uma parte específica da tabela usando a palavra-chave PART.
Query
CHECK TABLE t0 PART '201003_7_7_0'
FORMAT PrettyCompactMonoBlock
SETTINGS check_query_single_value_result = 0
Response
┌─part_path────┬─is_passed─┬─message─┐
│ 201003_7_7_0 │         1 │         │
└──────────────┴───────────┴─────────┘
Observe que, quando a parte não existe, a consulta retorna um erro:
Query
CHECK TABLE t0 PART '201003_111_222_0'
Response
DB::Exception: No such data part '201003_111_222_0' to check in table 'default.t0'. (NO_SUCH_DATA_PART)

​
Obtendo um resultado ‘Corrompido’

Aviso: o procedimento descrito aqui, incluindo a manipulação manual ou a remoção de arquivos diretamente do diretório de dados, destina-se apenas a ambientes experimentais ou de desenvolvimento. Não tente fazer isso em um servidor de produção, pois isso pode levar à perda de dados ou a outras consequências indesejadas.
Remova o arquivo de checksum existente: 
rm /var/lib/clickhouse-server/data/default/t0/201003_3_3_0/checksums.txt
Query
CHECK TABLE t0 PARTITION ID '201003'
FORMAT PrettyCompactMonoBlock
SETTINGS check_query_single_value_result = 0
Response
┌─part_path────┬─is_passed─┬─message──────────────────────────────────┐
│ 201003_7_7_0 │         1 │                                          │
│ 201003_3_3_0 │         1 │ Checksums recounted and written to disk. │
└──────────────┴───────────┴──────────────────────────────────────────┘
Se o arquivo checksums.txt estiver ausente, ele poderá ser restaurado. Ele será recalculado e gravado novamente durante a execução do comando CHECK TABLE para a partição específica, e o status continuará sendo informado como ‘is_passed = 1’. Você pode verificar de uma só vez todas as tabelas (Replicated)MergeTree existentes usando a consulta CHECK ALL TABLES. 
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 │         │
└──────────┴──────────┴─────────────┴───────────┴─────────┘

​
Se os dados estiverem corrompidos

Se a tabela estiver corrompida, você pode copiar os dados não corrompidos para outra tabela. Para isso:
  1. Crie uma nova tabela com a mesma estrutura da tabela danificada. Para isso, execute a consulta CREATE TABLE <new_table_name> AS <damaged_table_name>.
  2. Defina o valor de max_threads como 1 para processar a próxima consulta em uma única thread. Para isso, execute a consulta SET max_threads = 1.
  3. Execute a consulta INSERT INTO <new_table_name> SELECT * FROM <damaged_table_name>. Esse comando copia os dados não corrompidos da tabela danificada para outra tabela. Apenas os dados anteriores à parte corrompida serão copiados.
  4. Reinicie o clickhouse-client para redefinir o valor de max_threads.
Última modificação em 10 de junho de 2026