Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

Dataform 核心参考文档

本文档介绍了 Dataform 核心的方法、属性和配置选项。您可以在 SQLX 和 JavaScript 文件中使用 Dataform 核心。

assert()

assert (name: string, query?: AContextable)

向已编译的图表添加 Dataform 断言。

仅在 /definitions 目录中提供。

示例：

// definitions/file.js

assert("name").query(ctx => "select 1");

CommonContext

在评估可上下文化的 SQL 代码（例如在 SQLX 文件中）或将 Contextable 参数与 Dataform 核心搭配使用时，可以使用上下文方法。

`database`	`() => string`
	返回此数据集的数据库（如果适用）。
`name`	`() => string`
	返回此表的名称。
`ref`	`(ref: Resolvable \| string[], rest: string[]) => string`
	引用另一个操作，将其作为依赖项添加到此操作，并返回要在 `from` 表达式中使用的有效 SQL。您可以使用 `Resolvable` 对象调用此函数，例如： `${ref({ name: "name", schema: "schema", database: "database" })}` 也可以使用 `"database"`、`"schema"` 和 `"name"` 值的各个参数来调用此函数。如果仅提供两个值，则使用默认数据库，并将这两个值解读为 `"schema"` 和 `"name"`。如果仅提供一个值，系统会使用默认数据库和架构，并将提供的值解读为“名称”。 `${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}`
`resolve`	`(ref: Resolvable \| string[], rest: string[]) => string`
	与 `ref` 类似，但不会将引用的操作作为依赖项添加到此操作。
`self`	`() => string`
	等同于 `resolve(name())`。返回一个有效的 SQL 字符串，可用于引用此操作生成的表。
`schema`	`() => string`
	返回相应数据集的架构。

Contextable

可上下文参数可以为其泛型类型 T 传递普通值，也可以传递使用此类操作的上下文对象调用的函数。

T | (ctx: Context) => T

Dataform

包含 IProjectConfig 对象的全局变量。获取 IProjectConfig 属性时需要，例如：

dataform.projectConfig.vars.myVariableName === "myVariableValue"

declare()

declare (dataset: dataform.ITarget)

将数据集声明为 Dataform 数据源。

仅在 /definitions 目录中提供。

示例：

// definitions/file.js

declare({name: "a-declaration"})

defaultLocation

defaultLocation 属性指定默认 BigQuery 数据集位置。Dataform 使用此位置来处理您的代码并存储结果。此处理位置必须与 BigQuery 数据集的位置一致。但是，它不需要与 Dataform 代码库位置匹配。

如果您未设置 defaultLocation 属性，Dataform 会根据 SQL 查询引用的数据集确定位置。具体运作方式如下：

如果您的查询引用了同一位置的数据集，Dataform 会使用该位置。
如果查询引用了来自两个或更多不同位置的数据集，则会发生错误。如需详细了解此限制，请参阅跨区域数据集复制。
如果查询未引用任何数据集，Dataform 的默认位置为 US 多区域。如需选择其他位置，请设置 defaultLocation 属性。或者，您也可以在查询中使用 @@location 系统变量。

如需了解详情，请参阅指定位置。

IActionConfig

定义应用于工作流操作的 Dataform 标记和依赖项。

`tags`	`string[]`
	用户定义的标记列表，用于标记操作。
`dependencies`	`Resolvable\| Resolvable[]`
	操作的依赖项。
`disabled`	`boolean`
	如果设置为 true，则不会运行此操作。不过，该操作仍可依赖。可用于暂时关闭损坏的操作。

IAssertionConfig

assertion 操作类型的配置选项。

`database`	`string`
	要在其中为此断言创建相应视图的数据库（Google Cloud 项目 ID）。
`description`	`string`
	此断言的说明。
`disabled`	`boolean`
	如果设置为 `true`，则系统不会运行此操作。该操作仍可依赖。这对于暂时关闭损坏的操作非常有用。
`hermetic`	`boolean`
	声明此操作是否为封闭式操作。如果某个操作的所有依赖项都已明确声明，则该操作是密封的。如果此操作依赖于未声明为依赖项的来源中的数据，请将 `hermetic` 设置为 `false`。否则，请将其设置为 `true`。
`schema`	`string`
	要在其中为此断言创建相应视图的架构（BigQuery 数据集）。
