Dataform 核心概览

本文档介绍了 Dataform 核心，并展示了如何在 Dataform 中使用该核心。

Dataform 核心概览

Dataform 核心是一种用于创建 SQL 表和工作流的开源元语言。Dataform 核心通过提供依赖项管理系统、自动化数据质量测试和数据文档来扩展 SQL。

您可以将 Dataform 核心用于以下用途：

  • 定义表、视图、具体化视图或增量表。
  • 定义数据转换逻辑。
  • 声明源数据和管理表依赖项。
  • 在代码中记录表和列的说明。
  • 在不同查询中重复使用函数和变量。
  • 编写数据断言以确保数据一致性。

在 Dataform 中，使用 Dataform 核心来开发 SQL 工作流并将资产部署到 BigQuery。

Dataform 核心是开源 Dataform 数据建模框架的一部分，该框架还包含 Dataform CLI。您可以通过 Google Cloud 外部的 Dataform CLI 在本地编译和运行 Dataform 核心。

如需使用 Dataform 核心，您需要编写 SQLX 文件。每个 SQLX 文件均包含一个查询，用于定义 Dataform 在 BigQuery 内创建和更新的数据库关系。

Dataform 会实时编译您的 Dataform 核心代码，以创建您可以在 BigQuery 中执行的 SQL 编译结果。

Dataform 编译是封闭的，可确保编译一致性，这意味着同一代码每次都会编译为相同的 SQL 编译结果。Dataform 会在不连接到互联网的沙盒环境中编译您的代码。编译期间无法使用其他操作，例如调用外部 API。

SQLX 文件配置块

SQLX 文件由配置块和正文组成。所有配置属性以及配置块本身都是可选的。因此，任何普通 SQL 文件都是有效的 SQLX 文件，Dataform 按原样执行。

在 config 块中，您可以执行以下操作：

指定查询元数据

您可以使用配置元数据配置 Dataform 如何将查询具体化到 BigQuery，例如输出表类型、目标数据库或标签。

文档数据

您可以直接在配置块中记录表及其字段。表的文档直接推送到 BigQuery。您可以解析此文档，并将其推送到其他工具。

定义数据质量测试

您可以定义数据质量测试（称为“断言”），以检查唯一性、null 值或自定义条件。创建表后，Dataform 会将配置块中定义的断言添加到工作流依赖关系树中。您还可以在配置块之外，在单独的 SQLX 文件中定义断言。

以下代码示例展示了如何在 SQLX 文件的配置块中定义输出表类型、记录该表以及定义质量测试。

config {
  type: "table",
    description: "This table joins orders information from OnlineStore & payment information from PaymentApp",
  columns: {
    order_date: "The date when a customer placed their order",
    id: "Order ID as defined by OnlineStore",
    order_status: "The status of an order e.g. sent, delivered",
    customer_id: "Unique customer ID",
    payment_status: "The status of a payment e.g. pending, paid",
    payment_method: "How the customer chose to pay",
    item_count: "The number of items the customer ordered",
    amount: "The amount the customer paid"
  },
    assertions: {
    uniqueKey: ["id"]
  }
}

SQLX 文件正文

在 SQLX 文件的正文中，您可以执行以下操作：

定义表

如需定义新表，您可以使用 SQL SELECT 语句和 ref 函数。

ref 函数是一个 SQLX 内置函数，对于 Dataform 中的依赖项管理至关重要。借助 ref 函数，您可以引用 Dataform 项目中定义的表，而无需对数据表的架构和表名称进行硬编码。

Dataform 使用 ref 函数构建要创建或更新的所有表的依赖关系树。编译后，Dataform 会添加 CREATE、REPLACE 或 INSERT 等样板语句。

以下代码示例演示了如何使用 ref 函数引用 SQLX 文件中的表。

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, 3

输出类似于以下内容：

CREATE OR REPLACE TABLE Dataform.orders AS

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 Dataform_stg.store_clean

GROUP BY 1, 2, 3

如需详细了解其他依赖项管理（例如，使用其他 Dataform 核心内置函数有条件地执行代码），请参阅 Dataform 核心参考文档。

定义其他 SQL 操作

如需将 Dataform 配置为在创建表或视图之前或之后执行一个或多个 SQL 语句，您可以指定查询前和查询后操作。

以下代码示例展示了如何在查询后操作中配置表或查看访问权限。

SELECT * FROM ...

post_operations {
  GRANT `roles/bigquery.dataViewer` ON TABLE ${self()} TO "group:someusers@dataform.co"
}

封装 SQL 代码

如需定义可重复使用的函数以生成 SQL 代码的重复部分，您可以使用 JavaScript 块。您只能在定义 JavaScript 块的 SLQX 文件中重复使用在 JavaScript 块中定义的代码。如需在整个代码库中重复使用代码，您可以创建包含。

要动态修改查询，您可以在正文中的任何位置使用内嵌 JavaScript。

以下代码示例展示了如何在 SQLX 文件中定义 JavaScript 块并将其内嵌在查询内：

js {
  const columnName = "foo";
}

SELECT 1 AS ${columnName} FROM "..."

后续步骤