BigQuery サブスクリプション

このドキュメントでは、BigQuery サブスクリプションの概要、ワークフロー、関連するプロパティについて説明します。

BigQuery サブスクリプションは、受信時に既存の BigQuery テーブルにメッセージを書き込むエクスポート サブスクリプションの一種です。別のサブスクライバー クライアントを構成する必要はありません。 Google Cloud コンソール、Google Cloud CLI、クライアント ライブラリ、または Pub/Sub API を使用して、BigQuery サブスクリプションの作成、更新、一覧表示、接続解除、削除を行います。

BigQuery サブスクリプション タイプがない場合は、pull サブスクリプションまたは push サブスクリプションと、メッセージを読み取り、BigQuery テーブルに書き込むサブスクライバー（Dataflow など）が必要です。メッセージが BigQuery テーブルに保存される前に追加の処理が不要な場合は、Dataflow ジョブを実行するオーバーヘッドは必要ありません。代わりに BigQuery サブスクリプションを使用できます。

ただし、データを BigQuery テーブルに保存する前にデータ変換が必要な Pub/Sub システムでは、Dataflow パイプラインの使用をおすすめします。Dataflow を使用して変換で Pub/Sub から BigQuery にデータをストリーミングする方法については、Pub/Sub から BigQuery へのストリーミングをご覧ください。

Dataflow の Pub/Sub subscription to BigQuery テンプレートでは、デフォルトで 1 回限りの配信が適用されます。これは通常、Dataflow パイプライン内の重複排除メカニズムによって実現されます。ただし、BigQuery サブスクリプションでは少なくとも 1 回 の配信のみがサポートされます。ユースケースで正確な重複排除が重要な場合は、潜在的な重複を処理するために BigQuery のダウンストリーム プロセスを検討してください。

始める前に

このドキュメントを読む前に、次の内容をよく理解しておいてください。

BigQuery サブスクリプション ワークフロー

次の図は、BigQuery のサブスクリプションと BigQuery の間のワークフローを示しています。

BigQuery サブスクリプションのメッセージのフロー
図 1. BigQuery サブスクリプションのワークフロー

図 1 を参照するワークフローの簡単な説明を次に示します。

  1. Pub/Sub は BigQuery Storage Write API を使用して、データを BigQuery テーブルに送信します。
  2. メッセージは、BigQuery テーブルにバッチで送信されます。
  3. 書き込みオペレーションが正常に完了すると、API から OK レスポンスが返されます。
  4. 書き込みオペレーションでエラーが発生した場合、Pub/Sub メッセージ自体に否定応答が行われます。その後、メッセージが再送信されます。メッセージが十分な回数失敗し、サブスクリプションにデッドレター トピックが構成されている場合、メッセージはデッドレター トピックに移動します。

BigQuery のサブスクリプションのプロパティ

BigQuery サブスクリプションに対して構成するプロパティによって、Pub/Sub がメッセージを書き込む BigQuery テーブルと、そのテーブルのスキーマのタイプが決まります。

詳細については、BigQuery のプロパティをご覧ください。

スキーマの互換性

Pub/Sub と BigQuery では、異なる方法でスキーマを定義します。Pub/Sub スキーマは Apache Avro または Protocol Buffer の形式で定義されますが、BigQuery スキーマはさまざまな形式を使用して定義されています。Pub/Sub トピックと BigQuery テーブルとの間のスキーマ互換性に関する重要な情報を次に示します。

  • 不適切な形式のフィールドを含むメッセージは、BigQuery に書き込まれません。

  • BigQuery のスキーマで、INT、SMALLINT、INTEGER、BIGINT、TINYINT、BYTEINT は INTEGER のエイリアス、DECIMAL は NUMERIC のエイリアス、BIGDECIMAL は BIGNUMERIC のエイリアスです。

  • トピック スキーマの型が string で、BigQuery テーブルの型が JSON、TIMESTAMP、DATETIME、DATE、TIME、NUMERIC、または BIGNUMERIC の場合、Pub/Sub メッセージのフィールドは、BigQuery データ型に指定された形式に従う必要があります。

  • Avro の論理型の一部がサポートされています。サポートされているものを次の表に示します。表に記載されていない論理型は、その論理型によってアノテーションを付けられる同等の Avro 型と一致します。詳細については、Avro の仕様をご覧ください。

以下に、さまざまなスキーマ形式の BigQuery データ型へのマッピングのコレクションを示します。

Avro 型

Avro 型 BigQuery のデータ型
null Any NULLABLE
boolean BOOLEAN
int INTEGER、NUMERIC、またはBIGNUMERIC
long INTEGER、NUMERIC、またはBIGNUMERIC
float FLOAT64、NUMERIC、またはBIGNUMERIC
double FLOAT64、NUMERIC、またはBIGNUMERIC
bytes BYTES、NUMERIC、またはBIGNUMERIC
string STRING、JSON、TIMESTAMP、DATETIME、DATE、TIME、NUMERIC、またはBIGNUMERIC
record RECORD/STRUCT
array/Type REPEATED Type
値タイプ ValueType を持つ map REPEATED STRUCT <key STRING, value ValueType>
null と Type の 2 タイプがある union NULLABLE Type
その他の　union マッピング不可
fixed BYTES、NUMERIC、またはBIGNUMERIC
enum INTEGER

