このページは Cloud Translation API によって翻訳されました。

テーブルの作成

Dataform では、テーブルはワークフローを構成するオブジェクトの種類の一つです。ワークフロー用に宣言されたデータソースまたはワークフロー内の他のテーブルのデータを参照するテーブルを作成できます。Dataform は、テーブル定義をリアルタイムで SQL にコンパイルします。実行をトリガーすると、Dataform は SQL コードを実行し、BigQuery で定義済みテーブルを作成します。

type: "table" SQLX ファイルで次のテーブルタイプを作成できます。

table: 通常のテーブル。
incremental: 増分テーブル。
view: テーブルビュー。詳細については、ビューの概要をご覧ください。
- materialized: マテリアライズドテーブルビュー。詳細については、マテリアライズドビューの概要をご覧ください。

テーブルのパーティションとクラスタを定義することもできます。

テーブルの目的や、ワークフロー内の他のテーブルとの関係を記録するには、テーブルまたは選択した列にドキュメントを追加します。

テーブル内のデータを特定の条件に対してテストするには、アサーションと呼ばれるデータ品質テストクエリを作成します。 Dataform は、ワークフローを更新するたびにアサーションを実行し、アサーションが失敗した場合にアラートを送信します。

選択したテーブルのデフォルトのスキーマ、データベース、名前をオーバーライドするには、テーブル設定をオーバーライドします。

テーブルの作成を無効にするか、テーブルの作成前または作成後に SQL ステートメントを実行するには、追加のアクションを構成します。

BigQuery でテーブルを実行した後に整理するには、BigQuery ラベルを追加します。詳細については、ラベルの概要をご覧ください。

テーブルの列レベルでデータアクセスを制限するには、BigQuery ポリシータグを追加します。詳細については、列レベルのアクセス制御の概要をご覧ください。

type: "table" SQLX ファイルでテーブルを定義するだけでなく、type: "operations" SQLX ファイルでカスタム SQL クエリを定義することで、空のテーブルを作成できます。別のサービスでデータを入力できるように、空白のテーブルを作成することもできます。

始める前に

Google Cloud コンソールで、[Dataform] ページに移動します。

Dataform に移動
リポジトリで開発ワークスペースを作成して初期化します。
省略可: データソースを宣言します。

必要なロール

このドキュメントのタスクを完了するために必要な権限を取得するには、ワークスペースに対する Dataform 編集者（roles/dataform.editor）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

テーブルを作成する

このセクションでは、Dataform で Dataform コアを使用してテーブルを作成する方法について説明します。

テーブル定義について

テーブルを定義するには、テーブルタイプを定義し、type: "table" SQLX ファイルに SELECT ステートメントを記述します。次に、Dataform は、Dataform コアのコードを SQL にコンパイルして SQL コードを実行し、BigQuery で定義済みテーブルを作成します。

Dataform コアの SELECT ステートメントでは、テーブル構造を定義して、ワークフローの他のオブジェクトを参照します。

type: "table" SQLX ファイルでテーブルを定義するだけでなく、type: "operations" SQLX ファイルでカスタム SQL クエリを定義することで、空のテーブルを作成できます。詳細については、空のテーブルを作成するをご覧ください。

`ref` を使用して依存関係を参照する

SELECT ステートメントでワークフローアクションを参照し、依存関係として自動的に追加するには、ref 関数を使用します。Dataform は、正しいパイプラインの順序を確認するため、テーブルに依存するテーブルの前に依存関係を実行します。

ref 関数は、Dataform の依存関係管理に不可欠な Dataform コアの組み込み関数です。ref 関数を使用すると、スキーマとテーブル名をハードコードする代わりに、Dataform ワークフローで定義された次のオブジェクトを参照して自動的に依存関係を設定できます。

サポートされているすべてのテーブルタイプのテーブル。
データソースの宣言。
hasOutput プロパティが true に設定されたカスタム SQL オペレーション。

Dataform は ref 関数を使用して、作成または更新されるすべてのテーブルの依存関係ツリーを構築します。

コンパイル後、Dataform は CREATE、REPLACE、INSERT、MERGE などの定型ステートメントを SQL ステートメントに追加します。

次のコードサンプルは、ref 関数を使用したテーブル定義を示しています。

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

ref 関数で、依存するテーブルまたはデータソース宣言の名前を指定します。通常、これはテーブルまたはデータソース宣言が定義されている SQLX ファイルのファイル名です。

