使用 JavaScript 创建 Dataform SQL 工作流

本文档介绍了如何使用 JavaScript 在 Dataform 中创建 SQL 工作流元素。您可能需要使用 JavaScript，而非 Dataform Core，在工作流中重复创建类似的元素。

如何使用 JavaScript 在 Dataform 中开发工作流

Dataform core 可用于使用 SQLX 和 JavaScript 创建 SQL 工作流操作。借助 JavaScript，您可以在工作流中重复创建类似的操作。例如，您可以为工作流中的每个表创建一个视图，其中包含移除特定用户 ID 的场景。

通过以下 JavaScript 代码示例，您可以为每个表创建一个视图，其中 user_id 字段的值与 blocked_user_ids 列表中的某个值不对应：

  const tableNames = ["user_events", "user_settings", "user_logs"];

  tableNames.forEach(tableName => {
    publish(tableName + "_blocked_removed").query(
      ctx => `
        SELECT * FROM ${ctx.ref(tableName)}
        WHERE user_id NOT IN (
          SELECT user_id
          FROM ${ctx.ref("blocked_user_ids")}
        )`
    );
  });

此代码示例创建了三个名为 user_events_blocked_removed、user_settings_blocked_removed 和 user_logs_blocked_removed 的视图，它们不包含任何被屏蔽的用户 ID。

您可以使用 Dataform 全局方法和任意 JavaScript ES5 代码（例如循环和常量）在一个 JavaScript 文件中创建多个操作。

您可以在 Dataform 中使用 JavaScript 定义以下操作：

• Tables
• 数据源声明
• 断言
• 自定义 SQL 操作

准备工作

1. 在 Google Cloud 控制台中，前往 Dataform 页面。

   前往 Dataform

2. 选择或创建代码库。

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

所需的角色

如需获取使用 JavaScript 开发 SQL 工作流所需的权限，请让管理员授予您工作区的 Dataform Editor (roles/dataform.editor) IAM 角色。如需详细了解如何授予角色，请参阅管理访问权限。

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

在 Dataform 中创建 JavaScript 文件

将定义和数据源声明的 JavaScript 文件存储在 definitions/ 目录中。如需在 definitions/ 目录中创建新的 JavaScript 文件，请按以下步骤操作：

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

2. 点击创建文件。

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

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

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

   2. 点击创建文件。

使用 JavaScript 设置 Dataform SQL 工作流对象属性

您可以使用以下 Dataform 全局方法通过 Dataform 创建 SQL 工作流对象：

• declare：用于声明数据源。
• publish：用于定义表。
• assert：用于创建断言。
• operate。用于定义自定义 SQL 操作。

每个全局方法都包含可用于配置所创建对象的属性。如需详细了解全局方法及其属性，请参阅 Dataform 核心参考文档。

在创建表的 publish() 方法中，您可以通过将表属性作为第二个方法参数传递来设置表属性。

如需将表属性作为 publish() 的第二个参数传递，请按以下步骤操作：

1. 在开发工作区的 Files 窗格中，展开 definitions/。

2. 选择一个 JavaScript 文件。

3. 在该文件中，按以下格式向 publish() 方法添加表属性：

    method("first_method_argument", {
      property1: "property1_value",
      property2: "property2_value",
      property3: "property3_value",
    });
   

4. 可选：点击格式。

以下代码示例展示了如何通过将属性作为 publish() 方法的第二个参数传递来将属性设置为该方法：

  publish("table1", {
    type: "table",
    dependencies: ["other_table"],
    description: {
      "Value is 1"
    }
  }).query(ctx => "SELECT 1 AS test");

JavaScript 文件中包含引用

您可以在 JavaScript 文件中引用任何包含函数、宏或常量。如需详细了解 Dataform 中的 include 文件，请参阅通过 JavaScript include 重复使用变量和函数。

在 JavaScript 文件中引用“include”的语法取决于该 include 文件的位置。Dataform 将此类文件存储在 include 目录中。

参考顶级包含内容

• 如需引用顶级包含文件，请在声明变量时引用文件名。

以下代码示例引用了 includes/service.js 文件中的 serviceName 和 serviceId 变量：

  const {serviceName, serviceId} = service;

引用的嵌套包含

如需引用嵌套的 include 文件，请在 JavaScript require 函数中输入文件名。

以下代码示例引用了 includes/allServices/service.js 文件中的 serviceName 和 serviceId 变量：

  const {serviceName, serviceId} = require("includes/allServices/service.js");

在 JavaScript 方法中使用 Dataform 查询函数

Dataform 提供了一些可在查询中使用的内置函数，例如 ref 和 self。如需详细了解 Dataform 内置函数，请参阅 Dataform API 参考文档。

若要在 JavaScript 方法中使用内置查询函数，请按以下步骤操作：

1. 在开发工作区的 Files 窗格中，展开 definitions/。

2. 选择一个 JavaScript 文件。

3. 在文件中，输入一个全局的 Dataform JavaScript 方法。

4. 在该方法中，输入一个上下文 ctx 参数。

