Kafka JSON カタログを設定すると、Realtime Compute for Apache Flink ジョブは、スキーマを定義することなく、Kafka クラスター内の JSON トピックに直接アクセスできるようになります。このトピックでは、Kafka JSON カタログの作成、表示、削除の方法について説明します。
背景
Kafka JSON カタログ は、JSON 形式のメッセージを自動的にパースすることで、トピックのスキーマを推測します。これにより、Kafka テーブル のスキーマを宣言することなく、Flink SQL でメッセージ内の特定のフィールドにアクセスできます。Kafka JSON カタログ には、次の特徴があります。
-
カタログ内のテーブル名は Kafka トピック名 と一致します。これにより、DDL ステートメント による手動のテーブル登録が不要になり、開発効率と精度が向上します。
-
Kafka JSON カタログ のテーブルを、Flink SQL ジョブ のソーステーブルとして直接使用できます。
-
Kafka JSON カタログ を Flink CDC データインジェスト と組み合わせて使用すると、スキーマ変更時にデータを同期できます。詳細については、「既存のカタログの再利用」をご参照ください。
このトピックでは、Kafka JSON カタログ の管理方法について説明します。
制限事項
-
Kafka JSON カタログは、メッセージが JSON 形式のトピックのみをサポートします。
-
Kafka JSON カタログの設定は、Flink コンピューティングエンジン VVR 6.0.2 以降でのみサポートされています。
-
DDL ステートメントを使用して既存の Kafka JSON カタログを変更することはできません。
-
データテーブルのクエリのみが可能です。データベースやテーブルの作成、変更、削除はできません。
-
Kafka JSON カタログでは、SSL または SASL 認証が有効な Kafka クラスターへの読み書きはサポートされていません。
-
Kafka JSON カタログのテーブルは、Flink SQL ジョブでソーステーブルとして直接使用できますが、シンクテーブルやルックアップディメンションテーブルとしては使用できません。
-
現在、ApsaraMQ for Kafka はオープンソース Kafka と同じインターフェイスによる グループ の削除をサポートしていないため、グループ ID の自動削除を有効にするには、Kafka JSON カタログの作成時に aliyun.kafka.instanceId、aliyun.kafka.accessKeyId、aliyun.kafka.accessKeySecret、aliyun.kafka.endpoint、および aliyun.kafka.regionId を指定する必要があります。詳細については、「オープンソース Kafka との比較」をご参照ください。
使用上の注意
Kafka JSON カタログは、サンプルデータを解析することでテーブルのスキーマを推論します。トピックに一貫性のないデータフォーマットが含まれている場合、カタログはデフォルトですべての列を保持し、最も広いスキーマを返します。トピック内のデータフォーマットが変更されると、推論されるスキーマが変化し、再起動時にジョブの失敗を引き起こす可能性があります。
たとえば、セーブポイントから Kafka JSON カタログテーブルを読み取る Flink SQL ジョブを再起動する際、カタログは以前とは異なる新しいスキーマを推論する可能性があります。ジョブの実行計画は古いスキーマに基づいているため、フィルター条件の不一致やフィールドアクセスの誤りなどのランタイムエラーが発生する可能性があります。これらの問題を防ぐには、Flink SQL ジョブで CREATE TEMPORARY TABLE ステートメントを使用して、固定スキーマを持つ Kafka テーブルを定義してください。
Kafka JSON カタログの作成
-
Scripts ページで、SQL エディターに Kafka JSON カタログを作成するステートメントを入力します。
-
セルフマネージド Kafka クラスターまたは EMR on ECS Kafka クラスター の場合
CREATE CATALOG <YourCatalogName> WITH( 'type'='kafka', 'properties.bootstrap.servers'='<brokers>', 'format'='json', 'default-database'='<dbName>', 'key.fields-prefix'='<keyPrefix>', 'value.fields-prefix'='<valuePrefix>', 'timestamp-format.standard'='<timestampFormat>', 'infer-schema.flatten-nested-columns.enable'='<flattenNestedColumns>', 'infer-schema.primitive-as-string'='<primitiveAsString>', 'infer-schema.parse-key-error.field-name'='<parseKeyErrorFieldName>', 'infer-schema.compacted-topic-as-upsert-table'='true', 'max.fetch.records'='100' ); -
CREATE CATALOG <YourCatalogName> WITH( 'type'='kafka', 'properties.bootstrap.servers'='<brokers>', 'format'='json', 'default-database'='<dbName>', 'key.fields-prefix'='<keyPrefix>', 'value.fields-prefix'='<valuePrefix>', 'timestamp-format.standard'='<timestampFormat>', 'infer-schema.flatten-nested-columns.enable'='<flattenNestedColumns>', 'infer-schema.primitive-as-string'='<primitiveAsString>', 'infer-schema.parse-key-error.field-name'='<parseKeyErrorFieldName>', 'infer-schema.compacted-topic-as-upsert-table'='true', 'max.fetch.records'='100', 'aliyun.kafka.accessKeyId'='<aliyunAccessKeyId>', 'aliyun.kafka.accessKeySecret'='<aliyunAccessKeySecret>', 'aliyun.kafka.instanceId'='<aliyunKafkaInstanceId>', 'aliyun.kafka.endpoint'='<aliyunKafkaEndpoint>', 'aliyun.kafka.regionId'='<aliyunKafkaRegionId>' );
パラメータ
タイプ
説明
必須
備考
YourCatalogName
String
Kafka JSON カタログの名前。
はい
カスタム名を指定します。
重要構文エラーを防ぐため、プレースホルダーをカタログ名に置き換え、山括弧 (<>) を削除してください。
type
String
カタログのタイプ。
はい
値は 'kafka' である必要があります。
properties.bootstrap.servers
String
Kafka ブローカーのアドレス。
はい
host1:port1,host2:port2,host3:port3の形式で 1 つ以上のアドレスを指定します。複数のアドレスはカンマ (,) で区切ります。
format
String
Kafka メッセージのフォーマット。
はい
現在、'json' のみがサポートされています。Flink は JSON 形式のメッセージを解析してスキーマを推論します。
default-database
String
カタログのデフォルトデータベース名。
いいえ
カタログは、テーブルを特定するために 3 つの部分から成る識別子 (catalog_name.db_name.table_name) を使用します。このパラメータで db_name を設定します。Kafka にはデータベースがないため、クラスターを表す任意の文字列を使用できます。
key.fields-prefix
String
メッセージキーから解析されたフィールド名に追加されるカスタムプレフィックスで、名前の競合を防ぎます。
いいえ
デフォルト値は 'key_' です。たとえば、キー内のフィールドが 'a' という名前の場合、テーブルスキーマでの名前は 'key_a' になります。
説明key.fields-prefix の値は、value.fields-prefix の値のプレフィックスにすることはできません。たとえば、value.fields-prefix が 'test1_value_' に設定されている場合、key.fields-prefix を 'test1_' に設定することはできません。
value.fields-prefix
String
メッセージ値から解析されたフィールド名に追加されるカスタムプレフィックスで、名前の競合を防ぎます。
いいえ
デフォルト値は 'value_' です。たとえば、値内のフィールドが 'b' という名前の場合、テーブルスキーマでの名前は 'value_b' になります。
説明value.fields-prefix の値は、key.fields-prefix の値のプレフィックスにすることはできません。たとえば、key.fields-prefix が 'test2_value_' に設定されている場合、value.fields-prefix を 'test2_' に設定することはできません。
timestamp-format.standard
String
JSON メッセージ内のタイムスタンプフィールドを解析するためのフォーマット。 Flink は最初にこのフォーマットを使用してタイムスタンプの解析を試みます。解析に失敗した場合、自動的に他の標準フォーマットを試行します。
いいえ
有効な値:
-
SQL (デフォルト)
-
ISO-8601
infer-schema.flatten-nested-columns.enable
Boolean
JSON メッセージ値内のネストされた列を再帰的に展開するかどうかを指定します。
いいえ
有効な値:
-
true:ネストされた列を再帰的に展開します。
展開された列の場合、 Flink はアクセスパスを列名として使用します。たとえば、
{"nested": {"col": true}}内の列 'col' の場合、展開後の列名は 'nested.col' になります。説明このパラメータを true に設定する場合は、Flink CDC データインジェストジョブと併用することを推奨します。その他の DML ステートメントは、ネストされた列の自動展開をサポートしていません。
-
false (デフォルト):ネストされた型を STRING として扱います。
infer-schema.primitive-as-string
Boolean
JSON メッセージ値内のすべてのプリミティブ型を STRING として推論するかどうかを指定します。
いいえ
有効な値:
-
true:すべてのプリミティブ型を STRING として推論します。
-
false (デフォルト):標準ルールに基づいて型を推論します。
infer-schema.parse-key-error.field-name
String
空でないメッセージキーが JSON として解析できない場合、 Flink は生のキーデータを保持するために VARBINARY フィールドをスキーマに追加します。この新しいフィールドの名前は、key.fields-prefix の値とこのパラメータの値を組み合わせたものになります。
いいえ
デフォルト値は 'col' です。たとえば、メッセージ値が 'value_name' という名前のフィールドに解析され、メッセージキーが空でないが解析に失敗した場合、結果のスキーマには 'key_col' と 'value_name' の 2 つのフィールドが含まれます。
infer-schema.compacted-topic-as-upsert-table
Boolean
トピックを Upsert Kafka テーブルとして扱うかどうかを指定します。これは、トピックのクリーンアップポリシーが 'compact' で、メッセージキーが空でない場合にのみ適用されます。
いいえ
デフォルト値は true です。Flink CDC データインジェストを使用して ApsaraMQ for Kafka インスタンスにデータを同期する場合、このパラメータを true に設定する必要があります。
説明このパラメータは VVR 6.0.2 以降でのみサポートされています。
max.fetch.records
Int
スキーマ推論のためにサンプリングするメッセージの最大数。
いいえ
デフォルト値は 100 です。
aliyun.kafka.accessKeyId
String
Alibaba Cloud アカウントの AccessKey ID。詳細については、「AccessKey ペアの作成」をご参照ください。
いいえ
Flink CDC データインジェストを使用して ApsaraMQ for Kafka インスタンスにデータを同期する場合、このパラメータが必要です。
説明このパラメータは VVR 6.0.2 以降でのみサポートされています。
aliyun.kafka.accessKeySecret
String
Alibaba Cloud アカウントの AccessKey Secret。詳細については、「AccessKey ペアの作成」をご参照ください。
いいえ
Flink CDC データインジェストを使用して ApsaraMQ for Kafka インスタンスにデータを同期する場合、このパラメータが必要です。
説明このパラメータは VVR 6.0.2 以降でのみサポートされています。
aliyun.kafka.instanceId
String
ApsaraMQ for Kafka インスタンスのインスタンス ID。インスタンス ID は、ApsaraMQ for Kafka コンソールのインスタンス詳細ページで確認できます。
いいえ
Flink CDC データインジェストを使用して ApsaraMQ for Kafka インスタンスにデータを同期する場合、このパラメータが必要です。
説明このパラメータは VVR 6.0.2 以降でのみサポートされています。
aliyun.kafka.endpoint
String
ApsaraMQ for Kafka の API エンドポイント。詳細については、「エンドポイント」をご参照ください。
いいえ
Flink CDC データインジェストを使用して ApsaraMQ for Kafka インスタンスにデータを同期する場合、このパラメータが必要です。
説明このパラメータは VVR 6.0.2 以降でのみサポートされています。
aliyun.kafka.regionId
String
トピックが存在するインスタンスのリージョン ID。詳細については、「エンドポイント」をご参照ください。
いいえ
Flink CDC データインジェストを使用して ApsaraMQ for Kafka インスタンスにデータを同期する場合、このパラメータが必要です。
説明このパラメータは VVR 6.0.2 以降でのみサポートされています。
-
-
CREATE CATALOG ステートメントを選択し、左側のガターで[実行]をクリックします。
CREATE CATALOG KafkaCatalog WITH( 'type'='kafka', 'properties.bootstrap.servers'='<brokers>', 'format'='json', 'default-database'='<dbName>', 'key.fields-prefix'='<keyPrefix>', 'value.fields-prefix'='<valuePrefix>', 'timestamp-format.standard'='<timestampFormat>', 'infer-schema.flatten-nested-columns.enable'='<flattenNestedColumns>', 'infer-schema.primitive-as-string'='<primitiveAsString>', 'infer-schema.parse-key-error.field-name'='<parseKeyErrorFieldName>', 'infer-schema.compacted-topic-as-upsert-table'='true', 'max.fetch.records'='100', 'aliyun.kafka.accessKeyId'='<aliyunAccessKeyId>', 'aliyun.kafka.accessKeySecret'='<aliyunAccessKeySecret>', 'aliyun.kafka.instanceId'='<aliyunKafkaInstanceId>', 'aliyun.kafka.endpoint'='<aliyunKafkaEndpoint>', 'aliyun.kafka.regionId'='<aliyunKafkaRegionId>' ); -
左側の[カタログ] エリアにカタログが表示されていることを確認します。
Kafka JSON カタログ
-
[スクリプト] エディターで、以下のコマンドを入力します。
DESCRIBE `${catalog_name}`.`${db_name}`.`${topic_name}`;パラメーター
説明
${catalog_name}
Kafka JSON カタログの名前。
${db_name}
Kafka クラスターの名前。
${topic_name}
Kafka トピックの名前。
-
DESCRIBE ステートメントを選択し、左側のガターで [Run] をクリックします。
ステートメントが正常に実行されると、結果ペインに Kafka ソーステーブルのフィールド定義が表示されます。出力には、ビジネスフィールド
value_from(STRING)、value_name(STRING)、value_order(BIGINT) と、メタデータ仮想フィールドpartition(INT、プライマリキー)、offset(BIGINT、プライマリキー)、timestamp(TIMESTAMP_LTZ(3)) が含まれます。これらのメタデータ仮想フィールドでは、extras列にMETADATA VIRTUALが表示されます。
Kafka JSON カタログの使用
-
Kafka トピックからデータを読み取るソーステーブルとして使用します。
INSERT INTO ${other_sink_table} SELECT... FROM `${kafka_catalog}`.`${db_name}`.`${topic_name}`/*+OPTIONS('scan.startup.mode'='earliest-offset')*/;説明Kafka JSON カタログ内のテーブルに追加の WITH オプションを指定するには、SQL ヒント を使用します。たとえば、上記の SQL ステートメントでは、最も古いオフセットからデータの消費を開始するヒントを使用しています。その他のパラメーターの詳細については、ApsaraMQ for Kafka ソーステーブルのパラメーターおよびApsaraMQ for Kafka シンクテーブルのパラメーターをご参照ください。
-
ソーステーブルとして、Flink CDC データインジェストを使用して、Kafka トピックから Paimon の宛先テーブルにデータを同期します。
using.built-in-catalogパラメーターは、既存のカタログを再利用し、設定を簡素化します。-
単一テーブルをリアルタイムで同期します。
source: type: kafka using.built-in-catalog: kafka_json_catalog topic: topic0 properties.group.id: cdc_kafka_json_to_paimon # 初回起動時に各トピックで利用可能な最も古いオフセットから消費を開始します。 scan.startup.mode: earliest-offset value.format: json sink: type: paimon using.built-in-catalog: paimon_dlf_catalog # topic0の書き込み先となるPaimonテーブルを指定します。 route: - source-table: topic0 sink-table: db.table0 -
単一のジョブで複数のテーブルを同期します。
source: type: kafka using.built-in-catalog: kafka_json_catalog topic: "topic0;topic1;topic2" properties.group.id: cdc_kafka_json_to_paimon # 初回起動時に各トピックで利用可能な最も古いオフセットから消費を開始します。 scan.startup.mode: earliest-offset value.format: json # 起動時に認識されるcreate tableイベントをバッチで送信します。 scan.emit.create-table-events.in-batch.enabled: true sink: type: paimon using.built-in-catalog: paimon_dlf_catalog # 各トピックを異なるテーブルに書き込みます。 route: - source-table: topic0 sink-table: db.table0 - source-table: topic1 sink-table: db.table1 - source-table: topic2 sink-table: db.table2
-
Kafka JSON カタログを使用したエンドツーエンドの例については、リアルタイムログウェアハウジング をご参照ください。
Kafka JSON カタログの削除
Kafka JSON カタログを削除しても、実行中のジョブには影響しません。ただし、カタログのテーブルを使用しているジョブをデプロイまたは再起動すると、「table not found」 エラーで失敗します。操作は慎重に行ってください。
-
[スクリプト] ページの SQL エディターで、次のコマンドを入力します。
DROP CATALOG ${catalog_name};${catalog_name} を Kafka JSON カタログの名前に置き換えます。
-
DROP CATALOG コマンドを選択して右クリックし、[実行] を選択します。
-
左側の[カタログ]エリアの一覧に、該当のカタログが表示されなくなったことを確認します。
Kafka JSON カタログのテーブル
Kafka JSON カタログのテーブルの利用を簡素化するため、カタログは推論されたテーブルにデフォルトの設定パラメーター、メタデータ、およびプライマリキー情報を自動的に追加します。
-
Kafka テーブルのスキーマ推論
トピックのスキーマを推論する際、Kafka JSON カタログは最大 max.fetch.records 件のメッセージをサンプリングします。各メッセージのスキーマを解析し、これらの個別のスキーマを最終的なスキーマにマージします。解析ルールは、Kafka が Flink CDC データインジェストのデータソースとして使用する場合の 基本ルール と同じです。
重要-
スキーマ推論中、Kafka JSON カタログはトピックからデータを読み取るためのコンシューマーグループを作成します。カタログは、カタログが作成したことを示すために、コンシューマーグループ名にプレフィックスを付けます。
-
ApsaraMQ for Kafka の場合、バージョン 6.0.7 以降の Kafka JSON カタログを使用することを推奨します。6.0.7 より前のバージョンではコンシューマーグループが自動的に削除されないため、メッセージバックログに関するアラートが発生する可能性があります。
スキーマは次の部分で構成されます:
-
推論された物理列
Kafka JSON カタログは、メッセージキーとメッセージバリューから物理列を推論します。
メッセージキーが空ではなく、解析できない場合、カタログは VARBINARY 列を返します。この列の名前は、key.fields-prefix パラメーターの値と infer-schema.parse-key-error.field-name パラメーターの値を連結したものです。
Kafka メッセージのバッチをフェッチした後、カタログは各メッセージを解析し、結果の物理列をトピックの統一されたスキーマにマージします。
-
推論された物理列に結果スキーマにないフィールドが含まれている場合、カタログはそれらを結果スキーマに自動的に追加します。
-
両方に同じ名前の列が含まれている場合、次のルールが適用されます:
-
型が同じで精度が異なる場合、より高い精度の型が使用されます。
-
型が異なる場合、システムは型ツリー (下図参照) でそれらの最小共通親を見つけ、それを列の型として使用します。ただし、精度を維持するため、Decimal 型と Float 型がマージされる場合、結果の型は Double になります。

