> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> CoalescingMergeTree herda do motor MergeTree. Sua principal característica é a capacidade de armazenar automaticamente o último valor não nulo de cada coluna durante as mesclagens de partes.

# Motor de tabela CoalescingMergeTree

<Info>
  **Disponível a partir da versão 25.6**

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

Este motor herda de [MergeTree](/docs/pt-BR/reference/engines/table-engines/mergetree-family/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](/docs/pt-BR/reference/engines/table-engines/mergetree-family/mergetree)) 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](/docs/pt-BR/reference/engines/table-engines/mergetree-family/replacingmergetree).

<div id="creating-a-table">
  ## Criar uma tabela
</div>

```sql theme={null}
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](/docs/pt-BR/reference/statements/create/table).

<div id="parameters-of-coalescingmergetree">
  ### Parâmetros do CoalescingMergeTree
</div>

<div id="columns">
  #### Colunas
</div>

`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.

<div id="query-clauses">
  ### Cláusulas da consulta
</div>

Ao criar uma tabela `CoalescingMergeTree`, são necessárias as mesmas [cláusulas](/docs/pt-BR/reference/engines/table-engines/mergetree-family/mergetree) que na criação de uma tabela `MergeTree`.

<details markdown="1">
  <summary>Método obsoleto de criação de tabela</summary>

  <Note>
    Não use este método em novos projetos e, se possível, migre os projetos antigos para o método descrito acima.
  </Note>

  ```sql theme={null}
  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(date-column [, sampling_expression], (primary, key), index_granularity, [columns])
  ```

  Todos os parâmetros, exceto `columns`, têm o mesmo significado que em `MergeTree`.

  * `columns` — tupla com os nomes das colunas cujos valores serão somados. Parâmetro opcional. Para obter uma descrição, veja o texto acima.
</details>

<div id="usage-example">
  ## Exemplo de uso
</div>

Considere a tabela a seguir:

```sql theme={null}
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:

```sql theme={null}
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:

```sql theme={null}
SELECT * FROM test_table ORDER BY key;
```

```text theme={null}
┌─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:

```sql theme={null}
SELECT * FROM test_table FINAL ORDER BY key;
```

```text theme={null}
┌─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.

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

  ```sql theme={null}
  SELECT key, last_value(value_int), last_value(value_string), last_value(value_date)  FROM test_table GROUP BY key; -- Não recomendado.
  ```
</Note>

<div id="tuple-element-aggregation">
  ## Agregação de elementos de Tuple
</div>

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.

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

```sql theme={null}
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;
```

```text theme={null}
┌─key─┬─data.value_a─┬─data.value_b─┬─data.nested.value_c─┐
│   1 │          100 │ hello        │                  42 │
└─────┴──────────────┴──────────────┴─────────────────────┘
```