JavaScript で Dataform SQL ワークフローを作成する

このドキュメントでは、JavaScript を使用して Dataform に SQL ワークフロー要素を作成する方法について説明します。Dataform core で JavaScript を使用して、ワークフロー内で同様の要素を繰り返し作成することをおすすめします。

JavaScript を使用した Dataform でのワークフロー開発について

Dataform コアでは、SQLX と JavaScript を使用して SQL ワークフロー アクションを作成できます。JavaScript を使用すると、ワークフロー内で同様のアクションを繰り返し作成できます。たとえば、特定のユーザー ID を削除した、ワークフロー内の各テーブルのビューを作成できます。

次の JavaScript コードサンプルを使用すると、user_id フィールドの値が blocked_user_ids リスト内の値のいずれにも一致しない各テーブルのビューを作成できます。

  const tableNames = ["user_events", "user_settings", "user_logs"];

  tableNames.forEach(tableName => {
    publish(tableName + "_blocked_removed").query(
      ctx => `
        SELECT * FROM ${ctx.ref(tableName)}
        WHERE user_id NOT IN (
          SELECT user_id
          FROM ${ctx.ref("blocked_user_ids")}
        )`
    );
  });

このコードサンプルは、ブロックされたユーザー ID を含まない user_events_blocked_removed、user_settings_blocked_removed、user_logs_blocked_removed という名前の 3 つのビューを作成します。

Dataform グローバル メソッドと任意の JavaScript ES5 コード（ループや定数など）を使用して、1 つの JavaScript ファイル内に複数のアクションを作成できます。

Dataform では、JavaScript で次のアクションを定義できます。

始める前に

  1. Google Cloud コンソールの [Dataform] ページに移動します。

    Dataform に移動

  2. リポジトリを作成または選択します。

  3. 開発ワークスペースを作成または選択します。

必要なロール

JavaScript を使用して SQL ワークフローを開発するために必要な権限を取得するには、ワークスペースに対するDataform 編集者（roles/dataform.editor）IAM ロールの付与を管理者に依頼してください。ロールの付与の詳細については、アクセスの管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

Dataform で JavaScript ファイルを作成する

定義とデータソース宣言のための JavaScript ファイルを definitions/ ディレクトリに保存します。definitions/ ディレクトリに新しい JavaScript ファイルを作成するには、次の手順に沿って操作します。

  1. [ファイル] ペインで、definitions/ の横にある [その他] メニューをクリックします。

  2. [ファイルを作成] をクリックします。

  3. [新しいファイルを作成] ペインで、次の操作を行います。

    1. [ファイルパスの追加] フィールドで、definitions/ の後にファイルの名前の後に .js を入力します。例: definitions/definitions.js

      ファイル名 には数字、英字、ハイフン、アンダースコアのみを使用できます。

    2. [ファイルを作成] をクリックします。

JavaScript で Dataform SQL ワークフロー オブジェクト プロパティを設定する

次の Dataform グローバル メソッドを使用して、Dataform で SQL ワークフロー オブジェクトを作成できます。

  • declare。データソースの宣言に使用されます。
  • publish。テーブルの定義に使用します。
  • assert。アサーションの作成に使用されます。
  • operate。カスタム SQL オペレーションの定義に使用します。

各グローバル メソッドには、作成されたオブジェクトの構成に使用できるプロパティが含まれています。グローバル メソッドとそのプロパティの詳細については、Dataform コア リファレンスをご覧ください。

テーブルを作成する publish() メソッドで、2 番目のメソッド引数としてテーブル プロパティを渡すことでテーブル プロパティを設定できます。

テーブルのプロパティを publish() の 2 番目の引数として渡すには、次のようにします。

  1. 開発ワークスペースの [ファイル] ペインで、definitions/ を展開します。

  2. JavaScript ファイルを選択します。

  3. このファイルに、次の形式でテーブル プロパティを publish() メソッドに追加します。

     method("first_method_argument", {
   property1: "property1_value",
   property2: "property2_value",
   property3: "property3_value",
 });

  4. 省略可: [書式] をクリックします。