`tags`	`string[]`
	应用于相应操作的用户定义标记的列表。

IBigQueryOptions

BigQuery 专属仓库选项。

`additionalOptions`
	表、视图和物化视图选项的键值对。某些选项（例如 `partitionExpirationDays`）具有专用的类型/有效性检查字段。对于此类选项，请使用专用字段。字符串值必须用英文双引号括起来，例如： `additionalOptions: {numeric_option: "5"`、`string_option: '"string-value"'}` 如果选项名称包含特殊字符，请用英文引号将名称括起来，例如：`additionalOptions: { "option-name": "value" }`。
`clusterBy`	`string[]`
	用于对分区进行聚类的键。
`labels`
	BigQuery 标签的键值对。如果标签名称包含特殊字符（例如连字符），请用英文引号括住其名称，例如 `labels: { "label-name": "value" }.`
`partitionBy`	`string`
	用于对表进行分区的键。通常是时间戳或日期列的名称。
`partitionExpirationDays`	`number`
	BigQuery 在每个分区中存储数据的天数。该设置适用于表中的所有分区，但会根据分区时间为每个分区单独计算。
`requirePartitionFilter`	`boolean`
	声明分区表是否需要用于过滤分区列的 `WHERE` 子句谓词过滤条件。
`updatePartitionFilter`	`string`
	在应用增量更新时使用的基于 SQL 的过滤条件。
`iceberg`	`IIcebergOptions`
	Iceberg 托管式表的 Apache Iceberg 专用选项。

IIcebergOptions

Iceberg 托管式表的 Apache Iceberg 特有选项。

`connection`	`string`
	可选。Cloud Storage 连接的资源名称，该连接提供用于读取和写入外部存储空间的凭证。您可以按以下方式设置其格式： `PROJECT_ID.LOCATION.CONNECTION_ID` 替换以下值： `PROJECT_ID`： Google Cloud 项目 ID `LOCATION`：连接的位置名称 `CONNECTION_ID`：连接的名称或 ID `projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID` `DEFAULT` 默认为 `DEFAULT`。如需了解详情，请参阅默认连接概览。
`file_format`	`string`
	可选。表数据的文件格式。仅支持 `PARQUET`。默认值为 `PARQUET`。
`bucket_name`	`string`
	在表或工作流级别为必填项。存储表数据的 Cloud Storage 存储桶的名称。您必须在表定义文件的 `config` 块中提供 `bucket_name`，或者在 `workflow_settings.yaml` 文件中设置工作流级默认值。如果两者都未提供，编译会失败。如需了解详情，请参阅为 Iceberg 表配置工作流级默认设置。
`table_folder_root`	`string`
	可选。Cloud Storage 存储桶内存储表格数据的一级文件夹的名称。如果您未设置此属性，Dataform 会使用 `workflow_settings.yaml` 中的工作流级默认值（如果已设置）。否则，默认值为 `_dataform`。
`table_folder_subpath`	`string`
	可选。`tableFolderRoot` 中的子文件夹。如果您未设置此属性，Dataform 会使用 `workflow_settings.yaml` 中的工作流级默认值（如果已设置）。如果未设置该属性，也未设置工作流级默认值，则子路径默认为 `DATASET_NAME/TABLE_NAME`。

这些值会按以下格式构建 Cloud Storage URI：gs://BUCKET_NAME/TABLE_FOLDER_ROOT/TABLE_FOLDER_SUBPATH。

IColumnsDescriptor

描述表中的列。

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

declaration 操作类型的配置选项。

`columns`	`IColumnsDescriptor`
	表中各列的说明。
`database`	`string`
	源表所在的数据库（Google Cloud 项目 ID）。
`description`	`string`
	表的说明。
`schema`	`string`
	源表所在的架构 (BigQuery 数据集)。

IDependenciesConfig

定义工作流操作的依赖项。

`dependencies`	`Resolvable\| Resolvable[]`
	相应操作的一个或多个显式依赖项。依赖项操作将在被依赖项操作之前运行。通常，此属性会保持未设置状态，因为大多数依赖项都是在使用 `ref` 函数时作为副产品声明的。