Avro の論理型

Avro の論理型 BigQuery のデータ型
timestamp-micros TIMESTAMP
date DATE
time-micros TIME
duration INTERVAL

プロトコル バッファタイプ

プロトコル バッファ型 BigQuery のデータ型
double FLOAT64、NUMERIC、またはBIGNUMERIC
float FLOAT64、NUMERIC、またはBIGNUMERIC
int32 INTEGER、NUMERIC、BIGNUMERIC または DATE
int64 INTEGER、NUMERIC、BIGNUMERIC、DATE、DATETIME または TIMESTAMP
uint32 INTEGER、NUMERIC、BIGNUMERIC または DATE
uint64 NUMERIC または BIGNUMERIC
sint32 INTEGER、NUMERIC、またはBIGNUMERIC
sint64 INTEGER、NUMERIC、BIGNUMERIC、DATE、DATETIME または TIMESTAMP
fixed32 INTEGER、NUMERIC、BIGNUMERIC または DATE
fixed64 NUMERIC または BIGNUMERIC
sfixed32 INTEGER、NUMERIC、BIGNUMERIC または DATE
sfixed64 INTEGER、NUMERIC、BIGNUMERIC、DATE、DATETIME または TIMESTAMP
bool BOOLEAN
string STRING、JSON、TIMESTAMP、DATETIME、DATE、TIME、NUMERIC、またはBIGNUMERIC
bytes BYTES、NUMERIC、またはBIGNUMERIC
enum INTEGER
message RECORD/STRUCT
oneof マッピング不可
map<KeyType, ValueType> REPEATED RECORD<key KeyType, value ValueType>
enum INTEGER
repeated/array of Type REPEATED Type

日付と時刻の整数表現

整数から日付型または時刻型のいずれかにマッピングする場合、数値が正しい値を表す必要があります。BigQuery のデータ型からデータ型を表す整数へのマッピングを以下に示します。

BigQuery のデータ型 整数表現
DATE Unix エポックである1970 年 1 月 1 日からの日数
DATETIME CivilTimeEncoder を使用して常用時として表された日時（マイクロ秒単位）
TIME CivilTimeEncoder を使用して常用時として表された時間（マイクロ秒単位）
TIMESTAMP Unix エポックである1970 年 1 月 1 日 00:00:00 UTC からのマイクロ秒数

BigQuery の変更データ キャプチャ

BigQuery サブスクリプションでは、use_topic_schema または use_table_schema がサブスクリプション プロパティで true に設定されてる場合、変更データ キャプチャ（CDC）の更新がサポートされます。use_topic_schema でこの機能を使用するには、次のフィールドを使用してトピックのスキーマを設定します。

  • _CHANGE_TYPE（必須）: UPSERT または DELETE に設定された string フィールド。

    • BigQuery テーブルに書き込まれた Pub/Sub メッセージの _CHANGE_TYPE が UPSERT に設定されている場合、BigQuery は同じキーが存在する場合は対象のキーで行を更新し、同じキーが存在しない場合は新しい行を挿入します。

    • BigQuery テーブルに書き込まれた Pub/Sub メッセージの _CHANGE_TYPE が DELETE に設定されている場合、BigQuery は同じがキーが存在する場合は対象のキーでテーブル内の行を削除します。

  • _CHANGE_SEQUENCE_NUMBER（省略可）: BigQuery テーブルに対する更新と削除を確実に行うために設定された int64（long）または int32（int）フィールドが順番に処理されます。同じ行キーのメッセージには、_CHANGE_SEQUENCE_NUMBER の単調に増加する値が含まれている必要があります。行に対して処理された最大シーケンス番号よりも小さいシーケンス番号を持つメッセージは、BigQuery テーブルの行には影響しません。

use_table_schema でこの機能を使用するには、上記のフィールドを JSON メッセージに含めます。

Pub/Sub サービス アカウントの権限

BigQuery サブスクリプションを作成するには、Pub/Sub サービス アカウントに、特定の BigQuery テーブルへの書き込みとテーブル メタデータの読み取りを行う権限が必要です。詳細については、BigQuery のロールを Pub/Sub サービス アカウントに割り当てるをご覧ください。

メッセージ エラーの処理

Pub/Sub メッセージを BigQuery に書き込めない場合、メッセージの確認応答はできません。このような配信不能メッセージを転送するには、BigQuery サブスクリプションでデッドレター トピックを構成します。デッドレター トピックに転送される Pub/Sub メッセージには、Pub/Sub メッセージを BigQuery に書き込めなかった理由を示す属性 CloudPubSubDeadLetterSourceDeliveryErrorMessage が含まれています。

割り当てと上限

リージョンごとの BigQuery サブスクライバーのスループットには割り当て上限があります。詳細については、Pub/Sub の割り当てと上限をご覧ください。

BigQuery サブスクリプションは、BigQuery Storage Write API を使用してデータを書き込みます。Storage Write API の割り当てと制限については、BigQuery Storage Write API リクエストをご覧ください。BigQuery のサブスクリプションは、Storage Write API のスループットの割り当てのみを消費します。このインスタンスでは、Storage Write API の他の割り当て考慮事項は無視できます。

料金

BigQuery サブスクリプションの料金については、Pub/Sub の料金ページをご覧ください。

次のステップ