このドキュメントでは、JavaScript インクルードを作成して Dataform でコードを再利用する方法について説明します。
リポジトリの includes/
フォルダで、JavaScript インクルードを定義できます。インクルードは、リポジトリ全体で再利用できるグローバルな定数または関数です。
始める前に
Google Cloud コンソールの [Dataform] ページに移動します。
Dataform リポジトリの作成または選択。
Dataform 開発ワークスペースを作成または選択します。
必要なロール
JavaScript コードを使ってコードを再利用するために必要な権限を取得するには、ワークスペースに対する Dataform 編集者 (roles/dataform.editor
) IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。
必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
Dataform でインクルードする JavaScript ファイルを作成する
includes/
ディレクトリに新しい JavaScript ファイルを作成する手順は次のとおりです。
[ファイル] ペインで、
includes/
の横にある [その他] メニューをクリックします。[ファイルを作成] をクリックします。
[新しいファイルを作成] ペインで、次の操作を行います。
[ファイルパスを追加] フィールドにおいて、
includes/
の後で、ファイル名の後に.js
を入力します。例:includes/constants.js
。ファイル名 には数字、英字、ハイフン、アンダースコアのみを使用できます。
[ファイルを作成] をクリックします。
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 コアの概要をご覧ください。