テーブル名がオーバーライドされている場合は、ref 関数でオーバーライドされた名前を使用します。たとえば、config { name: "overridden_name" } を ref("overridden_name") としてテーブルを参照します。詳細については、テーブル設定をオーバーライドするとオーバーライドされたテーブル名でテーブルを参照するをご覧ください。

異なるスキーマに同じ名前のテーブルが複数ある場合は、ref 関数にスキーマ名とテーブル名の 2 つの引数を指定して、特定のテーブルを参照できます。

次のコードサンプルは、特定のスキーマ内のテーブルを指定する 2 つの引数を持つ ref 関数を示しています。

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

また、SELECT ステートメントの ref 関数で参照されていないテーブル、アサーション、データソース宣言、またはカスタム SQL オペレーションの config ブロックにテーブルの依存関係を手動で追加することもできます。Dataform は、従属テーブルの前にこれらの依存関係を実行します。

次のコードサンプルは、config ブロックのテーブル依存関係を示しています。

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

ワークフローでの依存関係の管理の詳細については、依存関係を設定するをご覧ください。

`resolve` を使用して他のテーブルを参照する

resolve 関数を使用すると、ref 関数のように SELECT ステートメントでテーブルまたはデータソースの宣言を参照できますが、参照は依存関係として追加されません。つまり、resolve 関数を使用して参照されるオブジェクトは、resolve 関数を使用するテーブルの実行に影響しません。

組み込みの Dataform コア関数の詳細については、Dataform コアのリファレンスをご覧ください。

テーブル定義用の SQLX ファイルを作成する

テーブル定義 SQLX ファイルを definitions/ ディレクトリに保存します。definitions/ ディレクトリに新しい SQLX ファイルを作成する手順は次のとおりです。

Google Cloud コンソールで、[Dataform] ページに移動します。

Dataform に移動
リポジトリを開くには、リポジトリ名をクリックします。
開発ワークスペースを開くには、ワークスペース名をクリックします。
[ファイル] ペインで、definitions/ の横にある [その他] をクリックします。
[ファイルを作成] をクリックします。
[ファイルパスを追加] フィールドに、ファイルの名前の後に definitions/ の後に .sqlx を入力します。例: definitions/my-table.sqlx。

ファイル名には数字、英字、ハイフン、アンダースコアのみを使用できます。
[ファイルを作成] をクリックします。

テーブルの型を定義する

新しいテーブル型の定義を作成する手順は次のとおりです。

開発ワークスペースの [ファイル] ペインで definitions/ ディレクトリを開きます。
編集するテーブル定義 SQLX ファイルを選択します。
このファイルに次のコードスニペットを入力します。
```
config { type: "TABLE_TYPE" }
```
TABLE_TYPE は、次のいずれかのテーブルタイプに置き換えます。
- table
- incremental
- view
省略可: マテリアライズドビューを定義するには、type: "view" で次の形式で materialized プロパティを入力します。
```
config {
  type: "view",
  materialized: true
}
```
詳細については、ITableConfig をご覧ください。
省略可: [書式] をクリックします。

テーブルの構造と依存関係を定義する

テーブル定義 SELECT ステートメントを記述してテーブルの構造と依存関係を定義する手順は次のとおりです。

開発ワークスペースの [ファイル] ペインで definitions/ ディレクトリを開きます。
編集するテーブル定義 SQLX ファイルを選択します。
config ブロックの下に、SELECT ステートメントを記述します。
省略可: [書式] をクリックします。

次のコードサンプルは、SELECT ステートメントと ref 関数を含むテーブル定義を示しています。

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

手動テーブルの依存関係を追加する

SELECT ステートメントで参照されていないものの、現在のテーブルの前に実行する必要があるテーブルの依存関係を追加するには、次の手順を行います。

開発ワークスペースの [ファイル] ペインで definitions/ ディレクトリを開きます。
編集するテーブル定義 SQLX ファイルを選択します。
テーブルの config ブロックに次のコードスニペットを入力します。
```
dependencies: [ "DEPENDENCY_TABLE", ]
```
DEPENDENCY_TABLE は、依存関係として追加するテーブルのファイル名に置き換えます。複数のファイル名を入力できます。
省略可: [書式] をクリックします。

次のサンプルコードは、テーブル定義ファイルの config ブロックに手動のテーブル依存関係として追加される 2 つのテーブルを示しています。

