定义
$iceberg 阶段在连接注册表中指定到 Amazon Web Services S3 存储桶或 Azure Blob 存储容器的连接,您可以在其中将数据写入 Apache Iceberg 表。
展示位置
$iceberg 必须是其所在的任何管道的最后阶段。每个管道只能使用一个 $iceberg 阶段。
语法
$iceberg 管道阶段采用以下原型形式:
{ "$iceberg": { "connectionName": "<registered-connection>", "bucket": "<target-bucket>", "container": "<target-container>", "databaseName": "<database>", "tableName": "<string>" | <expression>, "path": "<key-prefix>", "region": "<target-region>", "mode": "cdc" | "insert", "idFieldName": "<field-name>", "partitionedBy": { "<column-name>": "<partition-transform>", . . . }, "catalog": { "type": "hadoop" | "glue" | "unity" | "horizon", "connectionName": "<data-catalog-connection>", "warehouse": "<warehouse>" }, "schemaInference": { "mode": "json" | "nested" } }}$iceberg 阶段采用包含以下字段的文档:
字段 | 类型 | 必要性 | 说明 |
|---|---|---|---|
| 字符串 | 必需 | 用于读取和写入的 Amazon Web Services S3 或 Azure Blob 存储连接的名称。这必须与连接注册表中的连接名称相匹配。 |
| 字符串 | 可选的 | S3 连接所必需。 包含目标 Apache Iceberg 数据库的 S 存储桶的名称。3如果设置了 |
| 字符串 | 可选的 | Azure Blob 存储连接所必需。 包含目标 Apache Iceberg 数据库的 Azure Blob 存储容器的名称。如果设置了 |
| 字符串 | 必需 | 包含目标表的 Apache Iceberg 数据库的名称。 |
| 字符串 |表达式 | 必需 | 目标 Apache Iceberg 表的名称。必须是 string 或计算结果为 string 的表达式。使用表达式实现每个文档的动态路由。 |
| 字符串 | 必需 | 路径前缀密钥,指向 Apache Iceberg 数据库。 |
| 字符串 | 可选的 | AWS存储桶所在的区域。未在 AWS 上运行的流处理器才需要。 不适用于 Azure Blob 存储连接。 |
| 字符串 | Optional | 确定每个输入文档要执行的操作的策略。
默认为 |
| 字符串 | Optional | 在 默认值为 |
| 文档 | Optional | 分区规格。如果您未设置此字段, 必须是一个包含一到三个键值对的文档。每个键必须是执行分区转换的列的名称,每个值必须是所使用的分区转换。第一个分区转换必须针对 要对 给定字段的分区转换值必须为以下值之一:
有关 Apache Iceberg 分区转换的更多信息,请参阅 Apache Iceberg 文档。 |
| 文档 | Optional | 定义要使用的 Iceberg 目录 的文档。必须是包含
|
| 文档 | Optional | 配置
默认为 |
catalog 字段
catalog 文档包含以下字段:
字段 | 类型 | 必要性 | 说明 |
|---|---|---|---|
| 字符串 | Optional | 要使用的 Apache Iceberg 目录类型。必须是以下值之一:
|
| 字符串 | 可选的 | 要使用的数据目录连接的名称。此名称必须与连接注册表中数据目录连接的名称相匹配。 如果 如果 |
| 字符串 | 可选的 | 目录中包含目标模式的位置。 如果 如果
|
对于 "unity" 和 "horizon" 目录,$iceberg 从 warehouse、databaseName 和 tableName 字段解析目标表:
Catalog Type | warehouse | databaseName | tableName |
|---|---|---|---|
| Databricks catalog | Databricks 模式 | 表名 |
| Snowflake 数据库 | 雪花模式 | 表名 |
注意
如果 Atlas Stream Processing 找不到数据仓库或模式,请确认您在正确的字段中指定了 warehouse 和 databaseName 值。Snowflake 数据库名称通常为大写。
行为
如果使用 $iceberg 阶段,则该阶段必须是流处理器中的最后阶段。
Atlas Stream Processing 仅支持 SP10、SP30 和 SP50 流处理器的 $iceberg 阶段。您的处理器层级决定动态路由支持的最大表数:
层级 | 最大表 |
|---|---|
SP 10 | 5 |
SP 30 | 10 |
SP 50 | 50 |
重要
如果具有动态路由的流处理器超过了其层级支持的最大表数,则处理器将进入 FAILED 状态。要了解故障原因和恢复,请参阅 错误处理和重试策略。
$iceberg 阶段根据流处理器的输出数据模式推断生成的 Apache Iceberg 表的模式。当 Atlas Stream Processing 观察到流中的新字段(包括 struct 列中的字段)时,表模式会相应地演变。
如果您指定的表尚不存在,则 Apache Iceberg 会在收到第一条针对该表的消息时创建该表。
Atlas Stream Processing 为输出到 Apache Iceberg 表提供至少一次处理。
您可以使用 动态表达式 作为 tableName 字段的值。通过使用动态表达式捕获文档特定值,您可以根据这些值将输入文档路由到不同的表中。表达式的结果必须为字符串。有关示例,请参阅 动态路由。要了解详情,请参阅 表达式操作符。
如果您使用动态表达式指定主题,但 Atlas Stream Processing 无法评估给定消息的表达式,则 Atlas Stream Processing 会将该消息发送到 死信队列(DLQ)(如果已配置)并处理后续消息。如果未配置 死信队列(DLQ),则 Atlas Stream Processing 会完全跳过该消息并处理后续消息。
类型转换
Atlas Stream Processing 在向 $iceberg 阶段中的表写入时,会将类型从 BSON 转换为 Iceberg 原始类型。
BSON | 详情 | |
|---|---|---|
|
| |
|
| |
|
| |
|
| |
|
| |
|
| 十六进制编码 |
|
| 字符化 UUID |
|
| 不适用于 UUID |
|
| 以微秒为单位的 UTC 时间 |
|
| UTC 时间,测量到微秒 |
|
| 默认序列化为 Basic JSON 字符串。在 |
|
| 默认序列化为 Basic JSON 字符串。在 |
不支持其他 BSON types。Atlas Stream Processing 会将包含不支持的 BSON types 的文档发送到 DLQ。
对象和数组字段
schemaInference.mode 字段决定了 Atlas Stream Processing 如何将 object 和 array 字段写入 Apache Iceberg 表:
在
json模式下,Atlas Stream Processing 将object和array字段序列化为 Basic JSON 字符串,并将它们写入string列。json是默认模式。在
nested模式下,Atlas Stream Processing 从object和array字段推断 Iceberg 嵌套类型:每个
object字段都会成为一个struct列。Atlas Stream Processing 从对象中的相应字段推断结构中每个字段的类型。这适用于嵌套的每一层。每个
array字段成为list列。Atlas Stream Processing 从数组的非空元素中推断出列表元素类型。原始元素必须都是相同类型。如果元素是对象,则元素类型是struct,其中包含所有对象的字段。
该模式仅适用于目标表中没有匹配列的字段。如果该列已存在,Atlas Stream Processing 将忽略该模式并根据列类型写入字段:
如果该列是
string,Atlas Stream Processing 会将该字段序列化为 Basic JSON 字符串。如果该列是
struct或list,Atlas Stream Processing 会将该字段写入为该嵌套类型。
如果输入包含新的 object 或 array 字段,Atlas Stream Processing 将使用该模式来推断新列的类型。
示例
以下示例说明了 $iceberg 阶段的各种应用。
存档变更流
以下示例展示了如何以只能添加的方式将 Atlas 数据库的初始内容和变更流写入 Apache Iceberg 表,从而创建该数据库操作历史的持久性存档。此聚合有两个阶段:
$source阶段与 Atlas 数据库建立连接,具体针对db数据库中的orders集合。它可以在处理器激活时启用初始同步以捕获数据库中的文档,并确保每个变更流事件都能捕获完整的文档。$iceberg阶段建立与 AWS S3 存储桶的连接,将数据写入名为myTable的表,并存储在iceberg-warehouse/路径中。通过仅指定insert操作,它可确保只能添加的日志式写入流。
{ "$source": { "connectionName": "atlas1", "db": "db", "coll": "orders", "initialSync": { "enable": true }, "config": { "fullDocument": "required" } }, "$iceberg": { "connectionName": "myS3Connection", "bucket": "myData", "path": "iceberg-warehouse/", "tableName": "myTable", "mode": "insert" }}镜像集合
以下示例演示如何将 Atlas 集合完整镜像到 Apache Iceberg 表。
在定义聚合之前,设置以下变量:
const isDeleteExpr = {$eq: [{$meta: "stream.source.operationType"}, "delete"]};下面的聚合会添加、更新和删除 Apache Iceberg 表目录,以与 Atlas 源集合的更改保持同步。它有四个阶段:
$source阶段与 Atlas 数据库建立连接,具体针对db数据库中的orders集合。它可以在处理器激活时启用初始同步以捕获数据库中的文档,并确保每个变更流事件都能捕获完整的文档。$match阶段对operationType进行**过滤器**,以便仅处理具有有效操作类型声明的文档。$replaceRoot阶段会根据操作类型更改文档根。对于删除操作,它会将文档根更改为文档的密钥。这会导致生成一条记录,表明文档已被删除,但会将其内容从进一步处理中排除。
对于所有其他操作,它会将文档根更改为
fullDocument,传递文档内容以供进一步处理,同时排除变更流元数据。
The
$icebergstage establishes a connection to the AWS S3 bucket, writing to an Apache Iceberg table namedmyTablein theiceberg-warehouse/path. Incdcmode, this stage determines the operation to perform against the Apache Iceberg table by reading from thestream.source.operationTypemetadata field of each document.
{ "$source": { "connectionName": "atlas1", "db": "db", "coll": "orders", "initialSync": { "enable": true }, "config": { "fullDocument": "required" } }, "$match": { "operationType": { "$in": ["insert", "update", "delete", "replace"] } }, "$replaceRoot": { "newRoot": { "$cond": { "if": isDeleteExpr, "then": "$documentKey", "else": "$fullDocument" } } } "$iceberg": { "connectionName": "myS3Connection", "bucket": "myData", "path": "iceberg-warehouse/", "tableName": "myTable", "mode": "cdc" }}从多集合源到多表 Apache Iceberg 目标
在以下示例中,Atlas Stream Processing 使用动态表达式将文档动态路由至各种输出目标。
$source阶段与 Atlas 数据库建立连接,具体针对位于db数据库中的集合a、b和c。它可以在处理器激活时启用初始同步以捕获数据库中的文档,并确保每个变更流事件都能捕获完整的文档。$match阶段会过滤operationType为"insert"、"update"、"delete"或"replace"之一的文档。$replaceRoot阶段会根据操作类型更改文档根。对于删除操作,它会将文档根更改为文档的密钥。这会导致生成一条记录,表明文档已被删除,但会将其内容从进一步处理中排除。
对于所有其他操作,它会将文档根更改为
fullDocument,传递文档内容以供进一步处理,同时排除变更流元数据。
The
$icebergstage establishes a connection to the AWS S3 bucket namedmyData, writing to an Apache Iceberg table in theiceberg-warehouse/path. It determines the name of the table according to the name of the sourcecollectionas retrieved from document metadata. It also determines the operation to perform according to document metadata.
{ "$source": { "connectionName": "atlas1", "db": "db", "coll": ["a", "b", "c"], "initialSync": { "enable": true }, "config": { "fullDocument": "required" } }},{ "$match": { "operationType": { "$in": ["insert", "update", "delete", "replace"] } }},{ "$replaceRoot": { "newRoot": { "$cond": { "if": { "$eq": [{ "$meta": "stream.source.operationType" }, "delete"] }, "then": "$documentKey", "else": "$fullDocument" } } }},{ "$iceberg": { "connectionName": "myS3Connection", "databaseName": "iceberg-db", "bucket": "myData", "path": "iceberg-warehouse/", "tableName": { "$meta": "stream.source.ns.coll" }, "mode": "cdc" }}写入数据目录表
以下示例演示了如何将 Atlas 集合的初始内容和变更流写入由数据目录托管的 Apache Iceberg 表中。选择您的目录类型对应的标签页。该示例将 mode 设置为 insert,以便将每个文档作为新行追加到表中。此聚合有两个阶段:
$source阶段与 Atlas 数据库建立连接,具体针对db数据库中的orders集合。它可以在处理器激活时启用初始同步以捕获数据库中的文档,并确保每个变更流事件都能捕获完整的文档。$iceberg阶段通过myS3Connection连接写入名为myData的 Amazon Web Services S3 存储桶。它使用数据目录连接写入目录的orders表。
$iceberg 阶段使用 myUnityCatalog 数据目录连接写入 Databricks main 目录中 sales 模式下的 orders 表。unity 目录类型不支持 cdc 模式,因此必须将 mode 设置为 insert。
[ { "$source": { "connectionName": "atlas1", "db": "db", "coll": "orders", "initialSync": { "enable": true }, "config": { "fullDocument": "required" } } }, { "$iceberg": { "connectionName": "myS3Connection", "bucket": "myData", "path": "iceberg-warehouse/", "databaseName": "sales", "tableName": "orders", "mode": "insert", "catalog": { "type": "unity", "connectionName": "myUnityCatalog", "warehouse": "main" } } }]$iceberg 阶段使用 myHorizonCatalog 数据目录连接将数据写入 Snowflake ICEBERG_DB 数据库中 SALES 模式下的 orders 表。
[ { "$source": { "connectionName": "atlas1", "db": "db", "coll": "orders", "initialSync": { "enable": true }, "config": { "fullDocument": "required" } } }, { "$iceberg": { "connectionName": "myS3Connection", "bucket": "myData", "path": "iceberg-warehouse/", "databaseName": "SALES", "tableName": "orders", "mode": "insert", "catalog": { "type": "horizon", "connectionName": "myHorizonCatalog", "warehouse": "ICEBERG_DB" } } }]