トラブルシューティングの概要

このドキュメントでは、BigQuery の問題のトラブルシューティングに役立つ診断ツール、テレメトリー インターフェース、ドキュメント リソースの概要について説明します。

クエリの失敗、パフォーマンスのボトルネック、権限エラー、割り当て上限、データの取り込みの問題が発生した場合は、BigQuery に組み込まれているツールを使用して、根本原因を特定し、問題を迅速に解決できます。

トラブルシューティングのワークフロー

BigQuery の問題を効果的にトラブルシューティングするには、次の診断基準を検討してください。

  1. 症状と障害モードを特定します。タスクの結果を確認して、問題がハード障害（エラーコードやジョブの失敗など）、パフォーマンスの低下（クエリの遅延やスロットの不足など）、権限拒否、予期しない費用の不一致のいずれであるかを判断します。
  2. ジョブ実行の詳細を確認します。 Google Cloud コンソールのジョブ エクスプローラ、クエリ実行グラフ、またはコマンドライン ツールを使用して、ステージレベルのタイミング、スロット割り当て、エラーの詳細を確認します。Gemini Cloud Assist に問題の調査を依頼することもできます。
  3. テレメトリーとメタデータを分析します。情報スキーマ ビューをクエリするか、Cloud Audit Logs を調べて、ジョブの動作とリソース競合、予約上限、管理上の変更を関連付けます。
  4. 対象を絞った緩和策を適用します。カテゴリ固有のトラブルシューティング ガイドまたは防御的 SQL 関数を使用して、根本原因を修正します。

トラブルシューティングと最適化を区別する

BigQuery を使用する場合は、トラブルシューティング、パフォーマンスの最適化、ベスト プラクティスを区別することが重要です。

  • トラブルシューティング。ジョブが正常に完了しない原因となる予期しない障害、ランタイム エラー、パイプラインの破損、割り当ての枯渇、意図しない動作の診断と解決に重点を置きます。
  • パフォーマンスの最適化。すでに正常に実行されているクエリとワークロードの実行速度、レイテンシ、リソース効率の改善に重点を置きます。詳細については、クエリ パフォーマンスを最適化するをご覧ください。
  • ベスト プラクティス。データ モデリング、ストレージ、セキュリティ、費用管理のアーキテクチャ パターンと設計パターンに焦点を当てています。詳細については、ベスト プラクティスの概要をご覧ください。

診断ツール

以降のセクションでは、ワークロード全体の問題の診断に役立つ BigQuery インターフェースと自動化ツールについて説明します。

ビジュアル ツールとコンソール ツール

次のツールは、Google Cloud コンソールから BigQuery のトラブルシューティングを行うのに役立ちます。

  • ジョブ エクスプローラ。SQL クエリを記述せずに、プロジェクトまたは組織全体の過去のジョブと実行中のジョブを検索、フィルタ、検査できます。エラー メッセージ、スロット使用率、実行タイムライン、ジョブ メタデータを表示できます。詳細については、ジョブ エクスプローラでジョブをモニタリングするをご覧ください。
  • クエリ実行グラフ。クエリのステージごとの実行プランを視覚的に確認します。実行グラフは、シャッフルがディスクにスピルする、計算バウンド ステージ、データスキュー、入出力の遅延などのボトルネックを特定するのに役立ちます。詳細については、クエリのパフォーマンス分析情報を取得するをご覧ください。
  • Query Insights とリソースグラフ。スロット使用率、ジョブの同時実行、予約割り当てのリアルタイム グラフと履歴グラフを表示して、容量の制約を診断します。詳細については、管理リソースグラフを使用するをご覧ください。
  • Gemini Cloud Assist in BigQuery。失敗したクエリとパフォーマンスのボトルネックのコンテキストに応じた AI 支援分析を取得します。Gemini Cloud Assist は、Google Cloud コンソールでエラーコードを説明し、問題のある SQL 構文をハイライト表示して、修復手順を提案します。詳細については、Gemini Cloud Assist を使用してクエリのトラブルシューティングを行うをご覧ください。

コマンドラインと自動診断ツール

次のツールは、コマンドライン インターフェースから BigQuery の問題を診断するのに役立ちます。

  • bq コマンドライン ツール。bq show -j <var>JOB_ID</var> コマンドを使用するか、クエリ コマンドに --format=prettyjson フラグを追加して、詳細なエラー構造、リクエスト ID、ジョブ メタデータを検査します。詳細については、CLI コマンドのトラブルシューティングをご覧ください。
  • gcpdiag ツール。コマンドラインから自動診断を実行して、IAM 権限のギャップ、ネットワーク制限、サービス アカウント エラーなど、一般的な Google Cloud 構成の問題を検出します。詳細については、gcpdiag を使用してクエリの失敗をトラブルシューティングするをご覧ください。

