> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentación de ALTER

# ALTER

La mayoría de las consultas `ALTER TABLE` modifican la configuración de la tabla o sus datos:

| Modificador                                                             |
| ----------------------------------------------------------------------- |
| [COLUMN](/es/reference/statements/alter/column)                         |
| [PARTITION](/es/reference/statements/alter/partition)                   |
| [DELETE](/es/reference/statements/alter/delete)                         |
| [UPDATE](/es/reference/statements/alter/update)                         |
| [ORDER BY](/es/reference/statements/alter/order-by)                     |
| [SAMPLE BY](/es/reference/statements/alter/sample-by)                   |
| [INDEX](/es/reference/statements/alter/skipping-index)                  |
| [PROJECTION](/es/reference/statements/alter/projection)                 |
| [CONSTRAINT](/es/reference/statements/alter/constraint)                 |
| [TTL](/es/reference/statements/alter/ttl)                               |
| [STATISTICS](/es/reference/statements/alter/statistics)                 |
| [SETTING](/es/reference/statements/alter/setting)                       |
| [APPLY DELETED MASK](/es/reference/statements/alter/apply-deleted-mask) |
| [APPLY PATCHES](/es/reference/statements/alter/apply-patches)           |

<Note>
  La mayoría de las consultas `ALTER TABLE` solo son compatibles con tablas [\*MergeTree](/es/reference/engines/table-engines/mergetree-family/index), [Merge](/es/reference/engines/table-engines/special/merge) y [Distributed](/es/reference/engines/table-engines/special/distributed).
</Note>

Estas sentencias `ALTER` manipulan vistas:

| Sentencia                                                           | Descripción                                                                                |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [ALTER TABLE ... MODIFY QUERY](/es/reference/statements/alter/view) | Modifica la estructura de una [vista materializada](/es/reference/statements/create/view). |

Estas sentencias `ALTER` modifican entidades relacionadas con el control de acceso basado en roles:

| Sentencia                                                           |
| ------------------------------------------------------------------- |
| [USER](/es/reference/statements/alter/user)                         |
| [ROLE](/es/reference/statements/alter/role)                         |
| [QUOTA](/es/reference/statements/alter/quota)                       |
| [ROW POLICY](/es/reference/statements/alter/row-policy)             |
| [MASKING POLICY](/es/reference/statements/alter/masking-policy)     |
| [SETTINGS PROFILE](/es/reference/statements/alter/settings-profile) |

| Sentencia                                                                            | Descripción                                                                                                            |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| [ALTER TABLE ... MODIFY COMMENT](/es/reference/statements/alter/comment)             | Agrega, modifica o elimina comentarios en la tabla, independientemente de si se habían establecido antes o no.         |
| [ALTER DATABASE ... MODIFY COMMENT](/es/reference/statements/alter/database-comment) | Agrega, modifica o elimina comentarios en la base de datos, independientemente de si se habían establecido antes o no. |
| [ALTER NAMED COLLECTION](/es/reference/statements/alter/named-collection)            | Modifica las [Named Collections](/es/concepts/features/configuration/server-config/named-collections).                 |

<div id="mutations">
  ## Mutaciones
</div>

Las consultas `ALTER` destinadas a modificar datos de tablas se implementan mediante un mecanismo llamado "mutaciones", en particular [ALTER TABLE ... DELETE](/es/reference/statements/alter/delete) y [ALTER TABLE ... UPDATE](/es/reference/statements/alter/update). Son procesos asíncronos en segundo plano, similares a las fusiones en tablas [MergeTree](/es/reference/engines/table-engines/mergetree-family/index), que producen nuevas versiones "mutadas" de las partes.

En las tablas `*MergeTree`, las mutaciones se ejecutan **reescribiendo partes de datos completas**.
No hay atomicidad: las partes se sustituyen por sus versiones mutadas en cuanto están listas, y una consulta `SELECT` que haya comenzado a ejecutarse durante una mutación verá datos de partes que ya han sido mutadas junto con datos de partes que aún no han sido mutadas.

Las mutaciones están totalmente ordenadas según su orden de creación y se aplican a cada parte en ese orden. Las mutaciones también están parcialmente ordenadas con las consultas `INSERT INTO`: los datos que se insertaron en la tabla antes de que se enviara la mutación serán mutados, y los datos que se insertaron después no serán mutados. Tenga en cuenta que las mutaciones no bloquean las inserciones de ninguna manera.

