R2 Data Catalog 说明文档

# Cloudflare R2 数据目录技能参考 关于 Cloudflare R2 数据目录的专家指南——内置于 R2 存储桶中的 Apache Iceberg 目录。 ## 阅读顺序 **初次接触 R2 数据目录？** 从这里开始： 1. 阅读下方的“什么是 R2 数据目录？”和“何时使用” 2. [configuration.md](configuration.md) - 启用目录，创建令牌 3. [patterns.md](patterns.md) - PyIceberg 设置与常见模式 4. [api.md](api.md) - 按需查阅 REST API 参考 5. [gotchas.md](gotchas.md) - 遇到问题时的故障排除 **快速参考？** 跳转至： - [在存储桶上启用目录](configuration.md#enable-catalog-on-bucket) - [PyIceberg 连接模式](patterns.md#pyiceberg-connection-pattern) - [权限错误](gotchas.md#permission-errors) ## 什么是 R2 数据目录？ R2 数据目录是一个内置于 R2 存储桶中的**托管 Apache Iceberg REST 目录**。它提供： - **Apache Iceberg 表** - ACID 事务、模式演进、时间旅行查询 - **零出口费用** - 从任何云/区域查询，无需数据传输费用 - **标准 REST API** - 兼容 Spark、PyIceberg、Snowflake、Trino、DuckDB - **无需基础设施** - 完全托管，无需运行目录服务器 - **公开测试版** - 所有 R2 订阅者均可使用，除 R2 存储费用外无额外成本 ### 什么是 Apache Iceberg？ 用于对象存储中分析数据集的开放表格式。特点： - **ACID 事务** - 安全的并发读写 - **元数据优化** - 无需全表扫描即可快速查询 - **模式演进** - 添加/重命名/删除列而无需重写数据 - **时间旅行** - 查询历史快照 - **分区** - 组织数据以实现高效查询 ## 何时使用 **适用于：** - **日志分析** - 存储和查询应用程序/系统日志 - **数据湖/数据仓库** - 由多个引擎查询的分析数据集 - **BI 流水线** - 聚合数据以生成仪表板和报告 - **多云分析** - 跨云共享数据，无出口费用 - **时序数据** - 事件流、指标、传感器数据 **不适用于：** - **事务性工作负载** - 请改用 D1 或外部数据库 - **亚秒级延迟** - Iceberg 针对批处理/分析查询进行了优化 - **小型数据集 (<1GB)** - 设置开销不划算 - **非结构化数据** - 直接将文件存储在 R2 中，而非作为 Iceberg 表 ## 架构 ┌─────────────────────────────────────────────────┐ │ 查询引擎 │ │ (PyIceberg, Spark, T