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 リポジトリのリストには、Dataform ワークフロー開発用に作成されたリポジトリのみが表示されます。ノートブックや保存済みクエリなどの BigQuery Studio アセットのリポジトリは個別に管理され、このリストには表示されません。

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

• 構成ファイル

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

• 定義

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

• 含まれるサービス

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

各 Dataform リポジトリは、カスタム サービス アカウントに接続する必要があります。リポジトリを 作成するときに、カスタム サービス アカウントを選択します。 サービス アカウントは後で編集できます 。

バージョン管理

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 の実行をスケジュールできます。

• ワークフロー構成を作成して 、リリース構成で作成されたコンパイル結果の実行をスケジュールする
• Managed Service for Apache Airflow で実行をスケジュールする
• Workflows と Cloud Scheduler で実行をスケジュールする

Cloud Build トリガーを使用して実行を自動化することもできます 。

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

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

Dataform コア

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

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

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

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

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

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

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

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

SQLX ファイルの config ブロック

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

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

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

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

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

データのドキュメント化

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

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

アサーションと呼ばれるデータ品質テストを定義して、一意性、null 値、カスタム条件をチェックできます。Dataform は、テーブルの作成後に、config ブロックで定義されたアサーションをワークフローの依存関係ツリーに追加します。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 ブロックで定義されたコードは、ブロックが定義されている SQLX ファイル内でのみ再利用できます。リポジトリ全体でコードを再利用するには、インクルードを作成します。

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

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

js {
  const columnName = "foo";
}

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

制限事項

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

• Google Cloud の Dataform はプレーンな V8 ランタイムで動作し、Node.js が提供する追加機能とモジュールをサポートしません。 Google Cloud 既存のコードベースで 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 メソッドは、 AIP.134 ガイドラインに準拠していません。これは、* ワイルドカード エントリを不正なリクエストとして扱い、field_mask が省略されたときに設定されたフィールドではなくすべてのフィールドを更新するためです。

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

• スケジュールされたワークフロー構成の実行が、次のスケジュールされた実行の開始前に完了しない場合、次のスケジュールされた実行はスキップされ、エラーがマークされます。

次のステップ

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