创建表

本文档介绍如何在 Dataform 中使用 Dataform Core 定义表。

关于表定义

如需定义表,请定义表类型并在 type: "table" SQLX 文件中编写 SELECT 语句。然后,Dataform 会将您的 Dataform 核心代码编译为 SQL,执行 SQL 代码,并在 BigQuery 中创建定义的表。

在 Dataform 核心 SELECT 语句中,您可以定义表结构并引用 SQL 工作流的其他对象。

除了在 type: "table" SLQX 文件中定义表之外,您还可以通过在 type: "operations" SQLX 文件中定义自定义 SQL 查询来创建空表。如需了解详情,请参阅创建空表

通过 ref 引用依赖项

如需在 SELECT 语句中引用 SQL 工作流对象并自动将其添加为依赖项,请使用 ref 函数。Dataform 会先执行各种依赖项,然后再执行依赖于这些依赖项的表,以确保流水线排序正确。

ref 函数是 Dataform 核心内置函数,对 Dataform 中的依赖项管理至关重要。借助 ref 函数,您可以引用并自动依赖于 Dataform SQL 工作流中定义的以下对象,而不是对架构和表名称进行硬编码:

Dataform 使用 ref 函数构建要创建或更新的所有表的依赖关系树。

编译后,Dataform 会将 CREATEREPLACEINSERTMERGE 等样板语句添加到 SQL 语句中。

以下代码示例展示了使用 ref 函数的表定义:

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

ref 函数中,您需要提供要依赖的表或数据源声明的名称。这通常是在其中定义了表或数据源声明的 SQLX 文件的文件名。

如果表名称被替换,请在 ref 函数中使用被替换的名称。 例如,引用 config { name: "overridden_name" }ref("overridden_name") 的表。如需详细了解如何覆盖表名称,请参阅配置其他表设置

如果不同架构中有多个同名表,您可以通过向 ref 函数提供两个参数(架构名称和表名称)来引用特定表。

以下代码示例展示了包含两个参数的 ref 函数,该函数用于在特定架构中指定表:

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

对于未在 SELECT 语句的 ref 函数中引用的表、断言、数据源声明或自定义 SQL 操作,您还可以手动将表依赖项添加到 config 代码块中。Dataform 会先执行这些依赖项,然后再执行从属表。

以下代码示例展示了 config 代码块中的表依赖项:

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

如需详细了解 SQL 工作流中的依赖项管理,请参阅声明依赖项

使用 resolve 引用其他表

利用 resolve 函数,您可以在 SELECT 语句(如 ref 函数)中引用表或数据源声明,但不会将引用添加为依赖项。这意味着,使用 resolve 引用的对象不会影响使用 resolve 的表的执行。

如需详细了解内置的 Dataform 核心功能,请参阅 Dataform 核心参考文档

准备工作

  1. 在您的代码库中创建并初始化开发工作区
  2. 可选:声明数据源

所需的角色

如需获取定义表所需的权限,请让管理员向您授予工作区的 Dataform Editor (roles/dataform.editor) IAM 角色。如需详细了解如何授予角色,请参阅管理访问权限

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

创建用于表定义的 SQLX 文件

将表定义 SQLX 文件存储在 definitions/ 目录中。如需在 definitions/ 目录中创建新的 SQLX 文件,请按以下步骤操作:

  1. 在 Cloud 控制台中,转到 Dataform 页面。

    转到 Dataform 页面

  2. 如需打开代码库,请点击代码库名称。

  3. 如需打开开发工作区,请点击工作区名称。

  4. Files 窗格的 definitions/ 旁边,点击 More 菜单。

  5. 点击创建文件

  6. 添加文件路径字段中,输入文件的名称,在 definitions/ 后面加上 .sqlx。例如 definitions/my-table.sqlx

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

  7. 点击创建文件

定义表类型

如需创建新的表类型定义,请按以下步骤操作:

  1. 在开发工作区的文件窗格中,展开 definitions/ 目录。
  2. 选择要修改的表定义 SQLX 文件。
  3. 在文件中输入以下代码段:

    config { type: "TABLE_TYPE" }
    

    TABLE_TYPE 替换为以下表类型之一:

    • table
    • incremental
    • view
  4. 可选:如需定义具体化视图,请按以下格式在 type: "view" 下输入 materialized 属性:

    config {
      type: "view",
      materialized: true
    }
    

    如需了解详情,请参阅 ITableConfig Dataform 核心参考文档

  5. 可选:点击格式

定义表结构和依赖项

如需编写表定义 SELECT 语句并定义表结构和依赖项,请按以下步骤操作:

  1. 在开发工作区的文件窗格中,展开 definitions/ 目录。
  2. 选择要修改的表定义 SQLX 文件。
  3. config 代码块下方,编写一个 SELECT 语句。
  4. 可选:点击格式

以下代码示例展示了一个包含 SELECT 语句和 ref 函数的表定义:

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

手动添加表依赖项

如需添加 SELECT 语句中未引用但需要在当前表之前执行的表依赖项,请按以下步骤操作:

  1. 在开发工作区的文件窗格中,展开 definitions/ 目录。
  2. 选择要修改的表定义 SQLX 文件。
  3. 在表的 config 代码块中,输入以下代码段:

    dependencies: [ "DEPENDENCY_TABLE", ]
    

    DEPENDENCY_TABLE 替换为您要作为依赖项添加的表的文件名。您可以输入多个文件名。

  4. 可选:点击格式

以下代码示例显示了作为手动表依赖项添加到表定义文件的 config 块中的两个表:

config { dependencies: [ "some_table", "some_other_table" ] }

后续步骤