Dataform の概要

このドキュメントでは、Dataform のコンセプトとプロセスについて説明します。

Dataform は、データ アナリストが BigQuery でデータ変換を行う複雑なワークフローを開発、テスト、バージョン管理、スケジュール設定するためのサービスです。

Dataform を使用すると、データ統合の ELT（抽出、読み込み、変換）プロセスにおけるデータ変換を管理できます。ソースシステムから抽出して BigQuery に読み込んだ元データを、Dataformは、明確に定義、テスト、ドキュメント化された一連のデータテーブルに変換できます。

Dataform では、次のデータ変換アクションを実行できます。

• データ変換用のワークフローを開発して実行します。
• Git を使用して、チームメンバーとワークフローの開発を共同で行います。
• 多数のテーブルとその依存関係を管理します。
• ソースデータを宣言し、テーブルの依存関係を管理します。
• ワークフローの依存関係ツリーの可視化を表示します。
• 中央リポジトリ内の SQL コードを使用してデータを管理します。
• JavaScript でコードを再利用します。
• ソーステーブルと出力テーブルの品質テストで、データの正確性をテストします。
• SQL コードをバージョン管理します。
• SQL コード内のデータテーブルをドキュメント化します。

Dataform のデータ変換プロセス

Dataform のデータ変換ワークフローは次のとおりです。

1. Dataform では、コードを管理するためのリポジトリを作成できます。
2. Dataform では、開発用のワークスペースを作成できます。
3. Dataform では、開発ワークスペースでワークフローを開発できます。
4. Dataform は Dataform コアを SQL にコンパイルします。
5. Dataform は依存関係ツリーを実行します。

Dataform では、コードを管理するためのリポジトリを作成できます

Dataform リポジトリでは、SQL の拡張機能である Dataform コアを使用して、ワークフローを定義する SQLX ファイルを作成します。Dataform リポジトリはバージョン管理をサポートします。Dataform リポジトリをサードパーティの Git プロバイダにリンクできます。

Dataform では、開発用のワークスペースを作成できます

Dataform コア開発用に、Dataform リポジトリ内に開発ワークスペースを作成できます。開発ワークスペースでは、リポジトリを変更し、コンパイル、テストを行って、Git を介してメイン リポジトリに push できます。

Dataform では、開発ワークスペースで Dataform コアを開発できます

開発ワークスペースでは、テーブル、その依存関係、変換ロジックを定義してドキュメント化し、ワークフローを構築できます。JavaScript でアクションを構成することもできます。

Dataform は Dataform コアをコンパイルする

コンパイル中、Dataform は次のタスクを実行します。

• Dataform コアを標準 SQL のワークフローにコンパイルします。
• クエリ構成で CREATE TABLE や INSERT などのボイラープレート SQL ステートメントをコードにインラインで追加します。
• JavaScript を SQL にトランスパイル（ソース間でコンパイル）します。
• 依存関係を解決し、欠落している依存関係や循環依存関係などのエラーをチェックします。
• BigQuery で実行されるすべてのアクションの依存関係ツリーを構築します。

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

リアルタイムでデバッグするには、開発ワークスペースのインタラクティブ グラフで、プロジェクトのコンパイル済みワークフローを検査します。

Dataform は依存関係ツリーを実行する

BigQuery では、Dataform は次のタスクを実行します。

• 依存関係ツリーの順序に従って SQL コマンドを実行します。
• テーブルとビューに対してアサーション クエリを実行して、データの正確性を確認します。
• 定義した他の SQL オペレーションを実行します。

実行後、テーブルとビューをすべての分析目的に使用できます。

ログを表示すると、作成されたテーブル、アサーションの成功または失敗、各アクションの完了にかかった時間などの情報を確認できます。BigQuery で実行された正確な SQL コードを表示することもできます。

Dataform の機能

Dataform を使用すると、テーブル、増分テーブル、ビューを開発して BigQuery にデプロイできます。Dataform には、次のアクティビティ用のウェブ環境が用意されています。

• ワークフローの開発
• GitHub、GitLab、Azure DevOps Services、Bitbucket との接続
• 継続的インテグレーションと継続的デプロイ
• ワークフローの実行

以降のセクションでは、Dataform の主な機能について説明します。

リポジトリ

各 Dataform プロジェクトはリポジトリに保存されます。Dataform リポジトリには、JSON 構成ファイル、SQLX ファイル、JavaScript ファイルのコレクションが格納されています。

