Manipulação de partições e partes

Documentação sobre PARTITION

As seguintes operações com partições estão disponíveis:

• DETACH PARTITION|PART — Move uma partição ou parte para o diretório detached e deixa de reconhecê-la.
• DROP PARTITION|PART — Exclui uma partição ou parte.
• DROP DETACHED PARTITION|PART - Exclui uma parte ou todas as partes de uma partição em detached.
• FORGET PARTITION — Exclui os metadados de uma partição do ZooKeeper se ela estiver vazia.
• ATTACH PARTITION|PART — Adiciona à tabela uma partição ou parte do diretório detached.
• ATTACH PARTITION FROM — Copia a partição de dados de uma tabela para outra e a adiciona.
• REPLACE PARTITION — Copia a partição de dados de uma tabela para outra e a substitui.
• MOVE PARTITION TO TABLE — Move a partição de dados de uma tabela para outra.
• CLEAR COLUMN IN PARTITION — Redefine o valor de uma coluna especificada em uma partição.
• CLEAR INDEX IN PARTITION — Redefine o índice secundário especificado em uma partição.
• FREEZE PARTITION — Cria um backup de uma partição.
• UNFREEZE PARTITION — Remove um backup de uma partição.
• FETCH PARTITION|PART — Baixa uma parte ou partição de outro servidor.
• MOVE PARTITION|PART — Move a partição/parte de dados para outro disco ou volume.
• UPDATE IN PARTITION — Atualiza os dados dentro da partição com base em uma condição.
• DELETE IN PARTITION — Exclui os dados dentro da partição com base em uma condição.
• REWRITE PARTS — Reescreve completamente as partes da tabela (ou de uma partição específica).

​

DETACH PARTITION|PART

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

Move todos os dados da partição especificada para o diretório detached. O servidor deixa de considerar a partição de dados movida para detached, como se ela não existisse. O servidor não reconhecerá esses dados até que você execute a consulta ATTACH.

Exemplo:

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

Leia sobre como definir a expressão de partição na seção Como definir a expressão de partição.

Depois que a consulta for executada, você poderá fazer o que quiser com os dados no diretório detached — excluí-los do sistema de arquivos ou simplesmente deixá-los lá.

Esta consulta é replicada — ela move os dados para o diretório detached em todas as réplicas. Observe que essa consulta só pode ser executada em uma réplica líder. Para verificar se uma réplica é líder, execute a consulta SELECT na tabela system.replicas. Como alternativa, é mais fácil executar uma consulta DETACH em todas as réplicas — todas elas lançam uma exceção, exceto as réplicas líderes (já que vários líderes são permitidos).

​

DROP PARTITION|PART

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

Exclui a partição especificada da tabela. Esta consulta marca a partição como inativa e exclui completamente os dados em aproximadamente 10 minutos.

Leia sobre como definir a expressão de partição na seção Como definir a expressão de partição.

A consulta é replicada — ela exclui os dados em todas as réplicas.

Exemplo:

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

Remove a parte especificada ou todas as partes da partição especificada de detached. Leia mais sobre como definir a expressão de partição na seção Como definir a expressão de partição.

​

FORGET PARTITION

ALTER TABLE table_name FORGET PARTITION partition_expr

Remove todos os metadados de uma partição vazia do ZooKeeper. A consulta falha se a partição não estiver vazia ou não for reconhecida. Certifique-se de executar isso apenas para partições que nunca mais serão usadas.

Leia sobre como definir a expressão de partição na seção Como definir a expressão de partição.

Exemplo:

ALTER TABLE mt FORGET PARTITION '20201121';

​

ATTACH PARTITION|PART

ALTER TABLE table_name ATTACH PARTITION|PART partition_expr

Adiciona dados à tabela a partir do diretório detached. É possível adicionar dados de uma partição inteira ou de uma parte individual. Exemplos:

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

Leia mais sobre como definir a expressão de partição na seção Como definir a expressão de partição.

Esta consulta é replicada. A réplica iniciadora verifica se há dados no diretório detached. Se houver dados, a consulta verifica a integridade deles. Se tudo estiver correto, a consulta adiciona os dados à tabela.

