6.3. Debezium Oracle コネクターによるデータ型のマッピング方法

Debezium Oracle コネクターは、テーブル行の値の変化を検出すると、その変化を表す change イベントを発行します。各変更イベントレコードは、元のテーブルと同じように構造化されており、イベントレコードは各カラム値のフィールドを含んでいます。テーブルカラムのデータ型は、以下のセクションの表に示すように、コネクターが変更イベントフィールドでカラムの値をどのように表現するかを決定します。

テーブルの各カラムに対して、Debezium はソースデータ型を対応するイベントフィールドの リテラル型、場合によっては セマンティック型 にマッピングします。

リテラル型
以下のカフカコネクトスキーマタイプのいずれかを使用して、値が文字通りどのように表現されるかを記述します。INT8INT16INT32INT64FLOAT32FLOAT64BOOLEANSTRINGBYTESARRAYMAP、および STRUCT
セマンティック型
フィールドの Kafka Connect スキーマの名前を使用して、Kafka Connect スキーマがフィールドの 意味 をキャプチャーする方法を記述します。

デフォルトのデータ型変換がニーズを満たさない場合、コネクター用の カスタムコンバータを作成 することができます。

一部の Oracle ラージオブジェクト (CLOB、NCLOB、BLOB) および数値データ型については、デフォルトの設定プロパティー設定を変更することにより、コネクターがタイプマッピングを実行する方法を操作することができます。Debezium プロパティーがこれらのデータ型のマッピングをどのように制御するかの詳細については、Binary and Character LOB types および Numeric types をご覧ください。

Debezium コネクターによる Oracle データ型のマッピング方法に関する詳細は、以下を参照してください。

文字タイプ

以下の表は、コネクターによる基本の文字タイプへのマッピング方法を説明しています。

表6.6 Oracle 基本文字型のマッピング

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

CHAR[(M)]

STRING

該当なし

NCHAR[(M)]

STRING

該当なし

NVARCHAR2[(M)]

STRING

該当なし

VARCHAR[(M)]

STRING

該当なし

VARCHAR2[(M)]

STRING

該当なし

バイナリーおよび文字の LOB 型

Debezium Oracle コネクターでの BLOBCLOBNCLOB の 使用は、技術プレビュー機能のみです。テクノロジープレビュー機能は、Red Hat 製品のサービスレベルアグリーメント (SLA) の対象外であり、機能的に完全ではないことがあります。Red Hat は実稼働環境でこれらを使用することを推奨していません。テクノロジープレビューの機能は、最新の製品機能をいち早く提供して、開発段階で機能のテストを行い、フィードバックを提供していただくことを目的としています。Red Hat のテクノロジープレビュー機能のサポート範囲に関する詳細は、テクノロジープレビュー機能のサポート範囲 を参照してください。

以下の表は、コネクターによるバイナリーおよび文字 LOB (Large Object) 型へのマッピング方法を説明しています。

表6.7 Oracle バイナリーおよび文字 LOB 型のマッピング

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

BFILE

該当なし

このデータ型はサポートされていません。

BLOB

BYTES

binary.handling.mode コネクター設定を基にし、raw バイト (デフォルト)、base64 でエンコードされた文字列、または 16 進数でエンコードされた文字列のいずれか。

CLOB

STRING

該当なし

LONG

該当なし

このデータタイプはサポートされていません。

LONG RAW

該当なし

このデータタイプはサポートされていません。

NCLOB

STRING

該当なし

RAW

該当なし

このデータタイプはサポートされていません。

注記

Oracle は、CLOBNCLOB、および BLOB データタイプのカラム値を、SQL ステートメントで明示的に設定または変更された場合にのみ供給します。その結果、変更イベントには、変更されていない CLOBNCLOB、または BLOB カラムの値が含まれることはありません。代わりに、コネクタープロパティー unavailable.value.placeholder で定義されているプレースホルダーが含まれます。

CLOBNCLOB、または BLOB 列の値が更新されると、対応する更新変更イベントの after 要素に新しい値が追加されます。before 要素には使用できない値プレースホルダーが含まれます。