メタデータとテレメトリー ビュー

情報スキーマ ビューを使用すると、標準 SQL を使用して、ジョブ、容量、ストリーミング取り込み、データセットに関するリアルタイムのメタデータと履歴メタデータをクエリできます。これらのビューには次のものが含まれます。

詳細については、BigQuery INFORMATION_SCHEMA の概要をご覧ください。

Cloud Monitoring と Cloud Audit Logs

  • Cloud Audit Logs。管理アクティビティ監査ログとデータアクセス監査ログを確認して、特定のオペレーションを開始したユーザーを追跡し、呼び出し元の ID を検査して、PERMISSION_DENIED エラーを診断します。詳細については、BigQuery 監査ロギング リファレンスをご覧ください。
  • Cloud Monitoring。スロット使用率、クエリ実行時間、アップロードされたバイト数などの指標を追跡し、しきい値または割り当てを超えたときにチームに通知するようにアラート ポリシーを構成します。詳細については、Cloud Monitoring を使用して BigQuery をモニタリングするをご覧ください。

防御的 SQL 関数とデバッグ ステートメント

ランタイム データエラーが原因でクエリが予期せず失敗するのを防ぐには、次のものを使用します。

  • 安全な式。SAFE_CAST()、SAFE_DIVIDE()、SAFE_OFFSET()、SAFE_ORDINAL() を使用して、データ型や配列の境界が一致しない場合に、実行時エラーを生成する代わりに NULL を返します。ほとんどのスカラー関数は SAFE. 接頭辞をサポートしています。詳細については、関数のデバッグと SAFE. 接頭辞をご覧ください。
  • SQL アサーション。複数ステートメント トランザクションまたはスクリプトで ASSERT ステートメントを使用して、データ検証条件を適用し、ダウンストリーム オペレーションが実行される前にカスタム エラー メッセージで失敗します。詳細については、デバッグ ステートメントをご覧ください。

問題のカテゴリに応じてトラブルシューティングを行う

次のセクションからカテゴリを選択すると、エラーコードの詳細、根本原因、解決手順のガイドが表示されます。

クエリのパフォーマンスと実行

実行に失敗したクエリ、タイムアウトしたクエリ、リソース制約が発生したクエリ、予期しない遅延が発生したクエリを診断します。

Identity and Access Management（IAM）とセキュリティ

アクセス制御の失敗、ロールの割り当ての欠落、データガバナンス ポリシーのブロックを診断します。

割り当て、レート上限、予約

ワークロードが BigQuery サービスの上限または容量の割り当てを超えた場合の問題を解決します。

データの取り込み、ストリーミング、転送

データの読み込み、レコードのストリーミング、外部ソースの同期で発生した障害を診断します。

外部データソースと連携クエリ

BigQuery の外部でデータをクエリする際の接続、認証、実行エラーを診断します。

請求と費用の不一致

コンピューティングとストレージ全体で予期しない請求と請求の不一致を調査します。

データ損失の軽減

変更または削除された履歴データを復元したり、リージョン停止中にビジネスの継続性を維持したりするには、次の障害復旧ツールとデータ保持ツールを使用します。

  • データを復元します。タイムトラベル期間内に変更または削除されたテーブルデータのクエリまたは復元。詳細については、データを復元するをご覧ください。
  • タイムトラベル。構成された保持期間にわたって、更新または削除されたデータをデータセットに保持し、誤った変更を防ぎます。詳細については、タイムトラベルをご覧ください。
  • リージョン フェイルオーバー。BigQuery マネージド障害復旧を使用している場合、リージョンが停止したときにセカンダリ レプリカをプライマリ ロールに昇格させます。詳細については、リージョン フェイルオーバーをご覧ください。

API の使用

BigQuery をプログラムで操作する場合は、次のリソースを使用してリクエスト レイテンシを最適化し、アップロード ワークフローを管理します。

  • API のパフォーマンスに関するヒント。接続プールの管理、バッチ オペレーションの使用、再試行の処理など、API 呼び出しを行うためのベスト プラクティスに従います。詳細については、API のパフォーマンスに関するヒントをご覧ください。
  • API アップロード。REST API の再開可能なアップロード リクエストとマルチパート アップロード リクエストを使用して、データの取り込みのトラブルシューティングと管理を行います。詳細については、API アップロードをご覧ください。

次のステップ