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

后续步骤