altinity-expert-clickhouse-merges

マージの健全性とパーツの滞留

system.merges、system.part_log、system.parts から、「マージは実行されているか、どのテーブルが対象か、何が妨げになっているか」に回答します。 接続モード、クラスター、時間範囲がまだ確定していない場合は、先に altinity-expert-clickhouse-connection を実行してください。

クエリパック

• checks.sql — 8 つのチェック：メモリ、アルゴリズム、種類を含む現在のマージ状況（merges-01）、ホスト別およびクラスター全体のアクティブなマージメモリ（merges-02、merges-03）、時間別のマージ成功／失敗の傾向（merges-04）、テーブル単位のマージ判定（merges-05）、マージ理由とアルゴリズムのマトリクス（merges-06）、テーブル別のマージ RAM ピーク（merges-07）、パーツ数の要注意テーブル（merges-08）。merges-04 から merges-07 までのチェックには system.part_log が必要です。
• reference.md — 背景情報（マージと TTL の設定、アドホッククエリの安全策）。推奨事項の説明が必要な場合にのみ読みます。

クエリパックの実行方法

1. スキルのディレクトリから各パックファイルを読み込みます（スキルローダーがディレクトリパスを出力します）。
2. ステートメントはファイル全体ではなく、1 つずつ実行します。ステートメントは ; で終わり、-- @check <id> <title> ヘッダーで始まります。結果には ID を付けてください。
3. -- @requires に従います。指定されたテーブルがない場合、keeper が必須なのにサーバーに Keeper／ZooKeeper がない場合、またはバージョン条件を満たさない場合は、そのステートメントをスキップします。スキップした ID と理由を一覧にしてください。
4. クラスターのマクロが存在する場合は、{cluster} を記載どおりに使用します。存在しない場合は、接続スキルの書き換えルールを適用します。その他の {placeholder} はテンプレート変数です。実際の値に置き換えるか、ステートメントをスキップしてください。
5. エラーが発生した場合は、チェック ID とエラーの最初の行を記録してから続行します。UNKNOWN_IDENTIFIER の場合に限り、DESCRIBE TABLE system.<table> を実行し、存在しない列を取り除きます。
6. severity 列はその行の判定です。そのまま転記し、再判定しないでください。

解釈ルール

チェックは ID 順に実行します。現在のマージ（merges-01）、次に履歴の傾向（merges-04）、テーブル単位の判定（merges-05）、理由とアルゴリズム（merges-06）、現在およびピーク時の RAM（merges-02、merges-03、merges-07）、最後にパーツ数の要注意テーブル（merges-08）の順です。

• レポートの最後には、判定を必ず 1 つだけ記載します。PROVED（時間範囲内に成功したマージが 1 つもない）、DECLINED（クラスター全体でマージが成功している）、または PARTIAL（特定のテーブルでブロックされている一方、ほかのテーブルではマージが継続している）。
• 同じ時間範囲内にマージに成功しているテーブルが 1 つでもある場合、判定は PARTIAL または DECLINED です。クラスター全体のマージ停止とは判定しないでください。
• merge_ok = 0 で MEMORY_LIMIT_EXCEEDED が繰り返し発生しているテーブルは、テーブル単位のブロックであり、クラスター全体のブロックではありません。
• マージの 100 パーセントが Horizontal の場合は、プランナーが水平マージを選択したと伝えてください。マージツリーの設定で確認できない限り、垂直アルゴリズムが無効だとは主張しないでください。
• merges-08 で最大のパーツ数が system.* テーブルに由来する場合は、検出元とアラートの対象の不一致を明記し、業務テーブルに誤って原因を帰属させないようにしてください。
• merges-07 の RAM ピークは履歴上の値です。現在マージが行われていない状態でピーク値が高い場合、問題はすでに発生したものであり、現在発生中ではありません。
• system.part_log がない場合、merges-04 から merges-07 はスキップされるため、クラスター全体のマージ停止は証明できません。判定を選ぶのではなく、「part_log がないため証明できません」と伝えてください。

証拠が裏付ける場合に挙げるべき構造上の原因：

• 単一のホットパーティション（partition_id = 'all'）では、各マージでテーブル全体を再読み込みします。時間ベースのパーティショニングを推奨してください。
• 高頻度でデータが取り込まれるテーブルで負荷の高い TTL ... GROUP BY ... SET ... があると、マージが直列化されます。ロールアップをマテリアライズドビューまたはバッチテーブルに移し、ベーステーブルの TTL は削除のみにしてください。
• 大規模な水平マージが繰り返し OOM で失敗する場合、原因はプールの容量ではなく、行幅とパーツサイズにあると考えられます。
• マージが正常なのにパーツが増え続ける場合、挿入のペースがマージを上回っています。マージ設定ではなく、挿入バッチのサイズと頻度を調整してください。

詳細な分析

直近1時間における、1つのテーブルの挿入速度とマージ速度です。net_reduction が数分間にわたり負の値を維持している場合、マージより挿入のほうが多いことを意味します。

SELECT
    toStartOfMinute(event_time) AS minute,
    countIf(event_type = 'NewPart') AS new_parts,
    countIf(event_type = 'MergeParts') AS merges,
    countIf(event_type = 'MergeParts') - countIf(event_type = 'NewPart') AS net_reduction
FROM system.part_log
WHERE database = '{database}'
  AND table = '{table}'
  AND event_time > now() - INTERVAL 1 HOUR
GROUP BY minute
ORDER BY minute DESC
LIMIT 60;

レポート形式

1. ヘッダー：接続モード、クラスターまたは「単一ノード」、ClickHouse のバージョン、時間範囲。
2. 調査結果：check、severity、object、evidence、recommendation の列を持つテーブル。調査結果ごとに1行を記載し、Critical を先頭にします。根拠には結果行の数値を引用します。
3. 問題のないチェック：問題のある行が返されなかったチェック ID を1行で列挙します。
4. スキップしたチェックと失敗したチェック：ID と理由、またはエラーの最初の行を記載します。このセクションは省略しないでください。
5. 次のステップ：次に読み込むスキルと、直ちに行う対応。

調査結果セクションの最初の行に、PROVED／DECLINED／PARTIAL の判定を記載します。

次のスキル

• マージが MEMORY_LIMIT_EXCEEDED で失敗する、またはマージ時のピーク RAM が上限に近い → スキル altinity-expert-clickhouse-memory を読み込みます
• ディスクのスループットは正常なのにマージが遅い、またはパーティショニングと ORDER BY の設定が適切でないように見える → スキル altinity-expert-clickhouse-schema を読み込みます
• ディスク I/O が高い、またはディスクの空き容量がないためにマージが遅い → スキル altinity-expert-clickhouse-storage を読み込みます
• マージキューがミューテーションで滞留している、または MutatePart エラーが発生している → スキル altinity-expert-clickhouse-mutations を読み込みます
• マージの問題とともにレプリケーションの遅延やレプリケーションキューの増加が見られる → スキル altinity-expert-clickhouse-replication を読み込みます
• マージ容量ではなく、パーツの作成速度が主な要因である → スキル altinity-expert-clickhouse-ingestion を読み込みます
• パーツごとの詳細な履歴が必要 → スキル altinity-expert-clickhouse-part-log を読み込みます