- ADD COLUMN — Adiciona uma nova coluna à tabela.
- DROP COLUMN — Exclui a coluna.
- RENAME COLUMN — Renomeia uma coluna existente.
- CLEAR COLUMN — Redefine os valores da coluna.
- COMMENT COLUMN — Adiciona um comentário de texto à coluna.
- MODIFY COLUMN — Altera o tipo da coluna, a expressão padrão, o TTL e as configurações da coluna.
- MODIFY COLUMN REMOVE — Remove uma das propriedades da coluna.
- MODIFY COLUMN MODIFY SETTING - Altera as configurações da coluna.
- MODIFY COLUMN RESET SETTING - Redefine as configurações da coluna.
- MATERIALIZE COLUMN — Materializa a coluna nas partes em que ela está ausente. Essas ações são descritas em detalhes abaixo.
ADD COLUMN
name, type, codec e default_expr especificados (consulte a seção Expressões padrão).
Se a cláusula IF NOT EXISTS estiver incluída, a consulta não retornará erro se a coluna já existir. Se você especificar AFTER name_after (o nome de outra coluna), a coluna será adicionada depois da coluna especificada na lista de colunas da tabela. Se quiser adicionar uma coluna no início da tabela, use a cláusula FIRST. Caso contrário, a coluna será adicionada ao final da tabela. Em uma cadeia de ações, name_after pode ser o nome de uma coluna adicionada em uma das ações anteriores.
Adicionar uma coluna apenas altera a estrutura da tabela, sem executar nenhuma ação sobre os dados. Os dados não são gravados em disco após ALTER. Se não houver dados para uma coluna ao ler da tabela, ela será preenchida com valores padrão (executando a expressão padrão, se houver, ou usando zeros ou strings vazias). A coluna passa a aparecer no disco após a mesclagem das partes de dados (consulte MergeTree).
Essa abordagem permite concluir a consulta ALTER instantaneamente, sem aumentar o volume dos dados antigos.
Exemplo:
DROP COLUMN
name. Se a cláusula IF EXISTS for especificada, a consulta não retornará erro se a coluna não existir.
Exclui dados do sistema de arquivos. Como isso remove arquivos inteiros, a consulta é concluída quase instantaneamente.
Exemplo:
RENAME COLUMN
name para new_name. Se a cláusula IF EXISTS for especificada, a consulta não retornará erro se a coluna não existir. Como a renomeação não envolve os dados subjacentes, a consulta é concluída quase instantaneamente.
NOTA: As colunas especificadas na expressão de chave da tabela (seja com ORDER BY ou PRIMARY KEY) não podem ser renomeadas. Tentar alterar essas colunas resultará em SQL Error [524].
Exemplo:
CLEAR COLUMN
IF EXISTS for especificada, a consulta não retornará erro se a coluna não existir.
Exemplo:
COMMENT COLUMN
IF EXISTS for especificada, a consulta não retornará erro se a coluna não existir.
Cada coluna pode ter um comentário. Se já houver um comentário para a coluna, um novo comentário substituirá o anterior.
Os comentários são armazenados na coluna comment_expression retornada pela consulta DESCRIBE TABLE.
Exemplo:
MODIFY COLUMN
name:
- Tipo
- Expressão padrão
- Codec de compressão
- TTL
- Configurações no nível da coluna
IF EXISTS for especificada, a consulta não retornará erro se a coluna não existir.
Ao alterar o tipo, os valores são convertidos como se as funções toType tivessem sido aplicadas a eles. Se apenas a expressão padrão for alterada, a consulta não faz nada complexo e é concluída quase instantaneamente.
Exemplo:
FIRST | AFTER; veja a descrição de ADD COLUMN, mas, nesse caso, o tipo da coluna é obrigatório.
Exemplo:
ALTER é atômica. Para tabelas MergeTree, ela também não requer bloqueios.
A consulta ALTER para alterar colunas é replicada. As instruções são salvas no ZooKeeper e, em seguida, cada réplica as aplica. Todas as consultas ALTER são executadas na mesma ordem. A consulta aguarda a conclusão das ações apropriadas nas outras réplicas. No entanto, uma consulta para alterar colunas em uma tabela replicada pode ser interrompida, e todas as ações serão executadas de forma assíncrona.
Tenha cuidado ao alterar uma coluna Nullable para Non-Nullable. Certifique-se de que ela não contenha nenhum valor NULL; caso contrário, isso causará problemas na leitura. Nesse caso, a solução alternativa seria interromper a mutação e reverter a coluna para o tipo Nullable.
MODIFY COLUMN REMOVE
DEFAULT, ALIAS, MATERIALIZED, CODEC, COMMENT, TTL, SETTINGS.
Sintaxe:
MODIFY COLUMN MODIFY SETTING
max_compress_block_size da coluna para 1MB:
MODIFY COLUMN RESET SETTING
max_compress_block_size para o valor padrão:
MATERIALIZE COLUMN
DEFAULT ou MATERIALIZED. Ao adicionar uma coluna materializada usando ALTER TABLE table_name ADD COLUMN column_name MATERIALIZED, as linhas existentes sem valores materializados não são preenchidas automaticamente. A instrução MATERIALIZE COLUMN pode ser usada para reescrever os dados existentes da coluna após a adição ou atualização de uma expressão DEFAULT ou MATERIALIZED (o que atualiza apenas os metadados, mas não altera os dados existentes). Observe que materializar uma coluna na chave de ordenação é uma operação inválida, pois isso pode quebrar a ordenação.
Implementado como uma mutação.
Para colunas com uma expressão de valor MATERIALIZED nova ou atualizada, todas as linhas existentes são reescritas.
Para colunas com uma expressão de valor DEFAULT nova ou atualizada, o comportamento depende da versão do ClickHouse:
- No ClickHouse < v24.2, todas as linhas existentes são reescritas.
- O ClickHouse >= v24.2 distingue se o valor de uma linha em uma coluna com expressão de valor
DEFAULTfoi especificado explicitamente no momento da inserção ou não, ou seja, se foi calculado a partir da expressão de valorDEFAULT. Se o valor foi especificado explicitamente, o ClickHouse o mantém como está. Se o valor foi calculado, o ClickHouse o altera para a expressão de valorMATERIALIZEDnova ou atualizada.
- Se você especificar uma PARTITION, uma coluna será materializada somente para a partição especificada.
Limitações
ALTER permite criar e excluir elementos individuais (colunas) em estruturas de dados aninhadas, mas não estruturas de dados aninhadas inteiras. Para adicionar uma estrutura de dados aninhada, você pode adicionar colunas com um nome como name.nested_name e o tipo Array(T). Uma estrutura de dados aninhada equivale a várias colunas de array com nomes que têm o mesmo prefixo antes do ponto.
A renomeação de colunas com pontos no nome tem suporte parcial. Os pontos são reservados para acesso a subcolunas de Nested, portanto o prefixo (nome pai) deve permanecer o mesmo. Apenas o sufixo (nome da subcoluna) pode ser alterado. Por exemplo, a.b pode ser renomeado para a.c, mas renomear a.b para b.d não é permitido porque isso altera o prefixo pai de Nested.
Não há suporte para excluir colunas da chave primária ou da chave de amostragem (colunas usadas na expressão ENGINE). Alterar o tipo de colunas incluídas na chave primária só é possível se essa mudança não fizer com que os dados sejam modificados (por exemplo, é permitido adicionar valores a um Enum ou alterar um tipo de DateTime para UInt32).
Se a consulta ALTER não for suficiente para fazer as alterações na tabela de que você precisa, você pode criar uma nova tabela, copiar os dados para ela usando a consulta INSERT SELECT, depois trocar as tabelas usando a consulta RENAME e excluir a tabela antiga.
A consulta ALTER bloqueia todas as leituras e escritas da tabela. Em outras palavras, se um SELECT demorado estiver em execução no momento da consulta ALTER, a consulta ALTER aguardará sua conclusão. Ao mesmo tempo, todas as novas consultas para a mesma tabela ficarão aguardando enquanto esse ALTER estiver em execução.
Para tabelas que não armazenam dados por si mesmas (como Merge e Distributed), ALTER apenas altera a estrutura da tabela e não altera a estrutura das tabelas subordinadas. Por exemplo, ao executar ALTER em uma tabela Distributed, você também precisará executar ALTER nas tabelas em todos os servidores remotos.