En ClickHouse, un upsert con ReplacingMergeTree normalmente se modela insertando una nueva versión de la fila, no modificando la anterior en el sitio. Las versiones con la misma clave ORDER BY pueden coexistir físicamente hasta que los merges de fondo las consoliden; por eso una consulta normal puede mostrar duplicados. Cuando una lectura necesita el estado vigente antes de esa consolidación, SELECT ... FINAL aplica la lógica de reemplazo durante la consulta, con trabajo adicional de lectura.
Qué significa «upsert» en ReplacingMergeTree
El motor no ofrece una restricción de unicidad transaccional que impida insertar dos filas con la misma identidad. En su lugar, ClickHouse identifica para reemplazo las filas que comparten las columnas de ORDER BY. Los merges de fondo pueden reducir esas filas a una ganadora, pero ese proceso es asíncrono: hasta entonces, las versiones pueden seguir presentes en distintas partes y ser visibles en una lectura ordinaria.
As an Amazon Associate I earn from qualifying purchases.
Con una columna de versión configurada, la fila con el valor de versión más alto es la que prevalece al aplicar el reemplazo. Sin una versión explícita, el resultado depende del orden en que se mezclen las partes. Para cargas con actualizaciones —en especial si llegan fuera de orden— una versión lógica explícita permite expresar cuál es el estado más reciente sin depender de ese orden físico.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchCómo insertar una nueva versión
Supongamos que cada artículo de un pedido se identifica con (order_id, item_id). La primera inserción guarda el estado inicial. Si cambia la cantidad o el estado del artículo, la aplicación inserta otra fila con la misma pareja de identidad y una versión mayor. La documentación técnica de ClickHouse describe este patrón como insertar una nueva versión con la misma clave de ordenación para actualizar una fila.
CREATE TABLE order_items
(
order_id UInt64,
item_id UInt64,
quantity UInt32,
version UInt64
)
ENGINE = ReplacingMergeTree(version)
ORDER BY (order_id, item_id);La definición es ilustrativa: el tipo de columnas y la clave deben corresponder al esquema real. Una actualización conceptual de un artículo consiste en insertar otra fila con el mismo order_id y item_id, el nuevo valor de quantity y una versión superior. No se borra ni se sobrescribe inmediatamente la fila antigua.
Qué define la identidad de una fila
La clave ORDER BY es semántica
En este motor, ORDER BY no es solo una elección de rendimiento: sus columnas determinan qué filas se consideran versiones de la misma entidad para el reemplazo. Si se omite una columna que distingue entidades, filas distintas podrían competir como si fueran la misma. Si se incluye un valor que cambia en cada actualización, las versiones dejarán de coincidir y no se reemplazarán entre sí.
Por ejemplo, si una fecha mutable forma parte de la clave de ordenación y cambia al actualizar un registro, la nueva fila tendrá otra identidad desde la perspectiva de ReplacingMergeTree. Diseña una clave estable que identifique la fila lógica, y mantén esa misma identidad en cada versión. Si la propia clave debe cambiar, el patrón ya no equivale a actualizar la misma fila: hay que modelar explícitamente la salida de la identidad anterior y la entrada de la nueva.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →La versión resuelve el orden lógico
En una carga CDC, los eventos pueden llegar desordenados. Configurar una columna de versión permite elegir el valor lógico mayor al aplicar el reemplazo, en vez de confiar en qué parte entra primero en un merge. La versión debe representar el orden de actualización que importa para la aplicación; el simple hecho de que una fila se haya insertado después no prueba que sea más reciente en términos de negocio.
Cuándo usar FINAL al leer
Para una lectura que necesita el estado deduplicado sin esperar a los merges asíncronos, añade FINAL a la tabla de la consulta:
SELECT order_id, item_id, quantity, version
FROM order_items FINAL
WHERE order_id = 42;FINAL aplica en esa consulta la lógica de merge del motor y devuelve la versión ganadora para las filas coincidentes. No fuerza una consolidación física de la tabla; el trabajo se realiza al leer y puede costar más que una lectura normal. El coste depende de la consulta y los datos, así que no hay una ventaja de rendimiento universal frente a otras formas de seleccionar la versión.
ClickHouse también documenta el ajuste final = 1, que aplica el comportamiento de FINAL a las tablas de la consulta. La disponibilidad y el alcance exactos de ajustes pueden depender de la versión desplegada; verifica la documentación de esa versión antes de adoptarlo como configuración general.
FINAL frente a una lectura normal
| Lectura | Cuándo se deduplica | Implicación |
|---|---|---|
Consulta sin FINAL |
Cuando los merges de fondo consoliden las partes pertinentes | Antes de la consolidación pueden aparecer varias versiones |
Consulta con FINAL |
Durante esa consulta | Entrega el estado reemplazado sin esperar el merge, a costa de trabajo adicional de lectura |
Particiones: mantén juntas las versiones que deben competir
Los merges ordinarios se realizan dentro de cada partición. Por tanto, el diseño de particionado debe permitir que las versiones de una misma fila lógica permanezcan juntas. Si una columna de partición cambia al actualizar el registro —por ejemplo, una fecha que sitúa cada nueva versión en una partición distinta— los merges de fondo no las consolidarán entre sí.
Esta consideración también afecta a FINAL. Solo habilita do_not_merge_across_partitions_select_final = 1 cuando el diseño garantiza que las versiones que deben reemplazarse residen en la misma partición. Si pueden estar repartidas entre particiones, esa opción deja de ser una suposición segura para obtener la fila vigente. La guía de ClickHouse sobre particionado y CDC enfatiza que la clave de partición debe permanecer estable para la fila dentro de este patrón.
Borrados: la marca no equivale a eliminación inmediata
Una forma documentada de representar borrados es configurar el motor con versión y columna de borrado, por ejemplo ReplacingMergeTree(version, deleted). La versión ganadora puede quedar marcada como borrada y la consulta que representa el estado actual debe excluir esas filas. La inserción de la marca no implica que los datos desaparezcan físicamente en ese instante.
Antes de usar este patrón, define cómo se filtran las filas marcadas en cada consulta de estado actual y qué política de retención física se necesita. Un filtro que omita la marca puede volver a exponer registros que la aplicación considera eliminados; la limpieza física es una decisión distinta de la visibilidad lógica.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
ReplacingMergeTree, UPDATE ligero y OPTIMIZE FINAL no son lo mismo
| Mecanismo | Cómo representa el cambio | Cuándo aplica el trabajo |
|---|---|---|
ReplacingMergeTree con versión |
Inserta una fila nueva con la misma identidad de ordenación y una versión superior | En merges asíncronos o durante la lectura con FINAL |
UPDATE ligero |
Usa patch parts que se aplican en lectura y en merges; no es insertar una fila completa versionada | Al leer y al consolidar, según el mecanismo |
OPTIMIZE TABLE ... FINAL |
Fuerza trabajo de merge físico | En la operación de optimización, no solo en una consulta |
Los UPDATE ligeros son un mecanismo diferente, presentado en materiales de ClickHouse para versiones recientes mediante patch parts. La conveniencia depende del patrón de cambio, la versión de ClickHouse y el diseño de los datos; no hay una regla única que los haga preferibles a las inserciones versionadas en todos los casos.
No confundas SELECT ... FINAL con OPTIMIZE TABLE ... FINAL. El primero aplica la lógica de reemplazo a una lectura. El segundo fuerza un merge físico, que puede elevar la presión sobre recursos y réplicas. La guía de ClickHouse sobre OPTIMIZE TABLE ... FINAL desaconseja tratarlo como sustituto rutinario de una estrategia de lectura correcta o de los merges normales.
Decisión práctica para una carga de actualizaciones
- Define la identidad lógica. Escoge las columnas estables de
ORDER BYque identifican una fila y no deben cambiar entre versiones. - Elige una versión lógica. Configura una columna que permita distinguir qué actualización debe prevalecer, especialmente si la carga CDC puede entregar eventos fuera de orden.
- Comprueba el particionado. Asegúrate de que las versiones competidoras queden en la misma partición; no habilites
do_not_merge_across_partitions_select_finalsin esa garantía. - Decide qué exige cada lectura. Si necesita el estado vigente antes de la consolidación de fondo, considera
FINAL. Si no lo necesita, una lectura normal puede exponer versiones coexistentes. - Modela los borrados aparte. Si usas una marca de borrado, filtra los registros marcados en las consultas de estado actual y establece una expectativa de retención física.
- Valida la versión instalada. Comprueba la sintaxis y los ajustes vigentes para tu despliegue, y mide la consulta con el esquema y la carga reales antes de sacar conclusiones de coste.
La formación de ClickHouse Academy, en su catálogo «Data Warehousing with ClickHouse: Level 2», incluye contenidos sobre ReplacingMergeTree, deduplicación, mutaciones y patrones con FINAL y argMax. argMax también puede servir para escoger valores por versión o fecha en una consulta; la forma adecuada depende de la consulta concreta, y no debe suponerse que sea siempre más rápida o más clara que FINAL.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →
