altinity-expert-clickhouse-dictionaries

Dictionary diagnostics

system.dictionaries、system.query_log、system.asynchronous_metrics、system.text_log を使って、「ディクショナリが読み込まれているか、最新の状態か、メモリ使用量に見合う価値があるか」を確認します。 接続モード、クラスター、時間範囲がまだ確定していない場合は、先に altinity-expert-clickhouse-connection を実行してください。

クエリパック

• checks.sql — 15 項目を確認します。ディクショナリの一覧、健全性と読み込み状態、サーバー RAM に対するメモリ使用量、メモリ使用量上位のディクショナリ、設定とレイアウト、lifetime_max に対する鮮度、現在の失敗、ログ内の読み込みエラー、query_log によるルックアップのパフォーマンス、ヒット率とミス率、キャッシュディクショナリの分析、フラット型とハッシュ型のサイズ確認、ソースの種類、ClickHouse をソースとするディクショナリのソース接続、定期的な再読み込みの状態を確認します。このうち 1 項目では system.text_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 カラムはその行の判定です。そのまま転記し、再判定しないでください。

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

ディクショナリを再読み込みした後、または特定のディクショナリを詳しく調べる場合は、その読み込み状態を直接確認してください。{dictionary_name} は、チェック dictionaries-02 または dictionaries-07 で確認した名前に置き換えます。

SELECT
    database,
    name,
    status,
    loading_start_time,
    last_successful_update_time,
    loading_duration,
    element_count,
    formatReadableSize(bytes_allocated) AS memory,
    last_exception
FROM clusterAllReplicas('{cluster}', system.dictionaries)
WHERE name = '{dictionary_name}';

解釈ルール

• ステータスが FAILED または LOADING_FAILED で、last_exception が空でない場合は、ClickHouse の問題ではなくソース側の問題です。例外テキストを引用してください。失敗しているホスト、テーブル、または認証情報が示されています。dictionaries_lazy_load が有効で、まだ辞書に対するクエリがない場合、NOT_LOADED は正常です。
• seconds_since_update が lifetime_max を超えている場合は、再読み込みの期限が過ぎているか、再読み込みがひそかに失敗しています。lifetime_max の 2 倍を超えている場合、辞書は古いデータを提供しており、しばらく再読み込みに失敗しています。dictionaries-08 のロードエラーと照らし合わせて、どれが該当するか確認してください。
• bytes_allocated / element_count がキーあたり 1000 バイトを超える場合は、レイアウトに無駄があります。疎な整数キーや大きな整数キーに対する flat レイアウトは、キー範囲全体にメモリを割り当てます。hashed または sparse_hashed に切り替えてください。非常に大きなソースの一部だけがワーキングセットの場合は、すべてを保持するより cache または ssd_cache レイアウトのほうが低コストです。
• キャッシュ型の辞書でヒット率が低い場合（dictionaries-10、dictionaries-11）、選択したレイアウトが適切でないか、サイズが小さすぎます。ミスするたびにソースへの同期ラウンドトリップが発生するため、ヒット率が低いと、辞書を使わない場合よりも検索が遅くなります。キャッシュサイズを増やすか、すべてを保持できるハッシュ型レイアウトに切り替えてください。
• ソースに到達できない場合は、このセッションを実行しているマシンではなく、ClickHouse サーバーのホストから接続を確認してください。辞書のソースはサーバー側で解決されます。DNS、ファイアウォールルール、認証情報はいずれもサーバーのものです。ノート PC からは動作するソースでも、サーバー上では失敗することがあります。
• 強制的に再読み込みするには、ユーザーが 1 つの辞書に対して SYSTEM RELOAD DICTIONARY、すべての辞書に対して SYSTEM RELOAD DICTIONARIES を実行できます。どちらも自分では実行しないでください。大きな辞書の再読み込みは検索をブロックし、ソース全体を再読み込みします。また、すべてを一度に再読み込みすると、負荷の高いサーバーでメモリ使用量が急増することがあります。
• 辞書のメモリはサーバー全体のメモリ予算に含まれ、メモリ逼迫時にも解放されません。dictionaries-03 で RAM の 2 桁の割合を占めている場合、そのメモリは max_server_memory_usage に関係なくクエリに使えません。

レポート形式

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

次に読み込むスキル

• 辞書が RAM の大きな割合を占めている、またはメモリ制限によりクエリが失敗している場合 → スキル altinity-expert-clickhouse-memory を読み込みます
• サーバーログから完全な例外テキストを確認する必要があるロード失敗 → スキル altinity-expert-clickhouse-logs を読み込みます
• dictGet の検索が遅く、クエリ時間の大部分を占めている場合 → スキル altinity-expert-clickhouse-reporting を読み込みます
• ClickHouse をソースとする辞書がリモートホストまたはレプリカで失敗している場合 → スキル altinity-expert-clickhouse-replication を読み込みます
• 権限によりソースクエリが拒否されている場合 → スキル altinity-expert-clickhouse-grants を読み込みます
• 全般的な健全性の把握、または問題領域が不明な場合 → スキル altinity-expert-clickhouse-overview を読み込みます