Dataform 核心参考文档

本文档介绍了 Dataform 核心。您可以在 SQLX 中使用 Dataform 核心 和 JavaScript 文件

assert()

assert (name: string, query?: AContextable)

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

仅在 /definitions 目录中可用。

示例:

// definitions/file.js

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

CommonContext

在评估可上下文的 SQL 代码时,可以使用上下文方法, 例如在 SQLX 文件中 Dataform 核心的 Contextable 参数。

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"。 如果只提供一个值,则使用默认数据库和架构。 并将提供的值解释为“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()

declare (dataset: dataform.ITarget)

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

仅在 /definitions 目录中可用。

示例:

// definitions/file.js

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

IActionConfig

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

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

您可以在工作流程设置中设置 IProjectConfig 属性 在代码库级别指定

您可以defaultSchemadefaultDatabase 属性替换为 单个表

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

以下代码示例显示了 myVariableName 自定义编译变量 在工作流程设置中设置, projectConfig.vars 个属性, 在 SQLX 文件的 SELECT 语句中访问:

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

详细了解如何覆盖项目配置设置 有关各个编译结果的信息,请参阅 projects.locations.repositories.compilationResults#CodeCompilationConfig REST 资源位于 Dataform API

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操作的配置选项,包括 tableviewincremental 表类型。

扩展 IActionConfigIDependenciesConfig, IDocumentableConfig, INamedConfigITargetableConfig.

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 参数。

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

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

database string

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

schema string

应在其中创建此操作输出的架构。

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