altinity-expert-clickhouse-mutations

Mutation の追跡と分析

system.mutations、system.merges、system.parts、system.replication_queue、system.part_log から、「この Mutation が停止している、または遅いのはなぜか」という疑問に答えます。Mutation はバックグラウンドでパーツ全体を書き換える処理であり、トランザクションによる行の更新ではありません。 接続モード、クラスター、時間範囲がまだ確定していない場合は、先に altinity-expert-clickhouse-connection を実行してください。

クエリパック

• checks.sql — 11 個のチェック：現在の Mutation の状態、テーブルごとの Mutation の概要、経過時間による停止中の Mutation の検出、最近完了した Mutation、テーブルごとの Mutation の実行時間、パーツログ内の失敗した Mutation、現在実行中の Mutation、Mutation 待ちのパーツ、バックグラウンドプールをめぐる Mutation とマージの競合、Mutation の作成率、Mutation コマンドの種類ごとの内訳です。このうち 3 個には system.part_log が必要です。
• reference.md — 背景情報（設定、サイズ調整、アンチパターン）。推奨事項の説明が必要な場合にのみ読みます。

クエリパックの実行方法

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 カラムは、その行の判定です。その値をそのままコピーし、再判定しないでください。

詳細調査用ステートメント

停止中の Mutation が特定できたら、以下の 3 つのステートメントで、何が妨げになっているかを確認します。check mutations-03 のテーブルから {database} と {table} を置き換えてください。

同じテーブルで競合しているマージを確認します。Mutation は、マージ中のパーツでは開始できないためです。

SELECT hostName() AS host, database, table, is_mutation, elapsed, progress, num_parts, result_part_name
FROM clusterAllReplicas('{cluster}', system.merges)
WHERE database = '{database}' AND table = '{table}';

同じテーブルのレプリケーションキューを確認します。レプリケートされたテーブルでは、Mutation はキューエントリであり、無限に再試行されることがあるためです。

SELECT hostName() AS host, type, create_time, is_currently_executing, num_tries, last_exception
FROM clusterAllReplicas('{cluster}', system.replication_queue)
WHERE database = '{database}' AND table = '{table}'
ORDER BY create_time
LIMIT 20;

パーツごとの Mutation バージョンを確認します。data_version は、そのパーツが適用済みの Mutation バージョンです。値にばらつきがある場合、Mutation は一部のパーツにしか適用されていません。

SELECT hostName() AS host, name, active, level, data_version, modification_time
FROM clusterAllReplicas('{cluster}', system.parts)
WHERE database = '{database}' AND table = '{table}' AND active
ORDER BY data_version DESC, modification_time DESC
LIMIT 30;

解釈ルール

• 検出事項とは、テーブルに保留中のミューテーションが10件を超えている場合、1時間を超えているミューテーションがある場合、または latest_fail_reason が空でない場合を指します。3つのうちいずれか1つに該当すれば十分です。証拠として mutation_id、経過時間、失敗理由を引用してください。
• latest_fail_reason が空でなく、num_tries が増加している場合、そのミューテーションは進行中ではなく再試行中です。まず例外テキストを確認してください。メモリ制限、カラムの欠落、型エラーでは必要な修正が異なり、ミューテーションが自然に成功することはありません。
• 頻繁に実行される小規模な ALTER UPDATE ステートメントが、キュー増大の一般的な原因です。それぞれが該当するすべてのパーツを書き換えるミューテーションを作成します。多数の行更新を1つのミューテーションにまとめるか、更新をINSERTとして処理する ReplacingMergeTree モデルまたは CollapsingMergeTree モデルへの移行を推奨してください。
• WHERE 句がない ALTER DELETE、または大半の行に一致する ALTER DELETE は、テーブル全体を書き換えます。代わりに TTL または DROP PARTITION を推奨してください。どちらもメタデータレベルの操作で、比較するとほぼ瞬時に完了します。
• 同じテーブルに対する多数の同時ミューテーションは、いずれにせよ順番に実行され、マージを妨げます（mutations-09 を確認してください）。並列で実行するのではなく、1つずつ実行するよう推奨してください。
• 停滞したミューテーションをキャンセルするには、ユーザーが check mutations-01 の mutation_id とデータベース名、テーブル名を指定した WHERE 句を付けて KILL MUTATION を実行できます。自分では実行しないでください。ミューテーションを停止すると、テーブルは一部だけ変更された状態になります。一部のパーツには新しいデータが反映され、ほかのパーツには反映されません。また、自動ロールバックはありません。
• @requires table:system.part_log とマークされたチェックは、part_log が無効の場合にスキップされます。これがないと、ミューテーションの所要時間や過去の失敗は不明です。ミューテーションが問題なく完了したと報告するのではなく、その旨を伝えてください。

レポート形式

1. ヘッダー：接続モード、クラスターまたは「シングルノード」、ClickHouse のバージョン、時間範囲。
2. 検出事項：check、severity、object、evidence、recommendation の列を含むテーブル。検出事項ごとに1行とし、Critical を先頭にします。Evidence には結果行の数値を引用します。
3. 問題のなかったチェック：問題のある行が返されなかったチェック ID を1行に列挙します。
4. スキップおよび失敗したチェック：ID と理由、または最初のエラー行。必ずこのセクションを含めてください。
5. 次のステップ：次に読み込むスキルと、すぐに行うアクション。

次のスキル

• アクティブなマージによってミューテーションがブロックされている場合、またはバックグラウンドプールが飽和している場合 → スキル altinity-expert-clickhouse-merges を読み込みます
• MEMORY_LIMIT_EXCEEDED によってミューテーションが失敗している場合、またはピークメモリ使用量が高い場合 → スキル altinity-expert-clickhouse-memory を読み込みます
• 大きなパーツに対するミューテーションが遅く、ディスクまたは IO が飽和している場合 → スキル altinity-expert-clickhouse-storage を読み込みます
• ミューテーションがレプリケーションキューで停滞している場合、または1つのレプリカにしか適用されていない場合 → スキル altinity-expert-clickhouse-replication を読み込みます
• 頻繁な更新から、テーブルを Replacing または Collapsing にすべきと判断できる場合 → スキル altinity-expert-clickhouse-schema を読み込みます
• ミューテーションの例外についてサーバーログ全体のテキストが必要な場合 → スキル altinity-expert-clickhouse-logs を読み込みます