Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

BigQuery Storage API エラーのトラブルシューティング

このドキュメントでは、BigQuery Storage Read API、BigQuery Storage Write API（gRPC）、または BigQuery Storage Write API（REST）（tabledata.insertAll メソッド）を使用したストリーミング挿入を使用して BigQuery でデータを読み取るかストリーミングする際に発生する問題のトラブルシューティング方法について説明します。

INFORMATION_SCHEMA ビューを使用してストリーミングテレメトリーを分析する

INFORMATION_SCHEMA ビューをクエリして、ストリーミング取り込みの健全性をモニタリングし、スループットのボトルネックを特定し、1 分間隔でエラーコードを検査できます。

Storage Write API（gRPC）: INFORMATION_SCHEMA.WRITE_API_TIMELINE ビューをクエリして、gRPC ストリーミング取り込みリクエスト、追加された合計バイト数と行数、error_code ごとのエラー数を調べます。
Storage Write API（REST）: INFORMATION_SCHEMA.STREAMING_TIMELINE ビューをクエリして、以前の REST tabledata.insertAll ストリーミングリクエストと割り当てまたはレート上限のエラーを検査します。

次の例では、INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT をクエリして、過去 24 時間の Storage Write API（gRPC）のエラー数と取り込まれたバイト数を取得します。

SELECT
  start_timestamp,
  error_code,
  SUM(total_requests) AS request_count,
  SUM(total_input_bytes) AS input_bytes
FROM
  `region-REGION`.INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT
WHERE
  start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
  AND error_code IS NOT NULL
GROUP BY
  start_timestamp,
  error_code
ORDER BY
  start_timestamp DESC;

REGION は、データセットのリージョン名（us や europe-west1 など）に置き換えます。

Storage Read API エラーのトラブルシューティング

Storage Read API の使用時によく発生するエラーは次のとおりです。

エラー: Stream removed: 解決策: Storage Read API リクエストを再試行します。これは一時的なエラーである可能性が高く、リクエストを再試行することで解決できます。問題が解決しない場合は、Cloud カスタマーケアにお問い合わせください。
エラー: Stream expired: 原因: このエラーは、Storage Read API セッションが 6 時間のタイムアウトに達したときに発生します。; 解決策:

ジョブの並列処理を増やします。
ワーカーノードの CPU 使用率が比較的安定しており、85% を超えない場合は、より大きなマシンタイプでジョブを実行することを検討してください。
ジョブを複数のジョブまたは小さなクエリに分割します。

セッション管理とデータの読み取りの詳細については、Storage Read API の概要をご覧ください。

ストリーミング挿入のトラブルシューティング

以降のセクションでは、Storage Write API（REST）を使用して BigQuery にデータをストリーミングする際に発生するエラーのトラブルシューティングについて説明します。ストリーミング挿入の割り当てエラーを解決する方法について詳しくは、ストリーミング挿入の割り当てエラーをご覧ください。

失敗 HTTP レスポンスコード

ネットワークエラーなどの失敗 HTTP レスポンスコードが返された場合、ストリーミング挿入が成功したかどうかを確認する方法はありません。リクエストを再送信しようとすると、テーブル内に重複行が発生する可能性があります。テーブルを重複から保護するには、リクエストの送信時に insertId プロパティを設定します。BigQuery は、重複除去に insertId プロパティを使用します。

権限エラー、無効なテーブル名エラー、割り当て超過エラーが発生した場合、行は挿入されず、リクエスト全体が失敗します。

成功 HTTP レスポンスコード

成功 HTTP レスポンスコードが返された場合でも、BigQuery による行の挿入が部分的にしか成功しなかった可能性があります。レスポンスの insertErrors プロパティをチェックして、行の挿入が成功したかどうかを確認する必要があります。次のいずれかのシナリオが発生することがあります。

