analyzing-range-distribution

分析范围分布

使用 SHOW RANGES 和 SHOW ZONE CONFIGURATIONS 命令分析 CockroachDB 范围分布、租约持有者的位置以及区域配置的符合情况。识别范围数量异常、大小不均、租约持有者热点和副本问题——全程通过 SQL 完成，无需访问 DB Console。

与性能分析技能互补： 此技能分析范围级数据分布；如需了解查询性能模式，请参阅 profiling-statement-fingerprints。如需规划架构变更的存储，请参阅 analyzing-schema-change-storage-risk。

何时使用此技能

• 识别范围数量过多、表明存在碎片化的表／索引
• 检测范围大小不均或节点间数据分布不均
• 调查导致读取热点的租约持有者集中情况
• 验证区域配置对范围放置和副本分布的影响
• 诊断范围级副本问题（副本不足或范围不可用）
• 分析高写入量产生的范围拆分模式
• 无需访问 DB Console，仅通过 SQL 分析范围

架构变更规划： 在执行 CREATE INDEX 或 ADD COLUMN 操作前，使用 analyzing-schema-change-storage-risk 估算存储需求。

前提条件

• 连接到 CockroachDB 集群的 SQL 连接
• Admin 角色或 ZONECONFIG 系统权限
• 了解 CockroachDB 范围架构（默认最大大小为 512MB；使用 SHOW ZONE CONFIGURATION FOR RANGE default 验证）
• 了解集群拓扑（节点 ID、区域、可用区）

检查权限：

SHOW SYSTEM GRANTS FOR <username>;  -- Should show admin or ZONECONFIG

有关 RBAC 设置，请参阅权限参考。

核心概念

范围：数据分布的基本单位

范围： 连续的键空间片段（默认最大大小为 512MB，可通过区域配置 range_max_bytes 设置） Raft 组： 每个范围都会在多个节点间复制（默认 3 个副本） 租约持有者： 负责处理读取并协调范围写入的单个副本

重要： 范围会在达到 range_max_bytes（默认 512MB）时自动拆分；高写入流量下也可能因基于负载的拆分而进一步碎片化。

租约持有者与热点

租约持有者集中： 单个节点持有的租约持有者数量明显过多，即形成读取热点 基于负载的拆分： CockroachDB 会拆分 QPS 较高的范围，从而增加范围数量 热点症状： 单个节点 CPU 使用率高，特定表／索引读取缓慢

范围碎片化

碎片化： 过多的范围拆分会产生大量小范围（带来 Raft 协调开销） 成因： 高写入吞吐量、顺序插入（基于时间戳的主键）、基于负载的拆分 症状： 相对于数据量而言范围数量过多，Raft 开销导致延迟增加

碎片化指标： 每 GB 的范围数。使用默认 range_max_bytes（512MB）时，完全扩展的范围覆盖 0.5 GB，因此每 GB 约 2 个范围是自然下限。远高于此值（例如每 GB 10 个以上范围）可能表明存在基于负载的拆分或许多小范围；请根据工作负载调整。

区域配置

区域配置： 数据库、表或索引的副本和放置策略 副本因子： 每个范围的副本数（默认：3） 约束： 节点放置规则（区域、可用区、节点属性）

使用场景： 验证预期区域配置是否与实际范围放置情况一致。

SHOW RANGES DETAILS 选项

重要安全警告： WITH DETAILS 选项会按需计算 span_stats（范围大小、键数量），导致：

• CPU 使用率高，因为需要计算统计信息
• 内存开销随范围数量增加
• 大表查询未使用 LIMIT 时可能超时

最佳实践： 使用 DETAILS 时始终加上 LIMIT，指定目标表／索引，并避免扫描整个集群。

核心诊断查询

查询 1：按表统计 Range 数量（适用于生产环境）

SELECT
  table_name,
  index_name,
  COUNT(*) AS range_count
FROM [SHOW RANGES FROM TABLE your_table_name]
GROUP BY table_name, index_name
ORDER BY range_count DESC;

解读： 小表的 Range 数量很高（数千个）表示存在碎片。请结合表大小进行交叉核对。

安全性： 不使用 DETAILS 选项，对生产环境安全且开销极小。

查询 2：Range 大小分析（针对性使用 DETAILS）

SELECT
  range_id,
  start_key,
  end_key,
  (span_stats->>'approximate_disk_bytes')::INT / 1048576 AS size_mb,
  lease_holder,
  replicas
FROM [SHOW RANGES FROM TABLE your_table_name WITH DETAILS]
ORDER BY (span_stats->>'approximate_disk_bytes')::INT DESC
LIMIT 50;

解读： 接近或超过 range_max_bytes（默认值为 512MB）的 Range 表示拆分滞后；许多较小的 Range（<10MB）则表示存在碎片。