Se a réplica não iniciadora, ao receber o comando ATTACH, encontrar a parte com as somas de verificação corretas em seu próprio diretório detached, ela anexa os dados sem precisar buscá-los em outras réplicas. Se não houver uma parte com as somas de verificação corretas, os dados serão baixados de qualquer réplica que tenha essa parte.

Você pode colocar dados no diretório detached em uma réplica e usar a consulta ALTER ... ATTACH para adicioná-los à tabela em todas as réplicas.

​

ATTACH PARTITION FROM

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

Esta consulta copia a partição de dados de table1 para table2.

Observe que:

• Os dados não serão excluídos nem de table1 nem de table2.
• table1 pode ser uma tabela temporária.

Para que a consulta seja executada com sucesso, as seguintes condições devem ser atendidas:

• Ambas as tabelas devem ter a mesma estrutura.
• Ambas as tabelas devem ter a mesma chave de partição, a mesma chave ORDER BY e a mesma chave primária.
• Ambas as tabelas devem ter a mesma política de armazenamento.
• A tabela de destino deve incluir todos os índices e projeções da tabela de origem. Se a configuração enforce_index_structure_match_on_partition_manipulation estiver habilitada na tabela de destino, os índices e as projeções deverão ser idênticos. Caso contrário, a tabela de destino pode ter um conjunto que inclua todos os índices e projeções da tabela de origem, além de outros.

​

REPLACE PARTITION

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

Esta consulta copia a partição de dados de table1 para table2 e substitui a partição existente em table2. A operação é atômica.

Observe que:

• Os dados não serão excluídos de table1.
• table1 pode ser uma tabela temporária.

Para que a consulta seja executada com sucesso, as seguintes condições devem ser atendidas:

• Ambas as tabelas devem ter a mesma estrutura.
• Ambas as tabelas devem ter a mesma chave de partição, a mesma chave ORDER BY e a mesma chave primária.
• Ambas as tabelas devem ter a mesma política de armazenamento.
• A tabela de destino deve incluir todos os índices e projeções da tabela de origem. Se a configuração enforce_index_structure_match_on_partition_manipulation estiver habilitada na tabela de destino, os índices e as projeções deverão ser idênticos. Caso contrário, a tabela de destino pode conter um superconjunto dos índices e das projeções da tabela de origem.

​

MOVE PARTITION TO TABLE

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

Esta consulta move a partição de dados de table_source para table_dest, excluindo os dados de table_source.

Para que a consulta seja executada com sucesso, as seguintes condições devem ser atendidas:

• Ambas as tabelas devem ter a mesma estrutura.
• Ambas as tabelas devem ter a mesma chave de partição, a mesma chave ORDER BY e a mesma chave primária.
• Ambas as tabelas devem ter a mesma política de armazenamento.
• Ambas as tabelas devem pertencer à mesma família de engines (replicada ou não replicada).
• A tabela de destino deve incluir todos os índices e projeções da tabela de origem. Se a configuração enforce_index_structure_match_on_partition_manipulation estiver habilitada na tabela de destino, os índices e as projeções deverão ser idênticos. Caso contrário, a tabela de destino poderá ter um superconjunto dos índices e das projeções da tabela de origem.

​

CLEAR COLUMN IN PARTITION

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

Redefine todos os valores da coluna especificada em uma partição. Se a cláusula DEFAULT tiver sido definida ao criar a tabela, esta consulta define o valor da coluna para o valor padrão especificado.

Exemplo:

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']

Esta consulta cria um backup local de uma partição especificada. Se a cláusula PARTITION for omitida, a consulta criará o backup de todas as partições de uma só vez.

Todo o processo de backup é realizado sem interromper o servidor.

Observe que, em tabelas no formato antigo, você pode especificar o prefixo do nome da partição (por exemplo, 2019) — nesse caso, a consulta cria o backup de todas as partições correspondentes. Leia sobre como definir a expressão de partição na seção Como definir a expressão de partição.