Dataform リポジトリには、次の種類のファイルが含まれています。

• 構成ファイル

  Config JSON または SQLX ファイルを使用すると、ワークフローを構成できます。これには、新しいテーブルとビューを作成するための一般的な構成、実行スケジュール、スキーマが含まれます。

• 定義

  定義とは、BigQuery で実行する新しいテーブル、ビュー、追加の SQL オペレーションを定義する SQLX および JavaScript ファイルです。

• 含まれるサービス

  インクルードは、プロジェクトで使用する変数や関数を定義できる JavaScript ファイルです。

各 Dataform リポジトリは、サービス エージェントまたはサービス アカウントに接続されています。サービス アカウントは、リポジトリを作成するとき、または後でサービス アカウントを編集するときに選択できます。

デフォルトでは、Dataform はプロジェクト番号から派生した次の形式のサービス エージェントまたはサービス アカウントを使用します。

[e-mail]

バージョン管理

Dataform は、Git バージョン管理システムを使用して、プロジェクト ファイルに対する各変更の記録を保持し、ファイルのバージョンを管理します。

各 Dataform リポジトリは、独自の Git リポジトリを管理するか、リモートのサードパーティ Git リポジトリに接続できます。Dataform リポジトリを GitHub、GitLab、Azure DevOps Services、または Bitbucket のリポジトリに接続できます。

ユーザーは、Dataform ワークスペース内で ワークフロー コードをバージョン管理します。Dataform ワークスペースでは、リポジトリから変更を pull し、すべての変更または選択した変更を commit して、リポジトリの Git ブランチに push できます。

ワークフローの開発

Dataform で、開発ワークスペース内のファイルやディレクトリを変更します。開発ワークスペースは、Git リポジトリの内容の編集可能な仮想コピーです。Dataform では、セッションが切り替わっても開発ワークスペース内のファイルの状態は維持されます。

開発ワークスペースでは、Dataform コアを SQLX と JavaScript とともに使用するか、またはJavaScript のみを使用することで、ワークフロー アクションを開発できます。Dataform コアまたは JavaScript コードの書式を自動的に設定できます。

Dataform ワークフローの各要素（テーブルやアサーションなど）は、Dataform が BigQuery で実行するアクションに対応しています。たとえば、テーブル定義ファイルは、BigQuery でテーブルを作成または更新するアクションです。

Dataform ワークスペースでは、次のワークフロー アクションを開発できます。

• ソースデータの宣言
• テーブルとビュー
• 増分テーブル
• テーブル パーティションとクラスタ
• アクション間の依存関係
• テーブルのドキュメント
• カスタム SQL オペレーション
• BigQuery ラベル
• BigQuery のポリシータグ
• Dataform タグ
• アサーションと呼ばれるデータ品質テスト

JavaScript を使用して、次の方法で Dataform ワークフロー コードを再利用できます。

• コードのカプセル化を使用するファイル全体
• インクルードを使用するリポジトリ全体
• パッケージを使用するリポジトリ全体

Dataform は、ワークスペースのワークフロー コードをリアルタイムでコンパイルします。 ワークスペースで、コンパイルされたクエリと各ファイルのアクションの詳細を表示できます。コンパイルのステータスとエラーは、編集したファイルまたはリポジトリで確認することもできます。

コンパイルされた SQL クエリの出力を BigQuery で実行する前にテストするには、Dataform ワークスペースでクエリのプレビューを実行します。

ワークスペースで定義されたワークフロー全体を検査するには、インタラクティブなコンパイル済みグラフを表示します。このグラフには、SQL ワークフローのすべてのコンパイル済みアクションとそれらの関係が表示されます。

ワークフロー コンパイル

Dataform は、 で構成されているデフォルトのコンパイル設定を使用して、ワークスペース内のワークフロー コードをリアルタイムで SQL にコンパイルし、ワークスペースのコンパイル結果を作成します。

コンパイル設定をオーバーライドして、Dataform がワークフローをコンパイル結果にコンパイルする方法をカスタマイズできます。

ワークスペース コンパイル オーバーライドを使用すると、リポジトリ内のすべてのワークスペースに対してコンパイルのオーバーライドを構成できます。動的なワークスペース オーバーライドを設定して、ワークスペースごとにカスタムされたコンパイル結果を作成し、ワークスペースを分離された開発環境に変換できます。Dataform がワークスペースの内容を実行するプロジェクトをオーバーライドし、すべてのコンパイル済みテーブルの名前に接頭辞を追加して、デフォルトのスキーマに接尾辞を追加できます。 Google Cloud

