Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

7.3. Debezium Oracle 连接器如何映射数据类型

当 Debezium Oracle 连接器检测到表行值中的更改时，它会发出一个代表更改的事件。每个更改事件记录的结构化方式与原始表相同，事件记录包含每个列值的字段。表列的数据类型决定了连接器如何代表更改事件字段的值，如以下部分的表中所示。

对于表中的每个列，Debezium 将源数据类型映射到 字面类型，在某些情况下，在相应的事件字段中都有一个 语义类型。

字面类型
描述值如何表示，使用以下 Kafka Connect 模式类型之一： INT8,INT16,INT32,INT64, INT64 ,FLOAT32,FLOAT64,BOOLEAN,STRING,BYTES,ARRAY,MAP, 和 STRUCT.
语义类型
描述 Kafka Connect 模式如何使用字段的名称捕获字段 的含义。

如果默认数据类型转换不满足您的需要，您可以为连接器 创建自定义转换器。

对于某些 Oracle 大对象(CLOB、NCLOB 和 BLOB)和数字数据类型，您可以通过更改默认配置属性设置来操作连接器执行类型映射的方式。有关如何对这些数据类型的 Debezium 属性控制映射的更多信息，请参阅 Binary 和 Character LOB type 和 Numeric 类型。

有关 Debezium 连接器如何映射 Oracle 数据类型的更多信息，请参阅以下主题：

字符类型

下表描述了连接器如何映射基本字符类型。

Expand
表 7.9. Oracle 基本字符类型的映射
Oracle 数据类型字面类型(schema 类型)语义类型（模式名称）和备注

CHAR[(M)]

字符串

不适用

NCHAR[(M)]

字符串

不适用

NVARCHAR2[(M)]

字符串

不适用

VARCHAR[(M)]

字符串

不适用

VARCHAR2[(M)]

字符串

不适用

二进制和 Character LOB 类型

使用带有 Debezium Oracle 连接器的 BLOB、CLOB 和 NCLOB 只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。有关红帽技术预览功能支持范围的更多信息，请参阅 https://access.redhat.com/support/offerings/techpreview。

下表描述了连接器如何映射二进制和字符大对象(LOB)数据类型。

Expand
表 7.10. Oracle 二进制和字符 LOB 类型的映射
Oracle 数据类型字面类型(schema 类型)语义类型（模式名称）和备注

BFILE

不适用

不支持这个数据类型

BLOB

BYTES

raw 字节（默认值）、base64 编码的 String 或 base64-url-safe-encoded String 或基于 binary.handling.mode 连接器配置属性设置的十六进制编码的字符串。

CLOB

字符串

不适用

LONG

不适用

不支持此数据类型。

长原始

不适用

不支持此数据类型。

NCLOB

字符串

不适用

RAW

不适用

不支持此数据类型。

注意

Oracle 仅提供 CLOB、NCLOB 和 BLOB 数据类型的列值（如果它们在 SQL 语句中明确设置或更改）。因此，更改事件永远不会包含没有变化的 CLOB、NCLOB 或 BLOB 列的值。相反，它们包含由连接器属性 unavailable.value.placeholder 定义的占位符。

如果更新了 CLOB、NCLOB 或 BLOB 列的值，则新值将放置在相应更新更改事件的 after 项中。before 元素包含不可用值占位符。

数字类型

下表描述了 Debezium Oracle 连接器如何映射数字类型。

注意

您可以改变连接器映射 Oracle DECIMAL, NUMBER, NUMERIC, 和 REAL 数据类型的方式，方法是修改连接器的 decimal.handling.mode 配置属性的值。当属性设置为 精确的 默认值时，连接器会将这些 Oracle 数据类型映射到 Kafka Connect org.apache.kafka.connect.data.Decimal 逻辑类型，如表中所示。当属性的值设为 double 或 string 时，连接器对某些 Oracle 数据类型使用备用映射。如需更多信息，请参阅 下表中的 Semantic 类型和 notes 列。

Expand
表 7.11. Oracle 数字数据类型的映射
Oracle 数据类型字面类型(schema 类型)语义类型（模式名称）和备注

BINARY_FLOAT

FLOAT32

不适用

BINARY_DOUBLE

FLOAT64

不适用

