Dataform の operations で DTS 転送先テーブルに description を設定する

公開日 2026.3.21

カテゴリ：Dataform
タグ：Dataform,BigQuery,Terraform,自分用メモ

Dataform の operations で DTS 転送先テーブルに description を設定する

DTS（Data Transfer Service）で BigQuery にデータを取り込む際、書き込みモードに WRITE_TRUNCATE（洗い替え）を使うと、テーブルとカラムの description が消える可能性がある。テーブル数が増えるほど手動での再設定は現実的でなくなる。

本記事では、Dataform の type: "operations" で ALTER TABLE を実行し、DTS 転送後に description を自動で再設定する方法を記録する。

前提
方針
IAM 権限の追加
SQLX ファイルの作成
動作確認
1. 開発ワークスペースでの実行
2. Workflows パイプラインでの確認
テーブル追加時の運用

前提

Workflows で DTS + Dataform の ETL パイプラインを構築済み
DTS 転送先データセット: dl_gcs（GCS コネクタ）、dl_s3（S3 コネクタ）
Dataform の SA: dataform-executor
Terraform でインフラ管理済み

パイプラインの構成:

Cloud Scheduler
  │
  ↓
Cloud Workflows
  ├→ DTS: GCS / S3 転送（並列実行）
  │
  │  全て完了を待つ
  ↓
  └→ Dataform: ワークフロー実行
       ├→ dwh/dm テーブル作成
       └→ dl テーブル description 設定 ← 今回追加

方針

description の管理方法として以下を検討した。

方法	概要	評価
Dataform operations	SQLX で ALTER TABLE を実行	追加の仕組み不要。パイプライン内で自動適用
Cloud Run Function	JSON スキーマ定義 + API で適用	Function の開発・デプロイが必要
Terraform	`google_bigquery_table` で管理	DTS の WRITE_TRUNCATE と drift が発生する

Dataform operations を採用。理由:

追加の仕組みが不要（Dataform の既存機能で完結）
DTS → Dataform のパイプライン内で自然に適用される
SQLX ファイルとして Git 管理される
ALTER TABLE のコストは 0（スキャン量なし）

IAM 権限の追加

Dataform の SA（dataform-executor）は、これまで dl 層データセットに対して bigquery.dataViewer（読み取り専用）しか持っていなかった。ALTER TABLE の実行には bigquery.dataEditor が必要になる。

terraform/modules/dataform/service_account.tf に追加:

# BigQuery データ編集者（dl_gcs）- description 設定用
resource "google_bigquery_dataset_iam_member" "dl_gcs_editor" {
  dataset_id = "dl_gcs"
  role       = "roles/bigquery.dataEditor"
  member     = "serviceAccount:${google_service_account.dataform_executor.email}"
}

# BigQuery データ編集者（dl_s3）- description 設定用
resource "google_bigquery_dataset_iam_member" "dl_s3_editor" {
  dataset_id = "dl_s3"
  role       = "roles/bigquery.dataEditor"
  member     = "serviceAccount:${google_service_account.dataform_executor.email}"
}

適用後の dataform-executor SA の権限:

データセット	ロール	用途
dl_sample	bigquery.dataViewer	ソースデータ読み取り
dl_gcs	bigquery.dataEditor	description 設定
dl_s3	bigquery.dataEditor	description 設定
dwh_sample	bigquery.dataEditor	テーブル作成
dm_sample	bigquery.dataEditor	テーブル作成

SQLX ファイルの作成

Dataform の開発ワークスペースで、type: "operations" の SQLX ファイルを作成する。テーブルごとに 1 ファイルとする。

ディレクトリ構成

definitions/
  dl_gcs/
    descriptions_stores.sqlx
  dl_s3/
    descriptions_orders.sqlx
    descriptions_products.sqlx
    descriptions_users.sqlx
    descriptions_stores_parquet.sqlx
    descriptions_stores_csv.sqlx

SQLX の書き方

type: "operations" は任意の SQL を実行するための SQLX タイプ。--- で区切ることで、1 ファイル内に複数の SQL ステートメントを記述できる。

definitions/dl_gcs/descriptions_stores.sqlx:

config {
    type: "operations",
    tags: ["dl_descriptions"]
}

