ClickHouse 分布式表与本地表：查询路由机制与数据一致性-程序员充电站

ClickHouse 分布式表与本地表：查询路由机制与数据一致性

一、分布式查询的隐藏陷阱：你以为的"分布式"可能只是"转发"

ClickHouse 的分布式架构中，分布式表（Distributed Engine）和本地表（ReplicatedMergeTree 等）的关系是理解查询行为的关键。分布式表本身不存储数据，它只是一个查询路由层——接收查询请求，将查询分发到各个分片的本地表上执行，然后汇总结果。

这个"查询路由"看似简单，实则暗藏多个工程陷阱。第一，查询路由的延迟开销：分布式表需要与每个分片建立连接、发送查询、等待响应，网络延迟会叠加到查询时间中。第二，数据一致性问题：本地表的副本之间可能存在复制延迟，不同副本返回的数据可能不一致。第三，路由策略的选择：ClickHouse 支持随机路由、轮询路由和优先级路由，不同策略对查询性能和负载均衡的影响差异显著。

在存储部的 ClickHouse 集群中，我们遇到过这样的案例：一个分布式查询在 3 个分片上执行，其中一个分片的副本正在合并 Part，导致该分片响应超时，整个查询被取消。这不是 ClickHouse 的 Bug，而是分布式查询路由机制的设计取舍。

二、分布式表查询路由的底层机制

2.1 分布式表的查询执行流程

当客户端向分布式表发送查询时，ClickHouse 的执行流程如下：

flowchart TD A[客户端发送查询到分布式表] --> B[解析查询 SQL] B --> C[确定分片列表] C --> D[为每个分片选择副本] D --> E{路由策略} E -->|随机| F[随机选择一个副本] E -->|轮询| G[按顺序选择副本] E -->|优先级| H[选择延迟最低的副本] F --> I[向各分片发送子查询] G --> I H --> I I --> J[各分片本地执行查询] J --> K[汇总结果到发起节点] K --> L[返回结果给客户端] subgraph 单分片内部 M[本地表 Replica 1] N[本地表 Replica 2] O[复制同步通道] M <-->|数据复制| N end

关键细节：分布式表将原始查询的 SQL 文本原样发送到各分片，各分片独立解析和执行。这意味着各分片的 ClickHouse 版本和配置必须兼容，否则可能出现语法错误。

2.2 副本选择与负载均衡

ClickHouse 的副本选择策略由load_balancing参数控制：

random（默认）：随机选择一个副本。简单但可能导致负载不均。
round_robin：轮询选择副本。负载更均衡，但不考虑副本的实际负载。
first_or_random：优先选择配置中的第一个副本，如果不可达则随机选择。适合有主从区分的场景。
in_order：按配置顺序尝试副本，第一个不可达则尝试第二个。适合有明确优先级的场景。

副本的健康检查基于 TCP 连接探测，不检查副本的数据完整性。如果一个副本的复制队列积压了 100 万条记录，但 TCP 连接正常，它仍然会被选为查询目标。

2.3 数据一致性的三个层次

分布式查询的数据一致性取决于三个因素：

分片内一致性：同一分片的不同副本之间，通过 ReplicatedMergeTree 的复制机制保证最终一致性。但存在复制延迟——写入主副本后，从副本可能需要数秒才能同步。
分片间一致性：不同分片之间没有事务保证。一个 INSERT 可能成功写入部分分片而失败于其他分片，导致数据不完整。
查询一致性：分布式查询在汇总时，各分片返回的是查询时刻本地表的数据快照。如果查询过程中有数据写入，不同分片可能看到不同版本的数据。

三、生产级配置与最佳实践

3.1 分布式表与本地表的规范定义

-- 本地表：每个分片的每个副本上创建 CREATE TABLE orders_local ON CLUSTER '{cluster}' ( order_id UInt64, user_id UInt64, amount Decimal(12, 2), product_category LowCardinality(String), city LowCardinality(String), created_at DateTime ) ENGINE = ReplicatedMergeTree( '/clickhouse/tables/{cluster}/{database}/orders_local/{shard}', '{replica}' ) PARTITION BY toYYYYMM(created_at) ORDER BY (city, product_category, created_at) SETTINGS index_granularity = 8192; -- 分布式表：只在查询入口节点创建 CREATE TABLE orders_all ON CLUSTER '{cluster}' ( order_id UInt64, user_id UInt64, amount Decimal(12, 2), product_category LowCardinality(String), city LowCardinality(String), created_at DateTime ) ENGINE = Distributed( '{cluster}', currentDatabase(), 'orders_local', -- 分片键：按 user_id 哈希分片 xxHash64(user_id) ) SETTINGS -- 路由策略：优先低延迟副本 load_balancing = 'in_order', -- 发送查询的超时时间 distributed_ddl_task_timeout = 180;

3.2 写入策略：直接写本地表 vs 写分布式表

-- 方式 1：直接写本地表（推荐） -- 客户端根据分片键计算目标分片，直接写入对应分片的本地表 -- 优点：写入延迟低，无分布式事务开销 -- 缺点：客户端需要实现分片路由逻辑 -- 方式 2：写分布式表 -- ClickHouse 自动按分片键路由写入 -- 优点：客户端无需关心分片逻辑 -- 缺点：写入需要经过分布式表的转发，延迟更高 INSERT INTO orders_all VALUES (1, 1001, 99.90, '电子产品', '北京', '2026-06-12 10:00:00'); -- 内部流程：分布式表接收 → 计算分片 → 转发到目标分片的本地表

生产环境的推荐策略是：写入走本地表，查询走分布式表。写入时由客户端或中间件层（如 CHProxy）负责分片路由，避免分布式表的写入转发开销。

3.3 复制延迟监控与查询降级

-- 监控复制延迟：查看每个副本的复制队列深度 SELECT database, table, replica_name, absolute_delay, -- 主副本与当前副本的延迟秒数 queue_size, -- 复制队列中待处理的条目数 parts_to_check -- 需要校验的 Part 数量 FROM system.replicas WHERE absolute_delay > 60 -- 延迟超过 60 秒的副本 ORDER BY absolute_delay DESC; -- 查询降级：当副本延迟过高时，排除该副本 SET load_balancing = 'in_order'; -- 配置优先级：将健康副本排在前面，延迟副本排在后面 -- 在 config.xml 中配置 <remote_servers> 的 <replica> 顺序

3.4 分布式查询的超时与重试

-- 设置分布式查询的超时时间 SET max_execution_time = 300; -- 单分片查询最大执行时间 300s SET connect_timeout = 10; -- 连接超时 10s SET receive_timeout = 300; -- 接收数据超时 300s SET send_timeout = 300; -- 发送数据超时 300s -- 设置连接池参数，减少连接建立开销 SET distributed_connections_pool_size = 16; -- 每个分片的连接池大小 SET connections_with_failover_max_tries = 3; -- 连接失败时的重试次数