config { dependencies: [ "some_table", "some_other_table" ] }

テーブルの設定をオーバーライドする

選択したテーブルのデフォルトのスキーマ、データベース、名前をオーバーライドできます。

デフォルトでは、テーブルは workflow_settings.yaml で設定したスキーマとデータベースの構成に従います。テーブルの名前は、テーブル定義 SQLX ファイルの名前と同じです。

選択したテーブルのスキーマと名前をオーバーライドする手順は次のとおりです。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
SQLX テーブル定義ファイルを開きます。
このファイルに次のコードスニペットを入力します。
```
 {
   schema: "OVERRIDDEN_SCHEMA",
   database: "OVERRIDDEN_DATABASE",
   name: "OVERRIDDEN_NAME"
 }
```
次のように置き換えます。
- OVERRIDDEN_SCHEMA: テーブルを作成する BigQuery データセット。
- OVERRIDDEN_DATABASE: テーブルを作成する BigQuery プロジェクトの ID。
- OVERRIDDEN_NAME: テーブルの名前。SQLX テーブル定義のファイル名とは異なります。
省略可: [書式] をクリックします。

詳細については、オーバーライドされたテーブル名でテーブルを参照するをご覧ください。

テーブルパーティションとクラスタを作成する

このセクションでは、Dataform コアを使用してテーブルパーティションとクラスタを作成する方法について説明します。BigQuery は、パーティション分割テーブルとテーブルクラスタリングをサポートしています。詳細については、パーティション分割テーブルの概要とクラスタ化テーブルの作成と使用をご覧ください。

テーブルパーティションを作成する

テーブルパーティションを作成するには、次の手順に沿って操作します。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
テーブル定義 SQLX ファイルを開きます。
config ブロックで、テーブルタイプの宣言の下に次の形式で bigquery ブロックを追加します。
```
config {
  type: "table",
  bigquery: {
  }
}
```
この bigquery ブロックに次のコードスニペットを入力します。
```
    partitionBy: "PARTITION_EXPRESSION"
```
PARTITION_EXPRESSION は、テーブルをパーティショニングするための式に置き換えます。
省略可: [書式] をクリックします。

次のサンプルコードは、テーブル定義 SQLX ファイルでの 1 時間ごとのテーブル分割を示しています。

config {
  type: "table",
  bigquery: {
    partitionBy: "DATETIME_TRUNC(<timestamp_column>, HOUR)"
  }
}

次のサンプルコードは、テーブル定義 SQLX ファイルでの整数値にるテーブル分割を示しています。

config {
  type: "table",
  bigquery: {
    partitionBy: "RANGE_BUCKET(<integer_column>, GENERATE_ARRAY(0, 1000000, 1000))"
  }
}

パーティションフィルタを設定する

パーティションフィルタを設定する手順は次のとおりです。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
パーティション分割テーブルの定義 SQLX ファイルを開きます。
この bigquery ブロックに次のコードスニペットを入力します。
```
requirePartitionFilter : true
```
省略可: [書式] をクリックします。

次のサンプルコードは、パーティション分割テーブル SQLX ファイルの bigquery ブロックに設定されたパーティションフィルタを示しています。

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    requirePartitionFilter : true
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

BigQuery のパーティションフィルタの詳細については、パーティション分割テーブルのパーティションフィルタ必須属性の設定をご覧ください。

パーティションの保持期間を設定する

パーティション分割テーブル内のすべてのパーティションの保持を制御するには、次の操作を行います。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
パーティション分割テーブルの定義 SQLX ファイルを開きます。
この bigquery ブロックに次のコードスニペットを入力します。
```
partitionExpirationDays: NUMBER_OF_DAYS
```
NUMBER_OF_DAYS は、パーティションを保持する日数に置き換えます。
省略可: [書式] をクリックします。

次のコードサンプルは、パーティション分割テーブル SQLX ファイルの bigquery ブロックで、14 日に設定されたパーティションの保持期間を示しています。

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    partitionExpirationDays: 14,
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

テーブルクラスタを作成する

テーブルクラスタを作成するには、次の手順に沿って操作します。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
テーブル定義 SQLX ファイルを開きます。
この bigquery ブロックに次のコードスニペットを入力します。
```
    clusterBy: ["CLUSTER_COLUMN"]
```
CLUSTER_COLUMN は、テーブルをクラスタ化する列の名前に置き換えます。詳細については、clustering_column_list をご覧ください。
省略可: [書式] をクリックします。

