テーブルを作成する

このドキュメントでは、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/ ディレクトリに保存します。新しい SQLX ファイルを definitions/ ディレクトリ内に作成する手順は次のとおりです。

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

次のステップ