对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

$iceberg 聚合阶段

$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 阶段采用包含以下字段的文档:

字段
类型
必要性
说明

connectionName

字符串

必需

用于读取和写入的 Amazon Web Services S3 或 Azure Blob 存储连接的名称。这必须与连接注册表中的连接名称相匹配。

bucket

字符串

可选的

S3 连接所必需。

包含目标 Apache Iceberg 数据库的 S 存储桶的名称。3如果设置了 bucket,则必须设置 region,但不要设置 container。

container

字符串

可选的

Azure Blob 存储连接所必需。

包含目标 Apache Iceberg 数据库的 Azure Blob 存储容器的名称。如果设置了 container,请勿设置 bucket 或 region。

databaseName

字符串

必需

包含目标表的 Apache Iceberg 数据库的名称。

tableName

字符串 |表达式

必需

目标 Apache Iceberg 表的名称。必须是 string 或计算结果为 string 的表达式。使用表达式实现每个文档的动态路由。

path

字符串

必需

路径前缀密钥,指向 Apache Iceberg 数据库。

region

字符串

可选的

AWS存储桶所在的区域。未在 AWS 上运行的流处理器才需要。

不适用于 Azure Blob 存储连接。

mode

字符串

Optional

确定每个输入文档要执行的操作的策略。

  • "cdc" 导致 Atlas Stream Processing 通过读取 stream.source.operationType 元数据字段来确定操作类型。

  • "insert" 导致 Atlas Stream Processing 将每个文档作为新行添加到目标表中,忽略 stream.source.operationType 元数据字段中的操作类型声明。

默认为 cdc。"unity" 目录类型不支持 cdc 模式。如果 catalog.type 为 "unity",请将 mode 设置为 "insert"。

idFieldName

字符串

Optional

在 cdc 模式下用作行键的字段和列名称。

默认值为 "_id"。

partitionedBy

文档

Optional

分区规格。如果您未设置此字段,$iceberg 将为 idFieldName 列设置默认分区转换。

必须是一个包含一到三个键值对的文档。每个键必须是执行分区转换的列的名称,每个值必须是所使用的分区转换。第一个分区转换必须针对 idFieldName。

要对 struct 列中嵌套的字段进行分区,请指定该字段的点限定路径,示例 outer.inner.key_field。路径在任何级别都不能包含 list 列。

给定字段的分区转换值必须为以下值之一:

  • "identity"

  • "year"

  • "month"

  • "day"

  • "hour"

  • { truncate: int }

  • { bucket: int }

有关 Apache Iceberg 分区转换的更多信息,请参阅 Apache Iceberg 文档。

catalog

文档

Optional

定义要使用的 Iceberg 目录 的文档。必须是包含 type 字段且值为 "hadoop"、"glue"、"unity" 或 "horizon" 的文档。"unity" 和 "horizon" 目录类型还需要 connectionName 和 warehouse 字段。要了解详情,请参阅catalog 字段。

"unity"、"horizon" 和 "hadoop" 目录类型同时支持 S3 和 Azure Blob 存储连接。

"glue" 目录类型仅支持 S3 连接。

schemaInference

文档

Optional

配置 $iceberg 如何推断表模式的文档。必须是包含 mode 字段的文档,具有以下值之一:

  • "json" 使 Atlas Stream Processing 将 object 和 array 字段写入为 JSON string 列。

  • "nested" 导致 Atlas Stream Processing 将 object 字段写入为 struct 列,并将 array 字段写入为 list 列。

默认为 "json"。要了解更多信息,请参阅 类型转换。

catalog 文档包含以下字段:

字段
类型
必要性
说明

type

字符串

Optional

要使用的 Apache Iceberg 目录类型。必须是以下值之一:

  • "hadoop" 适用于 Amazon Web Services 和 Azure 中的数据目录

  • "glue" 用于 Amazon Web Services 中的数据目录

  • "unity" 适用于 Amazon Web Services 和 Azure 中的 Databricks Unity Catalog

  • "horizon" 适用于 Amazon Web Services 和 Azure 中的 Snowflake Horizon 目录

connectionName

字符串

可选的

要使用的数据目录连接的名称。此名称必须与连接注册表中数据目录连接的名称相匹配。