No momento da execução, para criar um snapshot dos dados, a consulta cria hardlinks para os dados da tabela. Os hardlinks são colocados no diretório /var/lib/clickhouse/shadow/N/..., onde:

• /var/lib/clickhouse/ é o diretório de trabalho do ClickHouse especificado na configuração.
• N é o número incremental do backup.
• se o parâmetro WITH NAME for especificado, então o valor do parâmetro 'backup_name' será usado em vez do número incremental.

Se você usar um conjunto de discos para armazenamento de dados em uma tabela, o diretório shadow/N aparecerá em cada disco, armazenando as partes de dados correspondentes à expressão PARTITION.

A mesma estrutura de diretórios existente em /var/lib/clickhouse/ é criada dentro do backup. A consulta executa chmod em todos os arquivos, impedindo a gravação neles.

Depois de criar o backup, você pode copiar os dados de /var/lib/clickhouse/shadow/ para o servidor remoto e, em seguida, excluí-los do servidor local. Observe que a consulta ALTER t FREEZE PARTITION não é replicada. Ela cria um backup local apenas no servidor local.

A consulta cria o backup quase instantaneamente (mas primeiro aguarda a conclusão das consultas em andamento na tabela correspondente).

ALTER TABLE t FREEZE PARTITION copia apenas os dados, não os metadados da tabela. Para fazer um backup dos metadados da tabela, copie o arquivo /var/lib/clickhouse/metadata/database/table.sql

Para restaurar dados de um backup, faça o seguinte:

1. Crie a tabela, se ela ainda não existir. Para ver a consulta, use o arquivo .sql (substitua ATTACH nele por CREATE).
2. Copie os dados do diretório data/database/table/ dentro do backup para o diretório /var/lib/clickhouse/data/database/table/detached/.
3. Execute consultas ALTER TABLE t ATTACH PARTITION para adicionar os dados à tabela.

A restauração a partir de um backup não exige interromper o servidor.

A consulta processa partes em paralelo, e o número de threads é controlado pela configuração max_threads.

Para mais informações sobre backups e restauração de dados, consulte a seção “Backup e restauração no ClickHouse”.

​

UNFREEZE PARTITION

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

Remove do disco as partições frozen com o nome especificado. Se a cláusula PARTITION for omitida, a consulta remove o backup de todas as partições de uma só vez.

​

CLEAR INDEX IN PARTITION

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

A consulta funciona de forma semelhante a CLEAR COLUMN, mas reinicializa um índice em vez dos dados de uma coluna.

​

FETCH PARTITION|PART

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

Baixa uma partição de outro servidor. Esta consulta só funciona com tabelas replicadas.

A consulta faz o seguinte:

1. Baixa a partição|parte do shard especificado. Em ‘path-in-zookeeper’, você deve especificar o caminho para o shard no ZooKeeper.
2. Em seguida, a consulta coloca os dados baixados no diretório detached da tabela table_name. Use a consulta ATTACH PARTITION|PART para adicionar os dados à tabela.

Por exemplo:

1. FETCH PARTITION

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

2. 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;

Observe que:

• A consulta ALTER ... FETCH PARTITION|PART não é replicada. Ela coloca a parte ou partição no diretório detached apenas no servidor local.
• A consulta ALTER TABLE ... ATTACH é replicada. Ela adiciona os dados a todas as réplicas. Os dados são adicionados a uma das réplicas a partir do diretório detached e, às demais, a partir das réplicas vizinhas.

Antes do download, o sistema verifica se a partição existe e se a estrutura da tabela é compatível. A réplica mais adequada é selecionada automaticamente entre as réplicas saudáveis.

Embora a consulta se chame ALTER TABLE, ela não altera a estrutura da tabela nem modifica imediatamente os dados disponíveis na tabela.

​

MOVE PARTITION|PART

Move partições ou partes de dados para outro volume ou disco em tabelas com motor MergeTree. Consulte Uso de vários dispositivos de bloco para armazenamento de dados.

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

A consulta ALTER TABLE t MOVE:

