Dataform でインクルードを使用して変数と関数を再利用する

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

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

始める前に

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

Dataform に移動
Dataform リポジトリの作成または選択。
Dataform 開発ワークスペースを作成または選択します。

必要なロール

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

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

Dataform でインクルードする JavaScript ファイルを作成する

includes/ ディレクトリに新しい JavaScript ファイルを作成する手順は次のとおりです。

[ファイル] ペインで、includes/ の横にある [その他] メニューをクリックします。
[ファイルを作成] をクリックします。
[新しいファイルを作成] ペインで、次の操作を行います。
1. [ファイルパスを追加] フィールドにおいて、includes/ の後で、ファイル名の後に .js を入力します。例: includes/constants.js。
  
  ファイル名には数字、英字、ハイフン、アンダースコアのみを使用できます。
2. [ファイルを作成] をクリックします。

JavaScript 定数を作成する

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

開発ワークスペースに移動します。
[ファイル] ペインで includes/ を開きます。
.js という拡張子を持つ JavaScript ファイルを作成するか、選択します。
ファイルに次のコードスニペットを入力します。
```
 const CONSTANT_NAME = CONSTANT_VALUE;
 module.exports = { CONSTANT_NAME };
```
以下を置き換えます。
- CONSTANT_NAME: 定数の名前
- CONSTANT_VALUE: 定数の値
省略可: [書式] をクリックします。

次のコードサンプルでは、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 関数を作成する手順は次のとおりです。

開発ワークスペースに移動します。
[ファイル] ペインで includes/ を開きます。
.js という拡張子を持つ JavaScript ファイルを作成するか、選択します。
このファイルにカスタム JavaScript 関数を記述します。
ファイルに次のコードスニペットを入力します。
```
 module.exports = { FUNCTION_NAME }
```
FUNCTION_NAME は、関数の名前で置き換えます。
省略可: [書式] をクリックします。

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

  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"]
                                )}

次のコードサンプルは、上記の Dataform コアテーブル定義クエリを SQL にコンパイルしたものです。

  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/ ディレクトリの直下にあります。ネストされたインクルードファイルは 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 関数でネストされたインクルードを参照する手順は次のとおりです。

開発ワークスペースに移動します。
[ファイル] ペインで [definitions/] を展開します。
SQLX ファイルを選択します。
config ブロックに次のコードスニペットを入力します。
```
 js {
   var { VARIABLE_NAME } = require("SUBDIRECTORY_INCLUDE");
 }
```
以下を置き換えます。
- VARIABLE_NAME: インポートする定数または関数の名前
- SUBDIRECTORY_INCLUDE: ネストされた includes ファイルのパス
省略可: [書式] をクリックします。

次のコードサンプルは、テーブル定義 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 };

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

${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 コアの概要をご覧ください。

次のステップ

JavaScript ファイル内のインクルードを参照する方法については、JavaScript を使用して SQL ワークフローを作成するをご覧ください。
Dataform コアファイルでコードをブロックおよびインライン JavaScript と一緒に再利用する方法については、Dataform コアの概要をご覧ください。