ALTER TABLE ... COLUMN

Um conjunto de consultas que permite alterar a estrutura da tabela.

Sintaxe:

ALTER [TEMPORARY] TABLE [db].name [ON CLUSTER cluster] ADD|DROP|RENAME|CLEAR|COMMENT|{MODIFY|ALTER}|MATERIALIZE COLUMN ...

Na consulta, especifique uma lista de uma ou mais ações separadas por vírgulas. Cada ação é uma operação sobre uma coluna.

As seguintes ações são suportadas:

• 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.
• MODIFY COLUMN ADD ENUM VALUES - Adiciona novos valores ao Enum.
• MATERIALIZE COLUMN — Materializa a coluna nas partes em que ela está ausente. Essas ações são descritas em detalhes abaixo.

ADD COLUMN [IF NOT EXISTS] name [type] [default_expr] [COMMENT 'comment for column'] [codec] [STATISTICS] [TTL] [settings] [AFTER name_after | FIRST]

Adiciona uma nova coluna à tabela com name, type, codec e default_expr especificados (consulte a seção Expressões padrão). Os modificadores que seguem o tipo podem ser escritos em qualquer ordem, e cada um deles no máximo uma vez — consulte descrição da coluna.

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:

ALTER TABLE alter_test ADD COLUMN Added1 UInt32 FIRST;
ALTER TABLE alter_test ADD COLUMN Added2 UInt32 AFTER NestedColumn;
ALTER TABLE alter_test ADD COLUMN Added3 UInt32 AFTER ToDrop;
DESC alter_test FORMAT TSV;

Added1  UInt32
CounterID       UInt32
StartDate       Date
UserID  UInt32
VisitID UInt32
NestedColumn.A  Array(UInt8)
NestedColumn.S  Array(String)
Added2  UInt32
ToDrop  UInt32
Added3  UInt32

DROP COLUMN [IF EXISTS] name

Exclui a coluna com o nome 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:

ALTER TABLE visits DROP COLUMN browser

RENAME COLUMN [IF EXISTS] name to new_name

Renomeia a coluna 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:

ALTER TABLE visits RENAME COLUMN webBrowser TO browser

CLEAR COLUMN [IF EXISTS] name IN PARTITION partition_name

Redefine todos os dados de uma coluna na partição especificada. Leia mais sobre como definir o nome da partição na seção Como definir a expressão da partição.

Se a cláusula IF EXISTS for especificada, a consulta não retornará erro se a coluna não existir.

Exemplo:

ALTER TABLE visits CLEAR COLUMN browser IN PARTITION tuple()

COMMENT COLUMN [IF EXISTS] name 'Text comment'

Adiciona um comentário à coluna. Se a cláusula 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:

ALTER TABLE visits COMMENT COLUMN browser 'This column shows the browser used for accessing the site.'

MODIFY COLUMN [IF EXISTS] name
    [type] [default_expr] [COMMENT 'comment for column'] [codec] [STATISTICS] [TTL] [settings] [AFTER name_after | FIRST]
    | ADD ENUM VALUES ( 'name' [= number] [, ...] )
ALTER COLUMN [IF EXISTS] name
    TYPE [type] [default_expr] [COMMENT 'comment for column'] [codec] [STATISTICS] [TTL] [settings] [AFTER name_after | FIRST]
    | ADD ENUM VALUES ( 'name' [= number] [, ...] )

Os modificadores que seguem o tipo podem ser escritos em qualquer ordem, e cada um deles no máximo uma vez — consulte a descrição da coluna.

Esta consulta altera as propriedades da coluna name:

• Tipo

• Expressão padrão

• Codec de compressão

• TTL

• Configurações no nível da coluna

• Valores de enum para os tipos Enum/Enum8/Enum16

Para ver exemplos de modificação de CODECS de compressão de colunas, consulte Column Compression Codecs.

Para ver exemplos de modificação de TTL de colunas, consulte Column TTL.

Para ver exemplos de modificação de configurações no nível da coluna, consulte Column-level Settings.

Se a cláusula 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:

ALTER TABLE visits MODIFY COLUMN browser Array(String)

Alterar o tipo da coluna é a única ação complexa — isso modifica o conteúdo dos arquivos de dados. Em tabelas grandes, isso pode levar bastante tempo.

A consulta também pode alterar a ordem das colunas usando a cláusula FIRST | AFTER; veja a descrição de ADD COLUMN, mas, nesse caso, o tipo da coluna é obrigatório.

Exemplo:

CREATE TABLE users (
    c1 Int16,
    c2 String
) ENGINE = MergeTree
ORDER BY c1;

DESCRIBE users;
┌

A consulta 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.

Remove uma das propriedades da coluna: DEFAULT, ALIAS, MATERIALIZED, CODEC, COMMENT, TTL, SETTINGS.

Sintaxe:

ALTER TABLE table_name MODIFY COLUMN column_name REMOVE property;

Exemplo

Remova o TTL:

ALTER TABLE table_with_ttl MODIFY COLUMN column_ttl REMOVE TTL;

Veja também

• REMOVE TTL.

Modifica uma configuração de coluna.

Sintaxe:

ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING name=value,...;

Exemplo

Altere max_compress_block_size da coluna para 1MB:

ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING max_compress_block_size = 1048576;

Redefine uma configuração de coluna; isso também remove a declaração da configuração na expressão da coluna da consulta CREATE da tabela.

Sintaxe:

ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING name,...;

Exemplo

Restaure a configuração da coluna max_compress_block_size para o valor padrão:

ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING max_compress_block_size;

Adiciona novos valores a uma coluna do tipo Enum, Enum8, Enum16, Nullable(Enum), Nullable(Enum8) ou Nullable(Enum16)

Sintaxe:

ALTER TABLE table_name MODIFY COLUMN enum_column_name ADD ENUM VALUES ('EnumName' [= number], ...);

Exemplo

Adicione dois valores à coluna enum_column_name:

ALTER TABLE table_name MODIFY COLUMN enum_column_name ADD ENUM VALUES ('Hundred' = 100, 'HundredOne');

Materializa uma coluna com uma expressão de valor 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 DEFAULT foi especificado explicitamente no momento da inserção ou não, ou seja, se foi calculado a partir da expressão de valor DEFAULT. 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 valor MATERIALIZED nova ou atualizada.

Sintaxe:

ALTER TABLE [db.]table [ON CLUSTER cluster] MATERIALIZE COLUMN col [IN PARTITION partition | IN PARTITION ID 'partition_id'];

• Se você especificar uma PARTITION, uma coluna será materializada somente para a partição especificada.

Exemplo

DROP TABLE IF EXISTS tmp;
SET mutations_sync = 2;
CREATE TABLE tmp (x Int64) ENGINE = MergeTree() ORDER BY tuple() PARTITION BY tuple();
INSERT INTO tmp SELECT * FROM system.numbers LIMIT 5;
ALTER TABLE tmp ADD COLUMN s String MATERIALIZED toString(x);

ALTER TABLE tmp MATERIALIZE COLUMN s;

SELECT groupArray(x), groupArray(s) FROM (select x,s from tmp order by x);

┌

Consulte também

• MATERIALIZED.
• MATERIALIZE INDEX.

A consulta 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.