数字型

以下の表は、Debezium Oracle コネクターによる数値型のマッピング方法を説明しています。

注記

コネクターの decimal.handling.mode 設定プロパティーの値を変更することで、コネクターが Oracle DECIMALNUMBERNUMERIC、および REAL データ型をマッピングする方法を変更できます。このプロパティーをデフォルト値の precise に設定すると、コネクターは、表に示すように、これらの Oracle データ型を Kafka Connect org.apache.kafka.connect.data.Decimal 論理型にマッピングします。プロパティーの値を double または string に設定すると、コネクターは一部の Oracle データ型に別のマッピングを使用します。詳しくは、以下の表の セマンティックタイプおよび注意 事項の欄をご覧ください。

表6.8 Oracle 数値データ型のマッピング

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

BINARY_FLOAT

FLOAT32

該当なし

BINARY_DOUBLE

FLOAT64

該当なし

DECIMAL[(P, S)]

BYTES / INT8 / INT16 / INT32 / INT64

org.apache.kafka.connect.data.Decimal BYTES を使用する場合:

NUMBER と同様に処理されます (DECIMAL の場合には S は 0 に初期設定されます)。

decimal.handling.mode プロパティーが double に設定されている場合、コネクターは DECIMAL 値をスキーマタイプ FLOAT64 の Java double 値として表現する。

decimal.handling.mode プロパティーが string に設定されている場合、コネクターは DECIMAL 値をスキーマタイプ STRING でフォーマットされた文字列表現として表します。

DOUBLE PRECISION

STRUCT

io.debezium.data.VariableScaleDecimal

転送された値のスケールが含まれる INT32 型の scale と、元の値がスケーリングされていない形式で含まれる BYTES 型の value の 2 つのフィールドがある構造が含まれます。

FLOAT[(P)]

STRUCT

io.debezium.data.VariableScaleDecimal

転送された値のスケールが含まれる INT32 型の scale と、元の値がスケーリングされていない形式で含まれる BYTES 型の value の 2 つのフィールドがある構造が含まれます。

INTEGER, INT

BYTES

org.apache.kafka.connect.data.Decimal

INTEGER は Oracle で NUMBER(38,0) にマップされるため、INT タイプよりも大きな値を保持することができます。

NUMBER[(P[, *])]

STRUCT

io.debezium.data.VariableScaleDecimal

転送された値のスケールが含まれる INT32 型の scale と、元の値がスケーリングされていない形式で含まれる BYTES 型の value の 2 つのフィールドがある構造が含まれます。

decimal.handling.mode プロパティーを double に設定すると、コネクターは NUMBER の値をスキーマタイプが FLOAT64 の Java double 値として表します。

decimal.handling.mode プロパティーが string に設定された場合、コネクターは NUMBER の値をスキーマ型 STRING でフォーマットされた文字列表現として表します。

NUMBER(P, S <= 0)

INT8 / INT16 / INT32 / INT64

スケールが 0 の NUMBER 列は、整数を表します。負のスケールは 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 の値をスキーマタイプが FLOAT64 の Java double 値として表します。

decimal.handling.mode プロパティーが string に設定された場合、コネクターは NUMBER の値をスキーマ型 STRING でフォーマットされた文字列表現として表します。

NUMBER(P, S > 0)

BYTES

org.apache.kafka.connect.data.Decimal

NUMERIC[(P, S)]

BYTES / INT8 / INT16 / INT32 / INT64

org.apache.kafka.connect.data.Decimal BYTES を使用する場合:

NUMBER と同様に処理されます (NUMERIC の場合には S は 0 に初期設定されます)。

decimal.handling.mode プロパティーを double に設定すると、コネクターは NUMERIC の値をスキーマタイプが FLOAT64 の Java double 値として表します。

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

転送された値のスケールが含まれる INT32 型の scale と、元の値がスケーリングされていない形式で含まれる BYTES 型の value の 2 つのフィールドがある構造が含まれます。

