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

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

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

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

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

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

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

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

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

診断ツール

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

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

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

  • ジョブ エクスプローラ。SQL クエリを記述することなく、プロジェクトまたは組織全体で過去のジョブと実行中のジョブを検索、フィルタリング、検査します。エラー メッセージ、スロットの使用状況、実行タイムライン、ジョブのメタデータを表示できます。詳細については、Jobs Explorer でジョブをモニタリングするをご覧ください。
  • クエリ実行グラフ。クエリのステージごとの実行プランを視覚的に確認します。実行グラフは、ディスクへのシャッフル スピル、コンピューティング バウンド ステージ、データスキュー、入出力遅延などのボトルネックを特定するのに役立ちます。詳細については、クエリのパフォーマンス分析情報を取得するをご覧ください。
  • Query Insights とリソースグラフ。スロット使用率、ジョブの同時実行、予約割り当てのリアルタイム グラフと履歴グラフを表示して、容量の制約を診断します。詳細については、管理リソースグラフを使用するをご覧ください。
  • Gemini Cloud Assist in BigQuery。失敗したクエリとパフォーマンスのボトルネックに関するコンテキストに応じた AI 支援分析を取得します。Gemini Cloud Assist は、エラーコードの説明、問題のある SQL 構文のハイライト表示、修正手順の提案をGoogle Cloud コンソールで直接行います。詳細については、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 Data Transfer Service の問題、プライベート転送のネットワーク接続、CSV データの読み込みエラーを診断します。
  • 転送構成のトラブルシューティング。Amazon Simple Storage Service（Amazon S3）、Salesforce、Google 広告、Cloud Storage などのソース全体で BigQuery Data Transfer Service のサービス構成エラーを解決します。
  • BigQuery Storage API のトラブルシューティング。BigQuery Storage Read API、BigQuery Storage Write API（gRPC）、BigQuery Storage Write API（REST）のストリーミング取り込みエラー、行レベルの挿入エラー、スループット割り当てをデバッグします。
  • スキーマエラーのトラブルシューティング。読み込み、クエリ、コピー、スキーマ更新オペレーション（列の変更の欠落、重複、互換性のない変更など）によるスキーマ不一致エラーと、15 レベルのスキーマ、ファイル、ルーチンのネストの深さの上限を解決します。

データ ウェアハウスの移行

外部データ ウェアハウスを評価、変換、または BigQuery に移行する際の問題を診断します。

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

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

請求と費用の不一致

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

データ損失の軽減

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

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

API の使用

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

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

認証と ADC

アプリケーションのデフォルト認証情報（ADC）の使用時に発生する可能性のある一般的な問題のトラブルシューティングについては、ADC 設定のトラブルシューティングをご覧ください。

次のステップ