重要： 始终包含 LIMIT 并针对特定表。切勿对整个数据库运行 SHOW RANGES WITH DETAILS。

查询 3：Leaseholder 分布（热点检测）

SELECT
  lease_holder,
  COUNT(*) AS leaseholder_count,
  ROUND(COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (), 2) AS percentage
FROM [SHOW RANGES FROM TABLE your_table_name]
GROUP BY lease_holder
ORDER BY leaseholder_count DESC;

解读： 在负载均衡的集群中，单个节点上的 Leaseholder 超过 40% 表示存在热点。请检查表的区域配置是否偏向特定节点。

修复方法： 使用 ALTER TABLE ... CONFIGURE ZONE USING lease_preferences 分散 Leaseholder。

查询 4：Range 复制健康检查

SELECT
  range_id,
  start_key,
  replicas,
  array_length(replicas, 1) AS replica_count,
  voting_replicas,
  array_length(voting_replicas, 1) AS voting_replica_count,
  lease_holder
FROM [SHOW RANGES FROM TABLE your_table_name]
WHERE array_length(replicas, 1) < 3  -- Under-replicated
ORDER BY range_id
LIMIT 100;

解读： replica_count < 3 表示副本不足（存在数据丢失风险）。请检查节点故障、节点退役操作或区域配置不匹配。

安全性： 不使用 DETAILS，对生产环境安全。

查询 5：区域配置审计

SHOW ZONE CONFIGURATIONS;

输出列：

• target：数据库、表或索引
• raw_config_sql：区域配置 SQL（复制因子、约束）

使用场景： 验证预期的复制因子和放置约束是否符合设计要求。

交叉核对： 将区域配置与查询 3（Leaseholder 分布）和查询 4（副本健康状况）进行比较，以验证实际放置情况。

查询 6：碎片分析（每 GB 的 Range 数量）

WITH range_counts AS (
  SELECT
    table_name,
    index_name,
    COUNT(*) AS range_count
  FROM [SHOW RANGES FROM TABLE your_table_name]
  GROUP BY table_name, index_name
),
table_sizes AS (
  SELECT
    table_name,
    SUM((span_stats->>'approximate_disk_bytes')::INT) / 1073741824.0 AS size_gb
  FROM [SHOW RANGES FROM TABLE your_table_name WITH DETAILS]
  GROUP BY table_name
)
SELECT
  rc.table_name,
  rc.index_name,
  rc.range_count,
  ts.size_gb,
  ROUND(rc.range_count / NULLIF(ts.size_gb, 0), 2) AS ranges_per_gb
FROM range_counts rc
JOIN table_sizes ts ON rc.table_name = ts.table_name
ORDER BY ranges_per_gb DESC;

解读：

• 健康： 1-15 个 Range/GB
• 中度碎片： 16-50 个 Range/GB
• 严重碎片： 50 个以上 Range/GB

重要： 此查询使用 DETAILS，仅对已知大小的目标表运行，切勿在整个集群范围内运行。

修复方法： 通过区域配置提高 range_max_bytes（请谨慎），或在碎片由必要的基于负载的拆分造成时接受这种情况。

有关完整的查询变体和防护措施，请参阅 sql-queries reference。

常见工作流

工作流 1：热点调查

场景： 单个节点 CPU 使用率高，特定表的读取速度慢。

步骤：

1. 确定 Leaseholder 集中情况： 对疑似表运行查询 3
2. 验证区域配置： 运行查询 5，检查 lease_preferences
3. 检查基于负载的拆分： 运行查询 1，检测近期 Range 碎片（热点的表现）
4. 修复： 配置 lease preferences 以分散读取；如果热点位于连续键范围，则对表进行分区

示例：

-- Check leaseholder distribution
SELECT lease_holder, COUNT(*) FROM [SHOW RANGES FROM TABLE hot_table] GROUP BY lease_holder;

-- Validate zone config
SHOW ZONE CONFIGURATION FOR TABLE hot_table;

-- Spread leaseholders if concentrated
ALTER TABLE hot_table CONFIGURE ZONE USING lease_preferences = '[[+region=us-west]]';

工作流 2：区域配置验证

场景： 配置多区域设置后，验证 Range 是否按约束放置。

步骤：

1. 查看预期配置： 运行查询 5（SHOW ZONE CONFIGURATIONS）
2. 检查实际副本放置情况： 对关键表运行查询 4，检查 replicas 数组中的节点 ID
3. 将节点 ID 映射到区域： 使用 SHOW REGIONS（集群范围）或读取 cockroach node status 的 locality 列
4. 识别不匹配项： 不符合约束的 Range 表示正在进行重新均衡，或存在配置错误

示例：

-- Show zone config
SHOW ZONE CONFIGURATION FOR TABLE multi_region_table;

