analyzing-range-distribution

レンジ分布の分析

SHOW RANGES および SHOW ZONE CONFIGURATIONS コマンドを使用して、CockroachDB のレンジ分布、リースホルダーの配置、ゾーン設定への準拠状況を分析します。レンジ数の異常、サイズの不均衡、リースホルダーのホットスポット、レプリケーションの問題を、DB Console にアクセスすることなく、すべて SQL で特定します。

プロファイリングスキルとの補完関係： このスキルはレンジレベルのデータ分布を分析します。クエリパフォーマンスのパターンについては、profiling-statement-fingerprints を参照してください。スキーマ変更に伴うストレージ計画については、analyzing-schema-change-storage-risk を参照してください。

このスキルを使用する場面

• 過剰なレンジ数から断片化が疑われるテーブル／インデックスを特定する
• ノード間のレンジサイズの不均衡やデータ分布の偏りを検出する
• 読み取りのホットスポットを引き起こすリースホルダーの集中を調査する
• レンジの配置とレプリカ分布に対するゾーン設定の影響を検証する
• レンジレベルのレプリケーションの問題（レプリカ数不足または利用不可のレンジ）を診断する
• 書き込み量が多い場合のレンジ分割パターンを分析する
• DB Console にアクセスせず、SQL のみでレンジを分析する

スキーマ変更の計画について： CREATE INDEX または ADD COLUMN 操作の前にストレージ要件を見積もるには、analyzing-schema-change-storage-risk を使用してください。

前提条件

• CockroachDB クラスターへの SQL 接続
• 管理者ロール、または 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）に達すると自動的に分割されますが、書き込みトラフィックが多いと、負荷ベースの分割によってさらに細分化されることがあります。

リースホルダーとホットスポット

リースホルダーの集中： 1 つのノードが不均衡に多くのリースホルダーを保持している場合、読み取りのホットスポットになります 負荷ベースの分割： CockroachDB は QPS の高いレンジを分割するため、レンジ数が増加します ホットスポットの兆候： 1 つのノードの CPU 使用率が高い、特定のテーブル／インデックスの読み取りが遅い

レンジの断片化

断片化： 過剰なレンジ分割によって多数の小さなレンジが作成される状態です（Raft 調整のオーバーヘッドが発生します） 原因： 高い書き込みスループット、連番の挿入（タイムスタンプベースの主キー）、負荷ベースの分割 症状： データサイズに対してレンジ数が多い、Raft オーバーヘッドによるレイテンシの増加

断片化の指標： GB あたりのレンジ数です。デフォルトの range_max_bytes は 512MB なので、十分に大きくなったレンジ 1 つで 0.5 GB を占めます。したがって、約 2 レンジ／GB が自然な下限です。この値を大きく上回る場合（例：10 レンジ／GB 以上）、負荷ベースの分割や多数の小さなレンジが疑われます。ワークロードに合わせて調整してください。

ゾーン設定

ゾーン設定： データベース、テーブル、またはインデックスに対するレプリケーションと配置のポリシーです レプリケーション係数： レンジあたりのレプリカ数です（デフォルト：3） 制約： ノードの配置ルール（リージョン、アベイラビリティゾーン、ノード属性）

用途： 意図したゾーン設定が実際のレンジ配置と一致しているかを検証します。

SHOW RANGES の DETAILS オプション

重大な安全上の警告： WITH DETAILS オプションは span_stats（レンジサイズ、キー数）をオンデマンドで計算するため、次の影響が生じます。

• 統計計算による高い CPU 使用率
• レンジ数に応じて増加するメモリーオーバーヘッド
• LIMIT を指定しない場合、大きなテーブルでのクエリータイムアウト

ベストプラクティス： DETAILS を使用する際は必ず LIMIT を指定し、対象のテーブル／インデックスを絞り込み、クラスター全体のスキャンは避けてください。

主な診断クエリー

クエリ 1：テーブルごとの範囲数（本番環境でも安全）

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;

解釈： 小規模なテーブルで範囲数が非常に多い（数千単位）場合は、断片化が発生している可能性があります。テーブルサイズと照らし合わせて確認してください。

安全性： DETAILS オプションを指定しないため、本番環境でも安全で、オーバーヘッドは最小限です。

クエリ 2：範囲サイズの分析（対象を限定した 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）に近い、またはそれを超える範囲は、分割の遅延を示します。小さな範囲（10MB 未満）が多数ある場合は、断片化を示します。

