JavaScript を使用して Dataform SQL ワークフローを作成する

このドキュメントでは、JavaScript を使用して Dataform で SQL ワークフロー要素を作成する方法について説明します。Dataform コアで 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")}
        )`
    );
  });

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

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

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 で SQL ワークフロー オブジェクトを作成するには、次の Dataform グローバル メソッドを使用します。

  • 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 は、このようなファイルを include ディレクトリに保存します。

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

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

次のコードサンプルでは、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. 省略可: [書式] をクリックします。

次のコードサンプルは、パブリッシュメソッドのコンテキスト対応引数にラップされた ref クエリ関数を示しています。

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

JavaScript を使用して SQL ワークフロー データソースを宣言する

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

JavaScript ファイルでデータソースを宣言する手順は次のとおりです。

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

  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 メソッドを使用してテーブルを作成できます。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 アサーションを作成できます。アサートメソッドの詳細については、Dataform コアのリファレンスをご覧ください。

手動アサーション SQL クエリは行を返さないようにする必要があります。クエリの実行時にクエリが行を返すと、アサーションは失敗します。 1 つの JavaScript ファイルに複数の記述を作成できます。

Dataform の断言の詳細については、断言を使用してテーブルをテストするをご覧ください。

JavaScript ファイルで手動アサーションを作成する手順は次のとおりです。

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

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

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

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

    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 Operate 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. 省略可: [書式] をクリックします。

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

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

次のステップ