-- Check replica placement
SELECT range_id, replicas FROM [SHOW RANGES FROM TABLE multi_region_table] LIMIT 20;

-- Map node IDs to regions (cluster-level view)
SHOW REGIONS;
-- For per-node locality strings, use the CLI:
--   cockroach node status --certs-dir=<certs-dir> --host=<any-live-node>

工作流 3：碎片诊断

场景： 表的 Range 数量相对于其大小较高，并且延迟较高。

步骤：

1. 计算每 GB 的 Range 数量： 运行查询 6（针对特定表）
2. 检查基于负载的拆分： 查看写入模式（连续插入、高 QPS 时段）
3. 判断是否符合预期： 碎片可能是为了分散负载而有意产生的
4. 若碎片过多则修复： 提高 range_max_bytes（请谨慎——Range 越大，拆分越慢），或调查如何减少写入热点

重要： range_max_bytes 的默认值为 512MB。在不了解其对拆分/重新均衡性能的影响时进一步提高该值会有风险。

安全注意事项

DETAILS 选项成本

资源影响：

• CPU： 针对每个范围按需计算跨度统计信息
• 内存： 与返回的范围数量成正比
• 超时风险： 对于包含数千个范围且未使用 LIMIT 的表，风险很高

缓解策略：

1. 始终使用 LIMIT： 探索性分析时，将范围数限制为 50-100 个
2. 指定目标表： 使用 FROM TABLE table_name，不要使用集群范围的 SHOW RANGES WITH DETAILS
3. 先运行基本查询： 使用查询 1（不带 DETAILS）评估范围数量，然后再使用 DETAILS
4. 选择生产环境运行时段： 在维护窗口或低流量时段运行

权限安全

管理员角色： 拥有完整的集群访问权限，在生产环境中谨慎使用 ZONECONFIG 权限： 仅限查看范围和区域配置，更适合只读分析

最佳实践： 为范围分析操作员授予 ZONECONFIG，而非管理员权限。

如需授予最小权限，请参阅权限参考。

对生产环境的影响

只读操作： 所有查询都是不写入数据的 SELECT 或 SHOW 语句。

性能注意事项：

查询类型	影响	适用于生产环境？
基本 SHOW RANGES	CPU 消耗极少，仅访问元数据	是
SHOW RANGES WITH DETAILS（指定目标，LIMIT 50）	CPU 短暂升高	是（低流量时段）
SHOW RANGES WITH DETAILS（不带 LIMIT）	CPU 消耗高，有超时风险	否——绝不可使用
SHOW ZONE CONFIGURATIONS	影响极小，仅访问元数据	是

故障排除

问题	原因	修复方法
权限被拒绝	缺少管理员或 ZONECONFIG 权限	授予 ZONECONFIG：GRANT SYSTEM ZONECONFIG TO user
使用 DETAILS 时查询超时	未使用 LIMIT，范围过多	添加 LIMIT 50，并指定目标表
span_stats 列为空	缺少 DETAILS 关键字	在 SHOW RANGES 中添加 WITH DETAILS
范围数量异常偏高	基于负载的拆分或碎片化	运行查询 6 计算范围/GB，并检查写入模式
Leaseholder = 0 或 NULL	再平衡期间范围正在迁移	集群变更期间属正常情况，请重试查询
范围副本数不足	节点故障、退役或区域不匹配	检查节点状态，验证区域配置约束
SHOW ZONE CONFIGURATIONS 未显示自定义配置	正在使用默认的集群级配置	如果未设置表级或数据库级覆盖配置，则属正常情况

关键注意事项

• DETAILS 选项： 操作开销较大——始终搭配 LIMIT 并指定目标范围
• 碎片化有时是有意为之： 基于负载的拆分可提高并发能力
• Leaseholder 集中度： 在判断存在热点前，先检查区域配置（lease_preferences）
• 范围大小目标： 默认 range_max_bytes 为 512MB（使用 SHOW ZONE CONFIGURATION FOR RANGE default 验证）
• 复制延迟： 范围放置位置可能不会立即反映区域配置变更（再平衡需要时间）
• 交叉引用查询： 将范围分析与区域配置结合，全面了解情况
• 节点映射： 使用 SHOW REGIONS 查看集群级本地性，或使用 cockroach node status 查看各节点的本地性

参考资料

技能参考资料：

• SQL 查询变体和防护措施
• RBAC 和权限设置

CockroachDB 官方文档：

• SHOW RANGES
• SHOW ZONE CONFIGURATIONS
• 架构：分布层
• 配置复制区域
• ZONECONFIG 权限

相关技能：

• profiling-statement-fingerprints - 用于查询性能分析
• triaging-live-sql-activity - 用于实时查询分诊
• analyzing-schema-change-storage-risk - 用于在执行 DDL 操作前估算存储需求