`hermetic`	`boolean`
	声明此操作是否为封闭式。如果某个操作的所有依赖项都已明确声明，则该操作是封闭的。如果此操作依赖于未声明为依赖项的来源中的数据，则应将 `hermetic` 显式设置为 `false`。否则，如果此操作仅依赖于显式声明的依赖项中的数据，则应将其设置为 `true`。

IDocumentableConfig

定义数据集及其列的说明。

`columns`	`IColumnsDescriptor`
	数据集内各列的说明。
`description`	`string`
	数据集的说明。

INamedConfig

定义工作流操作的类型和名称。

`type`	`string`
	操作的类型。
`name`	`string`
	操作的名称。

IOperationConfig

operations 操作类型的配置选项。

`columns`	`IColumnsDescriptor`
	表格中各列的说明。
`database`	`string`
	要在其中创建此操作输出的数据库（Google Cloud 项目 ID）。
`description`	`string`
	表的说明。
`disabled`	`boolean`
	如果设置为 `true`，则系统不会运行此操作。该操作仍可依赖。可用于暂时关闭损坏的操作。
`hasOutput`	`boolean`
	声明此 `operations` 操作会创建一个可使用 `ref` 函数引用的表。如果设置为 `true`，此操作会使用 `self()` 上下文函数创建一个具有其配置名称的表。例如： `create or replace table ${self()} as select ...`
`hermetic`	`boolean`
	声明此操作是否为封闭式。如果操作的所有依赖项都已明确声明，则该操作是封闭的。如果此操作依赖于未声明为依赖项的来源中的数据，请将 `hermetic` 设置为 `false`。否则，请将其设置为 `true`。
`schema`	`string`
	用于创建此操作输出的架构（BigQuery 数据集）。
`tags`	`string[]`
	应用于此操作的用户定义标记列表。

IProjectConfig

包含 Dataform 代码库的编译设置。

`defaultDatabase`	`string`
	必需。默认数据库（Google Cloud 项目 ID）。
`defaultSchema`	`string`
	必需。默认架构（BigQuery 数据集 ID）。
`defaultLocation`	`string`
	可选。Dataform 创建表的默认 BigQuery 位置。
`assertionSchema`	`string`
	必需。断言的默认架构（BigQuery 数据集 ID）。
`vars`	`map (key: string, value: string)`
	可选。在编译期间可供项目代码使用的用户定义的变量。包含一系列 `"key": value` 对的对象。示例：`{ "name": "wrench", "mass": "1.3kg", "count": "3" }`。
`databaseSuffix`	`string`
	可选。应附加到所有数据库（Google Cloud 项目 ID）名称的后缀。
`schemaSuffix`	`string`
	可选。应附加到所有架构（BigQuery 数据集 ID）名称的后缀。
`tablePrefix`	`string`
	可选。应添加到所有表名称前面的前缀。
`defaultIcebergConfig`	`object`
	可选。Apache Iceberg 托管式表的工作流级默认设置。包含以下字段： `bucketName`：可选。Cloud Storage 存储桶的默认名称。 `tableFolderRoot`：可选。Cloud Storage 存储桶内第一级文件夹的默认名称。 `tableFolderSubpath`：可选。`tableFolderRoot` 中子文件夹的默认名称。如需了解详情，请参阅为 Iceberg 表配置工作流级默认设置。
`preserveGovernanceControls`	`boolean`
	可选。如果设置为 `true`，Dataform 会在工作流运行期间自动保留代码库中所有表的现有 BigQuery 数据政策和数据治理标记（预览版）。
`warehouse`	`string`
	必需。必须设置为 `bigquery`。

您可以在代码库级在工作流设置中设置 IProjectConfig 属性。

您可以为各个表替换 defaultSchema 和 defaultDatabase 属性。

您可以在 SQLX 或 JavaScript 文件中的 SQL SELECT 语句中访问所有 IProjectConfig 属性。

以下代码示例展示了在工作流设置中使用 projectConfig.vars 属性设置的 myVariableName 自定义编译变量，该变量在 SQLX 文件中的 SELECT 语句中访问：

  config { type: "view" }
  SELECT ${when(
    dataform.projectConfig.vars.myVariableName === "myVariableValue",
    "myVariableName is set to myVariableValue!",
    "myVariableName is not set to myVariableValue!"
  )}

如需详细了解如何为各个编译结果替换项目配置设置，请参阅 Dataform API 中的 CodeCompilationConfig REST 资源。

