本文档介绍了如何创建 JavaScript 包含,以在 Dataform 中重复使用代码。
在代码库的 includes/
文件夹中,您可以定义 JavaScript 包含。包含是指可在整个代码库中重复使用的全局常量或函数。
准备工作
在 Google Cloud 控制台中,转到 Dataform 页面。
选择或创建 Dataform 代码库。
所需的角色
如需获取通过 JavaScript include 重复使用代码所需的权限,请让管理员向您授予工作区的 Dataform Editor (roles/dataform.editor
) IAM 角色。如需详细了解如何授予角色,请参阅管理访问权限。
为“包含 Dataform 创建 JavaScript 文件
如需在 includes/
目录中创建新的 JavaScript 文件,请按以下步骤操作:
在 Files 窗格的
includes/
旁边,点击 More 菜单。点击创建文件。
在创建新文件窗格中,执行以下操作:
在添加文件路径字段中的
includes/
后,输入文件名,后跟.js
。例如includes/constants.js
。文件名只能包含数字、字母、连字符和下划线。
点击创建文件。
创建 JavaScript 常量
如需创建可在项目中重复使用的常量,请按以下步骤操作:
转到开发工作区。
在 Files 窗格中,展开
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 core 表定义查询:
SELECT * FROM my_project_name.my_schema_name.my_table_name
创建自定义 JavaScript 函数
如需创建可在项目中重复使用的自定义 JavaScript 函数,请按以下步骤操作:
转到开发工作区。
在 Files 窗格中,展开
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"]
)}
以下代码示例展示了上述已编译到 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 文件中引用任何包含函数或常量。引用 include 的语法取决于 include 文件的位置。顶级 include 文件直接位于 includes/
目录中。嵌套的 include 文件位于 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 函数引用嵌套 include,请按以下步骤操作:
转到开发工作区。
在 Files 窗格中,展开
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}
将 JavaScript include 函数与 Dataform 核心 ref
函数搭配使用
如需将 JavaScript include 函数与 Dataform 核心 ref
函数一起使用,您需要在 SQLX 文件中将 ref
作为 JavaScript include 函数的参数传递。
以下代码示例所示的 includes/script_builder.js
文件包含 renderScript
JavaScript 函数,该函数使用 SUM
聚合指标,然后按维度分组:
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 核心概览。
后续步骤
如需了解如何在 JavaScript 文件中引用包含内容,请参阅使用 JavaScript 创建 SQL 工作流。
如需了解如何在 Dataform 核心文件中通过、块和内嵌 JavaScript 重复使用代码,请参阅 Dataform 核心概览。