CREATE EXTERNAL TABLE … ENGINE = KAFKA

通过 ENGINE = KAFKA 子句将 MatrixOne 外部表映射到 Apache Kafka 主题的单个分区。该表只读,每条 Kafka 消息值必须恰好解析为一条记录,逐消息的元数据通过合成的 __mo_* 列暴露。

描述

CREATE EXTERNAL TABLE ... ENGINE = KAFKA 将 MatrixOne 外部表映射到 Kafka 主题分区。查询该表时,行数据从主题中流式读取。每条 Kafka 消息值必须恰好解析为一条记录:format=csv 时,是一条使用配置的分隔符、字段数等于声明列数的 CSV 记录;format=jsonl 时,是一个键包含所有声明列名的 JSON 对象。

该表只读:支持 SELECT,拒绝写入。对 Kafka 外部表执行 ALTER TABLE 会被拒绝。选项在 CREATE 阶段校验,无需连接 broker;只有在扫描该表时才会拨号连接 broker。

语法

CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name (
    column1 type1,
    column2 type2,
    ...
) ENGINE = KAFKA [WITH ("option" = 'value' [, "option" = 'value'] ...)];

参数

选项

是否必填

说明

brokers

是

逗号分隔的 host:port Kafka broker 列表。

topic

是

要读取的 Kafka 主题名称。

partition

否

要读取的分区号,默认 0。每张表一个分区;读取多个分区需创建多张表。

autocommit

否

false(默认)或 true。为 false 时读取需要显式的 __mo_read_start_id;为 true 时,0(默认)表示最早(含),-1 表示最新。

group

否

消费组名称,默认为 mo_kafka_<db>_<table>。

format

否

csv(默认)或 jsonl。

separator

否

仅 CSV。单个字符;默认 ,。

合成列

Kafka 外部表暴露在 SELECT * 中隐藏但可按名称查询的合成元数据列:

列

类型

含义

__mo_message_id

bigint

消息的 Kafka offset。

__mo_message_ts

timestamp(3)

Kafka 消息时间戳。

__mo_message_key

varchar

消息键(缺失时为 NULL)。

__mo_message_value

varchar

原始消息值。

__mo_read_start_id

bigint

读取控制:上次已消费的 offset;从 start_id + 1 开始读取。

__mo_read_size

bigint

读取控制:限制消息数量;0 表示不限制。

__mo_read_timeout

bigint

读取控制:超过该秒数无新消息则结束读取;0 表示一直阻塞。

读取控制

顶层 <control> = <constant> 合取式在编译期解析,用于定位读取位置而不是过滤行。它们会从谓词中被消费:

SELECT * FROM kt
WHERE __mo_read_start_id = 1000
  AND __mo_read_size = 1000000
  AND __mo_read_timeout = 10;

LAST_KAFKA_MESSAGE_ID() 返回本会话最近一次完成的 Kafka 扫描返回的最后一条消息的 offset(扫描前为 NULL)。在 autocommit=false 时,把它作为下一次的 __mo_read_start_id 即可实现精确一次消费。

使用说明

  • 只读:向 Kafka 外部表写入会被拒绝。

  • 读取隔离:扫描以 Kafka 的 read_committed 隔离级别消费;已中止或仍处于打开状态的生产者事务中的记录永远不会以行形式出现。

  • 校验:重复、未知或非法的选项会在 CREATE 阶段被拒绝。会导致算术溢出的控制值会在编译期被拒绝。

  • 保留名称:合成的 __mo_* 列名是保留的;表或列不能声明这些名称。

示例

以下示例创建 Kafka 外部表,往返查看其 DDL,并演示校验错误。这些内容都在 DDL 或编译期解析完成,因此无需 broker:

DROP DATABASE IF EXISTS kafka_ext_demo;
CREATE DATABASE kafka_ext_demo;
USE kafka_ext_demo;

CREATE EXTERNAL TABLE kt (a INT, b VARCHAR(100))
ENGINE = KAFKA WITH ('brokers' = '127.0.0.1:19092', 'topic' = 'events');

SHOW CREATE TABLE kt;

CREATE EXTERNAL TABLE kt2 (a INT, b VARCHAR(100))
ENGINE = KAFKA WITH ('brokers' = 'h1:9092,h2:9092', 'topic' = 't2', 'partition' = '3', 'autocommit' = 'true', 'group' = 'g2', 'format' = 'jsonl');

SHOW CREATE TABLE kt2;

-- NULL before any completed Kafka scan
SELECT last_kafka_message_id();

-- Expected-Success: false
CREATE EXTERNAL TABLE bad (a INT) ENGINE = KAFKA WITH ('brokers' = 'nohostport', 'topic' = 't');

DROP DATABASE kafka_ext_demo;

读取控制与精确一次消费链需要可访问的 broker,因此仅作语法模板而非可直接粘贴执行的脚本:

SELECT * FROM kt
WHERE __mo_read_start_id = 1000
  AND __mo_read_size = 100000;

SELECT last_kafka_message_id();   -- e.g. 4711

SELECT * FROM kt
WHERE __mo_read_start_id = 4711;  -- continues after

相关参考