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。
spannerTableId エクスポートする Spanner データベースのテーブル名。
sqlQuery Spanner データベースからデータを読み取るために使用する SQL クエリ。
outputTableSpec 書き込み先の BigQuery テーブル。例: <project>:<dataset>.<table_name>
spannerProjectId 省略可: Spanner データベースが存在するプロジェクトの ID。このパラメータのデフォルト値は、Dataflow パイプラインが動作しているプロジェクトです。
spannerRpcPriority 省略可: Cloud Spanner 呼び出しのリクエストの優先度。有効な値は HIGH、MEDIUM、LOW です。デフォルト値は HIGH です。
bigQuerySchemaPath 省略可: BigQuery スキーマを定義する JSON ファイルへの Cloud Storage パス（gs://）。例: gs://path/to/my/schema.json
writeDisposition 省略可: BigQuery WriteDisposition。サポートされる値は WRITE_APPEND、WRITE_EMPTY、WRITE_TRUNCATE です。デフォルト値は WRITE_APPEND です。
createDisposition 省略可: BigQuery CreateDisposition。サポートされる値は CREATE_IF_NEEDED と CREATE_NEVER です。デフォルト値は CREATE_IF_NEEDED です。
useStorageWriteApi 省略可: true の場合、パイプラインは BigQuery Storage Write API を使用します。デフォルト値は false です。詳細については、Storage Write API の使用をご覧ください。
useStorageWriteApiAtLeastOnce 省略可: Storage Write API を使用する場合は、書き込みセマンティクスを指定します。at-least-once セマンティクスを使用するには、このパラメータを true に設定します。1 回限りのセマンティクスを使用するには、パラメータを false に設定します。このパラメータは、useStorageWriteApi が true の場合にのみ適用されます。デフォルト値は false です。

テンプレートを実行する

コンソール

  1. Dataflow の [テンプレートからジョブを作成] ページに移動します。
    2. [テンプレートからジョブを作成] に移動
  2. [ジョブ名] フィールドに、固有のジョブ名を入力します。
  3. （省略可）[リージョン エンドポイント] で、プルダウン メニューから値を選択します。デフォルトのリージョンは us-central1 です。

    Dataflow ジョブを実行できるリージョンのリストについては、Dataflow のロケーションをご覧ください。

  4. [Dataflow テンプレート] プルダウン メニューから、the Spanner to BigQuery template を選択します。
  5. 表示されたパラメータ フィールドに、パラメータ値を入力します。
  6. [ジョブを実行] をクリックします。

gcloud

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

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 テーブルのロケーション

API

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" }
  }
}

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

  • PROJECT_ID: Dataflow ジョブを実行する Google Cloud プロジェクトの ID
  • JOB_NAME: 一意の任意のジョブ名
  • VERSION: 使用するテンプレートのバージョン

    使用できる値は次のとおりです。

    • latest: 最新バージョンのテンプレートを使用します。このテンプレートは、バケット内で日付のない親フォルダ（gs://dataflow-templates-REGION_NAME/latest/）にあります。
    • バージョン名（例: 2023-09-12-00_RC00）。特定のバージョンのテンプレートを使用します。このテンプレートは、バケット内で対応する日付の親フォルダ（gs://dataflow-templates-REGION_NAME/）にあります。
  • LOCATION: Dataflow ジョブをデプロイするリージョン（例: us-central1）
  • SPANNER_INSTANCE_ID: Spanner インスタンス ID
  • SPANNER_DATABASE_ID: Spanner データベース ID
  • SPANNER_TABLE_ID: Spanner テーブル名
  • SQL_QUERY: SQL クエリ
  • OUTPUT_TABLE_SPEC: BigQuery テーブルのロケーション

次のステップ