ClickHouse集群删除同步超时：如何等待所有副本完成删除？

问题背景 #

在400亿行的表中，需基于event_date列删除某一天的约5000万行数据，使用带WHERE子句的lightweight delete，但WHERE条件列不在PRIMARY KEY的ORDER BY中，因此需要全表扫描。当前无法采用分区、修改主键等优化方案，希望执行删除操作时，直到所有副本完成删除后才结束会话，而非180秒后被中断（已知后台仍在运行）。

执行DELETE FROM ... ON CLUSTER时已设置以下参数：

• alter_sync = 2
• replication_wait_for_inactive_replica_timeout = 600
• mutations_sync = 2

但操作超过120秒后仍报错：

DB::Exception: Watching task /clickhouse/cluster_name/task_queue/ddl/query-0023446431 is executing longer than distributed_ddl_task_timeout (=180) seconds. There are 10 unfinished hosts (0 of them are currently active), they are going to execute the query in background.

解决方案 #

报错的核心原因是**distributed_ddl_task_timeout参数默认值（180秒）不足以覆盖全表扫描删除的耗时**，这个参数控制着ClickHouse等待分布式DDL任务完成的最大超时时间。要让会话持续等待直到所有副本完成，需调整该参数：

1. 会话级别临时调整（推荐） #

在执行DELETE语句前，先设置会话级别的超时参数，仅对当前会话生效，不会影响全局配置：

SET distributed_ddl_task_timeout = 86400; -- 设置为24小时，可根据实际需求调整

如果希望无限等待直到任务完成，可以设置为0：

SET distributed_ddl_task_timeout = 0;

设置完成后，再执行你的DELETE语句：

DELETE FROM your_table ON CLUSTER cluster_name 
WHERE event_date = 'target_date'
SETTINGS alter_sync = 2, replication_wait_for_inactive_replica_timeout = 600, mutations_sync = 2;

2. 全局配置调整（不推荐，除非长期需要） #

如果需要全局生效，可以修改ClickHouse的配置文件（config.xml或users.xml）：

• 在config.xml中添加或修改：

<distributed_ddl_task_timeout>86400</distributed_ddl_task_timeout>

• 或者在users.xml的对应用户配置中添加：

<profile>
    <default>
        <distributed_ddl_task_timeout>86400</distributed_ddl_task_timeout>
    </default>
</profile>

修改后需要重启ClickHouse服务生效。

注意事项 #

• 设置distributed_ddl_task_timeout = 0会让会话无限等待，若有副本出现故障或任务卡住，会话将一直处于挂起状态，需谨慎使用。
• 由于是全表扫描的删除操作，本身耗时较长，建议根据预估的删除时间设置合理的超时值，避免不必要的资源占用。

内容的提问来源于stack exchange，提问作者Alexandr