Saltar al contenido principal
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

ADD COLUMN [IF NOT EXISTS] name [type] [default_expr] [codec] [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). 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

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.
No se puede eliminar una columna si una vista materializada hace referencia a ella. De lo contrario, se devolverá un error.
Ejemplo: 
ALTER TABLE visits DROP COLUMN browser

​
RENAME COLUMN

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

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

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

MODIFY COLUMN [IF EXISTS] name [type] [default_expr] [codec] [TTL] [settings] [AFTER name_after | FIRST]
ALTER COLUMN [IF EXISTS] name TYPE [type] [default_expr] [codec] [TTL] [settings] [AFTER name_after | FIRST]
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
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;
┌─name─┬─type───┬
│ c1   │ Int16  │
│ c2   │ String │
└──────┴────────┴

ALTER TABLE users MODIFY COLUMN c2 String FIRST;

DESCRIBE users;
┌─name─┬─type───┬
│ c2   │ String │
│ c1   │ Int16  │
└──────┴────────┴

ALTER TABLE users ALTER COLUMN c2 TYPE String AFTER c1;

DESCRIBE users;
┌─name─┬─type───┬
│ c1   │ Int16  │
│ c2   │ String │
└──────┴────────┴
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.
Tenga mucho cuidado al cambiar una columna Nullable a Non-Nullable. Asegúrese de que no tenga ningún valor NULL; de lo contrario, causará problemas al leerla. En ese caso, la solución alternativa sería ejecutar Kill sobre la mutación y revertir la columna al tipo Nullable.

​
MODIFY COLUMN REMOVE

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

​
MODIFY COLUMN MODIFY SETTING

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;

​
MODIFY COLUMN RESET SETTING

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;

​
MATERIALIZE COLUMN

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

┌─groupArray(x)─┬─groupArray(s)─────────┐
│ [0,1,2,3,4]   │ ['0','1','2','3','4'] │
└───────────────┴───────────────────────┘

ALTER TABLE tmp MODIFY COLUMN s String MATERIALIZED toString(round(100/x));

INSERT INTO tmp SELECT * FROM system.numbers LIMIT 5,5;

SELECT groupArray(x), groupArray(s) FROM tmp;

┌─groupArray(x)─────────┬─groupArray(s)──────────────────────────────────┐
│ [0,1,2,3,4,5,6,7,8,9] │ ['0','1','2','3','4','20','17','14','12','11'] │
└───────────────────────┴────────────────────────────────────────────────┘

ALTER TABLE tmp MATERIALIZE COLUMN s;

SELECT groupArray(x), groupArray(s) FROM tmp;

┌─groupArray(x)─────────┬─groupArray(s)─────────────────────────────────────────┐
│ [0,1,2,3,4,5,6,7,8,9] │ ['inf','100','50','33','25','20','17','14','12','11'] │
└───────────────────────┴───────────────────────────────────────────────────────┘
Véase también

​
Limitaciones

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.
Última modificación el 10 de junio de 2026