R2 Data Catalog 常见陷阱

# 常见问题与故障排除 常见问题 → 原因 → 解决方案。 ## 权限错误 ### 401 未授权 **错误：** `"401 Unauthorized"` **原因：** 令牌缺少 R2 数据目录权限。 **解决方案：** 使用“管理员读写”令牌（包含目录 + 存储权限）。使用 `catalog.list_namespaces()` 进行测试。 ### 403 禁止访问 **错误：** 数据文件出现 `"403 Forbidden"` **原因：** 令牌缺少存储权限。 **解决方案：** 令牌需要同时具备 R2 数据目录 + R2 存储桶项目权限。 ### 令牌轮换问题 **错误：** 轮换后新令牌失效。 **解决方案：** 创建新令牌 → 在测试环境测试 → 更新生产环境 → 监控 24 小时 → 撤销旧令牌。 ## 目录 URI 问题 ### 404 未找到 **错误：** `"404 Catalog not found"` **原因：** 未启用目录或 URI 错误。 **解决方案：** 运行 `wrangler r2 bucket catalog enable `。URI 必须是 HTTPS，包含 `/iceberg/` 且存储桶名称区分大小写。 ### 仓库错误 **错误：** 无法创建/加载表。 **原因：** 仓库名称 ≠ 存储桶名称。 **解决方案：** 设置 `warehouse="bucket-name"` 以与存储桶名称完全匹配。 ## 表与模式问题 ### 表/命名空间已存在 **错误：** `"TableAlreadyExistsError"` **解决方案：** 使用 try/except 加载现有表或先进行检查。 ### 命名空间未找到 **错误：** 无法创建表。 **解决方案：** 先创建命名空间：`catalog.create_namespace("ns")` ### 模式演进错误 **错误：** 模式更新时出现 `"422 Validation"`。 **原因：** 不兼容的更改（必填字段、类型收缩）。 **解决方案：** 仅添加可为空的列，或进行兼容的类型扩展（int→long，float→double）。 ## 数据与查询问题 ### 扫描结果为空 **错误：** 扫描未返回数据。 **原因：** 过滤器或分区列不正确。 **解决方案：** 先不加过滤器进行测试：`table.scan().to_pandas()`。验证分区列名称。 ### 查询缓慢 **错误：** 性能随时间下降。 **原因：** 小文件过多。 **解决方案：** 检查文件数量，如果 >1000 个或平均大小 <10MB，则进行压缩。参见 [api.md](api.md#compaction)。 ### 类型不匹配 **错误：** 追加数据时出现 `"Cannot cast"`。 **原因：** PyArrow 类型与 Iceberg 模式不匹配。 **解决方案：** 转换为 int64（Iceberg 默认值），而非 int32。检查 `table.schema()`。 ## 压缩问题 ### 压缩问题 **问题：** 文件数量未变或压缩耗时数小时。 **原因：** 目标大小设置过大，或表对于 PyIceberg 来说太大。 **解决方案：** 仅在平均大小 <50MB 时进行压缩。F