如果 type 为 "unity" 或 "horizon",则为必填项。

如果 type 为 "hadoop" 或 "glue",Atlas Stream Processing 将拒绝此字段。

warehouse

字符串

可选的

目录中包含目标模式的位置。

如果 type 为 "unity" 或 "horizon",则为必填项。

如果 type 为 "hadoop" 或 "glue",Atlas Stream Processing 将拒绝此字段。

  • 对于 "unity",Databricks 目录的名称。

  • 对于 "horizon",Snowflake 数据库的名称。

对于 "unity" 和 "horizon" 目录,$iceberg 从 warehouse、databaseName 和 tableName 字段解析目标表:

Catalog Type
warehouse
databaseName
tableName

"unity"

Databricks catalog

Databricks 模式

表名

"horizon"

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
详情

string

string

int

int

long

long

double

double

bool

boolean

ObjectId

string

十六进制编码

UUID

string

字符化 UUID

BinData

binary

不适用于 UUID

date

timestamptz

以微秒为单位的 UTC 时间

timestamp

timestamptz

UTC 时间,测量到微秒

object

string or struct

默认序列化为 Basic JSON 字符串。在 nested 模式下,变为 struct 列。要了解更多信息,请参阅 对象和数组字段。

array

string or list

默认序列化为 Basic JSON 字符串。在 nested 模式下,变为 list 列。要了解更多信息,请参阅 对象和数组字段。

不支持其他 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 表,从而创建该数据库操作历史的持久性存档。此聚合有两个阶段:

  1. $source 阶段与 Atlas 数据库建立连接,具体针对 db 数据库中的 orders 集合。它可以在处理器激活时启用初始同步以捕获数据库中的文档,并确保每个变更流事件都能捕获完整的文档。

  2. $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 源集合的更改保持同步。它有四个阶段:

  1. $source 阶段与 Atlas 数据库建立连接,具体针对 db 数据库中的 orders 集合。它可以在处理器激活时启用初始同步以捕获数据库中的文档,并确保每个变更流事件都能捕获完整的文档。

  2. $match 阶段对 operationType 进行**过滤器**,以便仅处理具有有效操作类型声明的文档。

  3. $replaceRoot 阶段会根据操作类型更改文档根。

    • 对于删除操作,它会将文档根更改为文档的密钥。这会导致生成一条记录,表明文档已被删除,但会将其内容从进一步处理中排除。

    • 对于所有其他操作,它会将文档根更改为 fullDocument,传递文档内容以供进一步处理,同时排除变更流元数据。

  4. The $iceberg stage establishes a connection to the AWS S3 bucket, writing to an Apache Iceberg table named myTable in the iceberg-warehouse/ path. In cdc mode, this stage determines the operation to perform against the Apache Iceberg table by reading from the stream.source.operationType metadata 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" }}

在以下示例中,Atlas Stream Processing 使用动态表达式将文档动态路由至各种输出目标。

  1. $source 阶段与 Atlas 数据库建立连接,具体针对位于 db 数据库中的集合 a、b 和 c。它可以在处理器激活时启用初始同步以捕获数据库中的文档,并确保每个变更流事件都能捕获完整的文档。

  2. $match 阶段会过滤 operationType 为 "insert"、"update"、"delete" 或 "replace" 之一的文档。

  3. $replaceRoot 阶段会根据操作类型更改文档根。

    • 对于删除操作,它会将文档根更改为文档的密钥。这会导致生成一条记录,表明文档已被删除,但会将其内容从进一步处理中排除。

    • 对于所有其他操作,它会将文档根更改为 fullDocument,传递文档内容以供进一步处理,同时排除变更流元数据。

  4. The $iceberg stage establishes a connection to the AWS S3 bucket named myData, writing to an Apache Iceberg table in the iceberg-warehouse/ path. It determines the name of the table according to the name of the source collection as 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,以便将每个文档作为新行追加到表中。此聚合有两个阶段:

  1. $source 阶段与 Atlas 数据库建立连接,具体针对 db 数据库中的 orders 集合。它可以在处理器激活时启用初始同步以捕获数据库中的文档,并确保每个变更流事件都能捕获完整的文档。

  2. $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" } } }]