次のサンプルコードは、プロパティをメソッドの 2 番目の引数として渡して、プロパティを publish() メソッドに設定する方法を示しています。

  publish("table1", {
    type: "table",
    dependencies: ["other_table"],
    description: {
      "Value is 1"
    }
  }).query(ctx => "SELECT 1 AS test");

JavaScript ファイルに含まれる参照

JavaScript ファイル内で、任意のインクルード関数、マクロ、定数を参照できます。Dataform のインクルードの詳細については、JavaScript インクルードで変数と関数を再利用するをご覧ください。

JavaScript ファイル内のインクルードを参照する構文は、インクルード ファイルの場所によって異なります。Dataform は、このようなファイルをインクルード ディレクトリに保存します。

最上位のインクルードを参照する

  • 最上位のインクルード ファイルを参照するには、変数を宣言するときにそのファイル名を参照します。

次のコードサンプルでは、includes/service.js ファイルから serviceName 変数と serviceId 変数を参照します。

  const {serviceName, serviceId} = service;

ネストされたインクルードを参照する

ネストされたインクルード ファイルを参照するには、JavaScript の require 関数にファイル名を入力します。

次のサンプルコードでは、includes/allServices/service.js ファイルから serviceName 変数と serviceId 変数を参照します。

  const {serviceName, serviceId} = require("includes/allServices/service.js");

JavaScript メソッドで Dataform クエリ関数を使用する

Dataform には、ref や self など、内部クエリで使用できる多くの組み込み関数が用意されています。Dataform の組み込み関数の詳細については、Dataform API リファレンスをご覧ください。

