用 MatrixOne 读写 Iceberg 订单表

Iceberg 文档索引:Iceberg 文档总览。

假设订单已经由 Spark 写入数据湖,业务需要直接用 MatrixOne SQL 查询订单,再补录一笔订单。本教程从空的本地环境开始,最终验证新订单已写回同一张 Iceberg 表。

流程是:启动 Nessie REST 目录与 MinIO 对象存储 → 用 Spark 创建 Iceberg 表并写入五笔订单 → 在 MatrixOne 中注册目录与外表 → 查询和补录订单 → 清理演示资源。

适用范围:使用包含 Iceberg 功能的 MatrixOne v4.2.0 或更新版本。本教程采用 MatrixOne 源码仓库的本地 Tier A 环境;Nessie、MinIO、数据库都运行在同一台机器上。命令中的 root/111、MinIO 测试凭据和 HTTP 端点仅用于本地演示。

准备环境

需要 Git、Docker Compose、MySQL 客户端、Java,以及带 spark-sql 命令的 Spark 3.5。首次执行 Spark 脚本时还需要联网下载 Iceberg 和 S3 依赖。MatrixOne 的构建依赖和机器资源要求参见从源码部署 MatrixOne。

在 MatrixOne 源码仓库根目录运行以下命令。后续终端命令也都在这个目录执行:

make build
make dev-up-iceberg-tier-a
curl -fsS http://127.0.0.1:19120/iceberg/v1/config > /dev/null

make dev-up-iceberg-tier-a 启动 Nessie(127.0.0.1:19120)和 MinIO(127.0.0.1:9000),并准备 s3://mo-iceberg/warehouse。最后一条命令成功且无输出,表示 REST 目录已可访问。端口 6001、9000、9001、19120 和 19121 应空闲。

备注

如果 Docker 提示源码仓库固定的 MinIO 镜像标签 not found,可改用源码仓库提供的本地服务脚本:先在 PATH 中准备 minio、mc、nessie 三个可执行程序,再运行 make dev-up-iceberg-tier-a-brew。这条路径使用相同的默认端点。采用它时,第 1 步改为直接运行 etc/launch-minio-local/tier-a/seed-iceberg-tier-a.sh,清理时运行 make dev-down-iceberg-tier-a-brew。

在另一个终端启动 MatrixOne,并保持这个终端运行:

MO_ICEBERG_ALLOW_PLAIN_HTTP=1 ./mo-service -launch etc/launch-minio-local/launch.toml

本地 cn.toml 已启用 Iceberg 的读取、写入、DML 和删除开关。MO_ICEBERG_ALLOW_PLAIN_HTTP=1 仅为访问本地 HTTP REST 目录。等待服务启动后,在第三个终端确认连接:

mysql -h 127.0.0.1 -P 6001 -u root -p111 -e 'SELECT 1;'

1. 用 Spark 创建真实 Iceberg 表

源码仓库的 Tier A 种子脚本 会调用 Spark,在 Nessie 和 MinIO 中创建测试用 Iceberg v2 表。它还会生成其他测试表;本教程只使用 tpch_sf01.orders。运行:

make dev-seed-iceberg-tier-a

成功时会显示 Tier A seed complete.。脚本没有设置 MO_ICEBERG_MO_SQL_CMD 时会跳过 MatrixOne 映射;下一步由我们手动完成。脚本里的 Spark SQL 会给 tpch_sf01.orders 写入五行,并按 bucket 分区。重复运行种子脚本会删除并重建这些测试表,所以补录订单后不要再次执行它。

2. 在 MatrixOne 中注册目录和映射外表

连接 MatrixOne:

mysql -h 127.0.0.1 -P 6001 -u root -p111

在 MySQL 客户端中执行:

CREATE DATABASE iceberg_orders_demo;

CREATE ICEBERG CATALOG iceberg_orders_cat WITH (
  'type' = 'rest',
  'uri' = 'http://127.0.0.1:19120/iceberg',
  'warehouse' = 's3://mo-iceberg/warehouse',
  'auth_mode' = 'none'
);

CALL iceberg_register_access(
  'iceberg_orders_cat',
  'scope=cluster,account_id=0,external_principal=local-tier-a,endpoint=localhost,region=us-east-1,bucket=mo-iceberg'
);

CREATE EXTERNAL TABLE iceberg_orders_demo.orders (
  order_id BIGINT,
  cust_id BIGINT,
  order_status TEXT,
  order_date DATE,
  total_price DECIMAL(12, 2),
  bucket INT
) ENGINE = ICEBERG WITH (
  'catalog' = 'iceberg_orders_cat',
  'namespace' = 'tpch_sf01',
  'table' = 'orders',
  'ref' = 'main',
  'read_mode' = 'append_only',
  'write_mode' = 'append_only'
);

这一步的列定义与 Spark 生成的表一致。MatrixOne 不会自动把远端 Iceberg schema 变成外表列。iceberg_register_access 同时注册访问主体映射和数据驻留策略;只有目录记录而没有这两项策略时,外表访问会被拒绝。生产环境应按实际主体、端点、区域和存储桶配置策略,并使用受保护的目录连接。

可以查看刚创建的映射:

SHOW ICEBERG CATALOGS;
SHOW ICEBERG NAMESPACES FROM iceberg_orders_cat;
SHOW ICEBERG TABLES FROM iceberg_orders_cat.tpch_sf01;

SHOW ICEBERG NAMESPACES 和 SHOW ICEBERG TABLES 展示的是 MatrixOne 已注册的外表映射,不会发现尚未映射的远端表。

3. 查询并核对订单

SELECT COUNT(*) AS order_count, SUM(total_price) AS total_amount
FROM iceberg_orders_demo.orders;

SELECT order_id, total_price
FROM iceberg_orders_demo.orders
WHERE bucket = 2
ORDER BY order_id;

第一条查询应得到 order_count = 5、total_amount = 1501.60;第二条应返回 order_id 为 3 和 4 的两行,金额分别为 300.75 和 400.00。这些值来自 Spark 种子数据,可用来确认 MatrixOne 读取了真实 Iceberg 文件,而不只是创建了表定义。

4. 通过 MatrixOne 补录订单

INSERT INTO iceberg_orders_demo.orders
  (order_id, cust_id, order_status, order_date, total_price, bucket)
VALUES (6, 60, 'O', '2026-03-02', 600.00, 3);

SELECT COUNT(*) AS order_count, SUM(total_price) AS total_amount
FROM iceberg_orders_demo.orders;

SELECT order_id, order_status, total_price
FROM iceberg_orders_demo.orders
WHERE order_id = 6;

此时应得到 order_count = 6、total_amount = 2101.60,且最后一条查询返回订单 6。这笔数据写入的是 Nessie 目录中的同一张 Iceberg 表,而不是 MatrixOne 本地表。如果要从 Spark 再次核对,可沿用第 1 步脚本的 Spark catalog 配置,查询 tiera.tpch_sf01.orders;不要重新运行种子脚本。

清理演示资源

先在 MySQL 客户端删除映射,再撤销访问策略并删除目录:

DROP DATABASE iceberg_orders_demo;
CALL iceberg_unregister_access('iceberg_orders_cat');
DROP ICEBERG CATALOG iceberg_orders_cat;

这只删除 MatrixOne 中的演示对象,不会删除 Nessie 和 MinIO 中的 Iceberg 表。如需停止本地服务,在源码仓库运行 make dev-down-iceberg-tier-a;MinIO 数据会保留,手动清除数据前请确认其中没有其他测试内容。

相关参考