ALTER TABLE `project-id.dl_gcs.stores`
SET OPTIONS (description = "店舗マスタ（GCS CSV 転送）")
---
ALTER TABLE `project-id.dl_gcs.stores`
ALTER COLUMN store_id SET OPTIONS (description = "店舗ID")
---
ALTER TABLE `project-id.dl_gcs.stores`
ALTER COLUMN store_name SET OPTIONS (description = "店舗名")
---
ALTER TABLE `project-id.dl_gcs.stores`
ALTER COLUMN prefecture SET OPTIONS (description = "都道府県")
---
ALTER TABLE `project-id.dl_gcs.stores`
ALTER COLUMN opened_at SET OPTIONS (description = "開店日")

テーブル description は ALTER TABLE ... SET OPTIONS (description = "...") で設定
カラム description は ALTER TABLE ... ALTER COLUMN ... SET OPTIONS (description = "...") で設定
BigQuery は 1 ステートメントに 1 つの ALTER TABLE しか実行できないため、--- で区切る
--- は Dataform の operations における複数ステートメント区切り構文
tags: ["dl_descriptions"] を付けておくと、タグ単位での実行も可能

他のテーブルも同じパターンで作成する。definitions/dl_s3/descriptions_orders.sqlx:

config {
    type: "operations",
    tags: ["dl_descriptions"]
}

ALTER TABLE `project-id.dl_s3.orders`
SET OPTIONS (description = "注文ヘッダー（S3 Parquet 転送）")
---
ALTER TABLE `project-id.dl_s3.orders`
ALTER COLUMN order_id SET OPTIONS (description = "注文ID")
---
ALTER TABLE `project-id.dl_s3.orders`
ALTER COLUMN user_id SET OPTIONS (description = "ユーザーID")
---
ALTER TABLE `project-id.dl_s3.orders`
ALTER COLUMN ordered_at SET OPTIONS (description = "注文日時")
---
ALTER TABLE `project-id.dl_s3.orders`
ALTER COLUMN status SET OPTIONS (description = "ステータス（pending/completed/cancelled）")

description の上限

BigQuery のカラム description は最大 1,024 文字。

Workflows の変更は不要

Workflows の Dataform 呼び出しでは includedTags 等のフィルタを指定していないため、リポジトリ内の全 SQLX が実行対象になる。今回追加した operations ファイルも、既存の dwh/dm テーブル作成と一緒に自動で実行される。

動作確認

開発ワークスペースでの実行

Dataform の開発ワークスペースで SQLX ファイルを作成し、手動実行して description が設定されることを確認する。

Workflows パイプラインでの確認

SQLX を main ブランチにマージした後、Cloud Scheduler から Workflows を強制実行する。

Cloud Scheduler → 強制実行
  → DTS（WRITE_TRUNCATE で全件洗い替え）
  → Dataform（operations で description 再設定）

パイプライン完了後、bq show で description が設定されていることを確認する。

$ bq show --format=json project-id:dl_gcs.stores | python3 -c "
import sys, json
d = json.load(sys.stdin)
print('table:', d.get('description', '(なし)'))
for f in d.get('schema', {}).get('fields', []):
    print('  ' + f['name'] + ': ' + f.get('description', '(なし)'))
"
table: 店舗マスタ（GCS CSV 転送）
  store_id: 店舗ID
  store_name: 店舗名
  prefecture: 都道府県
  opened_at: 開店日

DTS の WRITE_TRUNCATE 後でも、Dataform の operations で description が再設定されている。

テーブル追加時の運用

新しいテーブルが DTS で追加された場合の手順:

definitions/dl_<dataset>/descriptions_<table>.sqlx を作成
Dataform 開発ワークスペースで動作確認
PR → main マージ

SQLX ファイルはテーブル定義から機械的に作成できる。

まとめ

DTS の WRITE_TRUNCATE で消える description を、Dataform の type: "operations" で毎回再設定する構成を構築した
テーブルごとに 1 SQLX ファイルとし、--- 区切りで複数の ALTER TABLE を実行する
Dataform の SA に dl 層データセットへの bigquery.dataEditor 権限が必要
既存の Workflows パイプラインの変更は不要。Dataform 実行時に自動で operations が含まれる
ALTER TABLE のコストは 0（スキャン量なし）で、パイプラインへの負荷もない