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

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

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

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

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

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

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

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

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

診断ツール

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

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

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

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

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

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

  • bq コマンドライン ツール。bq show -j <var>JOB_ID</var> コマンドを使用するか、クエリ コマンドに --format=prettyjson フラグを追加して、詳細なエラー構造、リクエスト ID、ジョブ メタデータを調べます。詳細については、CLI コマンドのトラブルシューティングをご覧ください。
  • gcpdiag ツール。コマンドラインから自動診断を実行して、IAM 権限のギャップ、ネットワーク制限、サービス アカウント エラーなど、一般的な構成の問題を検出します。 Cloud de Confiance 詳細については、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）のストリーミング取り込みエラー、行レベルの挿入エラー、スループット割り当てをデバッグします。

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

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

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

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

請求と費用の不一致

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

データ損失の軽減

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

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

API の使用

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

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

次のステップ