ALTER TABLE ... COLUMN

Un conjunto de consultas que permiten modificar la estructura de la tabla.

Sintaxis:

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

En la consulta, especifique una lista de una o más acciones separadas por comas. Cada acción es una operación sobre una columna.

Se admiten las siguientes acciones:

• ADD COLUMN — Agrega una nueva columna a la tabla.
• DROP COLUMN — Elimina la columna.
• RENAME COLUMN — Cambia el nombre de una columna existente.
• CLEAR COLUMN — Restablece los valores de la columna.
• COMMENT COLUMN — Agrega un comentario de texto a la columna.
• MODIFY COLUMN — Cambia el tipo de la columna, la expresión predeterminada, el TTL y la configuración de la columna.
• MODIFY COLUMN REMOVE — Elimina una de las propiedades de la columna.
• MODIFY COLUMN MODIFY SETTING - Cambia la configuración de la columna.
• MODIFY COLUMN RESET SETTING - Restablece la configuración de la columna.
• MODIFY COLUMN ADD ENUM VALUES - Agrega nuevos valores a Enum.
• MATERIALIZE COLUMN — Materializa la columna en las partes donde no existe. Estas acciones se describen en detalle a continuación.

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

Agrega una nueva columna a la tabla con los name, type, codec y default_expr especificados (consulte la sección Expresiones predeterminadas). Los modificadores que siguen al tipo pueden escribirse en cualquier orden y cada uno de ellos como máximo una vez; consulte la descripción de columna.

Si se incluye la cláusula IF NOT EXISTS, la consulta no devolverá ningún error si la columna ya existe. Si especifica AFTER name_after (el nombre de otra columna), la columna se agrega después de la indicada en la lista de columnas de la tabla. Si quiere agregar una columna al principio de la tabla, use la cláusula FIRST. De lo contrario, la columna se agrega al final de la tabla. En una cadena de acciones, name_after puede ser el nombre de una columna que se agrega en una de las acciones anteriores.

Agregar una columna solo cambia la estructura de la tabla, sin realizar ninguna acción sobre los datos. Los datos no se guardan en disco después de ALTER. Si faltan datos para una columna al leer la tabla, se completan con valores predeterminados (ejecutando la expresión predeterminada si existe, o usando ceros o cadenas vacías). La columna aparece en disco después de fusionar las partes de datos (consulte MergeTree).

Este enfoque permite completar la consulta ALTER al instante, sin aumentar el volumen de los datos antiguos.

Ejemplo:

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

Elimina la columna con el nombre name. Si se especifica la cláusula IF EXISTS, la consulta no devolverá ningún error si la columna no existe.

Elimina datos del sistema de archivos. Como esto elimina archivos completos, la consulta se completa casi al instante.

Ejemplo:

ALTER TABLE visits DROP COLUMN browser

RENAME COLUMN [IF EXISTS] name to new_name

Cambia el nombre de la columna name a new_name. Si se especifica la cláusula IF EXISTS, la consulta no devolverá un error si la columna no existe. Como el cambio de nombre no afecta a los datos subyacentes, la consulta se completa casi al instante.

NOTA: Las columnas especificadas en la expresión de clave de la tabla (ya sea con ORDER BY o PRIMARY KEY) no se pueden renombrar. Si se intenta cambiar estas columnas, se producirá SQL Error [524].

Ejemplo:

ALTER TABLE visits RENAME COLUMN webBrowser TO browser

CLEAR COLUMN [IF EXISTS] name IN PARTITION partition_name

Restablece todos los datos de una columna en una partición especificada. Lea más sobre cómo establecer el nombre de la partición en la sección Cómo establecer la expresión de partición.

Si se especifica la cláusula IF EXISTS, la consulta no devolverá ningún error si la columna no existe.

Ejemplo:

ALTER TABLE visits CLEAR COLUMN browser IN PARTITION tuple()

COMMENT COLUMN [IF EXISTS] name 'Text comment'

Agrega un comentario a la columna. Si se especifica la cláusula IF EXISTS, la consulta no devolverá ningún error si la columna no existe.

Cada columna puede tener un solo comentario. Si la columna ya tiene un comentario, el nuevo comentario sobrescribe el anterior.

Los comentarios se almacenan en la columna comment_expression que devuelve la consulta DESCRIBE TABLE.

Ejemplo:

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] [, ...] )

Los modificadores que siguen al tipo pueden escribirse en cualquier orden, y cada uno de ellos como máximo una vez; consulte la descripción de columna.

Esta consulta cambia las propiedades de la columna name:

• Tipo

• Expresión predeterminada

• Códec de compresión

• TTL

• Configuración a nivel de columna

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

Para ver ejemplos de cómo modificar los CODECS de compresión de las columnas, consulte Column Compression Codecs.

Para ver ejemplos de cómo modificar el TTL de las columnas, consulte Column TTL.

Para ver ejemplos de cómo modificar la configuración a nivel de columna, consulte Column-level Settings.

Si se especifica la cláusula IF EXISTS, la consulta no devolverá un error si la columna no existe.

Al cambiar el tipo, los valores se convierten como si se les hubieran aplicado las funciones toType. Si solo se cambia la expresión predeterminada, la consulta no realiza ninguna operación compleja y se completa casi al instante.

Ejemplo:

ALTER TABLE visits MODIFY COLUMN browser Array(String)

Cambiar el tipo de una columna es la única operación compleja, ya que modifica el contenido de los archivos de datos. En tablas grandes, esto puede llevar mucho tiempo.

