Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

CHECK TABLE

View as MarkdownEdit this pageReport an issueSet up docs MCP

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.

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:

Querysql
CHECK TABLE test_table;
Responsetext
┌─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.

Querysql
CHECK TABLE t0 PARTITION ID '201003'
FORMAT PrettyCompactMonoBlock
SETTINGS check_query_single_value_result = 0
Responsetext
┌─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.

Querysql
CHECK TABLE t0 PART '201003_7_7_0'
FORMAT PrettyCompactMonoBlock
SETTINGS check_query_single_value_result = 0
Responsetext
┌─part_path────┬─is_passed─┬─message─┐
│ 201003_7_7_0 │         1 │         │
└──────────────┴───────────┴─────────┘

Observe que, quando a parte não existe, a consulta retorna um erro:

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

Obtendo um resultado 'Corrompido'

Remova o arquivo de checksum existente:

rm /var/lib/clickhouse-server/data/default/t0/201003_3_3_0/checksums.txt
Querysql
CHECK TABLE t0 PARTITION ID '201003'
FORMAT PrettyCompactMonoBlock
SETTINGS check_query_single_value_result = 0
Responsetext
┌─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 │         │
└──────────┴──────────┴─────────────┴───────────┴─────────┘

Para verificar a saúde de um banco de dados inteiro, em vez da integridade de tabelas individuais, use a consulta CHECK DATABASE. Ela se destina principalmente a bancos de dados com o motor DataLakeCatalog, em que verifica se o catálogo externo está acessível.

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.
Navigation