Kafka 源连接器：负载模式配置

适用于 Neo4j 的 Kafka 源连接器支持两种负载模式来控制序列化并发布到 Kafka 主题的数据格式：EXTENDED（扩展）和 COMPACT（紧凑）。此功能可通过 neo4j.payload-mode 属性配置，允许用户根据数据要求选择首选的序列化格式。

负载模式

neo4j.payload-mode 配置提供以下选项

  • EXTENDED（扩展）（默认）：为每个属性提供详细的结构，支持模式兼容性和一致性。当存在模式变更（如属性类型变更）或时间类型时，此格式尤其有用，可确保数据在变更过程中保持一致性。

  • COMPACT（紧凑）：生成仅包含必要字段的更简单格式。这种格式更轻量，当不需要模式兼容性或复杂数据类型时，可能更受欢迎。

COMPACT（紧凑）模式的限制

  • 属性类型变更：COMPACT（紧凑）模式不支持属性类型变更。如果 Neo4j 中的属性类型发生变更（例如，从整数变更为字符串），可能会破坏模式。

  • Protobuf 兼容性：COMPACT（紧凑）模式不支持 Protobuf。它不支持时间类型（例如 LocalDate、LocalDateTime）的序列化。

配置

负载模式可在源连接器的设置中配置，如下所示

"neo4j.payload-mode": "EXTENDED" // Or "COMPACT" based on requirements

示例数据格式

以下示例展示了数据在每种负载模式下如何发布。

COMPACT（紧凑）模式示例

COMPACT（紧凑）模式生成一个仅包含必要字段的极简负载

{
  "name": "mary",
  "surname": "doe",
  "timestamp": 1729779296311
}

当性能和简洁性是首要考虑因素时，此模式很有用，适用于模式演变和时间一致性不是主要关注点的场景。

EXTENDED（扩展）模式示例

EXTENDED（扩展）模式包含额外的结构和元数据，以支持复杂类型和模式一致性，从而防止属性类型随时间变化时出现问题

{
  "name": {
    "type": "S",
    "B": null,
    "I64": null,
    "F64": null,
    "S": "mary",
    "BA": null,
    "TLD": null,
    "TLDT": null,
    "TLT": null,
    "TZDT": null,
    "TOT": null,
    "TD": null,
    "SP": null,
    "LB": null,
    "LI64": null,
    "LF64": null,
    "LS": null,
    "LTLD": null,
    "LTLDT": null,
    "LTLT": null,
    "LZDT": null,
    "LTOT": null,
    "LTD": null,
    "LSP": null
  },
  "surname": {
    "type": "S",
    "B": null,
    "I64": null,
    "F64": null,
    "S": "doe",
    "BA": null,
    "TLD": null,
    "TLDT": null,
    "TLT": null,
    "TZDT": null,
    "TOT": null,
    "TD": null,
    "SP": null,
    "LB": null,
    "LI64": null,
    "LF64": null,
    "LS": null,
    "LTLD": null,
    "LTLDT": null,
    "LTLT": null,
    "LZDT": null,
    "LTOT": null,
    "LTD": null,
    "LSP": null
  },
  "timestamp": {
    "type": "I64",
    "B": null,
    "I64": 1729779365447,
    "F64": null,
    "S": null,
    "BA": null,
    "TLD": null,
    "TLDT": null,
    "TLT": null,
    "TZDT": null,
    "TOT": null,
    "TD": null,
    "SP": null,
    "LB": null,
    "LI64": null,
    "LF64": null,
    "LS": null,
    "LTLD": null,
    "LTLDT": null,
    "LTLT": null,
    "LZDT": null,
    "LTOT": null,
    "LTD": null,
    "LSP": null
  }
}

即使 Neo4j 端的属性类型发生变更，此模式也能确保兼容性，因此对于具有复杂模式要求的数据尤其有利。

理解 EXTENDED（扩展）负载结构

在 EXTENDED（扩展）模式下，每个属性都包含所有受支持的 Neo4j 类型的字段。只有与实际属性类型对应的字段会包含非空值，而所有其他字段都设置为 null。这种结构确保了属性类型的任何变更都不会在源连接器或接收器连接器处导致模式强制执行错误。

字段 描述

类型

指示属性的类型。可能的值包括：B、I64、F64、S、BA、TLD、TLDT、TLT、TZDT、TOT、TD、SP，或它们的列表等效项（例如，LB、LI64、LF64、LS、LTLD 等）。

B

布尔类型 (true 或 false)

I64

64 位整数

F64

64 位浮点数

S

字符串

BA

字节数组

TLD

临时本地日期

TLDT

临时本地日期时间

TLT

临时本地时间

TZDT

临时带时区日期时间

TOT

临时偏移时间

TD

临时持续时间

SP

空间点

LB, LI64, LF64, LS, LTLD, etc.

各自对应类型的列表

例如，字符串字段将表示为

{
  "type": "S",
  "B": null,
  "I64": null,
  "F64": null,
  "S": "actual_value",
  ...
}

配置建议

当生成的消​​息与其他连接器或应用程序一起使用，并且您可以在目标主题上放宽模式兼容模式时，COMPACT（紧凑）模式有用且更易于使用。如果您的环境需要模式兼容性、时间数据类型，或者您对不同的转换器（AVRO、JSON Schema、PROTOBUF 或 JSON Embedded）有严格的类型安全要求，则应优先选择 EXTENDED（扩展）模式。

与接收器连接器的兼容性

EXTENDED（扩展）格式在连接器 5.1.0 版本中引入，旨在确保发布到 Kafka 主题的所有数据都遵循一致的模式。这可以防止 Neo4j 端属性类型变更（例如，名称属性从整数变更为字符串）时出现问题，从而实现连接器和 Kafka 消费者之间的数据平滑处理。当 Neo4j 接收器连接器由 Neo4j 源连接器提供数据时，建议使用 EXTENDED（扩展）模式，因为 Neo4j 接收器连接器可以无缝处理 EXTENDED（扩展）数据类型。

© . All rights reserved.