PyIceberg 表读写与显式 SQL 桥接

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

验证边界

参考 PyIceberg 0.12.0、PyArrow 26.0.0。验证实际创建 catalog、追加 typed Arrow、按 load_id 扫描快照,然后由 DBAPI 写入 MatrixOne。不是 MatrixOne 原生 Iceberg connector,也不是将 Iceberg 快照与 SQL 事务原子提交。

主计划5000个组合中4500通过,500个原生转换组合在 SQL 写入前因 Arrow binary_join_element_wise(large_string,string,string) 缺少内核失败;MySQL 对照同样失败。这属于中间表示/计算内核问题,不能归为 MO SQL bug,也不能把本工具写为5000全通过。下面给出基础 append/scan 的最小示例。

安装与类型选择

安装 pyiceberg[sql-sqlite,pyarrow] pymysql,先完成共用连接。这里使用本机 SQLite catalog 和文件 warehouse,以验证格式桥接;生产 catalog、对象存储权限和并发提交要另测。

SQL 类型

Iceberg 表示

条件

DECIMAL(38,18)

decimal(38,18)

用 Decimal,不经过 float

DECIMAL(65,30)

精确字符串

显式适配,保留 precision/scale

UInt64/BIT64

decimal(20,0)

无符号范围,BIT 字节解码另记

TIME(6)

long,带符号微秒

不是 time-of-day

DATETIME(6)

timestamp,微秒

保留时区契约

SET

字符串列表

空集合与 NULL 分开,SQL 域约束需另验

from decimal import Decimal
from pathlib import Path
from uuid import uuid4
import pyarrow as pa
from pyiceberg.catalog import load_catalog
from pyiceberg.schema import Schema
from pyiceberg.types import NestedField, LongType, DecimalType, BinaryType, StringType
from pyiceberg.io.pyarrow import schema_to_pyarrow
from pyiceberg.expressions import EqualTo
from mo_common import connect

root = Path("iceberg_demo").resolve()
root.mkdir(exist_ok=True)
warehouse = root / "warehouse"
warehouse.mkdir(exist_ok=True)
cat = load_catalog("demo", type="sql", uri="sqlite:///" + str(root / "catalog.db"),
                   warehouse=warehouse.as_uri())
ns = "run_" + uuid4().hex
cat.create_namespace(ns)
schema = Schema(NestedField(1,"id",LongType(),required=True),
                NestedField(2,"amount",DecimalType(38,18),required=False),
                NestedField(3,"payload",BinaryType(),required=False),
                NestedField(4,"label",StringType(),required=False),
                NestedField(5,"rev",LongType(),required=False),
                NestedField(6,"load_id",StringType(),required=True))
t = cat.create_table((ns,"rows"), schema=schema)
load_id = uuid4().hex
rows = [dict(id=301, amount=Decimal("12345678901234567890.123456789012345678"),
             payload=b"\x00\xff\x80", label="Iceberg😀", rev=0, load_id=load_id)]
arrow = pa.Table.from_pylist(rows, schema=schema_to_pyarrow(t.schema()))
t.append(arrow)
scanned = t.scan(row_filter=EqualTo("load_id", load_id)).to_arrow().to_pylist()
assert scanned == rows
print("snapshot", t.current_snapshot().snapshot_id, "load_id", load_id)
with connect() as d:
    try:
        with d.cursor() as c:
            c.executemany("INSERT INTO lake_demo(id,amount,payload,label,rev) VALUES(%s,%s,%s,%s,%s)",
                          [[r[k] for k in ("id","amount","payload","label","rev")] for r in scanned])
        d.commit()
    except Exception:
        d.rollback()
        raise

转换排障、模式与恢复

遇到上述字符串内核错误时先输出 Arrow schema 和各输入类型。可尝试把参与运算的列/标量统一为 string,再转回表 schema 所要求的类型;这是待独立回归的修复方案,不能据此把失败案例改判为通过。改 schema 时用 Iceberg update_schema(),然后同步 SQL DDL;添加字段不能代表改名、缩窄或删除字段也可自动传播。

Iceberg append 不强制 SQL 主键唯一。重复 append 可能产生重复行,即使 SQL sink 之后拒绝重复。记录 load_id、snapshot_id、schema_id、文件哈希与 SQL 提交状态;未知提交时 reload catalog 并扫描该 load_id,不能见到异常就再 append 一次。只有识别出的 catalog CAS/锁竞争才可有限重试,其他错误原样保留。

扫描物理缺失行不是可靠删除事件。跨表快照与 SQL 的一致性依赖显式事件/合并协议,必须分别验证 tombstone、快照重放和失败恢复。