Dataform に含まれる include 変数と関数を再利用する

このドキュメントでは、Dataform でコードを再利用するための JavaScript の作成方法について説明します。

リポジトリの includes/ フォルダで、JavaScript インクルードを定義できます。これには、リポジトリ全体で再利用できるグローバル定数または関数が含まれます。

始める前に

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

    Dataform に移動

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

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

必要なロール

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

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

Dataform に含める JavaScript ファイルを作成する

includes/ ディレクトリに新しい JavaScript ファイルを作成するには、次の手順に沿って操作します。

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

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

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

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

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

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

JavaScript 定数を作成する

プロジェクト間で再利用できる定数を作成する手順は次のとおりです。

  1. 開発ワークスペースに移動します。

  2. [ファイル] ペインで、includes/ を展開します。

  3. .js 拡張子の JavaScript ファイルを作成または選択します。

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

     const CONSTANT_NAME = CONSTANT_VALUE;
 module.exports = { CONSTANT_NAME };

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

    • CONSTANT_NAME: 定数の名前
    • CONSTANT_VALUE: 定数の値

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

次のサンプルコードでは、includes/constants.js ファイルでの PROJECT_ID 定数を定義しています。

  // filename is includes/constants.js
  const PROJECT_ID = "my_project_name";
  module.exports = { PROJECT_ID };

次のサンプルコードは、SQLX ファイルのテーブル定義クエリで PROJECT_ID 定数を参照します。

  config { type: "table" }
  SELECT * FROM ${constants.PROJECT_ID}.my_schema_name.my_table_name

次のサンプルコードは、SQL にコンパイルされた上記の Dataform コアテーブル定義クエリを示しています。

  SELECT * FROM my_project_name.my_schema_name.my_table_name

カスタム JavaScript 関数を作成する

プロジェクト間で再利用できるカスタム JavaScript 関数を作成するには、次の手順に沿って操作します。

  1. 開発ワークスペースに移動します。

  2. [ファイル] ペインで、includes/ を展開します。

  3. .js 拡張子の JavaScript ファイルを作成または選択します。

  4. このファイルに、カスタム JavaScript 関数を記述します。

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

     module.exports = { FUNCTION_NAME }

    FUNCTION_NAME は、関数の名前で置き換えます。

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

次のサンプルコードは、SQL ファイルを生成する includes/functions.js ファイルの renderScript というカスタム JavaScript 関数を示しています。

  function renderScript(table, dimensions, metrics) {
    return `
        select
        ${dimensions.map(field => `${field} as ${field}`).join(",")},
        ${metrics.map(field => `sum(${field}) as ${field}`).join(",\n")}
        from ${table}
        group by ${dimensions.map((field, i) => `${i + 1}`).join(", ")}
      `;
  }

  module.exports = { renderScript };

次のコードサンプルは、Dataform コアテーブル定義クエリでカスタム renderScript JavaScript 関数を使用する方法を示しています。

  config {
      type: "table",
      tags: ["advanced", "hourly"],
      disabled: true
  }

  ${functions.renderScript(ref("source_table"),
                                ["country", "device_type"],
                                ["revenue", "pageviews", "sessions"]
                                )}

次のサンプルコードは、SQL にコンパイルされた上記の Dataform コアテーブル定義クエリを示しています。

  select
    country as country,
    device_type as device_type,
    sum(revenue) as revenue,
    sum(pageviews) as pageviews,
    sum(sessions) as sessions

  from "dataform"."source_table"

  group by 1, 2

SQLX ファイル内のインクルードを参照する

SQLX ファイル内で任意のインクルード関数または定数を参照できます。インクルードを参照する構文は、インクルード ファイルの場所によって異なります。最上位のインクルード ファイルは、includes/ ディレクトリに直接あります。ネストされたインクルード ファイルは、includes/ のサブディレクトリにあります。

SQLX ファイル内の最上位のインクルードを参照する

  • Dataform コアクエリでトップレベルのインクルード関数または定数を参照するには、.js 拡張子を含み、エクスポートされたオブジェクトの名前をインクルード定義のファイル名を入力します。

次のサンプルコードは、テーブル定義 SQLX ファイルの includes/constants.js ファイルで定義された firstDate 定数を参照します。

  config {type: "table"}
  select * from source_table where date > ${constants.firstDate}

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

definitions のサブディレクトリにあるインクルードを参照するには、JavaScript require 関数と js {} ブロックを使用してインクルードをインポートします。

require JavaScript 関数を使用してネストされたインクルードを参照するには、次の手順に従います。

  1. 開発ワークスペースに移動します。

  2. [ファイル] ペインで、definitions/ を展開します。

  3. SQLX ファイルを選択します。

  4. config ブロックに、次のコード スニペットを入力します。

     js {
   var { VARIABLE_NAME } = require("SUBDIRECTORY_INCLUDE");
 }

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

    • VARIABLE_NAME: インポートする定数または関数の名前
    • SUBDIRECTORY_INCLUDE: ネストされた includes ファイルのパス

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

次のサンプルコードは、テーブル定義の SQLX ファイル内のネストされた includes/allConstants/constants.js ファイルで定義されている firstDate 定数を参照しています。

  config {type: "table"}
  js {
    var { firstDate } = require("includes/allConstants/constants");
  }
  select * from source_table where date > ${firstDate}

Dataform コア ref 関数で JavaScript インクルード関数を使用する

Dataform コア ref 関数で JavaScript インクルード関数を使用するには、SQLX ファイル内の JavaScript インクルード関数の引数として ref を渡す必要があります。

次のサンプルコードは、SUM を使用して指標を集計し、次にディメンション別にグループ化する renderScript JavaScript 関数を含む includes/script_builder.js ファイルを示しています。

function renderScript(table, dimensions, metrics) {
  return `
      SELECT
      ${dimensions.map((field) => `${field} AS ${field}`).join(",\\n")},
      ${metrics.map((field) => `SUM(${field}) AS ${field}`).join(",\\n")}
      FROM ${table}
      GROUP BY ${dimensions.map((field, i) => `${i + 1}`).join(", ")}
    `;
}
module.exports = { renderScript };

次のサンプルコードは、definitions/stats_per_country_and_device.sqlx ファイルで使用される renderScript JavaScript 関数を引数として、Dataform コアの ref 関数を渡したものです。

${script_builder.renderScript(
  ref("source_table"),
  ["country", "device_type"],
  ["revenue", "pageviews", "sessions"])}

次のサンプルコードは、SQL にコンパイルされた definitions/stats_per_country_and_device.sqlx クエリを示しています。

SELECT country AS country,
       device_type AS device_type,
       SUM(revenue) AS revenue,
       SUM(pageviews) AS pageviews,
       SUM(sessions) AS sessions
FROM my_schema.source_table
GROUP BY 1, 2

Dataform コアref関数の詳細については、Dataform コアの概要をご覧ください。

次のステップ