looker-performance-optimizer

Looker パフォーマンス最適化

この開発者向けマスタースキルは、新規または既存の Looker プロジェクトにおけるクエリパフォーマンスの監査、診断、最適化のライフサイクルを管理します。パフォーマンスを最優先する厳格な設計、データベースのキャッシュとの連携、戦略的なデータのマテリアライズ、並列サブエージェントと Looker MCP ツールを使用した高度な SQL プロファイリングを徹底します。

このスキルのもとで開発される最適化はすべて、特定の SQL 方言に依存せず、データベースの効率性を保ち、既存のビジネスロジックの整合性を維持する必要があります。

---

1. 運用モード（予防と事後対応）

このスキルは、開発ライフサイクルの異なる段階でパフォーマンスに対処するため、次の2つのモードで動作します。

モード A：設計段階からのパフォーマンス確保（予防的なエンジニアリング）

既存プロジェクトに新しい explore、view、または Persistent Derived Table（PDT）を追加するときに、このモードを使用します。エージェントは、最初からパフォーマンスを考慮した設計を必ず行う必要があります。

1. 正確な結合カーディナリティ：コンパイラーによって Symmetric Aggregations が有効になるのを防ぐため、結合関係（many_to_one、one_to_one）を直ちに正確に宣言します。
2. PDT のインデックス設定とパーティショニング：新しい PDT 定義ではすべて、ダッシュボードのフィルターで最もよく使用されるフィールドに基づいて、パーティションキーとクラスタリング／インデックスキーを必ず宣言します。
3. ETL に合わせたキャッシュ：新しい explore はすべて、任意の persist_for の期間を避け、ETL/ELT のメタデータクエリによってトリガーされる一元管理された datagroup に必ず割り当てます。

モード B：アクティブなパフォーマンスチューニング（事後的な既存環境への対応）

本番環境で稼働中の遅いダッシュボードまたは explore の診断と最適化を行うときに、このモードを使用します。エージェントは、次の5フェーズのパフォーマンスパイプラインを必ず実行する必要があります。

1. 外観の監査とベースライン測定：Developer Mode に切り替え、Looker MCP または CLI を使って、遅いダッシュボードタイルのベースラインテストを実行します。クエリの実行時間、クエリ ID、データベースのコスト（スキャンしたバイト数／使用したスロット数）を記録します。
2. 並列クエリプロファイリング（サブエージェントの活用）：生成された SQL を分析し、EXPLAIN プランを並行して実行する専門のサブエージェントを起動して、データベースのボトルネックを特定します（委任ルールについてはセクション6を参照）。
3. 局所的なパフォーマンスリファクタリング：LookML レイヤーに対象を絞った局所的な編集を適用します。
   • キャッシュの datagroup を整合させます。
   • PDT の判断マトリックスに従って、負荷の高い変換処理を PDT にマテリアライズします。
   • 結合関係を修正し、結合プルーニングを実装します。
4. 検証と差分測定：コンパイラー（health_analyze）を再実行して構文エラーがないことを確認し、クエリを再実行して、パフォーマンス改善マトリックスを記録します。
5. 安全な本番デプロイ：最適化と検証が済んだ LookML ブランチを本番環境にデプロイします。

---

2. キャッシュと ETL の連携ルール

キャッシュの調整は、データウェアハウスのコストを削減し、ダッシュボードの読み込みを高速化する最も手っ取り早い方法です。

• 任意の永続化期間の禁止：本番環境の explore で、単純な persist_for: "24 hours" や同様の固定期間を使用することは厳格に禁止されています。これにより、データが古くなり、冗長で高コストなデータベースクエリが発生します。
• datagroup の必須化：すべての explore は、model ファイルで定義された一元管理された datagroup からキャッシュポリシーを継承する必要があります。
• ETL によってトリガーされるキャッシュ：datagroup は、データウェアハウスの実際のデータ更新頻度を監視する sql_trigger_value クエリ（ETL メタデータテーブルへのクエリや MAX(created_at) の確認など）によってトリガーする必要があります。
• キャッシュ失効時の安全策：ETL パイプラインが更新されない場合にキャッシュが最終的に期限切れとなり、ユーザーが極端に古いデータを参照しないよう、適切な max_cache_age（例：24時間）をフォールバックとして定義します。