次のコードサンプルは、name 列と revenue 列でクラスタ化されたパーティション分割テーブルを示しています。

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    clusterBy: ["name", "revenue"]
  }
}
SELECT CURRENT_TIMESTAMP() as ts, name, revenue

増分テーブルを構成する

このセクションでは、Dataform コアを使用して増分テーブルを構成する方法について説明します。

増分テーブルについて

Dataform は、テーブルのタイプに基づいてテーブルを異なる方法で更新します。テーブルまたはビューの実行ごとに、Dataform はテーブルまたはビュー全体をゼロから再構築します。

増分テーブルを定義すると、Dataform は初回のみ増分テーブルをゼロから作成します。後続の実行では、構成した条件に従って、新しい行のみが増分テーブルに挿入または統合されます。

Dataform は、増分テーブルにすでに存在する列にのみ新しい行を挿入します。新しい列を追加するなどして、増分テーブル定義クエリを変更する場合、テーブルを最初から再構築するかどうかを決定する必要があります。テーブルを再構築するには、次回テーブルの実行をトリガーするときに、[フル更新で実行] オプションを選択します。その他のオプションについては、完全な更新なしで増分テーブルスキーマを変更するをご覧ください。

増分テーブルの一般的なユースケースを次に示します。

パフォーマンスの最適化: ウェブログや分析データなど、一部のデータについては、テーブル全体を再処理するのではなく、新しいレコードのみを処理することをおすすめします。
レイテンシの短縮: 増分テーブルを使用すると、ワークフローをすばやく頻繁に実行して、出力テーブルの下流レイテンシを短縮できます。
日次スナップショット: 増分テーブルを構成して、テーブルデータの日次スナップショットを作成できます。たとえば、本番環境のデータベースに格納されているユーザー設定の長期的な分析を行う場合などです。

増分テーブルの行のサブセットを処理する

Dataform が各実行で処理する行のサブセットを決定するには、増分テーブルの SQLX 定義ファイルに条件付き WHERE 句を追加します。WHERE 句では、増分条件と非増分条件を指定できます。Dataform は、フル更新なしでテーブルを実行するときに増分条件を適用し、フル更新で実行するときに非増分条件を適用します。

増分テーブルを構成する手順は次のとおりです。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
増分テーブル定義の SQLX ファイルを開きます
次の形式で WHERE 句を入力します。
```
config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }
```
以下を置き換えます。
- SELECT_STATEMENT: テーブルを定義する SELECT ステートメント。
- INCREMENTAL_CONDITION: WHERE 句で指定する条件。完全な更新なしでテーブル実行中に Dataform が処理する行を選択します。
- NON_INCREMENTAL_CONDITION: WHERE 句で指定する条件。完全更新でテーブル実行中に Dataform が処理する行を選択します。
省略可: [書式] をクリックします。

次のコードサンプルは、productiondb.logs テーブルの行をインクリメントに処理する増分テーブルを示しています。

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

次のコードサンプルは、productiondb.customers テーブルのスナップショットを作成する増分テーブルを示しています。

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

増分テーブルの行を統合する

増分テーブルに、選択した列の組み合わせに対応する行が 1 つだけ含まれていることを確認するには、選択した列を uniqueKey として設定し、同じ uniqueKey 値を持つ行を統合します。テーブルを更新するとき、Dataform は行を追加するのではなく、同じ uniqueKey 値を持つ行を統合します。

増分テーブルでマージを構成する手順は次のとおりです。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
増分テーブル定義の SQLX ファイルを選択します
config ブロックで、選択した列を次の形式で uniqueKey として設定します。
```
uniqueKey: ["COLUMN_NAME"]
```
COLUMN_NAME は、選択した列の名前に置き換えます。
省略可: [書式] をクリックします。

次のコードサンプルは、transaction_id 列を uniqueKey として設定した増分テーブルを示し、常に 1 行が含まれることを確認します。

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

増分テーブルの行をフィルタする

増分パーティション分割テーブルで、一致する行を見つけるために Dataform がテーブル全体をスキャンしないようにするには、updatePartitionFilter を設定して、レコードのサブセットのみを考慮します。

次のサンプルコードは、uniqueKey プロパティと updatePartitionFilter プロパティを設定して、マージ処理が設定された増分パーティション分割テーブルを示しています。

config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

パーティション分割テーブルから取り込む際に、完全なテーブルスキャンを回避する