リリース構成を使用すると、Dataform リポジトリのコンパイル結果を作成するためのコンパイル設定のテンプレートを構成できます。リリース構成では、Dataform がコンパイル結果を実行するプロジェクトをオーバーライドし、すべてのコンパイル済みテーブルの名前に接頭辞を追加して、デフォルトのスキーマに接尾辞を追加し、コンパイル変数を追加します。 Google Cloud コンパイル結果を作成する頻度も設定できます。選択したリリース構成で作成されたコンパイル結果の実行をスケジュールするには、ワークフロー構成を作成します。

ワークフロー実行

ワークフローの実行中、Dataform はワークフローのコンパイル結果を実行して、BigQuery でアセットを作成または更新します。

BigQuery のワークフローで定義されたテーブルとビューを作成または更新するには、開発ワークスペースでワークフローの実行を手動で開始するか、実行をスケジュールします。

BigQuery では、次の方法で Dataform の実行をスケジュールできます。

• リリース構成で作成されたコンパイル結果の実行をスケジュールするワークフロー構成を作成する
• Cloud Composer で実行をスケジュールする
• Workflows と Cloud Scheduler で実行をスケジュールする

エラーをデバッグするために、次の方法で実行をモニタリングできます。

• 詳細な Dataform 実行ログを表示する
• Dataform の監査ログを表示する
• Dataform の Cloud Logging ログを表示する

Dataform コア

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

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

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

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

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

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

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

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

SQLX ファイルの config ブロック

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

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

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

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

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

データのドキュメント化

構成ブロックで、テーブルとそのフィールドを直接ドキュメント化できます。テーブルのドキュメントは BigQuery に直接 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 ファイルの本文では、次の操作を行うことができます。

• テーブルとその依存関係を定義します。
• 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:[e-mail]"
}

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

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

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

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

js {
  const columnName = "foo";
}

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

制限事項

Dataform には、以下に示す既知の制限事項があります。

• Google Cloud の Dataform はプレーンな V8 ランタイムで動作し、Node.js が提供する追加機能とモジュールをサポートしません。既存のコードベースで Node.js モジュールが必要な場合は、これらの依存関係を削除する必要があります。

  package.json に名前フィールドが含まれていないプロジェクトでは、パッケージをインストールするたびに package-lock.json で差分が生成されます。この結果を回避するには、package.json に name プロパティを追加する必要があります。

• package.json の依存関係の git+https:// URL はサポートされていません。

  このような URL をプレーンの https:// アーカイブ URL に変換します。 たとえば、git+https://github.com/dataform-co/dataform-segment.git#1.5 を https://github.com/dataform-co/dataform-segment/archive/1.5.tar.gz に変換します。

• 単体テストを手動で実行することはできません。

• 開発ワークスペースでファイル コンテンツを検索することはできません。

  注: サードパーティのリモート リポジトリで Dataform IP を許可リストに登録するときに使用する下り（外向き）IP アドレス範囲のリストについては、Dataform のロケーションをご覧ください。

• Dataform コア 3.0.0. 以降、Dataform は Docker イメージを配布しません。Dataform の独自の Docker イメージを構築して、Dataform CLI コマンドと同等のコマンドを実行できます。独自の Docker イメージを構築するには、Docker ドキュメントのアプリケーションをコンテナ化するをご覧ください。

• 次の Dataform API メソッドは、* ワイルドカード エントリを不正なリクエストとして扱い、field_mask が省略されたときに設定されたフィールドではなくすべてのフィールドを更新するため、AIP.134 ガイドラインに準拠していません。

  • releaseConfigs - patch
  • repositories - patch
  • updateConfig
  • workflowConfigs - patch

次のステップ

• Dataform のコード ライフサイクルの詳細については、Dataform のコード ライフサイクルの概要をご覧ください。
• Dataform リポジトリの詳細については、リポジトリの概要をご覧ください。
• Dataform ワークスペースの詳細については、Dataform 開発ワークスペースを作成するをご覧ください。
• Dataform でのワークフローの開発の詳細については、ワークフローの概要をご覧ください。
• Dataform CLI の詳細については、Dataform CLI を使用するをご覧ください。