Spanner to BigQuery テンプレート

Spanner to BigQuery テンプレートは、Spanner テーブルからデータを読み取り、BigQuery に書き込むバッチパイプラインです。

パイプラインの要件

パイプラインを実行する前に、ソースの Spanner テーブルが存在する必要があります。
パイプラインの実行前に BigQuery データセットが存在している必要があります。
BigQuery スキーマを記述する JSON ファイル。
このファイルには、fields というタイトルの最上位の JSON 配列が含まれている必要があります。fields 配列の内容は、次のパターンを使用する必要があります。
{"name": "COLUMN_NAME", "type": "DATA_TYPE"}.

次の JSON は、BigQuery スキーマの例を示しています。
```
{
  "fields": [
    {
      "name": "location",
      "type": "STRING"
    },
    {
      "name": "name",
      "type": "STRING"
    },
    {
      "name": "age",
      "type": "STRING"
    },
    {
      "name": "color",
      "type": "STRING"
    },
    {
      "name": "coffee",
      "type": "STRING"
    }
  ]
}
```
Spanner to BigQuery バッチテンプレートでは、ターゲットの BigQuery テーブルの STRUCT（レコード）フィールドへのデータのインポートはサポートされていません。

テンプレートのパラメータ

必須パラメータ

spannerInstanceId: 読み取り元の Spanner データベースのインスタンス ID。
spannerDatabaseId: エクスポートする Spanner データベースのデータベース ID。
outputTableSpec: 出力を書き込む BigQuery 出力テーブルの場所。たとえば、<PROJECT_ID>:<DATASET_NAME>.<TABLE_NAME> です。指定された createDisposition によっては、ユーザーが指定した Avro スキーマを使用して出力テーブルが自動的に作成される場合があります。

オプションパラメータ

spannerProjectId: 省略可: Spanner データベースが存在するプロジェクトの ID。このパラメータのデフォルト値は、Dataflow パイプラインが動作しているプロジェクトです。
spannerTableId: エクスポートする Spanner データベースのテーブル名。sqlQuery が設定されている場合は無視されます。
spannerRpcPriority: Spanner 呼び出しのリクエストの優先度（https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions）。有効な値は HIGH、MEDIUM、LOW です。デフォルト値は HIGH です。
sqlQuery: Spanner データベースからデータを読み取るために使用する SQL クエリ。spannerTableId が空の場合は必須です。
bigQuerySchemaPath: BigQuery スキーマを定義する JSON ファイルの Cloud Storage パス（gs://）（例: gs://your-bucket/your-schema.json）。
writeDisposition : BigQuery WriteDisposition（https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationload）の値。例: WRITE_APPEND、WRITE_EMPTY、WRITE_TRUNCATE。デフォルトは WRITE_APPEND です。
createDisposition: BigQuery CreateDisposition（https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationload）。たとえば、CREATE_IF_NEEDED や CREATE_NEVER です。デフォルトは CREATE_IF_NEEDED です。
useStorageWriteApi: true の場合、パイプラインでは BigQuery Storage Write API（https://cloud.google.com/bigquery/docs/write-api）を使用します。デフォルト値は false です。詳細については、Storage Write API の使用（https://beam.apache.org/documentation/io/built-in/google-bigquery/#storage-write-api）をご覧ください。
useStorageWriteApiAtLeastOnce: Storage Write API を使用する場合は、書き込みセマンティクスを指定します。at-least-once セマンティクス（https://beam.apache.org/documentation/io/built-in/google-bigquery/#at-least-once-semantics）を使用するには、このパラメータを true に設定します。exactly-once セマンティクスを使用するには、パラメータを false に設定します。このパラメータは、useStorageWriteApi が true の場合にのみ適用されます。デフォルト値は false です。

テンプレートを実行する

コンソールgcloudAPI

Dataflow の [テンプレートからジョブを作成] ページに移動します。

[テンプレートからジョブを作成] に移動

[ジョブ名] フィールドに、固有のジョブ名を入力します。
（省略可）[リージョンエンドポイント] で、プルダウンメニューから値を選択します。デフォルトのリージョンは us-central1 です。
Dataflow ジョブを実行できるリージョンのリストについては、Dataflow のロケーションをご覧ください。
[Dataflow テンプレート] プルダウンメニューから、[ the Spanner to BigQuery template] を選択します。
表示されたパラメータフィールドに、パラメータ値を入力します。
[ジョブを実行] をクリックします。

シェルまたはターミナルで、テンプレートを実行します。

gcloud dataflow flex-template run JOB_NAME \
    --template-file-gcs-location=gs://dataflow-templates-REGION_NAME/VERSION/flex/Cloud_Spanner_to_BigQuery_Flex \
    --project=PROJECT_ID \
    --region=REGION_NAME \
    --parameters \
       spannerInstanceId=SPANNER_INSTANCE_ID,\
       spannerDatabaseId=SPANNER_DATABASE_ID,\
       spannerTableId=SPANNER_TABLE_ID,\
       sqlQuery=SQL_QUERY,\
       outputTableSpec=OUTPUT_TABLE_SPEC,\

次のように置き換えます。

JOB_NAME: 一意の任意のジョブ名
VERSION: 使用するテンプレートのバージョン
使用できる値は次のとおりです。
- latest: 最新バージョンのテンプレートを使用します。このテンプレートは、バケット内で日付のない親フォルダ（gs://dataflow-templates-REGION_NAME/latest/）にあります。
- バージョン名（例: 2023-09-12-00_RC00）。特定のバージョンのテンプレートを使用します。このテンプレートは、バケット内で対応する日付の親フォルダ（gs://dataflow-templates-REGION_NAME/）にあります。
注: 最新のテンプレートでは、互換性のない変更が行われている場合があります。こうした互換性のない変更が本番環境のワークフローに影響しないように、本番環境では最新の日付付き親フォルダに保存されているテンプレートを使用する必要があります。
REGION_NAME: Dataflow ジョブをデプロイするリージョン（例: us-central1）
SPANNER_INSTANCE_ID: Spanner インスタンス ID
SPANNER_DATABASE_ID: Spanner データベース ID
SPANNER_TABLE_ID: Spanner テーブル名
SQL_QUERY: SQL クエリ
OUTPUT_TABLE_SPEC: BigQuery テーブルのロケーション

REST API を使用してテンプレートを実行するには、HTTP POST リクエストを送信します。API とその認証スコープの詳細については、projects.templates.launch をご覧ください。

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
{
   "launchParameter": {
     "jobName": "JOB_NAME",
     "parameters": {
       "spannerInstanceId": "SPANNER_INSTANCE_ID",
       "spannerDatabaseId": "SPANNER_DATABASE_ID",
       "spannerTableId": "SPANNER_TABLE_ID",
       "sqlQuery": "SQL_QUERY",
       "outputTableSpec": "OUTPUT_TABLE_SPEC",
     },
     "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/Cloud_Spanner_to_BigQuery_Flex",
     "environment": { "maxWorkers": "10" }
  }
}