Dataform コアの概要

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

Dataform コアの概要

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

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

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

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

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

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

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

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

SQLX ファイルの config ブロック

SQLX ファイルは、構成ブロックと本文で構成されます。すべての config プロパティと config ブロック自体は省略可能です。したがって、書式なしの SQL ファイルは、Dataform がそのまま実行する有効な SQLX ファイルです。

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

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

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

ドキュメント データ

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

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

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

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

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 ファイルの本文では、次の操作を行えます。

テーブルを定義する

新しいテーブルを定義するには、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 "..."

次のステップ