• Não é replicada, porque diferentes réplicas podem ter políticas de armazenamento diferentes.
• Retorna um erro se o disco ou volume especificado não estiver configurado. A consulta também retorna um erro se não for possível aplicar as condições de movimentação de dados especificadas na política de armazenamento.
• Pode retornar um erro caso os dados a serem movidos já tenham sido movidos por um processo em segundo plano, por uma consulta ALTER TABLE t MOVE concorrente ou como resultado da mesclagem de dados em segundo plano. O usuário não deve executar nenhuma ação adicional nesse caso.

Exemplo:

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

Manipula os dados da partição especificada que correspondem à expressão de filtro informada. É implementado como uma mutação.

Sintaxe:

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

​

Exemplo

-- usando o nome da partição
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION 2 WHERE p = 2;

-- usando o ID da partição
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION ID '2' WHERE p = 2;

​

Veja também

• UPDATE

​

DELETE IN PARTITION

Exclui dados na partição especificada que correspondem à expressão de filtro especificada. Implementado como uma mutação.

Sintaxe:

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

​

Exemplo

-- usando nome da partição
ALTER TABLE mt DELETE IN PARTITION 2 WHERE p = 2;

-- usando id da partição
ALTER TABLE mt DELETE IN PARTITION ID '2' WHERE p = 2;

​

REWRITE PARTS

Isso reescreverá as partes do zero, usando todas as novas configurações. Isso faz sentido porque configurações no nível da tabela, como use_const_adaptive_granularity, por padrão só são aplicadas a partes recém-escritas.

​

Exemplo

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

​

Veja também

• DELETE

​

Como definir a expressão de partição

Você pode especificar a expressão de partição em consultas ALTER ... PARTITION de diferentes maneiras:

• Como um valor da coluna partition da tabela system.parts. Por exemplo, ALTER TABLE visits DETACH PARTITION 201901.
• Usando a palavra-chave ALL. Ela só pode ser usada com DROP/DETACH/ATTACH/ATTACH FROM. Por exemplo, ALTER TABLE visits ATTACH PARTITION ALL.
• Como uma tupla de expressões ou constantes que corresponda (em tipos) à tupla da chave de particionamento da tabela. No caso de uma chave de particionamento com um único elemento, a expressão deve ser envolvida na função tuple (...). Por exemplo, ALTER TABLE visits DETACH PARTITION tuple(toYYYYMM(toDate('2019-01-25'))).
• Usando o ID da partição. O ID da partição é um identificador de string da partição (legível para humanos, quando possível) usado como nome das partições no sistema de arquivos e no ZooKeeper. O ID da partição deve ser especificado na cláusula PARTITION ID, entre aspas simples. Por exemplo, ALTER TABLE visits DETACH PARTITION ID '201901'.
• Na consulta ALTER ATTACH PART e DROP DETACHED PART, para especificar o nome de uma parte, use um literal de string com um valor da coluna name da tabela system.detached_parts. Por exemplo, ALTER TABLE visits ATTACH PART '201901_1_1_0'.

O uso de aspas ao especificar a partição depende do tipo da expressão de partição. Por exemplo, para o tipo String, você precisa especificar o nome entre aspas ('). Para os tipos Date e Int*, não é necessário usar aspas.

Todas as regras acima também valem para a consulta OPTIMIZE. Se você precisar especificar a única partição ao otimizar uma tabela sem particionamento, defina a expressão PARTITION tuple(). Por exemplo:

OPTIMIZE TABLE table_not_partitioned PARTITION tuple() FINAL;

IN PARTITION especifica a partição à qual as expressões UPDATE ou DELETE são aplicadas como resultado da consulta ALTER TABLE. Novas partes são criadas apenas a partir da partição especificada. Dessa forma, IN PARTITION ajuda a reduzir a carga quando a tabela é dividida em muitas partições e você só precisa atualizar os dados de forma pontual.

Exemplos de consultas ALTER ... PARTITION são mostrados nos testes 00502_custom_partitioning_local e 00502_custom_partitioning_replicated_zookeeper.