流式处理表是一种 Delta 表,它额外支持流式处理或增量数据处理。 流表由管道支撑。 每次流表刷新时,其流都会处理源表的新数据。 Append flow(附加流程)向流表添加行,AUTO CDC 和 REPLACE flow 则用于更新或替换现有行。 可以手动或按计划刷新流式处理表。
若要详细了解如何执行或计划刷新,请参阅 运行管道更新。
Syntax
CREATE [OR REFRESH] [PRIVATE] STREAMING TABLE
table_name
[ table_specification ]
[ table_clauses ]
[ {flow_clause | AS query} ]
table_specification
( { column_identifier column_type [column_properties] } [, ...]
[ column_constraint ] [, ...]
[ , table_constraint ] [...] )
column_properties
{ NOT NULL | GENERATED ALWAYS AS ( expr ) | GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( [ START WITH start | INCREMENT BY step ] [ ...] ) ] | DEFAULT default_expression | COMMENT column_comment | column_constraint | MASK clause } [ ... ]
table_clauses
{ USING DELTA
PARTITIONED BY (col [, ...]) |
CLUSTER BY clause |
LOCATION path |
COMMENT view_comment |
TBLPROPERTIES clause |
WITH { ROW FILTER clause } } [ ... ]
} [ ... ]
flow_clause
FLOW { { INSERT [ONCE] BY NAME query } |
{ AUTO CDC auto_cdc_flow_spec } |
{ AUTO CDC [ONCE] auto_cdc_from_snapshot_spec } |
{ REPLACE WHERE predicate BY NAME query } |
{ REPLACE USING ( column_name [, ...] ) SEQUENCE BY sequence_column BY NAME query } }
auto_cdc_from_snapshot_spec
FROM SNAPSHOT ( snapshot_query )
[ WITH VERSION ( version_query ) ]
KEYS ( key [, ...] )
[ STORED AS { SCD TYPE 1 | SCD TYPE 2 } ]
[ TRACK HISTORY ON { col_list | * EXCEPT ( col_list ) } ]
参数
REFRESH
如果指定,则创建表或更新现有表及其内容。
私人
创建专用流式处理表。
- 它们不会添加到目录中,并且只能在定义管道中访问
- 它们可以与目录中的现有对象同名。 在管道中,如果专用流式处理表和目录中的对象具有相同的名称,则对名称的引用将解析为专用流式处理表。
- 专用流式处理表仅在管道的生存期内保留,而不仅仅是单个更新。
专用流式处理表以前是使用
TEMPORARY参数创建的。table_name
新创建的表的名称。 完全限定的表名称必须是独一无二的。
table_specification
此可选子句定义列的列表、列的类型、属性、说明和列约束。
-
列名必须具有唯一性,并映射到查询的输出列。
-
指定列的数据类型。 并非 Azure Databricks 支持的所有数据类型都受流式处理表支持。
column_comment
描述列的可选
STRING文本。 此选项必须与column_type一起指定。 如果未指定列类型,则会跳过列注释。始终生成为( expr )
指定此子句后,此列的值取决于
expr。表的
DEFAULT COLLATION须为UTF8_BINARY。expr可以由文字、表中的列标识符以及确定性内置的SQL函数或运算符组成,但不包括:此外,
expr不能包含任何子查询。生成 { 始终 |默认情况下 } 作为恒等元 [ [ 以 start 开始 ] [ 按步递增 ] )
适用于:
,Databricks SQL
,Databricks 运行时 10.4 LTS 及以上定义标识列。 如果你写入表但没有为标识列提供值,它将自动分配一个唯一且统计上递增的值(如果
step为负数则递减)。 只有 Delta 表支持此子句。 此子句只能用于具有 BIGINT 数据类型的列。自动分配的值以
start开头并以step为增量。 分配的值是唯一的,但不保证是连续的。 这两个参数都是可选的,默认值为 1。step不可能0。如果自动分配的值超出标识列类型的范围,则查询将失败。
使用
ALWAYS时,不能为标识列提供自己的值。不支持以下操作:
-
PARTITIONED BY单位列 -
UPDATE单位列
注释
在表上声明标识列会禁用并发事务。 仅在不需要对目标表进行并发写入的用例中使用标识列。
-
默认的 default_expression
适用于:
Databricks SQL
运行时 LTS 11.3 及以上为列定义一个
DEFAULT值,当未指定该列时,将在INSERT、UPDATE和MERGE ... INSERT上使用该值。如果未指定默认值,则
DEFAULT NULL应用于可为空的列。default_expression可以由文字组成,以及内置的SQL函数或运算符,但不包括:此外,
default_expression不能包含任何子查询。DEFAULT支持于CSV、JSON、PARQUET和ORC来源。-
将信息主键或信息外键约束添加到流式处理表中的列。
-
添加列掩码函数以对敏感数据进行匿名化处理。
请参阅 行筛选器和列掩码。
CONSTRAINT expectation_name 期待 (expectation_expr) [ 违反 { 失败 UPDATE |丢弃行 } ]
向流式处理表添加数据质量预期。 这些数据质量预期可以随着时间的推移进行跟踪,并通过流式处理表的事件日志进行访问。 在创建表和刷新表时,
FAIL UPDATE期望会导致处理失败。 如果未满足DROP ROW预期,则该预期会导致整行被删除。 请参阅通过管道预期管理数据质量。expectation_expr可以由文字、表中的列标识符以及确定性内置的SQL函数或运算符组成,但不包括:此外,
expr不能包含任何子查询。
-
table_constraint
指定架构时,可以定义主键和外键。 约束具备信息性,系统不会强制执行。 请参阅 SQL 语言参考中的 CONSTRAINT 子句。
注释
若要定义表约束,管道必须是启用了 Unity Catalog 的管道。
table_clauses
(可选)指定表的分区、注释和用户定义的属性。 每个子句只能指定一次。
使用 DELTA
指定数据格式。 唯一的选项是 DELTA。
此子句是可选的,默认为 DELTA。
划分为
包含一列或多列的可选列表,用于对表进行分区。 与
CLUSTER BY互斥。Liquid 聚类分析提供灵活的优化解决方案进行聚类分析。 请考虑使用
CLUSTER BY而不是PARTITIONED BY用于管道。CLUSTER BY
对表启用动态聚类,并定义要用作聚类键的列。 使用自动聚类功能与
CLUSTER BY AUTO,Databricks智能地选择聚类键以优化查询性能。 与PARTITIONED BY互斥。请参阅对表使用 liquid 聚类分析。
位置
表数据的可选存储位置。 如果未设置,系统将默认为管道存储位置。
仅当发布到 Hive 元存储时,此选项才可用。 在 Unity Catalog 中,存储位置会被自动管理。
评论
用于描述表的可选
STRING文本。TBLPROPERTIES(三元性)
表的表属性可选列表。
其中 ROW FILTER
向表中添加行筛选器函数。 将来对该表的查询会收到函数计算结果为 TRUE 的行的子集。 这对于精细的访问控制很有用,因为它允许函数检查调用用户的标识和组成员身份以决定是否筛选某些行。
请参阅
ROW FILTER条款。流畅
(可选)定义与表创建内联的 流 。 流是刷新表内容的有状态查询。 如果未
FLOW指定,则可以改用AS query流,也可以单独定义CREATE FLOW流。 可以指定以类型之一:INSERT 按名称
按列名将数据插入表中。
ONCE如果未提供该选项,则查询必须是流式处理查询。 要使用流式处理语义从源中读取,请使用STREAM关键字。 如果读取遇到对现有记录的更改或删除,则会引发错误。 从静态源或仅限追加的源读取是最安全的。注释
FLOW INSERT BY NAME等价于使用AS query。 以下两个语句具有相同的行为:CREATE OR REFRESH STREAMING TABLE raw_data AS SELECT * FROM STREAM read_files('/Volumes/catalog/schema/landing/my_path'); CREATE OR REFRESH STREAMING TABLE raw_data FLOW INSERT BY NAME SELECT * FROM STREAM read_files('/Volumes/catalog/schema/landing/my_path');曾经
(可选)将流定义为一次性流,例如回填。 提供时
ONCE,查询不是流式查询,默认情况运行一次。 如果使用完全刷新刷新表,流ONCE将再次运行以重新创建数据。ONCE适用于INSERT BY NAME和AUTO CDC ... FROM SNAPSHOT流。对于
AUTO CDC ... FROM SNAPSHOT的WITH VERSION流,每次更新按顺序处理版本,直到版本查询返回无行。ONCEONCE后续更新中发生的事情不同:-
没有
ONCE: ,流程在每次更新时都会运行。 每次更新都会处理任何新版本,然后返回,IDLE直到出现更新的版本或表完全刷新。 -
在 的情况下
ONCE, 流在首次成功快照提交后完成,后续增量更新时会被跳过。 如果第一个版本查询没有返回任何行,也没有快照提交,因此流程保持符合条件而非完成。 完全刷新后会重新运行。
-
没有
AUTO CDC重要
在 Databricks Runtime 17.3 及更高版本和
PREVIEW管道通道中可用。定义处理
AUTO CDC从源到表中的更改数据捕获(CDC)记录的流。 当源数据包含 CDC 语义时使用AUTO CDC。 请参阅 AUTO CDC API:使用管道简化变更数据捕获。AUTO CDC ... FROM SNAPSHOT定义了通过比较快照而非读取变更信息流的内联
AUTO CDC流程。 当源端未启用变更数据采集且仅提供完整快照时,请使用此表单。 源代码通过必FROM SNAPSHOT (snapshot_query)填子句和可选WITH VERSION (version_query)子句指定。 这个嵌入式流是匿名的,属于流表,没有INTO target子句。 它接受与独立形式相同的ONCE、FROM SNAPSHOT (...)、WITH VERSION (...)、KEYSSTORED ASTRACK HISTORY ON和 参数。 完整描述请参见创建流程(管道)。 另见“ 快照中的自动CDC工作原理”。来源必须使用括号中的
FROM SNAPSHOT (query)表格。 要迁移早期的单一标识符FROM SNAPSHOT source,将其改写为FROM SNAPSHOT (SELECT * FROM source)。用名称替换 WHERE谓词 查询
定义只
REPLACE WHERE重新计算和覆盖匹配predicate的行的流,使所有其他行保持不变。 用于REPLACE WHERE对联接和聚合、后期到达的数据、架构演变和回填进行增量批处理。BY NAME是必需的。 请参阅 使用 REPLACE WHERE 流的批处理。替换使用 ( column_name [, ...] )按sequence_column按名称排序查询
重要
此功能在 Beta 版中。 需要 Databricks 运行时 18.2 及以上版本。
定义一个
REPLACE USING流程,替换所有匹配指定键列的行,其他行保持不变。 当你的源是按列键的部分快照系列时使用REPLACE USING。SEQUENCE BY更新顺序使得密钥的最高序列获胜,即使更新顺序不一致。 源必须是流式处理源。BY NAME是必需的。 参见部分快照替换,即使用替换流。
-
此子句使用
query中的数据来填充表。 此查询必须是流式处理查询。 要使用流式处理语义从源中读取,请使用 STREAM 关键字。 如果读取遇到对现有记录的更改或删除,则会引发错误。 从静态源或仅限追加的源读取是最安全的。 若要引入具有更改提交的数据,可以添加skipChangeCommits读取选项来处理错误。同时指定
query和table_specification时,table_specification中指定的表架构必须包含query返回的所有列,否则会出现错误。 在table_specification中指定但未由query返回的任何列在查询时都返回null值。有关流数据的详细信息,请参阅 使用管道转换数据。
阅读选项
可以在查询中指定读取选项,以配置从源中读取数据的方式。 例如,可以指定
skipChangeCommits跳过源数据中的任何更改提交。 读取选项在查询子句中WITH指定为映射。 例如:SELECT * FROM STREAM source_table WITH (SKIPCHANGECOMMITS=TRUE, STARTINGVERSION=X)这是
=TRUE可选的,因此还可以指定如下所示的布尔选项:SELECT * FROM STREAM source_table WITH (SKIPCHANGECOMMITS)注释
Databricks Runtime 17.3 及更高版本仅支持读取选项。
Delta 支持以下读取选项,有关每个选项的详细信息,请参阅 Delta Lake 表流式读取和写入。
maxFilesPerTriggermaxBytesPerTriggerstartingVersionstartingTimestampreadChangeFeedwithEventTimeOrderskipChangeCommits
所需的权限
管道的运行方式用户必须具有以下权限:
-
SELECT对流式表引用的基表拥有特权。 -
USE CATALOG对父目录的特权和USE SCHEMA父架构的特权。 -
CREATE MATERIALIZED VIEW对流式表的模式拥有特权。
为了使用户能够更新在其中定义流式处理表的管道,他们需要:
-
USE CATALOG对父目录的特权和USE SCHEMA父架构的特权。 - 流式处理表的所有权或对流式处理表的
REFRESH特权。 - 流式处理表所有者必须对流式处理表引用的基表具有
SELECT特权。
要使用户能够查询生成的流式处理表,他们需要:
-
USE CATALOG对父目录的特权和USE SCHEMA父架构的特权。 -
SELECT对直播桌的特权。
局限性
- 只有表所有者才能刷新流式处理表以获取最新数据。
-
ALTER TABLE流式表中不允许使用命令。 表的定义和属性应该通过CREATE OR REFRESH或 ALTER STREAMING TABLE 语句进行更改。 - 不支持通过 DML 命令(如
INSERT INTO和MERGE)来发展表模式。 - 流式数据表不支持以下命令:
CREATE TABLE ... CLONE <streaming_table>COPY INTOANALYZE TABLERESTORETRUNCATEGENERATE MANIFEST[CREATE OR] REPLACE TABLE
- 不支持重命名表或更改所有者。
例子
-- Define a streaming table from a volume of files:
CREATE OR REFRESH STREAMING TABLE customers_bronze
AS SELECT * FROM STREAM read_files("/databricks-datasets/retail-org/customers/*", format => "csv")
-- Define a streaming table from a streaming source table:
CREATE OR REFRESH STREAMING TABLE customers_silver
AS SELECT * FROM STREAM(customers_bronze)
-- Use automatic liquid clustering to let Databricks choose the clustering columns:
CREATE OR REFRESH STREAMING TABLE customers_bronze_auto
CLUSTER BY AUTO
AS SELECT * FROM STREAM read_files("/databricks-datasets/retail-org/customers/*", format => "csv")
-- Define a table with a row filter and column mask:
CREATE OR REFRESH STREAMING TABLE customers_silver (
id int COMMENT 'This is the customer ID',
name string,
region string,
ssn string MASK catalog.schema.ssn_mask_fn COMMENT 'SSN masked for privacy'
)
WITH ROW FILTER catalog.schema.us_filter_fn ON (region)
AS SELECT * FROM STREAM(customers_bronze)
-- Define a streaming table with an identity column:
CREATE OR REFRESH STREAMING TABLE customers_with_id (
customer_id BIGINT GENERATED ALWAYS AS IDENTITY,
name string,
region string
)
AS SELECT name, region FROM STREAM(customers_bronze)
-- Define a streaming table that you can add flows into:
CREATE OR REFRESH STREAMING TABLE orders;
-- Define a streaming table with an inline append flow:
CREATE OR REFRESH STREAMING TABLE raw_data
FLOW INSERT BY NAME SELECT * FROM STREAM read_files('/Volumes/catalog/schema/landing/my_path');
-- Define a streaming table with an inline AUTO CDC flow:
CREATE OR REFRESH STREAMING TABLE target
FLOW AUTO CDC
FROM stream(cdc_data.users)
KEYS (userId)
SEQUENCE BY sequenceNum
STORED AS SCD TYPE 1;
-- Define a streaming table with an inline REPLACE USING flow that keeps the latest
-- row for each payment_id:
CREATE OR REFRESH STREAMING TABLE payments_current
FLOW REPLACE USING (payment_id) SEQUENCE BY payment_date BY NAME
SELECT payment_id, booking_id, status, payment_date
FROM STREAM(samples.wanderbricks.payments);
-- Define a streaming table with an inline AUTO CDC FROM SNAPSHOT flow that processes
-- each new snapshot version on every update, using WITH VERSION to pick the next one:
CREATE STREAMING TABLE users
FLOW AUTO CDC
FROM SNAPSHOT (
SELECT * FROM read_files('/Volumes/catalog/schema/landing/users/', format => 'json')
WHERE _metadata.file_path = (SELECT version.path FROM current_snapshot_version())
)
WITH VERSION (
SELECT struct(modification_time, path) AS version
FROM list_files('/Volumes/catalog/schema/landing/users/')
WHERE (
NOT EXISTS (SELECT 1 FROM last_snapshot_version())
OR struct(modification_time, path) > (SELECT version FROM last_snapshot_version())
)
ORDER BY modification_time, path
LIMIT 1
)
KEYS (user_id)
STORED AS SCD TYPE 1;
-- Define a streaming table with an inline one-shot AUTO CDC FROM SNAPSHOT backfill:
CREATE STREAMING TABLE customers
FLOW AUTO CDC ONCE
FROM SNAPSHOT (SELECT * FROM catalog.schema.customers_snapshot)
KEYS (customer_id)
STORED AS SCD TYPE 1;