在 Dataform 中通过 include 重复使用变量和函数

本文档介绍了如何创建 JavaScript 包含，以在 Dataform 中重复使用代码。

在代码库的 includes/ 文件夹中，您可以定义 JavaScript 包含。包含是指可在整个代码库中重复使用的全局常量或函数。

准备工作

  1. 在 Google Cloud 控制台中，转到 Dataform 页面。

    转到 Dataform

  2. 选择或创建 Dataform 代码库。

  3. 选择或创建 Dataform 开发工作区。

所需的角色

如需获取通过 JavaScript include 重复使用代码所需的权限，请让管理员向您授予工作区的 Dataform Editor (roles/dataform.editor) IAM 角色。如需详细了解如何授予角色，请参阅管理访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

为“包含 Dataform 创建 JavaScript 文件

如需在 includes/ 目录中创建新的 JavaScript 文件，请按以下步骤操作：

  1. 在 Files 窗格的 includes/ 旁边，点击 More 菜单。

  2. 点击创建文件。

  3. 在创建新文件窗格中，执行以下操作：

    1. 在添加文件路径字段中的 includes/ 后，输入文件名，后跟 .js。例如 includes/constants.js。

      文件名只能包含数字、字母、连字符和下划线。

    2. 点击创建文件。

创建 JavaScript 常量

如需创建可在项目中重复使用的常量，请按以下步骤操作：

  1. 转到开发工作区。

  2. 在 Files 窗格中，展开 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 core 表定义查询：

  SELECT * FROM my_project_name.my_schema_name.my_table_name

创建自定义 JavaScript 函数

如需创建可在项目中重复使用的自定义 JavaScript 函数，请按以下步骤操作：

  1. 转到开发工作区。

  2. 在 Files 窗格中，展开 includes/。

  3. 创建或选择扩展名为 .js 的 JavaScript 文件。

  4. 在文件中，编写您的自定义 JavaScript 函数。

  5. 在文件中输入以下代码段：

     module.exports = { FUNCTION_NAME }

    将 FUNCTION_NAME 替换为您的函数的名称。

  6. 可选：点击格式。

以下代码示例展示了 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，请按以下步骤操作：

  1. 转到开发工作区。

  2. 在 Files 窗格中，展开 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}

将 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 核心概览。

后续步骤