一条 DDL 在所有节点执行
ON CLUSTER 让一条 DDL 在集群所有节点上执行：建库建表、修改结构、删除表都适用。它依赖集群配置里同名的集群定义与一个健康的协调服务，执行记录与进度保存在 system.distributed_ddl_queue 里，可以按 query_id 或状态查询。
结构一致是硬要求
各节点的表结构必须保持一致，否则副本同步会出现异常。单机直连执行不带 ON CLUSTER 的语句只会改动一台机器，集群里随即出现结构不一致。因此集群环境下的结构变更应统一带上 ON CLUSTER，并在处理完失败节点后再继续后续变更。
基本信息
| 语法 | CREATE / ALTER / DROP ... ON CLUSTER <cluster> |
|---|---|
| 查看进度 | 查询 system.distributed_ddl_queue，按 query 标识或状态过滤 |
| 硬要求 | 各节点结构必须一致，否则副本同步异常 |
| 依赖 | 集群配置与协调服务健康 |
| 适用版本 | ClickHouse 各主流版本均支持 |
示例
示例
CREATE DATABASE IF NOT EXISTS analytics ON CLUSTER prod;
CREATE TABLE analytics.events_local ON CLUSTER prod
(
ts DateTime,
id UInt64
)
ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/events_local', '{replica}')
ORDER BY (id, ts);
-- 查看分布式 DDL 的执行结果与失败节点
SELECT entry, status, status_stopped_host
FROM system.distributed_ddl_queue
ORDER BY entry DESC LIMIT 10;典型使用场景
- 建库建表：新业务上线时在所有节点同步建结构
- 结构变更：统一加列、调整编码，避免逐台操作遗漏
- 批量清理：按集群删除临时表或历史分区
- 故障补齐：个别节点漏执行时定位并补跑
- 变更审计：通过队列表确认每条 DDL 的最终状态
要素与注意
| 要素 | 含义 | 注意 |
|---|---|---|
| 集群名 | 配置中定义的集群标识 | 写错会直接报找不到集群 |
| query 标识 | 本次 DDL 的执行记录标识 | 用于在队列里定位进度 |
| status | 执行状态 | 部分节点失败会体现在这里 |
| status_stopped_host | 暂停或失败的节点 | 修复后可重跑语句补齐 |
分布式 DDL 需要健康的协调服务与同名集群配置；个别节点失败时可以修复该节点后再重跑语句，或用 SYSTEM RESTART REPLICA 处理后重新同步。
单机直连执行不带 ON CLUSTER 的 DDL 只会改一台机器，集群副本结构随后不一致，后续写入或复制可能直接报错，排查成本远高于当初把语句写全。