IRecordDescriptor

描述具有嵌套列的表中的结构体、对象或记录。

`bigqueryPolicyTags`	`string \| string[]`
	应用于此列的 BigQuery 政策标记的完整标识符。BigQuery 政策标记的完整标识符包括项目名称、位置和分类例如：`"projects/1/locations/eu/taxonomies/2/policyTags/3"` BigQuery 支持为每列添加一个标记。
`columns`	`IColumnsDescriptor`
	结构体、对象或记录中的列的说明。
`description`	`string`
	结构、对象或记录的说明。

ITableAssertions

用于在表定义中创建断言的选项。

`nonNull`	`string \| string[]`
	永远不能为 `NULL` 的列。如果设置了此参数，则当任何行包含相应列的 `NULL` 值时，对应的断言会失败。
`rowConditions`	`string[]`
	应适用于表中所有行的常规条件。如果设置了此参数，则当任何行违反其中任何条件时，相应的断言都会失败。
`uniqueKey`	`string \| string[]`
	构成表的唯一键索引的列。如果设置此属性，当表中有多个行在所有这些列中具有相同的值时，生成的断言会失败。
`uniqueKeys`	`[]`
	列的组合，每种组合都构成表的唯一键索引。如果设置了此属性，当表中有多行在唯一键的所有列中具有相同的值时，生成的断言会失败。

ITableConfig

table 操作的配置选项，包括 table、view 和 incremental 表格类型。

扩展 IActionConfig、IDependenciesConfig、IDocumentableConfig、INamedConfig 和 ITargetableConfig。

`assertions`	`ITableAssertions`
	要对表运行的断言。如果已配置，系统会自动创建相关断言并将其作为此表的依赖项运行。
`bigquery`	`IBigQueryOptions`
	BigQuery 专用仓库选项。
`columns`	`IColumnsDescriptor`
	表格中各列的说明。
`database`	`string`
	要在其中创建此操作输出的数据库（Google Cloud 项目 ID）。
`description`	`string`
	表的说明。
`disabled`	`boolean`
	如果设置为 `true`，则不会运行此操作。该操作仍可依赖。可用于暂时关闭损坏的操作。
`hermetic`	`boolean`
	声明此操作是否为封闭式。如果某个操作的所有依赖项都已明确声明，则该操作是封闭的。如果此操作依赖于未声明为依赖项的来源中的数据，请将 `hermetic` 设置为 `false`。否则，请将其设置为 `true`。
`materialized`	`boolean`
	仅在表类型为 `view` 时有效。如果设置为 true，系统将创建具体化视图。
`onSchemaChange`	`onSchemaChange`
	仅在表类型为 `incremental` 时有效。 Dataform 检查 `SELECT` 查询以确定是否添加或移除了列后执行的操作。此功能处于预览版阶段。
`preserveGovernanceControls`	`boolean`
	可选。如果设置为 `true`，Dataform 会在完全刷新期间重新创建表、视图或增量表时备份并重新应用现有的 BigQuery 数据政策和数据治理标记（预览版）。替换 `workflow_settings.yaml` 中设置的工作流级默认值。
`protected`	`boolean`
	仅允许用于 `incremental` 表类型。如果设置为 true，则运行此操作会忽略 `full-refresh` 选项。这对于从临时数据构建的表非常有用，可用于验证历史数据是否永远不会丢失。
`schema`	`string`
	用于创建相应操作输出的架构 (BigQuery 数据集)。
`tags`	`string[]`
	应用于此操作的用户定义标记列表。
`type`	`TableType`
	表的类型。
`uniqueKey`	`string[]`
	增量表的合并条件的唯一键。如果已配置，系统会更新具有匹配唯一键的记录，而不是插入新行。

ITableContext

在评估可包含上下文的 SQL 代码（例如在 SQLX 文件中）或将 Contextable 参数与 Dataform 核心搭配使用时，可以使用上下文方法。

`incremental`	`() => boolean`
	当当前上下文指示表将以增量方式构建时，返回 true。
`name`	`() => string`
	返回此表的完全限定名称。