decimal.handling.mode プロパティーが double に設定されている場合、コネクターは REAL 値をスキーマタイプ FLOAT64 の Java double 値として表現する。

decimal.handling.mode プロパティーが string に設定されている場合、コネクターは REAL 値をスキーマタイプ STRING でフォーマットされた文字列表現として表します。

ブール値型

Oracle は、BOOLEAN データ型のネイティブサポートを提供しません。ただし、論理 BOOLEAN データ型の概念をシミュレートするために、特定のセマンティクスと他のデータ型を使用することが一般的です。

ソースカラムをブール型に変換できるように、Debezium は NumberOneToBooleanConverter custom converter を提供しており、以下のいずれかの方法で使用することができます。

  • すべての NUMBER(1) 列を BOOLEAN タイプにマッピングします。
  • 正規表現のコンマ区切りリストを使用して、列のサブセットを列挙します。
    このタイプの変換を使用するには、以下の例のように selector パラメーターを使用して converters 設定プロパティーを設定する必要があります。

    converters=boolean
    boolean.type=io.debezium.connector.oracle.converters.NumberOneToBooleanConverter
    boolean.selector=.*MYTABLE.FLAG,.*.IS_ARCHIVED

時間型

Oracle INTERVALTIMESTAMP WITH TIME ZONE、および TIMESTAMP WITH LOCAL TIME ZONE データ型以外では、コネクターが時間型を変換する方法は time.precision.mode 設定プロパティーの値に依存します。

time.precision.mode 設定プロパティーが adaptive (デフォルト) に設定された場合、コネクターは列のデータ型を基に時間型のリテラルおよびセマンティック型を決定し、イベントが正確にデータベースの値を表すようにします。

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

DATE

INT64

io.debezium.time.Timestamp

UNIX エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

INTERVAL DAY[(M)] TO SECOND

FLOAT64

io.debezium.time.MicroDuration

365.25 / 12.0 の計算式で月平均日数を算出した時間間隔の微小秒数です。

io.debezium.time.Interval (interval.handling.modestring に設定されている場合)

P<years>Y<months>M<days>DT<hours>H<minutes>M<second>S のパターンに従う区間値の文字列表現,例えば P1Y2M3DT4H5M6.78S など。

INTERVAL YEAR[(M)] TO MONTH

FLOAT64

io.debezium.time.MicroDuration

365.25 / 12.0 の計算式で月平均日数を算出した時間間隔の微小秒数です。

io.debezium.time.Interval (interval.handling.modestring に設定されている場合)

P<years>Y<months>M<days>DT<hours>H<minutes>M<second>S のパターンに従う区間値の文字列表現,例えば P1Y2M3DT4H5M6.78S など。

TIMESTAMP(0 - 3)

INT64

io.debezium.time.Timestamp

UNIX エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP, TIMESTAMP(4 - 6)

INT64

io.debezium.time.MicroTimestamp

UNIX エポックからの経過時間をマイクロ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP(7 - 9)

INT64

io.debezium.time.NanoTimestamp

UNIX エポックからのナノ秒数を表し、タイムゾーン情報は含まれない。

TIMESTAMP WITH TIME ZONE

STRING

io.debezium.time.ZonedTimestamp

タイムゾーン情報を含むタイムスタンプの文字列表現。

TIMESTAMP WITH LOCAL TIME ZONE

STRING

io.debezium.time.ZonedTimestamp

UTC のタイムスタンプの文字列表現。

time.precision.mode 設定プロパティーが connect に設定された場合、コネクターは事前定義された Kafka Connect の論理型を使用します。これは、コンシューマーが組み込みの Kafka Connect の論理型のみを認識し、可変精度の時間値を処理できない場合に便利です。Oracle がサポートする精度レベルは、Kafka Connect サポートの論理型を超過するため、time.precision.modeconnectに設定していて、データベース列の fractional second precision の値が 3 より大きい場合には a loss of precision という結果になります。

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

DATE

INT32

org.apache.kafka.connect.data.Date

UNIX エポックからの日数を表します。