重要： 必ず LIMIT を含め、特定のテーブルを対象にしてください。データベース全体に対して SHOW RANGES WITH DETAILS を実行しないでください。

クエリ 3：リース保持者の分布（ホットスポットの検出）

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;

解釈： 負荷が均衡したクラスターで、単一ノードにリース保持者が 40％を超えて集中している場合は、ホットスポットが発生している可能性があります。特定のノードが優先されるゾーン制約がテーブルに設定されていないか確認してください。

対処方法： ALTER TABLE ... CONFIGURE ZONE USING lease_preferences を使用して、リース保持者を分散させます。

クエリ 4：範囲レプリケーションの健全性チェック

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（リース保持者の分布）およびクエリ 4（レプリカの健全性）の結果とゾーン設定を比較し、実際の配置を検証します。

クエリ 6：断片化の分析（GB あたりの範囲数）

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 範囲/GB
• 中程度の断片化： 16～50 範囲/GB
• 深刻な断片化： 50 範囲/GB 以上

重要： このクエリは DETAILS を使用します。サイズが分かっている対象テーブルに対してのみ実行し、クラスター全体に対しては実行しないでください。

対処方法： ゾーン設定で range_max_bytes を増やす（慎重に行ってください）か、負荷に応じた分割が必要なために発生した断片化を許容します。

クエリのバリエーションと安全策の詳細については、sql-queries リファレンスを参照してください。

よくあるワークフロー

ワークフロー 1：ホットスポットの調査

シナリオ： 特定のテーブルで読み取りが遅く、単一ノードの CPU 使用率が高い。

手順：

1. リース保持者の集中を特定する： 疑わしいテーブルに対してクエリ 3 を実行します
2. ゾーン設定を検証する： クエリ 5 を実行して lease_preferences を確認します
3. 負荷に応じた分割を確認する： クエリ 1 を実行して、最近の範囲の断片化（ホットスポットの兆候）を検出します
4. 対処する： リース設定を構成して読み取りを分散させるか、ホットスポットが連番キーの範囲にある場合はテーブルをパーティション分割します

例：

-- 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：ゾーン設定の検証

シナリオ： マルチリージョン構成の設定後、制約に従って範囲が配置されていることを検証します。

手順：

1. 意図した設定を確認する： クエリ 5（SHOW ZONE CONFIGURATIONS）を実行します
2. 実際のレプリカ配置を確認する： 重要なテーブルに対してクエリ 4 を実行し、replicas 配列のノード ID を確認します
3. ノード ID をリージョンに対応付ける： クラスター全体を対象に SHOW REGIONS を使用するか、cockroach node status の locality 列を確認します
4. 不一致を特定する： 制約に合致しない範囲がある場合は、リバランス中か設定に誤りがあることを示します

例：

-- 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：断片化の診断

シナリオ： サイズに対して範囲数が多く、レイテンシーが発生しているテーブル。

手順：

1. GB あたりの範囲数を計算する： クエリ 6 を実行します（特定のテーブルを対象にします）
2. 負荷に応じた分割を確認する： 書き込みパターン（連番の挿入、QPS が高い時間帯）を確認します
3. 想定どおりか判断する： 負荷分散のために、意図的に断片化されている場合があります
4. 過剰な場合は対処する： range_max_bytes を増やす（慎重に行ってください。範囲が大きいほど分割が遅くなります）か、書き込みホットスポットの削減を検討します

重要： range_max_bytes のデフォルト値は 512MB です。分割やリバランスのパフォーマンスへの影響を理解せずに値をさらに引き上げるのは危険です。

安全性に関する考慮事項

DETAILS オプションのコスト

リソースへの影響：

• CPU： 範囲ごとにオンデマンドでスパン統計を計算します
• メモリ： 返される範囲数に比例します
• タイムアウトのリスク： LIMIT なしで数千の範囲があるテーブルでは高くなります

軽減策：

1. 常に LIMIT を使用する： 探索的な分析では、範囲数を 50～100 に制限します
2. 対象テーブルを指定する： FROM TABLE table_name を使用し、クラスター全体を対象とする SHOW RANGES WITH DETAILS は使用しないでください
3. まず基本クエリを使用する： DETAILS を使用する前に、Query 1（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 を追加します
範囲数が予想より多い	負荷に基づく分割または断片化	Query 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 操作の前に必要なストレージ容量を見積もるために使用します