DECIMAL[(P, S)]

BYTES / INT8 / INT16 / INT32 / INT64

org.apache.kafka.connect.data.Decimal if if BYTES

Handled to NUMBER （请注意，对于 DECIMAL，S 默认为 0。

当将 decimal.handling.mode 属性设置为 double 时，连接器将 DECIMAL 值表示为 Java 双 值，类型为 FLOAT64。

当将 decimal.handling.mode 属性设置为 string 时，连接器代表 DECIMAL 值，其格式的字符串表示为 STRING。

双精度

STRUCT

io.debezium.data.VariableScaleDecimal

Contains 一个结构，它有两个字段：类型为 INT32 的扩展，其中包含未 扩展 格式的传输 值 和值 BYTES。

FLOAT[(P)]

STRUCT

io.debezium.data.VariableScaleDecimal

Contains 一个结构，它有两个字段：类型为 INT32 的扩展，其中包含未 扩展 格式的传输 值 和值 BYTES。

整数， INT

BYTES

org.apache.kafka.connect.data.Decimal

INTEGER 在 Oracle 中映射到 NUMBER (38,0)，因此可以保存大于 INT 类型的值可以存储

NUMBER[(P[, *])]

STRUCT

io.debezium.data.VariableScaleDecimal

Contains 一个结构，它有两个字段：类型为 INT32 的扩展，其中包含未 扩展 格式的传输 值 和值 BYTES。

当将 decimal.handling.mode 属性设置为 double 时，连接器将 NUMBER 值表示为 Java 双 值，类型为 FLOAT64。

当将 decimal.handling.mode 属性设置为 string 时，连接器显示 NUMBER 值作为一个有特定格式的字符串（如 schema 类型 STRING）。

NUMBER (P, S <= 0)

INT8 / INT16 / INT32 / INT64

NUMBER 列，扩展为 0 代表整数。负比例表示 Oracle 中的舍入，例如，规模为 -2 会导致舍入成百。

根据精度和规模，选择以下匹配的 Kafka Connect 整数类型之一：

  • P - S < 3, INT8
  • P - S < 5, INT16
  • P - S < 10, INT32
  • P - S < 19, INT64
  • P - S >= 19, BYTES (org.apache.kafka.connect.data.Decimal)

当将 decimal.handling.mode 属性设置为 double 时，连接器将 NUMBER 值表示为 Java 双 值，类型为 FLOAT64。

当将 decimal.handling.mode 属性设置为 string 时，连接器显示 NUMBER 值作为一个有特定格式的字符串（如 schema 类型 STRING）。

NUMBER (P, S > 0)

BYTES

org.apache.kafka.connect.data.Decimal

数字[(P, S)]

BYTES / INT8 / INT16 / INT32 / INT64

org.apache.kafka.connect.data.Decimal if if BYTES

Handled 与 NUMBER （请注意，S 默认为 0 代表 NUMERIC）。

当将 decimal.handling.mode 属性设置为 double 时，连接器将 NUMERIC 值表示为 Java 双 值，类型为 FLOAT64。

当将 decimal.handling.mode 属性设置为 string 时，连接器代表 NUMERIC 值，其格式的字符串表示为 STRING。

SMALLINT

BYTES

org.apache.kafka.connect.data.Decimal

SMALLINT 在 Oracle 中映射到 NUMBER (38,0)，因此可以保存大于 INT 类型的值可以存储

REAL

STRUCT

io.debezium.data.VariableScaleDecimal

Contains 一个结构，它有两个字段：类型为 INT32 的扩展，其中包含未 扩展 格式的传输 值 和值 BYTES。

当将 decimal.handling.mode 属性设置为 double 时，连接器将 REAL 值表示为 Java 双 值，类型为 FLOAT64。

当将 decimal.handling.mode 属性设置为 string 时，连接器使用 schema type STRING 代表 REAL 值作为格式的字符串表示。

如上面提到的，Oracle 允许在 NUMBER 类型中进行负扩展。当数字以 Decimal 表示时，这可能会导致转换为 Avro 格式时出现问题。十进制 类型包括扩展信息，但 Avro 规格 只允许缩放的正值。根据所使用的模式 registry，可能会导致 Avro 序列化失败。要避免这个问题，您可以使用 NumberToZeroScaleConverter，它将带有负精度（小数点左面）的高的数字 (P - S >= 19) 转换为小数点右面零位的 Decimal 类型。它可以配置如下： 