JavaScript メソッドで組み込みクエリ関数を使用する手順は次のとおりです。

  1. 開発ワークスペースの [ファイル] ペインで、definitions/ を展開します。

  2. JavaScript ファイルを選択します。

  3. このファイルで、グローバル Dataform JavaScript メソッドを入力します。

  4. メソッドに、コンテキスト可能な ctx 引数を入力します。

  5. 省略可: JavaScript テンプレート文字列を使用している場合は、コンテキスト可能な引数をバッククォート（`）でラップします。

  6. コンテキスト可能な引数に、クエリ パラメータをパラメータとともにコンテキスト オブジェクトとして入力します。

  7. 省略可: [書式] をクリックします。

次のサンプルコードは、publish メソッドのコンテキスト可能な引数内にラップされた ref クエリ関数を示しています。

  publish("example").query(ctx => `SELECT * FROM ${ctx.ref("other_table")}`);

JavaScript で SQL ワークフロー データソースを宣言する

Dataform 宣言の JavaScript メソッドを使用して、1 つの JavaScript 宣言ファイルで複数のデータソースを宣言できます。宣言メソッドの詳細については、Dataform コア リファレンスをご覧ください。Dataform のデータソースの詳細については、データソースの宣言をご覧ください。

JavaScript ファイルでデータソースを宣言するには、次の手順を行います。

  1. 開発ワークスペースの [ファイル] ペインで、Definitions/ を展開します。

  2. JavaScript ファイルを選択します。

  3. このファイルに、次のコード スニペットを入力します。

     declare({
   database: "DATABASE_PROJECT_ID",
   schema: "BIGQUERY_SCHEMA",
   name: "RELATION_NAME",
 });

    次のように置き換えます。

    • DATABASE_PROJECT_ID: データソースを含むプロジェクトのプロジェクト ID
    • BIGQUERY_SCHEMA: 外部関係が存在する BigQuery データセット
    • RELATION_NAME: 後で Dataform のデータソースを参照するために使用できるリレーション名

  4. 同じファイルで別のデータソースを宣言するには、ファイルに declare ブロックを追加します。

  5. 省略可: [書式] をクリックします。

JavaScript を使用してテーブルを定義する

テーブルは、Dataform JavaScript publish メソッドを使用して作成できます。パブリッシュ メソッドの詳細については、Dataform コアリファレンスをご覧ください。

テーブル、増分テーブル、ビューのテーブルタイプを定義できます。Dataform でのテーブル定義の詳細については、テーブルの作成をご覧ください。

JavaScript ファイルでテーブルを定義するには、次の手順を行います。

  1. 開発ワークスペースの [ファイル] ペインで、definitions/ を展開します。

  2. JavaScript ファイルを選択します。

  3. このファイルに、次のコード スニペットを入力します。

     publish("TABLE_NAME").query(ctx => "SELECT_QUERY");

    1. TABLE_NAME は、テーブルの名前に置き換えます。

    2. SELECT_QUERY は、テーブルを定義する SQL SELECT ステートメントに置き換えます。

  4. テーブルタイプの設定、テーブル依存関係の追加、テーブル説明の追加を行うには、publish メソッドのオブジェクト プロパティを設定します。

  5. 同じファイル内に別のテーブルを定義するには、ステップ 3 とステップ 4 を繰り返します。

  6. 省略可: [書式] をクリックします。

JavaScript を使用して手動 Dataform アサーションを定義する

Dataform アサート JavaScript メソッドを使用して、JavaScript ファイルで手動 SQL アサーションを作成できます。assert メソッドの詳細については、Dataform コア リファレンスをご覧ください。

手動アサーション SQL クエリはゼロ行を返す必要があります。実行時に行が返される場合、アサーションは失敗します。1 つの JavaScript ファイルに複数のアサーションを作成できます。

Dataform のアサーションの詳細については、アサーションのテーブルをテストするをご覧ください。

JavaScript ファイルで手動アサーションを作成するには、次の手順を行います。

  1. 開発ワークスペースの [ファイル] ペインで、definitions/ を展開します。

  2. JavaScript ファイルを選択します。

  3. このファイルに、次のコード スニペットを入力します。

     assert("<var>ASSERTION_NAME</var>").query(ctx => "<var>CUSTOM_ASSERTION_QUERY</var>");

    1. ASSERTION_NAME はカスタム アサーションの名前に置き換えます。

    2. CUSTOM_ASSERTION_QUERY は、SQL アサーション クエリに置き換えます。

  4. 同じファイルに別のアサーションを作成するには、ステップ 3 を繰り返します。

  5. 省略可: [書式] をクリックします。

次のサンプルコードは、source_table の値が NULL でないことをアサートする JavaScript アサーションを示しています。

  assert("assertion1").query(ctx => "SELECT * FROM source_table WHERE value IS NULL");

JavaScript でカスタム SQL オペレーションを定義する

Dataform オペレーションの JavaScript メソッドを使用して、JavaScript ファイルでカスタム SQL オペレーションを定義できます。Dataform のカスタム SQL オペレーションの詳細については、カスタム SQL オペレーションの追加をご覧ください。

JavaScript によるカスタム SQL オペレーションの定義の手順は次のとおりです。

  1. 開発ワークスペースの [ファイル] ペインで、definitions/ を展開します。

  2. JavaScript ファイルを選択します。

  3. このファイルに、次のコード スニペットを入力します。

     operate("OPERATION_NAME").queries(ctx => "CUSTOM_SQL_QUERY");

    1. OPERATION_NAME はカスタム オペレーションの名前に置き換えます。

    2. CUSTOM_SQL_QUERY は、カスタム SQL クエリに置き換えます。

  4. 同じファイルで別のカスタム SQL オペレーションを定義するには、ステップ 3 を繰り返します。

  5. 省略可: [書式] をクリックします。

次のコードサンプルは、some_table に 1 つの新しい行を挿入し、新しい行の test_column を 2 に設定する JavaScript ファイル内のカスタム SQL オペレーションを示しています。

  operate("operation1").queries("INSERT INTO some_table (test_column) VALUES (2)");

次のステップ