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

> 包含 MergeTree 表变更及其进度信息的系统表。每条变更命令对应表中的一行。

# system.mutations

<div id="description">
  ## 描述
</div>

该表包含 [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 表的[变更](/zh/reference/statements/alter/index#mutations)及其进度信息。每个变更命令对应一行。

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

* `database` ([String](/zh/reference/data-types/index)) — 应用该变更的 database 名称。
* `table` ([String](/zh/reference/data-types/index)) — 应用该变更的表名称。
* `mutation_id` ([String](/zh/reference/data-types/index)) — 变更的 ID。对于复制表，这些 ID 对应于 ClickHouse Keeper 中 `<table_path_in_clickhouse_keeper>/mutations/` 目录里的 znode 名称。对于非复制表，这些 ID 对应于表数据目录中的文件名。
* `command` ([String](/zh/reference/data-types/index)) — 变更命令字符串 (即 查询 中 `ALTER TABLE [db.]table` 之后的部分) 。
* `create_time` ([DateTime](/zh/reference/data-types/index)) — 提交变更命令执行的日期和时间。
* `block_numbers.partition_id` ([Array(String)](/zh/reference/data-types/index)) — 对于复制表的变更，该数组包含各分区的 ID (每个分区一条记录) 。对于非复制表的变更，该数组为空。
* `block_numbers.number` ([Array(Int64)](/zh/reference/data-types/index)) — 对于复制表的变更，该数组对每个分区包含一条记录，记录该变更获取到的块编号。只有在该分区中包含编号小于此编号的块的数据分区片段才会被变更。对于非复制表，所有分区中的块编号构成一个统一序列。这意味着，对于非复制表的变更，该列将包含一条记录，其中只有一个由该变更获取的块编号。
* `parts_in_progress_names` ([Array(String)](/zh/reference/data-types/index)) — 当前正在进行变更的数据分区片段名称数组。
* `parts_to_do_names` ([Array(String)](/zh/reference/data-types/index)) — 该变更完成前仍需进行变更的数据分区片段名称数组。
* `parts_to_do` ([Int64](/zh/reference/data-types/index)) — 该变更完成前仍需进行变更的数据分区片段数量。注意：即使 `parts_to_do` = 0，由于可能存在一个长时间运行的 INSERT 正在创建新的数据分区片段，而该数据分区片段之后也需要进行变更，复制表的变更也可能尚未完成。
* `parts_postpone_reasons` ([Map(String, String)](/zh/reference/data-types/index)) — 从 分片 名称到其被推迟原因的映射。
* `is_done` ([UInt8](/zh/reference/data-types/index)) — 表示该变更是否已完成的标志。Possible values：1 表示变更已完成，0 表示变更仍在进行中。
* `is_killed` ([UInt8](/zh/reference/data-types/index)) — 表示某个变更是否已被终止。仅在 ClickHouse Cloud 中可用。注意：is\_killed=1 并不一定表示该变更已完全结束。变更可能长时间处于 is\_killed=1 且 is\_done=0 的状态。如果另一个长时间运行的变更阻塞了这个已终止的变更，就可能发生这种情况。这是正常现象。
* `latest_failed_part` ([String](/zh/reference/data-types/index)) — 最近一个无法进行变更的 分片 名称。
* `latest_fail_time` ([DateTime](/zh/reference/data-types/index)) — 最近一次 part mutation 失败的日期和时间。
* `latest_fail_reason` ([String](/zh/reference/data-types/index)) — 导致最近一次 part mutation 失败的异常消息。
* `latest_fail_error_code_name` ([String](/zh/reference/data-types/index)) — 导致最近一次 part mutation 失败的异常的错误代码名称。

<Note>
  - 如果某个 分片 名称不在 `parts_postpone_reasons` 中，且尚未进行变更，则表示该 分片 还未被调度执行变更。
  - 分片 名称 `all_parts` 表示所有尚未进行变更的 parts。
</Note>

* `is_killed` ([UInt8](/zh/reference/data-types/int-uint)) — 表示变更是否已被终止。**仅在 ClickHouse Cloud 中可用。**

<Note>
  `is_killed=1` 并不一定表示该变更已完全结束。变更可能会在较长一段时间内一直处于 `is_killed=1` 且 `is_done=0` 的状态。如果有另一个长时间运行的变更阻塞了这个已终止的变更，就可能出现这种情况。这是正常现象。
</Note>

* `is_done` ([UInt8](/zh/reference/data-types/int-uint)) — 表示变更是否完成的标志。可能的值：
  * `1`：变更已完成，
  * `0`：变更仍在进行中。

<Note>
  即使 `parts_to_do = 0`，复制表的变更也可能尚未完成，因为有一个长时间运行的 `INSERT` 查询会创建一个还需要执行变更的新分片。
</Note>

如果某些分片在变更过程中出现问题，以下列会包含附加信息：

* `latest_failed_part` ([String](/zh/reference/data-types/string)) — 最近一个无法完成变更的分片的名称。
* `latest_fail_time` ([DateTime](/zh/reference/data-types/datetime)) — 最近一次 part mutation 失败的日期和时间。
* `latest_fail_reason` ([String](/zh/reference/data-types/string)) — 导致最近一次 part mutation 失败的异常消息。

<div id="monitoring-mutations">
  ## 监控变更
</div>

要跟踪 `system.mutations` 表中的变更进度，请使用以下查询：

```sql theme={null}
SELECT * FROM clusterAllReplicas('cluster_name', 'system', 'mutations')
WHERE is_done = 0 AND table = 'tmp';

-- 或

SELECT * FROM clusterAllReplicas('cluster_name', 'system.mutations')
WHERE is_done = 0 AND table = 'tmp';
```

注意：这需要对 `system.*` 表具有读取权限。

<Tip>
  **Cloud 使用说明**

  在 ClickHouse Cloud 中，每个节点上的 `system.mutations` 表都包含集群中的所有变更，因此无需使用 `clusterAllReplicas`。
</Tip>

<div id="see-also">
  ## 另请参阅
</div>

* [变更](/zh/reference/statements/alter/index#mutations)
* [MergeTree](/zh/reference/engines/table-engines/mergetree-family/mergetree) 表引擎
* [ReplicatedMergeTree](/zh/reference/engines/table-engines/mergetree-family/replication) 家族