-
たとえば、次の 3 つのメッセージを含む Kafka トピックの場合、Kafka JSON カタログは下図のようにスキーマを推論します。

-
-
デフォルトのメタデータ列
デフォルトでは、Kafka JSON カタログはパーティション、オフセット、タイムスタンプの 3 つのメタデータ列を追加します。
メタデータ名
列名
型
説明
partition
partition
INT NOT NULL
パーティション ID。
offset
offset
BIGINT NOT NULL
メッセージのオフセット。
timestamp
timestamp
TIMESTAMP_LTZ(3) NOT NULL
メッセージのタイムスタンプ。
-
デフォルトのプライマリキー制約
Kafka JSON カタログのテーブルをソースとして使用する場合、メタデータ列のパーティションとオフセットがデフォルトのプライマリキーとして機能し、データの一意性を保証します。
説明Kafka JSON カタログによって推論されたスキーマが要件を満たさない場合は、CREATE TEMPORARY TABLE ... LIKE 構文を使用して、希望するスキーマを持つ一時テーブルを宣言できます。たとえば、JSON データに '2023-01-01 12:00:01' というフォーマットの
tsフィールドが含まれている場合、Kafka JSON カタログはtsフィールドを自動的に TIMESTAMP 型として推論します。tsフィールドを STRING 型として使用するには、次のようにテーブルを宣言します。デフォルトの設定ではメッセージバリューのフィールドにvalue_プレフィックスが追加されるため、ここでのフィールド名はvalue_tsになります。CREATE TEMPORARY TABLE tempTable ( value_name STRING, value_ts STRING ) LIKE `kafkaJsonCatalog`.`kafka`.`testTopic`; -
-
デフォルトのテーブルパラメーター
パラメーター
説明
備考
connector
コネクタのタイプです。
値は
kafkaまたはupsert-kafkaです。topic
対応するトピックの名前です。
宣言されたテーブル名と同じです。
properties.bootstrap.servers
Kafka ブローカーのアドレスです。
カタログの properties.bootstrap.servers 設定と同じです。
value.format
Flink Kafka コネクタが Kafka メッセージバリューをシリアル化または逆シリアル化するために使用するフォーマットです。
値は
jsonです。value.fields-prefix
Kafka メッセージバリューのすべてのフィールドにカスタムプレフィックスを指定して、メッセージキーやメタデータのフィールドとの名前の競合を回避します。
カタログの
value.fields-prefix設定と同じです。value.json.infer-schema.flatten-nested-columns.enable
メッセージバリューの JSON 内のネストされた列を再帰的に展開するかどうかを指定します。
カタログの
infer-schema.flatten-nested-columns.enable設定と同じです。value.json.infer-schema.primitive-as-string
メッセージバリューのすべてのプリミティブ型を STRING 型として推論するかどうかを指定します。
カタログの
infer-schema.primitive-as-string設定と同じです。value.fields-include
メッセージバリューがメッセージキーのフィールドをどのように扱うかを定義します。
値は
EXCEPT_KEYで、メッセージバリューにメッセージキーのフィールドが含まれないことを意味します。このパラメーターは、メッセージキーが空でない場合にのみ設定されます。
key.format
Flink Kafka コネクタが Kafka メッセージキーをシリアル化または逆シリアル化するために使用するフォーマットです。
値は
jsonまたはrawです。このパラメーターは、メッセージキーが空でない場合にのみ設定されます。
メッセージキーが空ではなく、解析に失敗した場合、値は
rawです。解析が成功した場合、値はjsonです。key.fields-prefix
Kafka メッセージキーのすべてのフィールドにカスタムプレフィックスを指定して、メッセージバリューのフィールドとの名前の競合を回避します。
カタログの
key.fields-prefix設定と同じです。このパラメーターは、メッセージキーが空でない場合にのみ設定されます。
key.fields
Kafka メッセージキーから解析されたデータを格納するフィールドです。
解析されたキーフィールドのリストが自動的に入力されます。
このパラメーターは、メッセージキーが空でなく、テーブルが Upsert Kafka テーブルでない場合にのみ設定されます。