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")}
        )`
    );
  });

このコードサンプルは、ブロックされたユーザー 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 で 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 は、このようなファイルをインクルード ディレクトリに保存します。

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

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

次のコードサンプルでは、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 の declare JavaScript メソッドを使用すると、1 つの JavaScript 宣言ファイルで複数のデータソースを宣言できます。宣言メソッドの詳細については、Dataform コアのリファレンスをご覧ください。Dataform でのデータソースの詳細については、データソースを宣言するをご覧ください。

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

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

  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 assert 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 操作 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)");

次のステップ