PyIceberg 是2026年初唯一完整支持Iceberg表生命周期、快照、Schema演进和元数据操作的纯Python客户端，不依赖JVM或Spark/Flink；需按场景显式安装子模块（如s3fs、glue），并严格区分REST与Glue Catalog配置及认证方式。
PyIceberg 是当前 Python 生态里唯一靠谱的 Iceberg 原生客户端
不是“之一”，是目前（2026 年初）唯一能完整支持 Iceberg 表生命周期管理、快照读取、Schema 演进和元数据操作的纯 Python 实现。它不依赖 JVM，不包装 Spark/Flink 的 Java API，而是直接解析 Iceberg 的 JSON 元数据与 Avro Manifest 文件，因此能跑在 Lambda、Docker 轻量容器甚至本地 notebook 里。
常见错误现象：ImportError: No module named 'pyiceberg' 或 ModuleNotFoundError: No module named 'pyiceberg.catalog.rest'——本质是没装对子模块；pyiceberg 默认不带任何 IO 后端，必须显式指定。
- 用 S3 + REST Catalog（如 S3 Tables）：装
pip install pyiceberg[s3fs,pyarrow]，别漏s3fs - 用 Glue Catalog：必须加
pip install pyiceberg[pyarrow,pandas,glue]，且boto3版本需 ≥ 1.34.0（否则glue_catalog.list_tables()报UnknownParameter） - 只读 Parquet 文件但不碰元数据？用
pyarrow.dataset更轻量，pyiceberg在这种场景下是杀鸡用牛刀
REST Catalog 和 Glue Catalog 的连接方式差异极大，不能混用配置
REST Catalog（如 AWS S3 Tables、Nessie、Tabular）靠 HTTP 请求访问元数据服务，所有认证、签名、region 都得手动塞进 load_catalog() 的 **kwargs；Glue Catalog 则走 AWS SDK 调用，依赖 boto3.session 的 region 和 credential 链，load_catalog() 只要传对 type="glue" 就自动复用环境变量或 profile。
典型坑：rest.sigv4-enabled="true" 忘设 → 403 Forbidden；rest.signing-name="s3tables" 写成 "s3" → SignatureDoesNotMatch；Glue Catalog 里 warehouse 配置被忽略（它由 Glue 自己管路径），但很多人还硬填导致 NamespaceAlreadyExistsError。
立即学习“Python免费学习笔记（深入）”；
- REST Catalog 示例关键参数：
uri（API 地址）、warehouse（ARN 或 S3 路径）、rest.sigv4-enabled、rest.signing-name、rest.signing-region - Glue Catalog 只需：
type="glue"+warehouse（可选，仅用于创建 namespace 时默认 location）+ 确保AWS_PROFILE或环境变量就位 - 别试图把 Glue 的
catalog_id塞进 REST 的**kwargs——类型不匹配，load_catalog()会静默忽略
表写入不是“append() 就完事”，文件提交和快照可见性有延迟
table.append() 只是生成新文件并更新元数据，但 Iceberg 的原子性靠的是“先写文件、再写 manifest、最后写 snapshot.json”三步。如果中间出错（比如 S3 权限不足导致 manifest 写失败），表状态可能卡在“半提交”状态，table.scan().to_arrow() 仍读不到新数据，但 table.current_snapshot() 已变。
常见错误现象：本地跑通，上 Lambda 就查不到刚插入的数据；或者 list_tables() 能看到表，scan() 却返回空 —— 很可能是 manifest 写入失败后没抛异常（尤其用 fsspec IO 时），或 S3 eventual consistency 导致新 manifest 还没同步到所有 endpoint。
- 务必检查
table.current_snapshot().manifest_list是否新增了条目 - 写入后加个简单验证：
len(list(table.scan().select("id").to_arrow())) > 0 - 生产环境别依赖“立刻可见”，查询侧建议加
table.refresh()再 scan，避免读到 stale snapshot
DuckDB + PyIceberg 是 Serverless 查询最稳组合，但要注意 Arrow schema 兼容边界
DuckDB 从 0.10 开始原生支持 Iceberg REST Catalog，但它只认 Arrow schema，不处理 Iceberg 的 type coercion（比如 TimestampType(without_timezone=True) 在 DuckDB 里会被当 TIMESTAMP，但若 Iceberg 表里存的是毫秒级 int96，DuckDB 会解析错）。
容易踩的坑：pyarrow.Table.from_pylist() 传的 dict 若含 datetime.date，Arrow 默认转成 date32，而 Iceberg 的 DateType 要求 date32，但 DuckDB 的 read_iceberg() 期望 date64 → 类型不匹配报 Invalid: Unsupported type。
- 写入前用
table.schema().as_arrow()拿真实 Arrow schema，再用pa.table(..., schema=...)构造 table - 读取时优先走
table.scan().to_arrow()，而非 DuckDB 直接read_iceberg()，可控性更强 - 时间字段统一用
pa.timestamp("us", tz=None)，避开int96和timestamp_ntz的模糊地带
Iceberg 的 Python 集成已经能覆盖 80% 的日常运维和分析需求，但它的“隐形契约”很多——比如 catalog 初始化时机、snapshot refresh 行为、IO 层重试策略——这些不会报错，只会让数据看起来“偶尔不对”。动手前，先读一遍 pyiceberg.catalog.Catalog 的 docstring，比看十篇博客有用。
