テーブルの作成

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

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

  • table: 通常のテーブル。
  • incremental: 増分テーブル。
  • view: テーブルビュー。詳細については、ビューの概要をご覧ください。

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

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

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

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

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

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

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

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

始める前に

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

    Dataform に移動

  2. リポジトリで開発ワークスペースを作成して初期化します。

  3. 省略可: データソースを宣言します。

必要なロール

このドキュメントのタスクを完了するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。

  • ワークスペースに対する Dataform 編集者 （roles/dataform.editor）
  • メタデータを Knowledge Catalog に同期するには: プロジェクトまたは @bigquery エントリ グループに対する Dataplex Catalog 編集者 （roles/dataplex.catalogEditor）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

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

テーブルを作成する

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

テーブル定義について

テーブルを定義するには、テーブルタイプを定義し、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 ワークフローで定義された次のオブジェクトを参照して自動的に依存関係を設定できます。

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 ファイルを作成する手順は次のとおりです。

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

    Dataform に移動

  2. リポジトリを開くには、リポジトリ名をクリックします。

  3. 開発ワークスペースを開くには、ワークスペース名をクリックします。

  4. [ファイル] ペインで、definitions/ の横にある [その他] をクリックします。

  5. [ファイルを作成] をクリックします。

  6. [ファイルパスを追加] フィールドに、ファイルの名前の後に definitions/ の後に .sqlx を入力します。例: definitions/my-table.sqlx。

    ファイル名 には数字、英字、ハイフン、アンダースコアのみを使用できます。

  7. [ファイルを作成] をクリックします。

テーブルタイプを定義する

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

  1. 開発ワークスペースの [ファイル] ペインで definitions/ ディレクトリを開きます。
  2. 編集するテーブル定義 SQLX ファイルを選択します。

  3. このファイルに次のコード スニペットを入力します。

    config { type: "TABLE_TYPE" }

    TABLE_TYPE は、次のいずれかのテーブルタイプに置き換えます。

    • table
    • incremental
    • view

  4. 省略可: マテリアライズド ビューを定義するには、type: "view" で次の形式で materialized プロパティを入力します。

    config {
  type: "view",
  materialized: true
}

    詳細については、ITableConfig をご覧ください。

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

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

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

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

次のコードサンプルは、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 ステートメントで参照されていないものの、現在のテーブルの前に実行する必要があるテーブルの依存関係を追加するには、次の手順を行います。

  1. 開発ワークスペースの [ファイル] ペインで definitions/ ディレクトリを開きます。
  2. 編集するテーブル定義 SQLX ファイルを選択します。

  3. テーブルの config ブロックに次のコード スニペットを入力します。

    dependencies: [ "DEPENDENCY_TABLE", ]

    DEPENDENCY_TABLE は、依存関係として追加するテーブルのファイル名に置き換えます。複数のファイル名を入力できます。

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

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

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

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

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

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

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

  1. 開発ワークスペースに移動します。

  2. [ファイル] ペインで definitions/ を展開します。

  3. SQLX テーブル定義ファイルを開きます。

  4. このファイルに次のコード スニペットを入力します。

     {
   schema: "OVERRIDDEN_SCHEMA",
   database: "OVERRIDDEN_DATABASE",
   name: "OVERRIDDEN_NAME"
 }

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

    • OVERRIDDEN_SCHEMA: テーブルを作成する BigQuery データセット。

    • OVERRIDDEN_DATABASE: テーブルを作成する BigQuery プロジェクトの ID。

    • OVERRIDDEN_NAME: テーブルの名前。SQLX テーブル定義のファイル名とは異なります。

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

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

Apache Iceberg マネージド テーブルを作成する

Dataform を使用して、Iceberg テーブル形式で BigQuery テーブルを作成します。これらのテーブルは、Iceberg マネージド テーブルと呼ばれます。必要なロールやその他の設定タスクの詳細については、Iceberg マネージド テーブル ワークフローの始める前にの手順をご覧ください。

Iceberg テーブル定義を作成する

テーブルを作成するには、テーブル定義ファイルの bigquery ブロックで Iceberg 構成を定義します。

テーブルを定義する手順は次のとおりです。

  1. 開発ワークスペースに移動します。
  2. [ファイル] ペインで definitions/ を展開します。
  3. テーブル定義 SQLX ファイルを開きます。

  4. config ブロックに、次の形式で iceberg ブロックを含む bigquery ブロックを追加します。

    config {
  type: "table",
  name: "my_table",
  uniqueKey: ["uniquekey"],
  bigquery: {
    iceberg: {
      bucket_name: "BUCKET_NAME"
    }
  }
}

    BUCKET_NAME は、テーブルデータが保存されている Cloud Storage バケットの名前に置き換えます。

    他のプロパティは省略可能で、指定しない場合はデフォルト値が使用されます。詳細については、iceberg プロパティをご覧ください。

    各テーブルの値を指定するか、workflow_settings.yaml でワークフロー レベルのデフォルトを設定できます。iceberg ブロックでプロパティを明示的に設定することで、ワークフロー レベルのデフォルトをオーバーライドできます。

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

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

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

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

  1. 開発ワークスペースに移動します。
  2. [ファイル] ペインで definitions/ を展開します。
  3. テーブル定義 SQLX ファイルを開きます。