Motor de tabela CoalescingMergeTree - ClickHouse Documentation

Disponível a partir da versão 25.6Este motor de tabela está disponível a partir da versão 25.6, tanto no OSS quanto no Cloud.

Este motor herda de MergeTree. A principal diferença está em como as partes de dados são mescladas: em tabelas CoalescingMergeTree, o ClickHouse substitui todas as linhas com a mesma chave primária (ou, mais precisamente, a mesma chave de ordenação) por uma única linha que contém os valores não NULL mais recentes de cada coluna. Isso permite upserts no nível da coluna, o que significa que você pode atualizar apenas colunas específicas, em vez de linhas inteiras. CoalescingMergeTree foi projetado para uso com tipos Nullable em colunas que não fazem parte da chave. Se as colunas não forem Nullable, o comportamento será o mesmo do ReplacingMergeTree.

Criar uma tabela

CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1],
    name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2],
    ...
) ENGINE = CoalescingMergeTree([columns])
[PARTITION BY expr]
[ORDER BY expr]
[SAMPLE BY expr]
[SETTINGS name=value, ...]

Para ver uma descrição dos parâmetros da requisição, consulte a descrição da requisição.

Parâmetros do CoalescingMergeTree

Colunas

columns - Opcional. Uma tupla com os nomes das colunas em que os valores serão unificados. As colunas fornecidas não devem estar na partição nem na chave de ordenação. Se columns não for especificado, ClickHouse unifica os valores em todas as colunas que não estão na chave de ordenação.

Cláusulas da consulta

Ao criar uma tabela CoalescingMergeTree, são necessárias as mesmas cláusulas que na criação de uma tabela MergeTree.

Exemplo de uso

Considere a tabela a seguir:

CREATE TABLE test_table
(
    key UInt64,
    value_int Nullable(UInt32),
    value_string Nullable(String),
    value_date Nullable(Date)
)
ENGINE = CoalescingMergeTree()
ORDER BY key

Insira dados nele:

INSERT INTO test_table VALUES(1, NULL, NULL, '2025-01-01'), (2, 10, 'test', NULL);
INSERT INTO test_table VALUES(1, 42, 'win', '2025-02-01');
INSERT INTO test_table(key, value_date) VALUES(2, '2025-02-01');

O resultado ficará assim:

SELECT * FROM test_table ORDER BY key;

┌─key─┬─value_int─┬─value_string─┬─value_date─┐
│   1 │        42 │ win          │ 2025-02-01 │
│   1 │      ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ         │ 2025-01-01 │
│   2 │      ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ         │ 2025-02-01 │
│   2 │        10 │ test         │       ᴺᵁᴸᴸ │
└─────┴───────────┴──────────────┴────────────┘

Consulta recomendada para obter o resultado correto e definitivo:

SELECT * FROM test_table FINAL ORDER BY key;

┌─key─┬─value_int─┬─value_string─┬─value_date─┐
│   1 │        42 │ win          │ 2025-02-01 │
│   2 │        10 │ test         │ 2025-02-01 │
└─────┴───────────┴──────────────┴────────────┘

Usar o modificador FINAL força o ClickHouse a aplicar a lógica de mesclagem no momento da consulta, garantindo que você obtenha o valor “mais recente” correto e consolidado para cada coluna. Esse é o método mais seguro e preciso ao consultar uma tabela CoalescingMergeTree.

Uma abordagem com GROUP BY pode retornar resultados incorretos se as partes subjacentes ainda não tiverem sido totalmente mescladas.

SELECT key, last_value(value_int), last_value(value_string), last_value(value_date)  FROM test_table GROUP BY key; -- Não recomendado.

Agregação de elementos de Tuple

Quando a configuração allow_tuple_element_aggregation está habilitada, as colunas Tuple são achatadas recursivamente para que cada elemento folha participe da coalescência de forma independente. Isso permite armazenar vários campos em uma única coluna Tuple e fazer com que eles sejam coalescidos por elemento durante as mesclagens — cada subcoluna Nullable mantém de forma independente o valor não NULL mais recente. As mesmas regras se aplicam às subcolunas achatadas e às colunas regulares:

As subcolunas que pertencem a uma Tuple na chave de ordenação ou na chave de partição são excluídas da coalescência.
Se columns for especificado, somente as subcolunas das colunas Tuple listadas serão coalescidas.

Essa configuração é imutável e deve ser especificada no momento da criação da tabela.

CREATE TABLE coalescing_tuples
(
    key UInt64,
    data Tuple(
        value_a Nullable(UInt64),
        value_b Nullable(String),
        nested Tuple(
            value_c Nullable(UInt64)
        )
    )
) ENGINE = CoalescingMergeTree()
ORDER BY key
SETTINGS allow_tuple_element_aggregation = 1;

INSERT INTO coalescing_tuples VALUES (1, (100, NULL, (NULL)));
INSERT INTO coalescing_tuples VALUES (1, (NULL, 'hello', (42)));

SELECT key, data.value_a, data.value_b, data.nested.value_c FROM coalescing_tuples FINAL;

┌─key─┬─data.value_a─┬─data.value_b─┬─data.nested.value_c─┐
│   1 │          100 │ hello        │                  42 │
└─────┴──────────────┴──────────────┴─────────────────────┘

​Criar uma tabela

​Parâmetros do CoalescingMergeTree

​Colunas

​Cláusulas da consulta

​Exemplo de uso

​Agregação de elementos de Tuple

Criar uma tabela

Parâmetros do CoalescingMergeTree

Colunas

Cláusulas da consulta

Exemplo de uso

Agregação de elementos de Tuple