converters=zero_scale
zero_scale.type=io.debezium.connector.oracle.converters.NumberToZeroScaleConverter
zero_scale.decimal.mode=precise
Copy to Clipboard Toggle word wrap

默认情况下，数字转换为 Decimal 类型(zero_scale.decimal.mode=precise)，但支持完整的两种支持类型(双 和 字符串)。

布尔值类型

Oracle 不支持 BOOLEAN 数据类型。但是，通常使用带有特定语义的其他数据类型来模拟逻辑 BOOLEAN 数据类型的概念。

为了允许您将源列转换为布尔值数据类型，Debezium 提供了一个 NumberOneTo BooleanConverter 自定义转换器，您可以使用以下方法之一使用：

  • 将所有 NUMBER (1) 列映射到 BOOLEAN 类型。

  • 使用以逗号分隔的正则表达式列表枚举列的子集。
    要使用这种类型的转换，您必须使用 selector 参数设置 converters 配置属性，如下例所示： 

    converters=boolean
boolean.type=io.debezium.connector.oracle.converters.NumberOneToBooleanConverter
boolean.selector=.*MYTABLE.FLAG,.*.IS_ARCHIVED
    Copy to Clipboard Toggle word wrap

时序类型

除了 Oracle INTERVAL,TIMESTAMP 之外，TIME ZONE 和 TIMESTAMP 利用 LOCAL TIME ZONE 数据类型，连接器转换 temporal 类型取决于 time.precision.mode 配置属性的值。

当将 time.precision.mode 配置属性设置为 adaptive （默认值）时，连接器会根据列的数据类型确定 temporal 类型的字面和语义类型，以便事件 准确 代表数据库中的值：

Expand
Oracle 数据类型字面类型(schema 类型)语义类型（模式名称）和备注

DATE

INT64

io.debezium.time.Timestamp

代表自 UNIX epoch 起的毫秒数，不包括时区信息。

INTERVAL DAY[(M)] 到 SECOND

FLOAT64

io.debezium.time.MicroDuration

使用每月平均值的 365.25 / 12.0 公式的微秒数。

io.debezium.time.Interval （当 interval.handling.mode 设置为 字符串）

字符串表示 遵循格式 P<years>Y<months>M<days>DT<hours>H<minutes>M<seconds>S, 例如，P1Y2M3DT4H5M6.78S。

INTERVAL YEAR[(M)] 到月份

FLOAT64

io.debezium.time.MicroDuration

使用每月平均值的 365.25 / 12.0 公式的微秒数。

io.debezium.time.Interval （当 interval.handling.mode 设置为 字符串）

字符串表示 遵循格式 P<years>Y<months>M<days>DT<hours>H<minutes>M<seconds>S, 例如，P1Y2M3DT4H5M6.78S。

TIMESTAMP(0 - 3)

INT64

io.debezium.time.Timestamp

代表自 UNIX epoch 起的毫秒数，不包括时区信息。

时间戳、时间戳(4 - 6)

INT64

io.debezium.time.MicroTimestamp

代表自 UNIX epoch 起的微秒数，不包括时区信息。

TIMESTAMP (7 - 9)

INT64

io.debezium.time.NanoTimestamp

代表 UNIX epoch 后的纳秒数量，不包括时区信息。

带有时区的时间戳

字符串

io.debezium.time.ZonedTimestamp

是带有时区信息的时间戳的字符串。

带有本地时区的时间戳

字符串

io.debezium.time.ZonedTimestamp

是 UTC 中时间戳的字符串。

当将 time.precision.mode 配置属性设为 connect 时，连接器使用预定义的 Kafka Connect 逻辑类型。当消费者只了解内置的 Kafka Connect 逻辑类型，且无法处理变量-precision 时间值时，这很有用。由于 Oracle 支持的精度级别超过 Kafka Connect 支持中的逻辑类型，如果将 time.precision.mode 设置为 connect，当数据库列的 fractional second precision 值大于 2 时，会出现丢失精度的结果：

Expand
Oracle 数据类型字面类型(schema 类型)语义类型（模式名称）和备注