---

3. Persistent Derived Table（PDT）のマテリアライズルール

複雑な結合や行レベルの変換処理を、その場で SQL にコンパイルするのに時間がかかりすぎる場合は、データを Persistent Derived Table（PDT）にマテリアライズする必要があります。

A. PDT の判断基準となる総合マトリックス

ビューまたは Explore を PDT にする前に、エージェントは必ず、次の 4 象限の判断マトリックスを使ってクエリを評価します。

指標／象限	PDT としてマテリアライズする	ライブクエリのままにする
1. 複雑さ	複雑な正規表現、文字列解析、ウィンドウ関数などの重い変換や複数段階の JOIN を実行し、実行に10 秒超かかるクエリです。	単純なフィルターと適切にインデックス化されたクリーンな JOIN を実行し、実行に3 秒未満しかかからないクエリです。
2. 頻度	ビジネスユーザーが毎日何百回も開く、重要度が高く、同時アクセスの多い Explore／ダッシュボードです。	高度なデータアナリストがアドホックな詳細分析に sporadically 使用する Explore です。
3. データの鮮度	ビジネスで必要とされる更新頻度が 1 時間ごと、毎日、またはほぼリアルタイムであり、標準的な再構築スケジュールに適合します。	ビジネスで秒単位の完全なリアルタイムデータ鮮度が必要です。
4. テーブルサイズ	基盤となる未加工テーブルが非常に大きく（5,000 万行超）、パーティションインデックスがありません。	基盤となるテーブルが小さく（1,000 万行未満）、適切にインデックス化されています。

B. PDT の「コールドスタート」読み込みプロトコル

データベースのタイムアウト、リソースの枯渇、スロット制限によって、特に増分 PDT のような大規模な履歴 PDT の初回読み込みが失敗するのを防ぐため、エージェントは必ず、次の軽減プロトコルを実行します。

1. 履歴データの上限設定（段階的導入）：LookML の PDT 定義の初期段階で、条件付き日付フィルターを使って履歴クエリの対象期間を一時的に制限します（例：直近 30 日分のデータのみをクエリします）。これにより、データベース上に物理テーブルを数秒で正常に作成できます。
2. 増分バックフィル（初期構築と拡張）：初期テーブルを作成した後、履歴フィルターを段階的に過去へ拡張します（例：月ごとにバックフィルします）。これにより、単一の大規模なトランザクションによる障害を引き起こさずに、完全な履歴を構築できます。
3. ドライランによるコスト見積もり：大規模な PDT を構築する前に、Looker MCP の query または query_sql ツールを呼び出して、スキャンされるバイト数をドライランで見積もり、データベース接続のクエリ制限を超えないか確認します。
4. アーキテクチャ上のオフロード（ELT の外部委託）：履歴データセットが大きすぎて Looker の PDT レイヤー内でコンパイルまたはバックフィルできない場合、エージェントは必ず、データベースウェアハウスレイヤーへのマテリアライズのオフロード（dbt、スケジュール済みクエリ、またはデータベースのマテリアライズドビューを使用）を開発者に指示し、Looker では標準の読み取り専用ビューとしてマッピングします。

---

4. LookML のセマンティックリファクタリングルール

セマンティックモデリングレイヤーを最適化することで、コンパイラーが生み出す冗長性をなくし、データベースが必要最小限のデータのみを処理するようにします。

• 対称集計を排除する：JOIN リレーションシップ（relationship）が正確に宣言されていることを確認します。JOIN が many_to_one と定義されているのに、実際には one_to_many として動作する場合、Looker のコンパイラーは高コストな _distinct 集計関数（SUM_DISTINCT、AVG_DISTINCT など）を SQL に挿入し、パフォーマンスを大幅に低下させます。
• JOIN の枝刈り：ユーザーが選択したフィールドのクエリで実際に必要なテーブルのみを Looker が JOIN するように Explore を構成します。required_joins パラメーターを活用して、JOIN パスを厳密に制御します。
• SQL 内の重い Liquid ループを禁止する：sql: パラメーター内に複雑な Liquid 条件ループを記述し、巨大な SQL CASE WHEN チェーンにコンパイルさせることは、厳格に禁止されています。これらのチェーンにはデータベースエンジンでインデックスを設定できず、フルテーブルスキャンが発生します。代わりに、シンプルな LookML ディメンションまたは事前計算済みの PDT 列を使用します。