`ref`	`(ref: Resolvable \| string[], rest: string[]) => string`
	引用另一个操作，将其作为依赖项添加到此操作中，并返回要在 from 表达式中使用的有效 SQL。可以使用 `Resolvable` 对象调用此函数，例如： `${ref({ name: "name", schema: "schema", database: "database" })}` 也可以使用 `"database"`、`"schema"` 和 `"name"` 值的各个参数来调用此函数。如果仅提供两个值，则系统会使用默认数据库，并将这些值解释为 `"schema"` 和 `"name"`。如果仅提供一个值，则会使用默认数据库架构，并将提供的值解释为 `"name"`。 `${ref("database", "schema", "name")} ${ref("schema", "name")} ${ref("name")}`
`resolve`	`(ref: Resolvable \| string[], rest: string[]) => string`
	与 `ref` 类似，但它不会添加依赖项，而是会解析提供的引用，以便在 SQL 中使用，例如在 `from` 表达式中使用。
`self`	`() => string`
	等同于 `resolve(name())`。返回一个有效的 SQL 字符串，该字符串可用于引用此操作生成的表。
`when`	`(cond: boolean, trueCase: string, falseCase: string) => string`
	`if` 条件的简写形式。等同于 `cond ? trueCase : falseCase`。 `falseCase` 是可选的，默认值为空字符串。

ITarget

对 BigQuery 中表的引用。

`database`	`string`
`name`	`string`
`schema`	`string`

ITargetableConfig

定义工作流操作的目标数据库和架构。

`database`	`string`
	应在哪个数据库中创建相应操作的输出。必须设置为 BigQuery。
`schema`	`string`
	应在其中创建此操作输出的架构。

onSchemaChange

设置 onSchemaChange 属性后，Dataform 会检查 SELECT 查询，以确定是否添加或移除了列。然后，Dataform 会执行 onSchemaChange 属性值指定的操作。您可以将操作设置为以下任一项：

IGNORE（默认）：忽略添加的列，并针对缺失的列显示错误。如果未设置 onSchemaChange，则这是架构更改时的默认行为。
FAIL：如果 Dataform 检测到任何架构更改，则会停止操作，这有助于保持架构一致。
EXTEND：将查询中的新列添加到增量表中，并为之前的记录添加 NULL 值。如果查询中的原始架构中移除或缺少某个列，则会显示错误。您可以使用此设置在运行时向增量表添加新列。
SYNCHRONIZE：将查询中的新列添加到增量表中，并为之前的记录添加 NULL 值。移除原始架构中存在但当前查询中缺失的列。

注意：SYNCHRONIZE 操作无法撤消，并且使用此选项移除列时可能会丢失数据。
注意：不支持删除分区列和聚簇列，因为删除这些列可能会产生负面后果。如果分区列或聚簇列仍被删除，则使用 ALTER TABLE DROP COLUMN 语句进行处理。Dataform 不会执行检查或验证来阻止在分区列或聚簇列上运行 ALTER TABLE DROP COLUMN 语句。因此，如果您要删除此类列，请谨慎操作，并注意潜在的负面后果。

operate()

operate (name: string, queries?: Contextable)

定义 SQL 操作。

仅在 /definitions 目录中提供。

示例：

// definitions/file.js

operate("an-operation", ["SELECT 1", "SELECT 2"])

publish()

publish (name: string, queryOrConfig?: Contextable | ITableConfig)

创建表或视图。

仅在 /definitions 目录中提供。

示例：

// definitions/file.js

publish("published-table", {
    type: "table",
    dependencies: ["a-declaration"],
  }).query(ctx => "SELECT 1 AS test");

可解决

可解析对象可以是 string 形式的表名称，也可以是描述关系完整路径的对象。

string | ITarget

TableType

支持的表操作类型。

类型为 view 的表将创建为视图。

table 类型的表将创建为表。

类型为 incremental 的表必须包含 where 子句。如需了解详情，请参阅配置增量表。

Dataform 核心参考文档 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

assert()

CommonContext

Contextable

Dataform

declare()

defaultLocation

IActionConfig

IAssertionConfig

IBigQueryOptions

IIcebergOptions

IColumnsDescriptor

IDeclarationConfig

IDependenciesConfig

IDocumentableConfig

INamedConfig

IOperationConfig

IProjectConfig

IRecordDescriptor

ITableAssertions

ITableConfig

ITableContext

ITarget

ITargetableConfig

onSchemaChange

operate()

publish()

可解决

TableType

Dataform 核心参考文档