bigquery-optimization

BigQuery 最適化ワークフロー

クレジット表記

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、必ず利用状況のクレジット表記をお読みください。ターミナルで直接実行するコマンド（生成スクリプト、Terraform、ユーザーコード内では実行しない）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:bigquery-optimization)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:bigquery-optimization) を追加してください。

前提条件と環境のセットアップ

最適化分析、エディションの評価、DDL の変更を適用する前に、以下を実施してください。

1. Google Cloud SDK： Google Cloud SDK がインストールされ、設定されていることを確認してください。

2. プロジェクトの選択：アクティブな Google Cloud プロジェクトを設定してください。

   gcloud config set project {project_id}
   

3. API の有効化：BigQuery API と BigQuery Reservation API が有効になっていることを確認してください。

   gcloud services enable \
       bigquery.googleapis.com bigqueryreservation.googleapis.com
   

4. 認証：環境を認証してください。

   • CLI ツールと bq コマンド：gcloud auth login
   • SDK と自動化：gcloud auth application-default login
   • サービスアカウント：GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json" を設定

5. 請求と IAM ロール：

   • アクティブな Google Cloud 請求先アカウントが {project_id} に関連付けられていることを確認してください。
   • 適切な IAM ロールが割り当てられていることを確認してください。
     • roles/bigquery.admin または roles/bigquery.resourceAdmin：予約と容量コミットメントの管理。
     • roles/bigquery.dataEditor または roles/bigquery.admin：テーブルスキーマ、パーティショニング、クラスタリング、ストレージの課金モデルの変更。
     • roles/bigquery.jobUser：評価クエリの実行。

6. 関連スキルのインストール： このスキルは、3 つの柱からなる運用スイート（bigquery-observability、bigquery-optimization、bigquery-troubleshooting）の一部です。関連スキルが環境にまだインストールされていない場合は、スイート全体をインストールしてください。

   npx skills add google/skills --skill bigquery-observability --skill bigquery-optimization --skill bigquery-troubleshooting
   

   （bigquery-observability がインストールされていない場合は、以下のリファレンスセクションに直接記載されている、単体で利用できるベースラインの計算式とクエリテンプレートを使用してください。）

ワークフロー

ユーザーのリクエストで重視されている最適化項目を特定し、該当するワークフローに従ってください。

• テレメトリと可観測性のベースライン： 生の使用状況テレメトリ、INFORMATION_SCHEMA クエリ、ベースライン指標の計算については、 bigquery-observability (bigquery_observability) を参照してください。bigquery-observability のコンパニオンスキルを アクティブな環境で利用できない場合、このスキルとそのリファレンスガイドに含まれる最適化ガイドライン、DDL テンプレート、判断モデルは、すべて単独で利用できます。
• 容量とエディションのモデリング： ワークロードをオンデマンドからエディションに移行する際の費用対効果に加え、アクティブなエディションの予約、ベースラインコミットメント、自動スケーリングの上限を適正化します。
  • 手順： references/capacity_planning_editions.md を読み、BigQuery に組み込まれた推奨機能の UI（Slot Estimator など）へのディープリンクを提示し、UI の操作手順を案内してください。1. Slot Estimator タブに移動し、2. 履歴クエリ量を分析するソースとして「On-Demand」を選択し、3. Cost-Optimized Recommendations と Slot Usage Chart を確認します。