Una consulta de mutación devuelve el resultado inmediatamente después de que se añade la entrada de mutación (en el caso de las tablas replicadas, en ZooKeeper; en las tablas no replicadas, en el sistema de archivos). La mutación en sí se ejecuta de forma asíncrona usando la configuración del perfil del sistema. Para seguir el progreso de las mutaciones, puede usar la tabla [`system.mutations`](/es/reference/system-tables/mutations). Una mutación enviada correctamente seguirá ejecutándose incluso si se reinician los servidores de ClickHouse. No hay forma de revertir la mutación una vez enviada, pero si la mutación se queda atascada por algún motivo, puede cancelarse con la consulta [`KILL MUTATION`](/es/reference/statements/kill#kill-mutation).

Las entradas de las mutaciones finalizadas no se eliminan de inmediato (el número de entradas conservadas lo determina el parámetro del motor de almacenamiento `finished_mutations_to_keep`). Las entradas de mutación más antiguas se eliminan.

<div id="synchronicity-of-alter-queries">
  ## Sincronía de las consultas ALTER
</div>

Para las tablas no replicadas, todas las consultas `ALTER` se realizan de forma síncrona. Para las tablas replicadas, la consulta solo agrega en `ZooKeeper` instrucciones para las acciones correspondientes, y dichas acciones se realizan lo antes posible. Sin embargo, la consulta puede esperar a que estas acciones se completen en todas las réplicas.

Para las consultas `ALTER` que crean mutaciones (p. ej., entre otras, `UPDATE`, `DELETE`, `MATERIALIZE INDEX`, `MATERIALIZE PROJECTION`, `MATERIALIZE COLUMN`, `APPLY DELETED MASK`, `APPLY PATCHES`, `CLEAR STATISTIC`, `MATERIALIZE STATISTIC`), la sincronía se define mediante la configuración [mutations\_sync](/es/reference/settings/session-settings/mutations#mutations_sync).

Para otras consultas `ALTER` que solo modifican los metadatos, puede usar la configuración [alter\_sync](/es/reference/settings/session-settings/alter#alter_sync) para definir la espera.

Puede especificar cuánto tiempo (en segundos) esperar a que las réplicas inactivas ejecuten todas las consultas `ALTER` con la configuración [replication\_wait\_for\_inactive\_replica\_timeout](/es/reference/settings/session-settings/other#replication_wait_for_inactive_replica_timeout).

<Note>
  Para todas las consultas `ALTER`, si `alter_sync = 2` y algunas réplicas permanecen inactivas durante más tiempo del especificado en la configuración `replication_wait_for_inactive_replica_timeout`, se lanza una excepción `UNFINISHED`.
</Note>

<div id="concurrent-alter-assignment-on-one-table">
  ### Asignación concurrente de `ALTER` en una misma tabla
</div>

En tablas replicadas, enviar varias sentencias `ALTER` independientes contra la misma tabla en rápida sucesión puede generar el error `CANNOT_ASSIGN_ALTER` (código 517). La ruta replicada genera este error cuando la réplica aún no ha aplicado algunos `ALTER` anteriores (la versión de los metadatos sigue por detrás de los metadatos comunes; el servidor puede indicar que la réplica "still not applied some of previous alters" o "Probably too many alters executing concurrently"). Esta condición puede persistir incluso después de que se haya asignado un `ALTER` anterior. Se trata de una condición **general de `ALTER` de metadatos o mutaciones concurrentes**; no se limita a sentencias que solo producen mutaciones. Las operaciones concurrentes habituales de modificación de metadatos (`ADD` / `DROP` / `MODIFY` y similares) pueden generar el mismo código reintentable (consulte, por ejemplo, la ruta de reintento cubierta por `tests/queries/0_stateless/03518_alter_logical_race.sh`).

Enfoques para evitar la condición de carrera:

* Combine operaciones de metadatos independientes en un **único** `ALTER` con varias cláusulas cuando la gramática lo permita (por ejemplo, varias cláusulas `ADD INDEX`).
* Serialice las sentencias `ALTER` y vuelva a intentarlo ante el código 517 hasta que los `ALTER` anteriores se hayan aplicado en la réplica.
* Para los `ALTER` que generan mutaciones, espere a que finalice la mutación anterior mediante un indicador observable documentado, como [`mutations_sync`](/es/reference/settings/session-settings/mutations#mutations_sync) o `is_done` en [`system.mutations`](/es/reference/system-tables/mutations), antes de enviar el siguiente.

<div id="combining-materialize-index-clauses">
  ### Combinación de cláusulas `MATERIALIZE INDEX`
</div>

Pueden incluirse varias cláusulas `MATERIALIZE INDEX` en un mismo `ALTER`. El caso cubierto en el código fuente consiste en agrupar varias cláusulas `ADD INDEX` junto con `MATERIALIZE INDEX` para esos mismos índices nuevos en una sola sentencia (consulte `tests/queries/0_stateless/02911_add_index_and_materialize_index.sql`). Esta forma agrupada de `ADD INDEX` + `MATERIALIZE INDEX` combina un segmento `AlterCommand` con un segmento `MutationCommand`, por lo que **`DatabaseReplicated` la rechaza** con `QUERY_IS_PROHIBITED` (`InterpreterAlterQuery::validateReplicatedDatabaseSegments`). Considere válido el ejemplo `02911` para bases de datos ordinarias (distintas de `DatabaseReplicated`); en `DatabaseReplicated`, mantenga los cambios de metadatos y las mutaciones de materialización en sentencias separadas.

En la implementación actual, cada cláusula `MATERIALIZE INDEX` se resuelve respecto a la instantánea de metadatos de la tabla cuando se prepara la mutación, por lo que las formas con varias cláusulas que solo materializan índices ya existentes siguen la misma ruta de preparación (solo mutación, por lo que permanecen dentro de un único segmento). Esta forma exacta aún no está cubierta por una prueba stateless específica; trátela como comportamiento de la implementación actual, no como un contrato garantizado de forma independiente, hasta que exista dicha cobertura.

Si necesita aplicar las mutaciones en orden, puede seguir emitiendo un `MATERIALIZE INDEX` por sentencia y esperar con [`mutations_sync`](/es/reference/settings/session-settings/mutations#mutations_sync).

<div id="related-content">
  ## Contenido relacionado
</div>

* Blog: [Cómo gestionar actualizaciones y eliminaciones en ClickHouse](https://clickhouse.com/blog/handling-updates-and-deletes-in-clickhouse)