5. 可选：如果您使用的是 JavaScript 模板字符串，请使用反引号 `` 将上下文参数封装起来。

6. 在上下文参数中，输入查询函数及其参数作为上下文对象。

7. 可选：点击格式。

以下代码示例展示了封装在 publish 方法的上下文相关参数中的 ref 查询函数：

  publish("example").query(ctx => `SELECT * FROM ${ctx.ref("other_table")}`);

使用 JavaScript 声明 SQL 工作流数据源

您可以使用 Dataform 声明 JavaScript 方法在一个 JavaScript 声明文件中声明多个数据源。如需详细了解声明方法，请参阅 Dataform 核心参考文档。如需详细了解 Dataform 中的数据源，请参阅声明数据源。

如需在 JavaScript 文件中声明数据源，请按以下步骤操作：

1. 在开发工作区的 Files 窗格中，展开 definitions/。

2. 选择一个 JavaScript 文件。

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

    declare({
      database: "DATABASE_PROJECT_ID",
      schema: "BIGQUERY_SCHEMA",
      name: "RELATION_NAME",
    });
   

   替换以下内容：

   • DATABASE_PROJECT_ID：包含数据源的项目的 ID
   • BIGQUERY_SCHEMA：存在外部关系的 BigQuery 数据集
   • RELATION_NAME：稍后您可用它来引用 Dataform 中的数据源的关系的名称

4. 如需在同一文件中声明其他数据源，请在文件中添加一个额外的 declare 块。

5. 可选：点击格式。

使用 JavaScript 定义表

您可以使用 Dataform JavaScript publish 方法创建表。如需详细了解发布方法，请参阅 Dataform 核心参考文档。

您可以定义以下表类型：表、增量表和视图。如需详细了解如何在 Dataform 中定义表，请参阅创建表。

如需在 JavaScript 文件中定义表，请按以下步骤操作：

1. 在开发工作区的 Files 窗格中，展开 definitions/。

2. 选择一个 JavaScript 文件。

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

    publish("TABLE_NAME").query(ctx => "SELECT_QUERY");
   

   1. 将 TABLE_NAME 替换为相应表的名称。

   2. 将 SELECT_QUERY 替换为定义表的 SQL SELECT 语句。

4. 如需设置表类型、添加表依赖项并添加表说明，请使用 publish 方法设置对象属性。

5. 如需在同一文件中定义另一个表，请重复第 3 步和第 4 步。

6. 可选：点击格式。

使用 JavaScript 定义手动 Dataform 断言

您可以使用 Dataform 断言 JavaScript 方法在 JavaScript 文件中创建手动 SQL 断言。如需详细了解断言方法，请参阅 Dataform 核心参考文档。

手动断言 SQL 查询必须返回零行。如果查询在执行时返回行，则断言失败。您可以在一个 JavaScript 文件中创建多个断言。

如需详细了解 Dataform 中的断言，请参阅使用断言测试表。

如需在 JavaScript 文件中创建手动断言，请按以下步骤操作：

1. 在开发工作区的 Files 窗格中，展开 definitions/。

2. 选择一个 JavaScript 文件。

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

    assert("<var>ASSERTION_NAME</var>").query(ctx => "<var>CUSTOM_ASSERTION_QUERY</var>");
   

   1. 将 ASSERTION_NAME 替换为您的自定义断言的名称。

   2. 将 CUSTOM_ASSERTION_QUERY 替换为您的 SQL 断言查询。

4. 如需在同一文件中创建另一个断言，请重复第 3 步。

5. 可选：点击格式。

以下代码示例展示了一个 JavaScript 断言，该断言断言 source_table 中没有值为 NULL：

  assert("assertion1").query(ctx => "SELECT * FROM source_table WHERE value IS NULL");

使用 JavaScript 定义自定义 SQL 操作

您可以使用 Dataform 操作 JavaScript 方法在 JavaScript 文件中定义自定义 SQL 操作。如需详细了解 Dataform 中的自定义 SQL 操作，请参阅添加自定义 SQL 操作。

如需使用 JavaScript 定义自定义 SQL 操作，请按以下步骤操作：

1. 在开发工作区的 Files 窗格中，展开 definitions/。

2. 选择一个 JavaScript 文件。

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

    operate("OPERATION_NAME").queries(ctx => "CUSTOM_SQL_QUERY");
   

   1. 将 OPERATION_NAME 替换为自定义操作的名称。

   2. 将 CUSTOM_SQL_QUERY 替换为您的自定义 SQL 查询。

4. 如需在同一文件中定义其他自定义 SQL 操作，请重复第 3 步。

5. 可选：点击格式。

以下代码示例展示了 JavaScript 文件中的自定义 SQL 操作，该操作将一个新行插入 some_table 并将新行的 test_column 设置为 2：

  operate("operation1").queries("INSERT INTO some_table (test_column) VALUES (2)");

后续步骤

• 如需详细了解 Dataform JavaScript 方法和内置查询函数，请参阅 Dataform 核心参考文档。
• 如需详细了解如何使用 JavaScript 在 Dataform 中进行开发，请参阅 Dataform 中的 JavaScript 简介。