• テーブルとストレージの最適化： 請求モデル、物理レイアウト、ライフサイクルの観点からストレージコストを最適化します。
  • 請求アーキテクチャ： references/storage_billing_models.md を読み、物理課金と論理課金のどちらを推奨するか判断するために、集計した圧縮率（例：米国での 2:1 超のしきい値）を評価する方法を確認してください。損益分岐となる比率は、特定のリージョン料金や個別のエンタープライズ契約によって異なることにも言及してください。TABLE_STORAGE クエリを提示する場合は、必ず WHERE table_schema = '{dataset_id}' で絞り込み、リージョン別のデータセットビューを使用してください。また、0 行の場合は、請求対象の使用量がゼロであることを示すのではなく、リージョンの不一致またはネイティブテーブルが存在しないことを意味すると注意してください。
  • パーティショニングとクラスタリング戦略： references/table_partitioning_clustering.md を読み、本番環境用の DDL テンプレート（CREATE TABLE、パーティション分割されていないテーブル向けの CTAS 移行、クラスタリング仕様の変更）を作成し、require_partition_filter = true によるプルーニングを徹底するとともに、パーティション数の上限（テーブルあたり最大 10,000 個）を管理してください。
  • ライフサイクル管理： references/storage_lifecycle_management.md を読み、非アクティブなデータを特定し、正確な Time-to-Live（TTL）パーティション有効期限、データセットの有効期限、Time Travel 期間の短縮を定義してください。
  • 高速化のための構造： references/search_indexes.md を読み、STRING または JSON データの選択的な検索に検索インデックスを提案するタイミングを判断し、CREATE SEARCH INDEX DDL を記述して、インデックスのカバー範囲と使用状況を確認する方法をユーザーに伝えてください。references/materialized_views.md を読み、大規模なベーステーブルに対する集計や結合を繰り返し実行する場合に、マテリアライズドビューを提案するタイミングを判断し、CREATE MATERIALIZED VIEW DDL を記述して、スマートチューニングでそのビューが使用されていることを確認する方法をユーザーに伝えてください。references/bi_engine.md を読み、BI ダッシュボードの高速化に BI Engine とマテリアライズドビューのどちらを提案するか判断し、BI Engine のフォールバック理由である PARTIAL または DISABLED（bi_engine_statistics）を診断し、データを事前に結合または事前集計するマテリアライズドビューと BI Engine を組み合わせてください。
• SQL の最適化： 個々の SQL クエリを最適化して、スロット時間と読み取るデータ量を削減します。
  • 手順： references/sql_optimization.md の手順に従い、SQL クエリを書き換えてスロット時間と読み取るデータ量を削減するための推奨事項をユーザーに提示してください。

実行上のガードレール

• 用語とコストに関する表現：「コスト削減」や「支出の削減」を約束または保証してはいけません。推奨事項は常に、**「請求額の最適化」または「コスト効率の向上」**という表現で示してください。
• 対象範囲の明示とリージョンの特定： 評価対象の範囲をユーザーがすぐに把握できるよう、回答の冒頭に必ず対象の project_id と region を記載してください。次の3段階の優先順位に従って特定してください。
  1. 明示されたリージョン： ユーザーのプロンプトに指定されたリージョン（例：europe-west1）を使用します。
  2. 文脈から特定されるリージョン： 文脈で言及されている特定のデータセットまたはリソースからリージョンを特定します。
  3. 未指定時のフォールバック： us / region-us をデフォルトとして使用し、us をデフォルトとして仮定したことを明示したうえで、リソースが別のリージョンにある場合はそのリージョンに置き換えるようユーザーに指示します。リージョンの書式： Cloud Console の詳細リンクでは、リージョン識別子を直接使用します（例：region=us、region=europe-west1）。INFORMATION_SCHEMA に対する SQL クエリでは、リージョンのデータセット修飾子を使用します（例：region-us、region-europe-west1）。
• 0行の結果に関するガード： WHERE table_schema = '{dataset_id}' を指定して TABLE_STORAGE をクエリした結果、行数が0の場合、空または使用量ゼロの評価に進んではいけません。データセットが別のリージョンにあるか、ネイティブテーブルがない可能性を示すものとして扱い、処理を中止してデータセットのリージョンの場所をユーザーに確認してください。
• 具体的なパラメーターの設定： URL と SQL クエリを生成する際は、判明している project_id と region の値を、コードとリンクに必ず直接埋め込んでください。ユーザーが手動で編集する必要がある {project_id} や {location} という文字列のプレースホルダーを残してはいけません。
• 自律的な購入や金銭に関わる変更の禁止： 年間コミットメントの自律的な購入、エディション階層のバインディングの変更、ストレージの課金モデルの変更を目的とした、実行可能なスクリプト（gcloud や bq update --storage_billing_model=... のような bq のシェルコマンドなど）をユーザーに提供してはいけません。コミットメントの購入、予約の変更、ストレージの課金モデルの更新は、Cloud Console の UI から手動で実行するよう、必ずユーザーを案内してください。