パーティション分割テーブルを参照する増分テーブルを作成する場合、各増分更新でパーティション分割テーブルの完全なテーブルスキャンを回避するためにテーブルクエリを作成することをおすすめします。

テーブルクエリで定数式を使用して増分テーブルを更新するために、BigQuery がスキャンするパーティション数を制限できます。パーティション分割テーブルの値を定数式に変換するには、BigQuery スクリプトを使用して pre_operations ブロックで変数として値を宣言します。次に、SELECT クエリの WHERE 句で、変数を定数式として使用します。

この構成により、Dataform は参照先パーティション分割テーブル全体をスキャンするのではなく、最新のパーティションに基づいて増分テーブルを更新します。

パーティション分割テーブルを参照し、完全なテーブルスキャンを回避する増分テーブルを構成するには、次の手順を行います。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
増分テーブル定義の SQLX ファイルを選択します
pre_operations ブロックで、BigQuery スクリプトを使用して変数を宣言します。
宣言された変数を参照する WHERE 句を使用して、テーブルを定義する SELECT ステートメントをフィルタします。
省略可: [書式] をクリックします。

次のサンプルコードは、参照先の raw_events テーブルが event_timestamp によって分割される増分テーブルを示しています。

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

上述のコードサンプルでは、event_timestamp_checkpoint 変数が pre_operations ブロックで定義されています。 event_timestamp_checkpoint 変数は、WHERE 句で定数式として使用されます。

フル更新で増分テーブルをゼロから再構築する

--full-refresh オプションを使用したコマンドラインインターフェース、またはワークフローの実行をトリガーするときに [フル更新で実行] を使用すると、増分テーブルをゼロから強制的に再構築できます。