DATE

INT32

org.apache.kafka.connect.data.Date

代表 UNIX epoch 后的天数。

INTERVAL DAY[(M)] 到 SECOND

FLOAT64

io.debezium.time.MicroDuration

使用每月平均值的 365.25 / 12.0 公式的微秒数。

io.debezium.time.Interval （当 interval.handling.mode 设置为 字符串）

字符串表示 遵循格式 P<years>Y<months>M<days>DT<hours>H<minutes>M<seconds>S, 例如，P1Y2M3DT4H5M6.78S。

INTERVAL YEAR[(M)] 到月份

FLOAT64

io.debezium.time.MicroDuration

使用每月平均值的 365.25 / 12.0 公式的微秒数。

io.debezium.time.Interval （当 interval.handling.mode 设置为 字符串）

字符串表示 遵循格式 P<years>Y<months>M<days>DT<hours>H<minutes>M<seconds>S, 例如，P1Y2M3DT4H5M6.78S。

TIMESTAMP(0 - 3)

INT64

org.apache.kafka.connect.data.Timestamp

代表自 UNIX epoch 起的毫秒数，不包括时区信息。

TIMESTAMP (4 - 6)

INT64

org.apache.kafka.connect.data.Timestamp

代表自 UNIX epoch 起的毫秒数，不包括时区信息。

TIMESTAMP (7 - 9)

INT64

org.apache.kafka.connect.data.Timestamp

代表自 UNIX epoch 起的毫秒数，不包括时区信息。

带有时区的时间戳

字符串

io.debezium.time.ZonedTimestamp

是带有时区信息的时间戳的字符串。

带有本地时区的时间戳

字符串

io.debezium.time.ZonedTimestamp

是 UTC 中时间戳的字符串。

ROWID 类型

下表描述了连接器如何映射 ROWID （托管地址）数据类型。

Expand
表 7.12. Oracle ROWID 数据类型的映射
Oracle 数据类型字面类型(schema 类型)语义类型（模式名称）和备注

ROWID

字符串

不适用

UROWID

不适用

不支持此数据类型。

用户定义的类型

Oracle 可让您定义自定义数据类型，以便在内置数据类型无法满足您的要求时提供灵活性。有几种用户定义的类型，如对象类型、REF 数据类型、Varrays 和 Nested Tables。目前，您不能将 Debezium Oracle 连接器与任何这些用户定义的类型一起使用。

Oracle 提供的类型

Oracle 提供基于 SQL 的接口，可用于在内置或 ANSI 支持的类型不足时定义新类型。Oracle 提供多种常用的数据类型来满足各种目的，如 Any、XML 或 Spatial 类型。目前，您不能将 Debezium Oracle 连接器与任何这些数据类型一起使用。

默认值

如果为数据库模式中的列指定了默认值，Oracle 连接器将尝试将此值传播到对应 Kafka 记录字段的 schema。最常见的数据类型受到支持，包括：

  • 字符类型(CHAR、NCHAR、VARCHAR、VARCHAR 2、NVARCHAR、NVARCHAR2)
  • 数字类型(INTEGER 、数字化等)
  • 时序类型(DATE、TIMESTAMP、INTERVAL 等)

如果临时类型使用 TO_TIMESTAMP 或 TO_DATE 等函数调用来代表默认值，则连接器将通过进行额外的数据库调用来评估函数来解析默认值。例如，如果 DATE 列定义了默认值 TO_DATE ('2021-01-02', 'YYYY-MM-DD')，则列的默认值将是该日期的 UNIX epoch 或 18629 的天数。

如果临时类型使用 SYSDATE 常数来代表默认值，则连接器将根据列是否定义为 NOT NULL 或 NULL 来解决此问题。如果列可为空，则不会设置默认值；但是，如果列不可为空，则默认值将解析为 0（用于 DATE 或 TIMESTAMP(n) 数据类型）或 1970-01-01T00:00:00Z (用于 TIMESTAMP WITH TIME ZONE 或 TIMESTAMP WITH LOCAL TIME ZONE 数据类型)。默认值为数字，除非列是 TIMESTAMP WITH TIME ZONE 或 TIMESTAMP WITH LOCAL TIME ZONE，在这种情况下，它作为字符串发出。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat