本文档介绍了 Dataform 核心。您可以在 SQLX 中使用 Dataform 核心 和 JavaScript 文件
assert()
assert
|
(name: string, query?: AContextable
|
向已编译的图添加 Dataform 断言。 仅在 |
示例:
// 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。
此函数可以使用
也可使用各参数的具体参数来调用此函数,
${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/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
|
声明此操作是否封闭。操作是封闭的
但前提是其所有依赖项均已明确声明。
此操作是否依赖于未声明的来源的数据
作为依赖项,然后将 |
|
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
属性替换为
单个表。
您可以在 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 政策标记的完整标识符
包括项目名称、位置和分类
例如: |
|
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
参数。
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
|
应在其中创建此操作输出的架构。 |
operate()
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
子句。
如需了解详情,请参阅
配置增量表。