您正在查看Debezium未发布版本的文档。开云体育官方注册网址
如果您想查看本页最新的稳定版本，请前往在这里．

MongoDB新文档状态提取

Debe开云体育官方注册网址zium MongoDB连接器发出数据更改消息，以表示MongoDB集合中发生的每个操作。这些事件消息的复杂结构忠实地表示了原始数据库事件的详细信息。开云体育电动老虎机但是，一些下游使用者可能无法以原始格式处理消息。例如，为了表示数据集合中的嵌套文档，连接器以包含嵌套字段的格式发出事件消息。为了支持接收器连接器或其他不能处理原始消息的分层格式的使用者，您可以使用Debezium MongoDB事件扁平化(ExtractNewDocumentState)单个消息转换(SMT)。开云体育官方注册网址SMT简化了原始消息的结构，并且可以以其他方式修改消息，从而使数据更容易处理。

事件扁平化变换是Kafka连接SMT．

本章中的信息仅描述Debezium MongoDB连接器的事件扁平化单消息转换(SMT)。开云体育官方注册网址有关用于关系数据库的等效SMT的信息，请参见开云体育电动老虎机用于新记录状态提取SMT的文档．

改变事件结构

Debe开云体育官方注册网址zium MongoDB连接器生成具有复杂结构的变更事件。每个事件消息包括以下部分:

元数据来源

包括但不限于以下字段:

  • 更改集合中数据的操作类型(创建/插入、更新或删除)。

  • 发生更改的数据库和集合的开云体育电动老虎机名称。

  • 标识更改时间的时间戳。

  • 可选的事务信息。

文档数据
之前数据

此字段出现在运行MongoDB 6.0及更高版本的环境中capture.mode为Debeziu开云体育官方注册网址m连接器设置为以下值之一:

后数据

表示当前操作之后出现在文档中的值的JSON字符串。存在后事件消息中的字段取决于事件类型和连接器配置。一个创建事件插入操作总是包含后场，不管之capture.mode设置。为更新事件,后字段仅在capture.mode设置为以下值之一:

  • change_streams_update_full

  • change_streams_update_full_with_pre_image．

    的后更改事件消息中的值不一定表示紧跟事件之后的文档状态。该值不是动态计算的;相反，在连接器捕获变更事件之后，它会查询集合以检索文档的当前值。

    例如，想象一种情况，有多个操作，一个，b,c快速连续修改文档。当连接器处理时，更改一个，它会查询集合以获取完整的文档。与此同时，变化b而且c发生。当连接器接收到对其完整文档查询的响应以进行更改时一个时，它可能会接收到基于的后续更改的文档版本b或c．有关的详细信息，请参阅capture.mode财产。

的基本结构创建连接器在MongoDB之后发出的change事件插入操作:

{“人事处”:“c”,“后”:“{\“field1 \”,\“newvalue1 \”,\“field2 \”,\“newvalue1 \“}”,“源”:{…}}

的复杂格式后上例中的字段提供有关源数据库中发生的更改的详细信息。开云体育电动老虎机但是，一些使用者不能处理包含嵌套值的消息。要将原始消息的复杂嵌套字段转换为更简单、更普遍兼容的结构，请使用MongoDB的事件扁平化SMT。SMT扁平化消息中嵌套字段的结构，如下例所示:

{"field1": "newvalue1"， "field2": "newvalue2"}

有关Debezium MongoDB连接器生成的消息的默认结构的更多信息，请参见开云体育官方注册网址连接器的文档．

行为

事件扁平化SMT为MongoDB提取后字段创建或更新由Debezium MongoDB连接器发出的change事件消息。开云体育官方注册网址类的内容后，SMT会生成一个简化版本后字段。

根据您的用例，您可以将ExtractNewDocumentState SMT应用于Debezium MongoDB连接器，或者应用于消耗Debezium连接器产生开云体育官方注册网址的消息的接收器连接器。如果将SMT应用到Debezium MongoDB连接器开云体育官方注册网址，SMT将修改连接器发出的消息，然后再将它们发送到Apache Kafka。为了确保Kafka以原始格式保留完整的Debezium更改事件消息，将SMT应用到接开云体育官方注册网址收器连接器。

当您使用事件扁平化SMT处理从MongoDB连接器发出的消息时，SMT将原始消息中的记录结构转换为可由典型接收器连接器使用的正确类型的Kafka Connect记录。例如，SMT转换表示的JSON字符串后将原始消息中的信息转换为任何使用者都可以处理的模式结构。

可选地，您可以为MongoDB配置事件扁平化SMT，以便在处理期间以其他方式修改消息。有关更多信息，请参见配置．

配置

为使用Debezium MongoDB连接器发出的消息的接收器连接器配置MongoDB的事件平坦化(ExtractNewDocumentState) SMT。开云体育官方注册网址

