使用 JavaScript 创建 Dataform SQL 工作流

本文档介绍了如何使用 JavaScript 在 Dataform 一样。您可能希望使用 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 代码，如 循环和常量的形式来表示。

您可以在 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/ 旁边的 更多菜单。

2. 点击创建文件。

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

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

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

   2. 点击创建文件。

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

您可以使用以下 Dataform 全局方法创建 SQL 与 Dataform 搭配使用的工作流对象：

• 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 include 文件重复使用变量和函数。

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

参考顶级包含

• 要引用顶级 include 文件，请在出现以下情况时引用该文件名： 声明变量的方法。

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

  const {serviceName, serviceId} = service;

引用嵌套包含

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

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

  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. 可选：点击格式。

以下代码示例显示了封装在ref 发布方法的 contextable 参数：

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

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

您可以在一个 JavaScript 声明文件中声明多个数据源，具体代码如下： Dataform 声明 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 方法。如需详细了解 断言方法，请参阅 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 方法。如需详细了解 自定义 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 简介。