altinity-expert-clickhouse-caches

キャッシュの分析とチューニング

system.metrics、system.asynchronous_metrics、system.events、system.parts、system.server_settings、system.metric_logから、「キャッシュのサイズは適切か、効果を発揮しているか」という疑問に答えます。 接続モード、クラスター、時間範囲がまだ確定していない場合は、まずaltinity-expert-clickhouse-connectionを実行してください。

クエリパック

• checks.sql — 12個のチェック：マークキャッシュの健全性（ヒット率とRAMに占める割合）、非圧縮キャッシュの健全性、クエリキャッシュ、コンパイル済み式キャッシュ、テーブルごとのマークバイト数、テーブルごとの主キーのメモリ使用量、時間経過に伴うキャッシュイベント、現在のキャッシュサーバー設定、マークキャッシュのサイズ分析、本日クエリされたテーブルに対するヒット率の診断、過剰な数のマークを保持しているテーブル、および直近1時間のマークキャッシュヒット率（分ごと）。checks-07にはsystem.asynchronous_metric_log、checks-12にはsystem.metric_logが必要です。これらのテーブルがない場合はスキップしてください。
• reference.md — 背景情報（設定、サイズ設定、アンチパターン）。推奨事項の説明が必要な場合にのみ読んでください。

クエリパックの実行方法

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

解釈ルール

• caches-01とcaches-02は2つの判定カラム、hit_severityとsize_severityを返します。キャッシュのサイズが適切でも役に立たないことがあり、効果があっても大きすぎることがあります。両方を転記してください。
• マークキャッシュのヒット率が0.7未満の場合はModerate、0.5未満の場合はMajor、0.3未満の場合はCriticalです。原因は、順に、ワーキングセットに対してキャッシュが小さすぎること、クエリが多数の異なるテーブルにアクセスすること、またはキャッシュされていないデータに対する小さなクエリが大量にあることです。サイズを変更する前に、caches-10を使って原因を見分けてください。
• マークキャッシュがRAMの15パーセントを超える場合、ヒット率が完璧でも問題として報告します。原因は次の順に対処してください。caches-11に表示されたテーブルのindex_granularityを大きくする、マージによって小さなパーツの数を減らす、未使用のテーブルを削除する、その後でのみmark_cache_sizeを小さくする。キャッシュを小さくするためにindex_granularityを小さくしてはいけません。粒度を小さくすると、マークの数は減るのではなく増えます。
• caches-09は目標値を示します。理想的なマークキャッシュのサイズは、ディスク上のマーク総数とRAMの15パーセントの小さい方です。マーク総数がすでにこの値を超えている場合、キャッシュはワーキングセットを保持できず、問題はスキーマにあります。
• 多数のミスが発生し、非圧縮キャッシュのヒット率がほぼゼロの場合でも、判定はCriticalではなくModerateです。サイズが0（無効）でも、本番環境での正当な選択です。このキャッシュが効果を発揮するのは、use_uncompressed_cacheがクエリまたはプロファイルごとに有効になっており、同じ小さなポイント読み取りが繰り返される場合に限られます。
• caches-08にはサーバー設定のみが表示されます。mark_cache_sizeとuncompressed_cache_sizeはサーバー設定です。クエリキャッシュのサイズはサーバー設定ファイルの<query_cache><max_size_in_bytes>にあり、結果に含まれない場合があります。use_query_cacheとuse_uncompressed_cacheはクエリレベルの設定なので、ここには表示されません。
• 非決定的なクエリや一度しか実行されないクエリが原因のクエリキャッシュミスは想定内です。クエリキャッシュが効果を発揮するのは、同一の決定的なクエリが繰り返される場合に限られます。
• caches-06の主キーのメモリ使用量はキャッシュではなく、追い出しもできません。キャッシュのサイズ設定とは分けて報告してください。

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

1 つのデータベース内のテーブルごとのマーク数を調べ、マークキャッシュを埋めているものを特定します。

SELECT table, count() AS parts, sum(marks) AS marks, formatReadableSize(sum(marks_bytes)) AS marks_size, formatReadableSize(sum(bytes_on_disk)) AS data_size FROM system.parts WHERE active AND database = '{database}' GROUP BY table ORDER BY sum(marks_bytes) DESC LIMIT 20;

1 つのテーブルで実際に適用されている index_granularity を確認し、変更を推奨する前に確かめます。

SELECT database, table, engine, create_table_query FROM system.tables WHERE database = '{database}' AND name = '{table}';

caches-03 でキャッシュが埋まっていることが示された場合に、クエリキャッシュのサイズが最大のエントリーを確認します。

SELECT substring(query, 1, 120) AS query_preview, formatReadableSize(result_size) AS result_size, stale, shared, expires_at FROM system.query_cache ORDER BY result_size DESC LIMIT 20;

レポート形式

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

次のスキル

• キャッシュが RAM 全体の大きな割合を占めている、またはサーバーがメモリ上限に近い → スキル altinity-expert-clickhouse-memory を読み込む
• ヒット率が低く、ディスク読み取り I/O が多い → スキル altinity-expert-clickhouse-storage を読み込む
• index_granularity が小さい、または ORDER BY の幅が広いことによりマーク数が過剰 → スキル altinity-expert-clickhouse-schema を読み込む
• 小さなパーツが多く、マーク数が増加している → スキル altinity-expert-clickhouse-merges を読み込む
• クエリキャッシュのミス、または高コストなクエリの繰り返し → スキル altinity-expert-clickhouse-reporting を読み込む