使用 JavaScript 创建 Dataform SQL 工作流

本文档介绍了如何使用 JavaScript 在 Google Cloud 控制台中创建 SQL 工作流元素, 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_removeduser_settings_blocked_removeduser_logs_blocked_removed,其中没有任何被屏蔽的用户 ID。

您可以使用 Dataform 全局方法和任意 JavaScript ES5 代码,如 循环和常量的形式来表示。

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

准备工作

  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 文件,请在出现以下情况时引用该文件名: 声明变量的方法。

以下代码示例引用了 serviceNameserviceId。 来自 includes/service.js 文件中的变量:

  const {serviceName, serviceId} = service;

引用嵌套包含

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

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

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

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

Dataform 提供了许多内置函数 例如 refself。如需详细了解 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_column2

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

后续步骤