使用 JavaScript 创建 Dataform SQL 工作流

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

关于使用 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 文件中引用任何 include 函数、宏或常量。如需详细了解 Dataform 中的包含内容，请参阅通过 JavaScript 包含内容重复使用变量和函数。

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

参考顶级包含

• 如需引用顶级 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 assert JavaScript 方法在 JavaScript 文件中创建手动 SQL 断言。如需详细了解断言方法，请参阅 Dataform 核心参考文档。

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

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

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

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

2. 选择一个 JavaScript 文件。

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

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

   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 简介。