基本配置

要获得SMT的默认行为，可以将SMT添加到sink connector的配置中，不需要指定任何选项，示例如下:

变换=打开……transforms.unwrap.type = i开云体育官方注册网址o.debezium.connector.mongodb.transforms.ExtractNewDocumentState

与任何Kafka Connect连接器配置一样，您可以设置变换=到多个逗号分隔的SMT别名。Kafka Connect应用你指定的转换，按照它们列出的顺序。

您可以为使用MongoDB事件扁平化SMT的连接器设置多个选项。属性的配置drop.tombstones，delete.handling.mode,add.headers连接器的选项:

变换=打开……transforms.unwrap.type = i开云体育官方注册网址o.debezium.connector.mongodb.transforms.ExtractNewDocumentState transforms.unwrap.drop。Tombstones =false transforms.unwrap.delete. handle .mode=drop transforms.unwrap.add.headers=op

有关上述示例中的配置选项的详细信息，请参见配置选项

定制配置

连接器可能发出多种类型的事件消息(例如，心跳消息、墓碑消息或关于事务的元数据消息)。若要将转换应用于事件的子集，可以定义选择性地应用转换的SMT谓词语句仅用于特定事件。

数组编码

默认情况下，事件扁平化SMT将MongoDB数组转换为与Apache Kafka Connect或Apache Avro模式兼容的数组。MongoDB数组可以包含多种类型的元素，而Kafka数组中的所有元素必须是同一类型。

为确保SMT以满足环境需求的方式对数组进行编码，可以指定array.encoding配置选项。设置数组编码的配置示例如下:

变换=打开……transforms.unwrap.type = i开云体育官方注册网址o.debezium.connector.mongodb.transforms.ExtractNewDocumentState transforms.unwrap.array.encoding = <数组|文档>

根据配置的不同，SMT会使用以下编码方法之一来处理源消息中数组的每个实例:

数组编码

如果array.encoding设置为数组(默认)，SMT编码使用数组对原始消息中的数组进行编码的数据类型。为了确保正确的处理，数组实例中的所有元素必须是相同类型的。这个选项有一定的限制，但是它使下游客户端能够轻松地处理数组。

文档编码

如果array.encoding设置为文档时，SMT将源中的每个数组转换为结构体的结构体，在某种程度上与BSON序列化．主要的结构体包含命名为_0，_1，_2，等等，其中每个字段名表示原始数组中元素的索引。SMT用它为源数组中的等效元素检索的值填充这些索引字段。索引名的前缀是下划线，因为Avro编码禁止字段名以数字字符开头。

下面的例子展示了Debezium MongoDB连接器如何表示一个包含包开云体育官方注册网址含异构数据类型的数组的数据库文档:开云体育电动老虎机

例1。示例:包含多种数据类型的数组的文档编码
{" _id ": 1、“a1”:[{“a”:1、“b”:“没有一个”},{“a”:“c”,“d”:“东西”}]}

如果array.encoding设置为文档时，SMT将上述文件转换为以下格式:

{" _id ": 1, " a1 ":{" _0 ":{“a”:1、“b”:“没有一个”},“_1”:{“a”:“c”,“d”:“东西”}}}

的文档encoding选项使SMT能够处理由异构元素组成的任意数组。但是，在使用此选项之前，请始终验证接收器连接器和其他下游使用者是否能够处理包含多种数据类型的数组。

嵌套结构扁平化

当数据库操作涉开云体育电动老虎机及嵌入式文档时，Debezium MongoDB连接器会发出一个Kafka事件记录，该事件记录的结构反映了原开云体育官方注册网址始文档的层次结构。也就是说，事件消息将嵌套文档表示为一组嵌套字段结构。在下游连接器无法处理包含嵌套结构的消息的环境中，您可以配置事件扁平化SMT以扁平化消息中的层次结构。扁平的消息结构更适合于类似表的存储。

要将SMT配置为平嵌套结构，请设置flatten.struct配置选项真正的．在转换后的消息中，将构造与文档源一致的字段名。SMT通过将父文档字段的名称与嵌套文档字段的名称连接起来，重命名每个扁平字段。属性定义的分隔符flatten.struct.delimiter选项分隔名称的各个部分。的默认值struct.delimiter是下划线字符(＿)．

以下示例显示了用于指定SMT是否平坦嵌套结构的配置:

变换=打开……transforms.unwrap.type = i开云体育官方注册网址o.debezium.connector.mongodb.transforms.ExtractNewDocumentState transforms.unwrap.flatten。struct = <真|假> transforms.unwrap.flatten.struct.delimiter = <字符串>

下面的示例显示了由MongoDB连接器发出的事件消息。该消息包括用于文档的字段一个，包含两个嵌套文档的字段，b而且c：