La consulta también puede cambiar el orden de las columnas mediante la cláusula FIRST | AFTER; consulta la descripción de ADD COLUMN, aunque en este caso el tipo de columna es obligatorio.

Ejemplo:

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

DESCRIBE users;
┌

La consulta ALTER es atómica. En las tablas MergeTree, tampoco requiere bloqueos.

La consulta ALTER para cambiar columnas se replica. Las instrucciones se guardan en ZooKeeper y luego cada réplica las aplica. Todas las consultas ALTER se ejecutan en el mismo orden. La consulta espera a que se completen las acciones correspondientes en las otras réplicas. Sin embargo, una consulta para cambiar columnas en una tabla replicada puede interrumpirse, y todas las acciones se realizarán de forma asíncrona.

Elimina una de las propiedades de una columna: DEFAULT, ALIAS, MATERIALIZED, CODEC, COMMENT, TTL, SETTINGS.

Sintaxis:

ALTER TABLE table_name MODIFY COLUMN column_name REMOVE property;

Ejemplo

Eliminar TTL:

ALTER TABLE table_with_ttl MODIFY COLUMN column_ttl REMOVE TTL;

Véase también

• REMOVE TTL.

Modifica una configuración de columna.

Sintaxis:

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

Ejemplo

Modifique el valor de max_compress_block_size de la columna a 1MB:

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

Restablece la configuración de una columna; además, elimina la declaración de esa configuración en la expresión de columna de la consulta CREATE de la tabla.

Sintaxis:

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

Ejemplo

Restablecer la configuración de la columna max_compress_block_size a su valor por defecto:

ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING max_compress_block_size;

Añade nuevos valores a una columna de tipo Enum, Enum8, Enum16, Nullable(Enum), Nullable(Enum8) o Nullable(Enum16)

Sintaxis:

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

Ejemplo

Agregue dos valores a la columna enum_column_name:

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

Materializa una columna con una expresión de valor DEFAULT o MATERIALIZED. Al añadir una columna materializada mediante ALTER TABLE table_name ADD COLUMN column_name MATERIALIZED, las filas existentes sin valores materializados no se rellenan automáticamente. La sentencia MATERIALIZE COLUMN puede usarse para reescribir los datos existentes de la columna después de añadir o actualizar una expresión DEFAULT o MATERIALIZED (lo que solo actualiza los metadatos, pero no modifica los datos existentes). Tenga en cuenta que materializar una columna en la clave de ordenación es una operación no válida porque podría alterar el orden de clasificación. Se implementa como una mutación.

En las columnas con una expresión de valor MATERIALIZED nueva o actualizada, se reescriben todas las filas existentes.

En las columnas con una expresión de valor DEFAULT nueva o actualizada, el comportamiento depende de la versión de ClickHouse:

• En ClickHouse < v24.2, se reescriben todas las filas existentes.
• ClickHouse >= v24.2 distingue si el valor de una fila en una columna con una expresión de valor DEFAULT se especificó explícitamente al insertarla o no; es decir, si se calculó a partir de la expresión de valor DEFAULT. Si el valor se especificó explícitamente, ClickHouse lo mantiene tal cual. Si el valor se calculó, ClickHouse lo cambia por la expresión de valor MATERIALIZED nueva o actualizada.

Sintaxis:

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

• Si especifica una PARTITION, solo se materializará una columna con la partición especificada.

Ejemplo

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);

┌

Véase también

• MATERIALIZED.
• MATERIALIZE INDEX.

La consulta ALTER permite crear y eliminar elementos individuales (columnas) en estructuras de datos anidadas, pero no estructuras de datos anidadas completas. Para añadir una estructura de datos anidada, puede añadir columnas con un nombre como name.nested_name y el tipo Array(T). Una estructura de datos anidada equivale a varias columnas de array cuyo nombre comparte el mismo prefijo antes del punto.

El cambio de nombre de columnas con puntos en sus nombres tiene compatibilidad parcial. Los puntos están reservados para el acceso a sub-columnas Nested, por lo que el prefijo (nombre padre) debe permanecer igual. Solo se puede cambiar el sufijo (nombre de la sub-columna). Por ejemplo, a.b puede renombrarse a a.c, pero no se permite renombrar a.b a b.d porque cambia el prefijo padre de Nested.

No se admite la eliminación de columnas de la clave primaria o de la clave de muestreo (columnas que se usan en la expresión ENGINE). Cambiar el tipo de las columnas incluidas en la clave primaria solo es posible si este cambio no modifica los datos (por ejemplo, se permite añadir valores a un Enum o cambiar un tipo de DateTime a UInt32).

Si la consulta ALTER no es suficiente para realizar los cambios de tabla que necesita, puede crear una tabla nueva, copiar los datos en ella mediante la consulta INSERT SELECT, luego intercambiar las tablas con la consulta RENAME y eliminar la tabla antigua.

La consulta ALTER bloquea todas las lecturas y escrituras de la tabla. En otras palabras, si se está ejecutando un SELECT largo en el momento de la consulta ALTER, la consulta ALTER esperará a que finalice. Al mismo tiempo, todas las consultas nuevas a la misma tabla quedarán en espera mientras este ALTER se esté ejecutando.

En las tablas que no almacenan datos por sí mismas (como Merge y Distributed), ALTER solo cambia la estructura de la tabla y no la estructura de las tablas subordinadas. Por ejemplo, al ejecutar ALTER para una tabla Distributed, también tendrá que ejecutar ALTER para las tablas en todos los servidores remotos.