フル更新オプションを選択した場合、開発ワークスペース、または Dataform CLI を使用して、Dataform は実行中に ${when(incremental(), ... } パラメータを無視し、CREATE OR REPLACE ステートメントでテーブルを再作成します。

フル更新から増分テーブルを保護する

増分テーブルをゼロから再作成して潜在的なデータ損失から保護するには、増分テーブルを protected として設定します。データソースが一時的な場合は、増分テーブルが再構築されないようにすることをおすすめします。

増分テーブルを protected としてマークする手順は次のとおりです。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
増分テーブル定義の SQLX ファイルを選択します。
config ブロックに「protected: true」と入力します。
省略可: [書式] をクリックします。

次のコードサンプルは、protected としてマークされた増分テーブルを示しています。

config {
  type: "incremental",
  protected: true
}
SELECT ...

フル更新なしで増分テーブルのスキーマを変更する

onSchemaChange 構成プロパティを使用すると、テーブルを完全に更新することなく、SELECT クエリで増分テーブルスキーマを変更できます。このプロパティを使用すると、履歴データを保持しながら、テーブルに新しい列を追加したり、既存の列を削除したりできます。このアプローチは、データ損失を防ぎ、BigQuery での手動更新を回避するのに役立ちます。

この機能を使用するには、Dataform コア 3.0.11 以降をインストールする必要があります。

onSchemaChange プロパティを設定すると、Dataform は SELECT クエリをチェックして、列が追加または削除されたかどうかを判断します。Dataform は、onSchemaChange プロパティの値で指定されたアクションを実行します。

onSchemaChange プロパティを設定する手順は次のとおりです。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
増分テーブル定義の SQLX ファイルを選択します。
この config ブロックに次のコードスニペットを入力します。
```
onSchemaChange: "ON_CHANGE_ACTION"
```
ON_CHANGE_ACTION は、次のいずれかの操作に置き換えます。
- IGNORE（デフォルト）: 追加された列を無視し、欠落している列のエラーを表示します。onSchemaChange が設定されていない場合、スキーマが変更されたときのデフォルトの動作になります。
- FAIL: Dataform がスキーマの変更を検出した場合にアクションを停止します。これにより、スキーマの一貫性を維持できます。
- EXTEND: クエリから増分テーブルに新しい列を追加し、以前のレコードに NULL 値を追加します。クエリの元のスキーマから列が削除されたり、列が欠落したりすると、エラーが表示されます。この設定を使用すると、実行時に増分テーブルに新しい列を追加できます。
- SYNCHRONIZE: クエリから増分テーブルに新しい列を追加し、以前のレコードの NULL 値を追加します。元のスキーマにはあったが、現在のクエリにはない列を削除します。
  
  注意: SYNCHRONIZE アクションは元に戻すことができません。このオプションを使用して列を削除すると、データが失われる可能性があります。
  注: パーティショニングされた列とクラスタ化された列の削除はサポートされていません。これらの列を削除すると、悪影響が生じる可能性があります。パーティショニングされた列またはクラスタ化された列が削除された場合、ALTER TABLE DROP COLUMN ステートメントで処理されます。Dataform は、パーティション分割列またはクラスタ化列での ALTER TABLE DROP COLUMN ステートメントの実行を防ぐためのチェックや検証を行いません。したがって、このような列を削除する場合は、慎重に進め、潜在的な悪影響に注意してください。
省略可: [書式] をクリックします。

次のコードサンプルは、onSchemaChange プロパティに EXTEND アクションが設定された増分テーブルを示しています。

config {
    type: "incremental",
    onSchemaChange: "EXTEND",
}
SELECT ...

テーブルドキュメントを追加する

このセクションでは、テーブルとその列とレコードの説明を Dataform コア SQLX ファイルに追加する方法について説明します。

Dataform のすべてのテーブルタイプ（テーブル、増分テーブル、ビュー）に、テーブル、列、レコードの説明を追加できます。

次の内容を文書化する場合があります。

テーブルの目的。
テーブル内の列またはレコードの内容または役割。
テーブルとワークフローの他のアクションの関係（現在のテーブルに依存するテーブルやビューなど）。
テーブルに適用されるアサーション。
テーブルに適用される前オペレーションまたは後オペレーション。
テーブルのオーナー（テーブルを作成したユーザー）。この情報は、複数のチームメンバーがワークフローに取り組んでいる場合に役立ちます。

テーブルの説明を追加する

SQLX ファイルのテーブルに説明を追加する手順は次のとおりです。

Google Cloud コンソールで、[Dataform] ページに移動します。

Dataform に移動
リポジトリを選択します。
開発ワークスペースを選択します。
[ファイル] ペインで、編集するテーブル定義 SQLX ファイルをクリックします。
ファイルの config ブロックに、次の形式でテーブルの説明を入力します。
```
description: "Description of the table",
```
省略可: [書式] をクリックします。

次のコードサンプルは、SQLX テーブル定義ファイルの config ブロックに追加されたテーブルの説明を示しています。

config {
  type: "table",
  description: "Description of the table",
 }

列とレコードの説明を追加する

個々の列とレコードの説明を SQLX ファイルに追加する手順は次のとおりです。

テーブル定義ファイルの config ブロックに「columns: {}」と入力します。
columns: {} 内で、次の形式で列の説明を入力します。
```
column_name: "Description of the column",
```

columns: {} 内で、次の形式でレコードの説明を入力します。

  record_name: {
      description: "Description of the record",
      columns: {
        record_column_name: "Description of the record column"
      }
}

省略可: [書式] をクリックします。

次のコードサンプルは、SQLX テーブル定義ファイルの config ブロック内のテーブル、列、レコードの説明を示しています。

config {
  type: "table",
  description: "Description of the table.",
  columns: {
    column1_name: "Description of the first column",
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    record_name: {
      description: "Description of the record.",
      columns: {
       record_column1_name: "Description of the first record column",
       record_column2_name: "Description of the second record column",
      }
    }
  }
}
SELECT
  "first_column_value" AS column_1_name,
  "second_column_value" AS column_2_name,
  "third_column_value" AS column_3_name,
  STRUCT("first" AS record_column1_name,
    "second" AS record_column2_name) AS record_name

インクルードを使用して列のドキュメントを再利用する

JavaScript インクルードを使用すると、Dataform の列の説明を SQL ワークフロー全体で再利用できます。SQL ワークフローで同じ名前と説明を持つ複数の列がある場合は、列のドキュメントを再利用することをおすすめします。

再利用可能な列の説明を作成するには、列の名前とその説明を含む JavaScript インクルード定数を定義します。

1 つの列の説明を含む定数を定義することも、セットまたは列の説明を含む定数を定義して、テーブル内のすべての列の説明を再利用することもできます。Dataform でのインクルードの作成と使用の詳細については、インクルードを使用して単一のリポジトリ全体でコードを再利用するをご覧ください。

次のコードサンプルは、includes/docs.js JavaScript ファイルで定義された個々の列の説明を含む複数の定数を示しています。


// filename is includes/docs.js

const user_id = `A unique identifier for a user`;
const age = `The age of a user`;
const creation_date = `The date this user signed up`;
const user_tenure = `The number of years since the user's creation date`;
const badge_count = `The all-time number of badges the user has received`;
const questions_and_answer_count = `The all-time number of questions and answers the user has created`;
const question_count = `The all-time number of questions the user has created`;
const answer_count = `The all-time number of answers the user has created`;
const last_badge_received_at = `The time the user received their most recent badge`;
const last_posted_at = `The time the user last posted a question or answer`;
const last_question_posted_at = `The time the user last posted an answer`;
const last_answer_posted_at = `The time the user last posted a question`;

module.exports = {
   user_id,
   age,
   creation_date,
   user_tenure,
   badge_count,
   questions_and_answer_count,
   question_count,
   answer_count,
   last_badge_received_at,
   last_posted_at,
   last_question_posted_at,
   last_answer_posted_at,
};

次のコードサンプルは、includes/docs.js で定義された user_id 定数と age 定数を示しています。これは、テーブル内の選択した列のドキュメントを生成するために、definitions/my_table.sqlx SQLX テーブル定義ファイルで使用されます。

config {
  type: "table",
  description: "Table description.",
  columns: {
    user_id: docs.user_id,
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    age: docs.age,
  }
}

SELECT ...

次のコードサンプルは、includes/docs.js JavaScript ファイルで定義された一連の列の説明を持つ定数です。


// filename is includes/docs.js

const columns = {
    user_id = `A unique identifier for a user`,
    age = `The age of a user`,
    creation_date = `The date this user signed up`,
    user_tenure = `The number of years since the user's creation date`,
    badge_count = `The all-time number of badges the user has received`,
    questions_and_answer_count = `The all-time number of questions and answers the user has created`,
    question_count = `The all-time number of questions the user has created`,
    answer_count = `The all-time number of answers the user has created`,
    last_badge_received_at = `The time the user received their most recent badge`,
    last_posted_at = `The time the user last posted a question or answer`,
    last_question_posted_at = `The time the user last posted an answer`,
    last_answer_posted_at = `The time the user last posted a question`,
}


module.exports = {
  columns
};

次のコードサンプルは、includes/table_docs.js で定義され、definitions/my_table.sqlx SQLX テーブル定義ファイルで使用されてテーブル内のすべての列のドキュメントを生成する columns 定数を示しています。

config { type: "table",
description: "My table description",
columns: docs.columns
}

SELECT 1 AS one

BigQuery ラベルを追加する

このセクションでは、Dataform でテーブルにラベルを追加する方法について説明します。

BigQuery は、リソースへのラベルの追加をサポートしています。BigQuery のラベルの詳細については、ラベルの概要をご覧ください。

Dataform のテーブルに BigQuery ラベルを追加するには、テーブル定義 SQLX ファイルの config ブロックの bigquery ブロックにラベルを追加します。

テーブル定義ファイルに BigQuery ラベルを追加する手順は次のとおりです。

開発ワークスペースに移動します。
[ファイル] ペインで definitions/ を展開します。
SQLX テーブル定義ファイルを選択します。
config ブロックに、次の形式でラベルを追加します。
```
bigquery: {
    labels: {
      LABEL1: "VALUE_OF_LABEL1"
    }
  }
```
以下を置き換えます。
- LABEL1: ラベルの名前
- VALUE_OF_LABEL1: ラベルの値
省略可: 特殊文字を含む名前のラベルを追加するには、ラベル名を引用符（""）で囲みます。
省略可: [書式] をクリックします。

次のコードサンプルは、パーティション分割テーブル定義 SQLX ファイルの bigquery ブロックに追加された department:shipping ラベルと cost-center:logistics ラベルを示しています。

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    labels: {
      department: "shipping",
      "cost-center": "logistics"
    }
  }
}

SELECT CURRENT_TIMESTAMP() AS ts

次のステップ

アサーションを使用してテーブルデータをテストする方法については、データ品質をテストするをご覧ください。
JavaScript を使用してテーブルを定義する方法については、JavaScript のみを使用してワークフローを作成するをご覧ください。
インクルードを使用してコードを再利用する方法については、インクルードを使用して単一のリポジトリ全体でコードを再利用するをご覧ください。
Dataform コマンドラインインターフェースの使用方法については、Dataform CLI を使用するをご覧ください。