本文档介绍了 Dataform Core 的方法、属性和配置选项。您可以在 SQLX 和 JavaScript 文件中使用 Dataform 核心。
assert()
assert
|
(name: string, query?: AContextable
|
向已编译的图添加 Dataform 断言。 仅在 |
示例:
// 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。
此函数可以使用
也可以使用 ${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/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
|
声明此操作是否封闭。如果某项操作的所有依赖项均已明确声明,则该操作是封闭的。
如果此操作依赖于某个来源的数据,但未声明为依赖项,请将 |
|
schema
|
string
|
要在其中创建此断言对应视图的架构(BigQuery 数据集)。 | |
tags
|
string[]
|
应用于此操作的用户定义代码列表。 |
IBigQueryOptions
特定于 BigQuery 的仓库选项。
additionalOptions
|
|
表、视图和具体化视图选项的键值对。
某些选项(例如
字符串值必须封装在英文双引号中,例如:
如果选项名称包含特殊字符,请将名称用英文引号引起来,例如: |
|
clusterBy
|
string[]
|
对分区进行聚类时所依据的键。 | |
labels
|
|
BigQuery 标签的键值对。
如果标签名称包含特殊字符(例如连字符),请将其名称用英文引号引起来,例如 |
|
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[]
|
此操作的一个或多个显式依赖项。依赖操作将在依赖操作之前运行。
通常情况下,此属性会保持未设置状态,因为大多数依赖项都声明为使用 |
|
hermetic
|
boolean
|
声明此操作是否封闭。如果一项操作的所有依赖项均已明确声明,则该操作是封闭的。如果此操作依赖于某个来源的数据,而该来源尚未声明为依赖项,则应将 |
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 函数引用的表。
如果设置为 create or replace table ${self()} as select ...
|
|
hermetic
|
boolean
|
声明此操作是否封闭。如果某项操作的所有依赖项均已明确声明,则该操作是封闭的。
如果此操作依赖于某个来源的数据,但未声明为依赖项,请将 |
|
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
属性。
您可以替换单个表的 defaultSchema
和 defaultDatabase
属性。
您可以在 SQLX 或 JavaScript 文件中访问 SQL SELECT
语句中的所有 IProjectConfig
属性。
以下代码示例显示了在 SQLX 文件的 SELECT
语句中访问且在工作流设置中通过 projectConfig.vars
属性设置的 myVariableName
自定义编译变量:
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 政策标记的完整标识符包括项目名称、位置和分类,
例如: |
|
columns
|
IColumnsDescriptor
|
结构体、对象或记录中的列的说明。 | |
description
|
string
|
结构体、对象或记录的说明。 |
ITableAssertions
用于创建将断言作为表定义一部分的选项。
nonNull
|
string | string[]
|
列(绝不能为 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
|
声明此操作是否封闭。如果某项操作的所有依赖项均已明确声明,则该操作是封闭的。
如果此操作依赖于某个来源的数据,但未声明为依赖项,请将 |
|
materialized
|
boolean
|
仅在表类型为 view 时有效。如果设置为 true,系统会创建一个具体化视图。 |
|
protected
|
boolean
|
只能用于 incremental 表类型。
如果设为 true,运行此操作会忽略 |
|
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。
此函数可以使用 ${ref({ name: "name", schema: "schema", database: "database" })}
也可以使用
如果只提供了两个值,系统会使用默认数据库,并将值解释为 如果只提供一个值,则使用默认数据库架构,并将提供的值解释为“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 。
|
ITarget
对 BigQuery 中的表的引用。
database
|
string
|
name
|
string
|
schema
|
string
|
ITargetableConfig
定义 SQL 工作流操作的目标数据库和架构。
database
|
string
|
应在其中创建此操作输出的数据库。必须设置为 BigQuery。 |
|
schema
|
string
|
应在其中创建此操作输出的架构。 |
actions()
operate
|
(name: string, queries?: Contextable
|
定义 SQL 操作。 仅在 |
示例:
// definitions/file.js
operate("an-operation", ["SELECT 1", "SELECT 2"])
publish()
publish
|
(name: string, queryOrConfig?: Contextable
|
创建表或视图。 仅在 |
示例:
// 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
子句。如需了解详情,请参阅配置增量表。