{" _id ": 1,“a”:{“b”:1、“c”:“没有一个”},“d”:100}

以下示例中的消息显示了MongoDB的SMT将前面消息中的嵌套结构平坦化后的输出:

{"_id": 1， "a_b": 1， "a_c": "none"， "d": 100}

在结果消息中，b而且c原始消息中嵌套的字段被平铺并重命名。重命名的字段是通过连接父文档的名称形成的一个使用嵌套文档的名称:a_b而且a_c．属性的设置所定义的新字段名的组件由下划线字符分隔struct.delimiter配置属性,

MongoDB美元的设置处理

在MongoDB中，美元的设置操作员和美元重命名操作符都从文档中删除字段。因为MongoDB集合是无模式的，在更新从文档中删除字段后，不可能从更新的文档中推断缺失字段的名称。为了支持接收器连接器或其他可能需要关于已删除字段的信息的使用者，Debezium发出更新消息，其中包含开云体育官方注册网址removedFields元素，该元素列出已删除字段的名称。

下面的示例显示了导致删除字段的操作的更新消息的一部分一个：

“有效载荷”:{“人事处”:“u”,“ts_ms ": "...", " 前”:“{…}"， "after": "{…}"， "updateDescription": {"removedFields": ["a"]， "updatedFields": null， "truncatedArrays": null}}

在上面的例子中，之前而且后表示源文档在更新文档之前和之后的状态。属性时，连接器发出的事件消息中才会出现这些字段capture.mode对于连接器的设置如下表所示:

之前场

提供更改之前文档的状态。此字段仅在以下情况出现capture.mode设置为以下值之一:

  • change_streams_with_pre_image

  • change_streams_update_full_with_pre_image．

后场

提供更改后文档的完整状态。此字段仅在以下情况出现capture.mode设置为以下值之一:

  • change_streams_update_full

  • change_streams_update_full_with_pre_image．

假设连接器被配置为捕获完整的文档，当ExtractNewDocumentStateSMT接收一个更新消息美元的设置事件时，SMT通过表示已删除的字段具有零值，示例如下:

{"id": 1， "a": null}

的更新事件时，对于未配置为捕获完整文档的连接器，SMT将接收到美元的设置操作时，它产生以下输出消息:

{"a": null}

确定原始操作

SMT平摊事件消息后，生成的消息不再指示生成事件的操作是否属于该类型创建，更新或初始快照读．通常，你可以识别删除通过配置连接器来公开关于墓碑的信息或重写伴随着删除的事件来进行操作。有关配置连接器以在事件消息中公开关于墓碑和重写的信息的详细信息，请参见drop.tombstones而且delete.handling.mode属性。

要在事件消息中报告数据库操作的类型，SMT可以添开云体育电动老虎机加人事处字段转换为以下元素之一:

  • 事件消息体。

  • 消息头。

例如，若要添加显示原始操作类型的头属性，请添加转换，然后添加add.headers属性设置为连接器配置，示例如下:

变换=打开……transforms.unwrap.type = i开云体育官方注册网址o.debezium.connector.mongodb.transforms.ExtractNewDocumentState transforms.unwrap.add.headers = op

在此基础上，SMT通过添加事件类型来上报事件类型人事处消息头，并为其分配一个字符串值以标识操作的类型。所分配的字符串值基于人事处字段值在原始MongoDB更改事件消息．

添加元数据字段

MongoDB的事件扁平化SMT可以将原始更改事件消息中的元数据字段添加到简化消息中。添加的元数据字段以双下划线(“_”)．向事件记录添加元数据可以包括内容，例如发生更改事件的集合的名称，或者包括特定于连接器的字段，例如复制集名称。目前，SMT只能从以下变更事件子结构中添加字段:源，事务而且updateDescription．

有关MongoDB更改事件结构的更多信息，请参见MongoDB连接器文档．

例如，您可以指定以下配置来添加副本集名称(rs)和最终扁平事件记录的变更事件的集合名称:

变换=打开……transforms.unwrap.type = i开云体育官方注册网址o.debezium.connector.mongodb.transforms.ExtractNewDocumentState transforms.unwrap.add.fields = rs,收藏

上面的配置导致以下内容被添加到平坦的记录中:

{“__rs”:“rs0”、“__collection”:“我的收藏”,…｝

如果希望SMT将元数据字段添加到删除事件，设置的值delete.handling.mode选项重写．

选择性地应用转换的选项

除了发生数据库更改时Debezium连接器发出的更改事件消息外，连接器还发出其他类型的消息，包括开云体育官方注册网址心跳消息和关于模式更改和事务的元数据消息。开云体育电动老虎机因为这些其他消息的结构与SMT设计用来处理的更改事件消息的结构不同，所以最好将连接器配置为选择性地应用SMT，以便它只处理预期的数据更改消息。

有关如何有选择地应用SMT的更多信息，请参见为转换配置SMT谓词．

配置选项

下表描述了MongoDB事件扁平化SMT的配置选项。

财产 默认的 描述

array.encoding

数组

指定SMT在对从原始事件消息中读取的数组进行编码时使用的格式。设置以下选项之一:

数组

SMT使用数组将MongoDB数组编码成与Apache Kafka Connect或Apache Avro模式兼容的格式。如果设置了此选项，请验证每个数组实例中的元素类型是否相同。尽管MongoDB允许数组包含多种数据类型，但一些下游客户端不能处理数组。

文档

SMT将每个MongoDB数组转换为一个结构体的结构体，在某种程度上与BSON序列化．主要的结构体包含具有名称的字段_0，_1，_2等等。为了符合Avro命名标准，SMT在每个索引字段的数字名称前加上下划线。每个数字字段名表示原始数组中元素的索引。SMT用从源文档检索指定数组元素的值填充每个索引字段。

有关的更多信息array.coding选项，请参阅在MongoDB事件消息中编码数组的选项．

flatten.struct

假

SMT通过连接消息中嵌套属性的名称(由可配置的分隔符分隔)来简化原始事件消息中的结构(struct)，以形成一个简单的字段名。

flatten.struct.delimiter

＿

当flatten.struct设置为真正的，指定转换在从输入记录连接的字段名之间插入的分隔符，以在输出记录中生成字段名。

drop.tombstones

真正的

开云体育官方注册网址Debezium为每一个生成一个墓碑记录删除操作。默认行为是事件扁平化SMT从流中删除墓碑记录。要在流中保留墓碑记录，请指定drop.tombstones = false．

delete.handling.mode

下降

指定SMT如何处理Debezium为之生成的更改事件记录开云体育官方注册网址删除操作。设置以下选项之一:

下降

SMT删除记录删除来自事件流的操作。

没有一个

SMT保留来自事件流的原始变更事件记录。记录只包含“价值”:“零”．

重写

SMT从流中保留变更事件记录的修改版本。为了提供另一种方法来指示已删除的记录，已修改的记录包括价值字段，该字段包含来自原始记录的键/值对，并添加__deleted:真到价值．

如果你设置重写选项时，您可能会发现已更新的、简化的记录删除操作对于跟踪已删除的记录是足够的。在这种情况下，您可能希望SMT能够丢掉墓碑唱片．

add.headers.prefix

__(双下划线)

将此可选字符串设置为标题的前缀。

add.headers

没有默认的

指定一个以逗号分隔、不带空格的元数据字段列表，您希望SMT将这些字段添加到简化消息的报头中。当原始消息包含重复的字段名时，您可以通过提供结构的名称和字段的名称来识别要修改的特定字段，例如，source.ts_ms．

可选地，您可以覆盖字段的原始名称，并通过向列表中添加以下格式的条目来为其分配一个新名称:

< field_name >：< new_field_name >．

例如:

版本:版本，连接器:连接器，source.ts_ms:EVENT_TIMESTAMP

指定的新名称值区分大小写。

当SMT将元数据字段添加到简化消息的报头时，它会在每个元数据字段名称前加上双下划线。对于结构规范，SMT还在结构名和字段名之间插入下划线。

如果指定的字段不在更改事件原始消息中，SMT不会将该字段添加到报头。

add.fields.prefix

__(双下划线)

指定一个可选字符串作为字段名的前缀。

add.fields

没有默认的

属性的元数据字段列表，以逗号分隔，不带空格价值元素的简化Kafka消息。当原始消息包含重复的字段名时，您可以通过提供结构的名称和字段的名称来识别要修改的特定字段，例如，source.ts_ms．
可选地，您可以覆盖字段的原始名称，并通过向列表中添加以下格式的条目来为其分配一个新名称:

< field_name >：< new_field_name >．

例如:

版本:版本，连接器:连接器，source.ts_ms:EVENT_TIMESTAMP

指定的新名称值区分大小写。

属性中添加元数据字段时价值元素时，它在每个元数据字段名前加上双下划线。对于结构规范，SMT还在结构名和字段名之间插入下划线。

如果指定的字段没有出现在原始更改事件消息中，SMT仍然会将指定的字段添加到价值元素。

已知的限制

  • 因为MongoDB是一个无模式数据库，所以在使用Debezium开云体育电动老虎机将更改流传输到基于模式的数据关系数据库时，为了确保列定义的一致性，集合中具有相同名称的字段必须存储相同类型的数据。开云体育官方注册网址

  • 配置SMT以生成与接收器连接器兼容的格式的消息。如果接收器连接器需要“平面”消息结构，但它接收到将源MongoDB文档中的数组编码为struct of struct的消息，则接收器连接器不能处理该消息。