すべての行が正常に挿入されている: insertErrors プロパティが空のリストになっている場合は、すべての行が正常に挿入されています。
一部の行が正常に挿入されている: いずれかの行にスキーマの不一致がある場合を除き、insertErrors プロパティで示された行が挿入されておらず、それ以外の行はすべて正常に挿入されています。errors プロパティには、行の挿入が失敗した理由に関する詳細情報が含まれます。index プロパティは、エラーに該当するリクエストの 0 ベースの行インデックスを示します。
行が正常に挿入されなかった: BigQuery がリクエスト内の個別行のスキーマ不一致を検出した場合は、いずれの行も挿入されず、スキーマ不一致がなかった行も含めて、各行に対して insertErrors エントリが返されます。スキーマ不一致がなかった行のエラーは reason プロパティが stopped に設定され、そのまま再送信できます。失敗した行には、スキーマ不一致に関する詳細情報が含まれます。BigQuery データ型でサポートされているプロトコルバッファの型については、サポートされているプロトコルバッファと Arrow のデータ型をご覧ください。

ストリーミング挿入のメタデータエラー

BigQuery ストリーミング API は高い挿入率を想定して設計されているため、ストリーミングシステムとやり取りする際に、基盤となるテーブルメタデータの変更は最終的に整合性が保たれます。通常、メタデータの変更は数分以内に反映されますが、この期間中は API レスポンスにテーブルの不整合な状態が反映されることがあります。

次のようなシナリオがあります。

スキーマの変更: 最近ストリーミング挿入を受け取ったテーブルのスキーマを変更すると、ストリーミングシステムがスキーマの変更をすぐに検出しない可能性があるため、スキーマの不一致エラーを含むレスポンスが発生する可能性があります。
テーブルの作成または削除: 存在しないテーブルへのストリーミングは、notFound レスポンスのバリエーションを返します。レスポンスで作成されたテーブルは、後続のストリーミング挿入で直ちに認識されないことがあります。同様に、テーブルを削除または再作成すると、ストリーミング挿入が古いテーブルに配信される期間が生じる可能性があります。ストリーミング挿入は新しいテーブルに存在しない場合があります。
テーブルの切り捨て: テーブルのデータを切り捨てる（writeDisposition 値が WRITE_TRUNCATE のクエリジョブを使用）と、整合性期間中の後続の挿入が同様にドロップされる可能性があります。

データが見つからない、または利用できない

ストリーミング挿入は、書き込み用に最適化されたストレージに一時的に存在します。このストレージは、マネージドストレージと可用性の特性が異なります。BigQuery の一部のオペレーション（テーブルコピージョブや tabledata.list などの API メソッドなど）では、書き込み用に最適化されたストレージは操作されません。最新のストリーミングデータが宛先テーブルまたは出力に存在しません。

ストリーミング挿入の割り当てエラー

このセクションでは、BigQuery へのデータのストリーミングに関連する割り当てエラーを解決するためのヒントを紹介します。

特定のリージョンでは、各行の insertId フィールドにデータを入力しないと、ストリーミング挿入の割り当て量が多くなります。ストリーミング挿入の割り当ての詳細については、ストリーミング挿入をご覧ください。BigQuery ストリーミングの割り当て関連エラーは、insertId の有無によって異なります。

エラーメッセージ

insertId フィールドが空の場合、次の割り当てエラーが発生する可能性があります。

割り当て上限	エラーメッセージ
プロジェクトごと 1 秒あたりのバイト数	リージョン: `REGION` 内の gaia_id: `GAIA_ID`、プロジェクト: `PROJECT_ID` のエンティティが、1 秒あたりの挿入バイト数に対する割り当てを超過しました。

insertId フィールドに値が入力されている場合、次の割り当てエラーが発生する可能性があります。

