テーブルの作成

このドキュメントでは、Dataform で Dataform コアを使用してテーブルを定義する方法について説明します。

テーブル定義について

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

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

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

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

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

ref 関数は、Dataform の依存関係管理に不可欠な Dataform コアの組み込み関数です。ref 関数を使用すると、スキーマとテーブル名をハードコードする代わりに、Dataform 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 ...

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

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

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

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

始める前に

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

必要なロール

テーブルの定義に必要な権限を取得するには、ワークスペースに対する Dataform 編集者 （roles/dataform.editor）IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

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

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

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

  1. 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 Dataform コアのリファレンスをご覧ください。

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

次のステップ