altinity-expert-clickhouse-schema

テーブルスキーマと設計の分析

system.parts、system.tables、system.columns、system.parts_columns、system.data_skipping_indices、system.merge_tree_settings を使って、「このテーブルは ClickHouse が推奨する設計になっているか」に回答します。 接続モード、クラスター、時間範囲がまだ確立されていない場合は、最初に altinity-expert-clickhouse-connection を実行してください。

クエリパック

• checks.sql — 10 項目のチェック：パーティションの健全性監査、Collapsing エンジンでの過大なパーティション、主キー分析、カラム数、Nullable カラム監査、長すぎるテーブル名とカラム名、マテリアライズドビューの設計上の問題、マテリアライズドビューの依存関係チェーン、テーブルの概要、以上すべてに影響するテーブル単位の MergeTree 設定。
• 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 カラムがその行の判定です。その値をそのまま使用し、再判定しないでください。

詳細分析用ステートメント

パーティションキーが細かすぎるかどうかを判断するための、1 テーブルのパーティション分布。

SELECT
    partition,
    count() AS parts,
    sum(rows) AS total_rows,
    formatReadableSize(sum(bytes_on_disk)) AS partition_size
FROM clusterAllReplicas('{cluster}', system.parts)
WHERE active AND database = '{database}' AND table = '{table}'
GROUP BY partition
ORDER BY partition DESC
LIMIT 100;

型またはコーデックが適切でないカラムを見つけるための、1 テーブルのカラム圧縮。

SELECT
    name, type, compression_codec,
    formatReadableSize(sum(data_compressed_bytes)) AS compressed,
    formatReadableSize(sum(data_uncompressed_bytes)) AS uncompressed,
    round(sum(data_uncompressed_bytes) / nullIf(sum(data_compressed_bytes), 0), 2) AS ratio
FROM clusterAllReplicas('{cluster}', system.columns)
WHERE database = '{database}' AND table = '{table}'
GROUP BY name, type, compression_codec
ORDER BY sum(data_compressed_bytes) DESC
LIMIT 50;

1 つのデータベース全体で宣言されているデータスキップインデックス。

SELECT database, table, name AS index_name, type, expr, granularity
FROM clusterAllReplicas('{cluster}', system.data_skipping_indices)
WHERE database = '{database}'
ORDER BY database, table;

解釈ルール

• ORDER BY の指針：最初のカラムはカーディナリティが低く、頻繁にフィルターされるもの（テナント、リージョン、タイプ）にします。範囲クエリがよく使われる場合、2 番目のカラムは時間ベースにします。残りのフィルターカラムは選択性の順に並べ、最も選択性の高いものを最後にします。UUID やハッシュを最初のカラムにするのはアンチパターンです。また、マイクロ秒精度の DateTime64 を最初にするのもアンチパターンです。すべての行で値が異なるため、スパースインデックスで絞り込めません。
• パーティション粒度の経験則：テーブルあたり数十から数百のパーティションを目安とし、それぞれのサイズを 1～10 GB にします。日単位でのパーティション分割が妥当なのは、月あたりおよそ 1 TB を超える場合に限られます。それより少ない場合は、通常、月単位のパーティション分割かパーティション分割なしが適切です。Check schema-01 でこれを評価します。根拠として、パーティションサイズの中央値を引用してください。
• 過大なパーティション（schema-02）が問題になるのは、Replacing、Collapsing、Summing、Aggregating、Graphite エンジンの場合に限られます。パーティションが max_bytes_to_merge_at_max_space_in_pool より大きいと、単一のパーツにマージできないため、重複排除や集計が完了しません。修正するには、プールを大きくするのではなく、より細かいパーティションキーを使います。
• 大きなカラムの圧縮率が 2 未満の場合、型またはコーデックが適切ではありません。繰り返しの多い文字列は LowCardinality(String) にするべきです。連番の整数やタイムスタンプには、ZSTD の前に Delta または DoubleDelta を適用すると効果があります。
• Check schema-03 が Minor を出力するのは仕様です。最初のキー列が ID のように見える、幅の広い型である、または圧縮率が低い場合にのみフラグを付けます。ORDER BY の変更にはテーブルの再構築が必要になるため、まず実際のクエリで使われるフィルターと照合してください。
• Check schema-07 は severity ではなく issue カラムを出力します。マテリアライズドビューの JOIN は左側のテーブルへの挿入時にのみ実行されるため、右側のテーブルの変更が気づかれないまま反映されなくなります。TO を指定しないマテリアライズドビューは、変更も個別のバックアップもできない、非表示の .inner テーブルを所有します。
• Checks schema-09 と schema-10 は検出結果ではなくコンテキストを返します。他の結果を説明するために使用し、これらの行を問題として列挙しないでください。

レポート形式

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

次のスキル

• 小さい、または頻繁な挿入が原因で小さなパーティションが多数ある → スキル altinity-expert-clickhouse-ingestion を読み込む
• 過大なパーティション、マージの滞留、またはパーティションごとのパーツ数が多い → スキル altinity-expert-clickhouse-merges を読み込む
• ワイドな主キーが RAM を消費している、またはマークキャッシュへの負荷が高い → スキル altinity-expert-clickhouse-memory を読み込む
• この ORDER BY で、クエリが返す行数に比べてはるかに多くの行をスキャンしている → スキル altinity-expert-clickhouse-index-analysis を読み込む
• クエリ実行時にマテリアライズドビューが遅い → スキル altinity-expert-clickhouse-reporting を読み込む
• ALTER UPDATE または ALTER DELETE で実行したスキーマ変更が停滞している → スキル altinity-expert-clickhouse-mutations を読み込む