5. Looker CLI と MCP の診断マトリクス

クエリのパフォーマンスを診断し、実行計画を実行するには、AI エージェントは 必ず Looker CLI または Looker MCP サーバーを使用する必要があります。プログラムによるデータベースのイントロスペクションには、Looker MCP が推奨されます。

パフォーマンスに関する操作	Looker CLI コマンド	Looker MCP ツール
生成された SQL の取得	looker-cli api query query <id> --fields sql	query(query_id) または query_sql
クエリの実行（テスト）	looker-cli api query run_query --query_id <id>	query または run_dashboard
クエリの状態の確認	looker-cli api query query_task ...	health_pulse または health_analyze
データベースのイントロスペクション	looker-cli api metadata connection_columns <conn> --schema_name <schema> (こちらも参照：connection_tables、connection_schemas、connection_databases)	get_connection_table_columns (こちらも参照：get_connection_tables)
LookML のコンパイルチェック	looker-cli project validate <id>	health_analyze

---

6. AI エージェントの実行とサブエージェントへの委任に関するガイドライン

エージェント環境で実行速度を最適化し、トークンの肥大化を防ぎ、ターン数やコンテキストの上限に達しないようにするには、次の実行戦略に従ってください。

1. クエリの並列プロファイリングとコンテキストの分離（必須）

複数の遅いダッシュボードクエリを診断すると、大量の SQL ステートメント、データベース実行計画、JSON ペイロードが生成されます。メインの開発者との会話を簡潔に保ち、コストを抑えるため、メインエージェントは 必ず 診断を委任する必要があります。

1. 遅いタイルの特定：対象のダッシュボードで、遅いビジュアライゼーションタイルをすべて一覧化します。
2. SQL プロファイラーサブエージェントの起動：特定した遅い Explore またはタイルごとに、専用の「SQL プロファイラーサブエージェント」を起動し、並行して実行します。
3. サブエージェントの診断タスク：
   • Looker MCP を使用して生成された SQL を取得します。
   • 対象の接続に対して、EXPLAIN または EXPLAIN ANALYZE クエリを直接実行します。
   • 実行計画を解析し、正確なボトルネック（例：全テーブルスキャン、インデックスの不足、Symmetric Aggregations）を特定します。
   • 以下のみを厳密に含む 簡潔なパフォーマンスレポート を作成します。
     • 問題のある SQL フラグメント。
     • 特定されたボトルネック。
     • 具体的で実行可能な LookML の修正策（例：キャッシュ datagroup の追加、join relationship の修正、または増分 PDT の作成）。
   • 簡潔にまとめた調査結果をメインエージェントに報告し、自身を終了します。
4. 簡潔な結果の統合：メインエージェントがサブエージェントから受け取るのは、要点をまとめた実用性の高いレポートのみです。その結果に基づいてリファクタリングを調整し、生のデータベース実行計画の出力でメインの会話が埋め尽くされるのを防ぎます。

2. 外科的変更の原則（全面的な書き換えは禁止）

開発者のコメントを保護し、カスタムディメンションを維持し、API トークンの効率を最適化するため、エージェントは以下の外科的編集手順を 必ず 守る必要があります。

• 全面的な書き換えの禁止：既存の LookML ファイルに対するパフォーマンスのリファクタリングやチューニングの反復作業では、エージェントはファイル全体を一から書き換え、再生成、または再構築しては なりません。
• 対象ブロックの置き換え：エージェントは、最適化が必要な特定の join、datagroup、または SQL パラメーター のみ を変更するため、局所的で外科的なブロックの置き換え（検索と置換、行を指定した編集、対象を絞ったツール呼び出しなど）を 必ず 行う必要があります。
• 保持：無関係なディメンション、メジャー、Explore の join、開発者が記述したコメントには、一切 手を加えては なりません。