> ## 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 继承自 MergeTree 引擎。其关键特性 是能够在 parts 合并期间自动存储每一列最后一个非 NULL 值。

# CoalescingMergeTree 表引擎

<Info>
  **自 25.6 版本起可用**

  此表引擎在 OSS 和 Cloud 中自 25.6 版本起可用。
</Info>

此引擎继承自 [MergeTree](/docs/zh/reference/engines/table-engines/mergetree-family/mergetree)。关键区别在于 parts 的合并方式：对于 `CoalescingMergeTree` 表，ClickHouse 会将具有相同主键的所有行 (更准确地说，具有相同[排序键](/docs/zh/reference/engines/table-engines/mergetree-family/mergetree)的所有行) 合并为一行，该行包含每一列最新的非 NULL 值。

这使得列级 upsert 成为可能，也就是说，你可以只更新特定列，而不必更新整行。

`CoalescingMergeTree` 适用于非键列中的 Nullable 类型。如果这些列不是 Nullable，则其行为与 [ReplacingMergeTree](/docs/zh/reference/engines/table-engines/mergetree-family/replacingmergetree) 相同。

<div id="creating-a-table">
  ## 创建表
</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, ...]
```

有关请求参数的描述，请参见[请求描述](/docs/zh/reference/statements/create/table)。

<div id="parameters-of-coalescingmergetree">
  ### CoalescingMergeTree 参数
</div>

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

`columns` - 可选。一个 Tuple，包含要合并其值的列名。给定的列不能位于分区或排序键中。如果未指定 `columns`，ClickHouse 会合并所有不在排序键中的列的值。

<div id="query-clauses">
  ### 查询子句
</div>

创建 `CoalescingMergeTree` 表时，需要使用与创建 `MergeTree` 表相同的[子句](/docs/zh/reference/engines/table-engines/mergetree-family/mergetree)。

<details markdown="1">
  <summary>已弃用的建表方法</summary>

  <Note>
    请勿在新项目中使用此方法；如果可能，请将旧项目切换为上述方法。
  </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])
  ```

  除 `columns` 外，所有参数的含义都与 `MergeTree` 中相同。

  * `columns` — 由其值将被求和的列名组成的 Tuple。可选参数。有关说明，请参见上文。
</details>

<div id="usage-example">
  ## 使用示例
</div>

以下表为例：

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

向其中插入数据：

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

结果如下所示：

```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         │       ᴺᵁᴸᴸ │
└─────┴───────────┴──────────────┴────────────┘
```

为获得正确的最终结果，建议使用以下查询：

```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 │
└─────┴───────────┴──────────────┴────────────┘
```

使用 `FINAL` 修饰符会强制 ClickHouse 在查询时应用合并逻辑，确保你能为每一列获取正确、合并后的"最新"值。这是在从 CoalescingMergeTree 表中查询时最安全、最准确的方法。

<Note>
  如果底层 parts 尚未完全合并，使用 `GROUP BY` 的方法可能会返回不正确的结果。

  ```sql theme={null}
  SELECT key, last_value(value_int), last_value(value_string), last_value(value_date)  FROM test_table GROUP BY key; -- 不推荐。
  ```
</Note>

<div id="tuple-element-aggregation">
  ## Tuple 元素聚合
</div>

启用 `allow_tuple_element_aggregation` 设置后，`Tuple` 列会被递归展平，使每个叶子元素都能独立参与合并。这让您可以在单个 `Tuple` 列中存储多个字段，并在 合并 期间按元素分别合并——每个 `Nullable` 子列都会独立保留最新的非 NULL 值。

展平后的子列适用与普通列相同的规则：

* 属于 排序键 或 partition key 中 `Tuple` 的子列不会参与合并。
* 如果指定了 `columns`，则只会合并所列 `Tuple` 列的子列。

<Note>
  此设置不可更改，必须在创建表时指定。
</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 │
└─────┴──────────────┴──────────────┴─────────────────────┘
```