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
	返回此数据集的架构。

可关联

可上下文的参数可以为其通用类型 T 传递一个普通值，也可以传递一个通过上下文对象调用的函数。

T | (ctx: Context) => T

Dataform

包含 IProjectConfig 对象的全局变量。这是获取 IProjectConfig 属性所必需的，例如：

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

声明()

declare	(dataset: dataform.ITarget)
	将数据集声明为 Dataform 数据源。 仅在 /definitions 目录中可用。

示例：

// definitions/file.js

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

IActionConfig

定义应用于 SQL 工作流操作的 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 的过滤条件，适用于应用增量更新的情况。

IColumnsDescriptor

描述表中的列。

{ [name]: string | IRecordDescriptor }

IDeclarationConfig

declaration 操作类型的配置选项。

columns	IColumnsDescriptor
	对表中列的说明。
database	string
	要在其中创建源表的数据库（Google Cloud 项目 ID）。
description	string
	表的说明。
schema	string
	源表所在的架构（BigQuery 数据集）。

IDependenciesConfig

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

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

IDocumentableConfig

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

columns	IColumnsDescriptor
	数据集中列的说明。
description	string
	数据集的说明。

INamedConfig

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

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
	必需。要使用的默认 BigQuery 位置。 如需详细了解 BigQuery 位置，请参阅 https://cloud.google.com/bigquery/docs/locations。
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
	可选。应添加到所有表名称前面的前缀。
warehouse	string
	必需。必须设置为 bigquery。

您可以在代码库级别在 dataform.json 中设置 IProjectConfig 属性。

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

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

以下代码示例展示了在 dataform.json 中使用 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 中的 projects.locations.repositories.compilationResults#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，系统将会创建一个具体化视图。
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"。 如果仅提供一个值，则使用默认数据库架构，并将提供的值解释为“名称”。 ${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

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

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

操作()

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 子句。 如需了解详情，请参阅配置增量表。