割り当て上限	エラーメッセージ
プロジェクトごと 1 秒あたりの行数	`REGION` 内のプロジェクト `PROJECT_ID` で、1 秒あたりのストリーミング挿入行数に対する割り当てを超過しました。
テーブルごと 1 秒あたりの行数	テーブル: `TABLE_ID` で、1 秒あたりのストリーミング挿入行数に対する割り当てを超過しました。
テーブルごと 1 秒あたりのバイト数	テーブル: `TABLE_ID` で、1 秒あたりのストリーミング挿入バイト数に対する割り当てを超過しました。

insertId フィールドの目的は、挿入した行の重複を排除することです。数分で同じ insertId が複数挿入されると、BigQuery は 1 つのバージョンのレコードを書き込みます。ただし、この自動重複排除は保証されていません。ストリーミングのスループットを最大にするために、insertId を含めずに手動の重複排除を使用することをおすすめします。詳細については、データ整合性の確保をご覧ください。

このエラーが発生した場合は、問題を診断し、推奨される手順を実施して解決します。

診断

ストリーミングトラフィックの分析には STREAMING_TIMELINE_BY_* ビューを使用します。これは、ストリーミング統計を 1 分間隔で集計し、error_code でグループ化したビューです。割り当てエラーは、結果で error_code が RATE_LIMIT_EXCEEDED または QUOTA_EXCEEDED に等しくなっています。

到達した割り当て上限に従い、total_rows または total_input_bytes を確認します。テーブルレベルの割り当てに関するエラーの場合は、table_id でフィルタリングします。

たとえば次のクエリは、1 分で取り込まれる合計バイト数と割り当てエラーの総数を示します。

SELECT
 start_timestamp,
 error_code,
 SUM(total_input_bytes) as sum_input_bytes,
 SUM(IF(error_code IN ('QUOTA_EXCEEDED', 'RATE_LIMIT_EXCEEDED'),
     total_requests, 0)) AS quota_error
FROM
 `region-REGION_NAME`.INFORMATION_SCHEMA.STREAMING_TIMELINE_BY_PROJECT
WHERE
  start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP, INTERVAL 1 DAY)
GROUP BY
 start_timestamp,
 error_code
ORDER BY 1 DESC

解決策

この割り当てエラーを解決するには、次の操作を行います。

ストリーミング割り当ての引き上げをサポートしているリージョンにあるプロジェクトで重複排除に insertId フィールドを使用している場合は、その insertId フィールドの削除をおすすめします。この解決策では、データの重複が発生すると手動で排除しなければならないため、追加の手順が必要になる場合があります。詳細については、手動の重複排除をご覧ください。
insertId を使用していない場合、または削除できない場合は、24 時間のストリーミングトラフィックをモニタリングし、割り当てエラーを分析します。
- 発生しているエラーが QUOTA_EXCEEDED ではなく主に RATE_LIMIT_EXCEEDED である場合、トラフィック全体が割り当ての 80% を下回ると、エラーで一時的な急増が示されることがあります。このようなエラーに対処するには、オペレーションを再試行します。その際、次の再試行の前に指数バックオフを行うようにします。
- Dataflow ジョブを使用してデータを挿入する場合は、ストリーミング挿入ではなく、読み込みジョブの使用を検討してください。詳細については、挿入方法の設定をご覧ください。カスタム I/O コネクタで Dataflow を使用している場合は、代わりに組み込み I/O コネクタの使用を検討してください。詳細については、カスタム I/O パターンをご覧ください。
- QUOTA_EXCEEDED エラーが発生した場合や、トラフィック全体が割り当ての 80% を常に超えている場合は、割り当ての引き上げをリクエストしてください。詳細については、割り当ての調整をリクエストするをご覧ください。
- また、ストリーミング挿入を新しい Storage Write API に置き換えることも検討してください。この API は高スループット、低料金であり、多くの便利な機能を使用できます。

BigQuery Storage API エラーのトラブルシューティング

INFORMATION_SCHEMA ビューを使用してストリーミング テレメトリーを分析する