Dataform コアの概要

このドキュメントでは、Dataform コアの概要と Dataform での使用方法について説明します。

Dataform コアの概要

Dataform コアは、SQL テーブルとワークフローを作成するためのオープンソースのメタ言語です。Dataform コアは、依存関係管理システム、自動データ品質テスト、データドキュメントを提供することで SQL を拡張します。

Dataform コアは次の目的で使用できます。

テーブル、ビュー、マテリアライズドビュー、増分テーブルを定義する。
データ変換ロジックを定義する。
ソースデータの宣言とテーブルの依存関係を管理する。
コード内でテーブルと列の説明を記録する。
異なるクエリ間で関数と変数を再利用する。
データアサーションを作成して、データの整合性を確保します。

Dataform では、Dataform コアを使用して SQL ワークフローを開発し、アセットを BigQuery にデプロイします。

Dataform コアは、Dataform CLI を含むオープンソースの Dataform データモデリングフレームワークの一部です。Google Cloud 外部の Dataform CLI を使用して、Dataform コアをローカルでコンパイルして実行できます。

Dataform コアを使用するには、SQLX ファイルを作成します。各 SQLX ファイルには、Dataform が BigQuery 内で作成して更新するデータベース関係を定義するクエリが含まれています。

Dataform は、Dataform コアコードをリアルタイムでコンパイルし、BigQuery で実行できる SQL コンパイル結果を作成します。

Dataform コンパイルは、コンパイルの整合性を確保するための密閉型です。つまり、同じコードが毎回同じ SQL コンパイル結果にコンパイルされます。Dataform は、インターネットにアクセスできないサンドボックス環境でコードをコンパイルします。コンパイル中は、外部 API の呼び出しなど、追加のアクションは使用できません。

SQLX ファイル構成ブロック

SQLX ファイルは、1 つの構成ブロックと本文で構成されています。すべての構成プロパティと構成ブロック自体は省略可能です。このため、プレーン SQL ファイルは、Dataform をそのまま実行する有効な SQLX ファイルになります。

config ブロックでは、次の操作を行うことができます。

クエリのメタデータを指定します。
ドキュメントデータ。
データ品質テストを定義します。

クエリのメタデータを指定する

構成メタデータを使用して、Dataform がクエリを BigQuery に実体化する方法（出力テーブルタイプ、ターゲットデータベース、ラベルなど）を構成できます。

ドキュメントデータ

構成ファイルとそのフィールドは、構成ブロックで直接ドキュメント化できます。テーブルのドキュメントは、BigQuery に直接 push されます。このドキュメントを解析し、他のツールに push できます。

データ品質テストを定義する

アサーションと呼ばれるデータ品質テストを定義して、一意性、null 値、またはカスタム条件をチェックできます。Dataform は、テーブルの作成後に構成ブロックで定義されたアサーションをワークフロー依存関係ツリーに追加します。別の SQLX ファイルで config ブロックの外部にアサーションを定義することもできます。

次のコードサンプルは、出力テーブルタイプを定義し、テーブルをドキュメント化し、SQLX ファイルの構成ブロックで品質テストを定義する方法を示しています。

config {
  type: "table",
    description: "This table joins orders information from OnlineStore & payment information from PaymentApp",
  columns: {
    order_date: "The date when a customer placed their order",
    id: "Order ID as defined by OnlineStore",
    order_status: "The status of an order e.g. sent, delivered",
    customer_id: "Unique customer ID",
    payment_status: "The status of a payment e.g. pending, paid",
    payment_method: "How the customer chose to pay",
    item_count: "The number of items the customer ordered",
    amount: "The amount the customer paid"
  },
    assertions: {
    uniqueKey: ["id"]
  }
}

SQLX ファイル本文

SQLX ファイルの本文では、次の操作を行えます。

テーブルとその依存関係を定義する。
BigQuery で実行する追加の SQL オペレーションを定義します。
JavaScript を使用して SQL コードを生成する。

テーブルの定義

新しいテーブルを定義するには、SQL SELECT ステートメントと ref 関数を使用します。

ref 関数は、Dataform の依存関係管理に不可欠な SQLX の組み込み関数です。ref 関数を使用すると、データテーブルのスキーマとテーブル名をハードコードする代わりに、Dataform プロジェクトで定義されたテーブルを参照できます。

Dataform は ref 関数を使用して、作成または更新されるすべてのテーブルの依存関係ツリーを構築します。コンパイル後、Dataform は CREATE、REPLACE、INSERT などの定型ステートメントを追加します。

次のサンプルコードは、ref 関数を使用して SQLX ファイル内のテーブルを参照する方法を示しています。

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, 3

出力は次のようになります。

CREATE OR REPLACE TABLE Dataform.orders AS

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 Dataform_stg.store_clean

GROUP BY 1, 2, 3

他の Dataform コア組み込み関数を使用した条件付きでのコード実行など、追加の依存関係管理の詳細については、Dataform コアリファレンスをご覧ください。

追加の SQL オペレーションを定義する

テーブルやビューの作成前または作成後に 1 つ以上の SQL ステートメントを実行するように Dataform を構成するには、クエリ前のオペレーションとクエリ後のオペレーションを指定します。

次のコードサンプルは、クエリ後のオペレーションでテーブルまたはビューにアクセス権を構成する方法を示しています。

SELECT * FROM ...

post_operations {
  GRANT `roles/bigquery.dataViewer` ON TABLE ${self()} TO "group:someusers@dataform.co"
}

SQL コードをカプセル化する

SQL コードの繰り返し部分を生成する再利用可能な関数を定義するには、JavaScript ブロックを使用します。JavaScript ブロックで定義されたコードは、ブロックが定義されている SLQX ファイル内でのみ再利用できます。リポジトリ全体でコードを再利用するには、インクルードを作成します。

クエリを動的に変更するには、本文内の任意の場所にインライン JavaScript を使用します。

次のサンプルコードは、SQLX ファイルで JavaScript ブロックを定義し、それをクエリ内でインラインで使用する方法を示しています。

js {
  const columnName = "foo";
}

SELECT 1 AS ${columnName} FROM "..."

次のステップ

Dataform コア組み込み関数の詳細については、Dataform コアリファレンスをご覧ください。
Dataform CLI の詳細については、Dataform CLI の使用をご覧ください。
追加の SQL オペレーションを定義する方法については、カスタム SQL オペレーションの追加をご覧ください。
JavaScript インクルードの作成方法については、インクルードを使用して変数と関数を再利用するをご覧ください。
Dataform を使用してテーブルを定義する方法については、テーブルの作成をご覧ください。

Dataform コアの概要