INTERVAL DAY[(M)] TO SECOND

FLOAT64

io.debezium.time.MicroDuration

365.25 / 12.0 の計算式で月平均日数を算出した時間間隔の微小秒数です。

io.debezium.time.Interval (interval.handling.modestring に設定されている場合)

P<years>Y<months>M<days>DT<hours>H<minutes>M<second>S のパターンに従う区間値の文字列表現,例えば P1Y2M3DT4H5M6.78S など。

INTERVAL YEAR[(M)] TO MONTH

FLOAT64

io.debezium.time.MicroDuration

365.25 / 12.0 の計算式で月平均日数を算出した時間間隔の微小秒数です。

io.debezium.time.Interval (interval.handling.modestring に設定されている場合)

P<years>Y<months>M<days>DT<hours>H<minutes>M<second>S のパターンに従う区間値の文字列表現,例えば P1Y2M3DT4H5M6.78S など。

TIMESTAMP(0 - 3)

INT64

org.apache.kafka.connect.data.Timestamp

UNIX エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP(4 - 6)

INT64

org.apache.kafka.connect.data.Timestamp

UNIX エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP(7 - 9)

INT64

org.apache.kafka.connect.data.Timestamp

UNIX エポックからの経過時間をミリ秒で表し、タイムゾーン情報は含まれません。

TIMESTAMP WITH TIME ZONE

STRING

io.debezium.time.ZonedTimestamp

タイムゾーン情報を含むタイムスタンプの文字列表現。

TIMESTAMP WITH LOCAL TIME ZONE

STRING

io.debezium.time.ZonedTimestamp

UTC のタイムスタンプの文字列表現。

ROWID タイプ

次の表は、コネクターが ROWID (行アドレス) データ型をどのようにマッピングするかを説明したものです。

表6.9 Oracle ROWID データタイプのマッピング

Oracle データ型リテラル型 (スキーマ型)セマンティック型 (スキーマ名) および注記

ROWID

STRING

該当なし

UROWID

該当なし

このデータ型はサポートされていません

ユーザー定義のタイプ

オラクルでは、組み込みのデータ型では要件を満たせない場合に、カスタムデータ型を定義して柔軟性を持たせることができます。オブジェクト型、REF データ型、Varrays、Nested Tables などのユーザー定義型があります。現時点では、Debezium Oracle コネクターをこれらのユーザー定義タイプで使用することはできません。

Oracle によって提供されたタイプ

Oracle は、組み込み型や ANSI でサポートされている型では不十分な場合に、新しい型を定義するために使用できる SQL ベースのインタフェースを提供しています。Oracle は、任意 の、XML、または Spatial 型など、幅広い目的に対応するために一般的に使用されるデータ型をいくつか提供しています。現時点では、Debezium Oracle コネクターはこれらのデータ型では使用できません。

デフォルト値

データベーススキーマのカラムにデフォルト値が指定されている場合、Oracle コネクターはこの値を対応する Kafka レコードフィールドのスキーマに伝搬させようと試みます。ほとんどの一般的なデータタイプがサポートされています。

  • 文字型 (CHARNCHARVARCHARVARCHAR2NVARCHARNVARCHAR2)
  • 数値型 (INTEGERNUMERIC、など)
  • 時間型 (DATETIMESTAMPINTERVAL など)。

一時的なタイプが TO_TIMESTAMPTO_DATE などの関数呼び出しを使用してデフォルト値を表す場合、コネクターは関数を評価するために追加のデータベース呼び出しを行うことでデフォルト値を解決します。例えば、DATE カラムが TO_DATE('2021-01-02', 'YYYY-MM-DD') というデフォルト値で定義されている場合、そのカラムのデフォルト値はその日付の UNIX エポックからの日数、この場合は 18629 となります。

一時的な型がデフォルト値を表すために SYSDATE 定数を使用する場合、コネクターは、列が NOT NULL または NULL として定義されているかどうかに基づいてこれを解決します。カラムが 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 の場合は文字列として出力されます。