Setting the file. One moment.
Chapter 04 · Cloudflare Deploy
Subchapter 4.162
references/r2-data-catalog/README.mdMarkdown7 KBView on GitHub
Expert guidance for Cloudflare R2 Data Catalog - Apache Iceberg catalog built into R2 buckets.
New to R2 Data Catalog? Start here:
Quick reference? Jump to:
R2 Data Catalog is a managed Apache Iceberg REST catalog built directly into R2 buckets. It provides:
Open table format for analytics datasets in object storage. Features:
Use R2 Data Catalog for:
Don’t use for:
┌─────────────────────────────────────────────────┐
│ Query Engines │
│ (PyIceberg, Spark, Trino, Snowflake, DuckDB) │
└────────────────┬────────────────────────────────┘
│
│ REST API (OAuth2 token)
▼
┌─────────────────────────────────────────────────┐
│ R2 Data Catalog (Managed Iceberg REST Catalog)│
│ • Namespace/table metadata │
│ • Transaction coordination │
│ • Snapshot management │
└────────────────┬────────────────────────────────┘
│
│ Vended credentials
▼
┌─────────────────────────────────────────────────┐
│ R2 Bucket Storage │
│ • Parquet data files │
│ • Metadata files │
│ • Manifest files │
└─────────────────────────────────────────────────┘Key concepts:
https://<account-id>.r2.cloudflarestorage.com/iceberg/<bucket>)logs, analytics)| Resource | Limit | Notes |
|---|---|---|
| Namespaces per catalog | No hard limit | Organize tables logically |
| Tables per namespace | <10,000 recommended | Performance degrades beyond this |
| Files per table | <100,000 recommended | Run compaction regularly |
| Snapshots per table | Configurable retention | Expire >7 days old |
| Partitions per table | 100-1,000 optimal | Too many = slow metadata ops |
| Table size | Same as R2 bucket | 10GB-10TB+ common |
| API rate limits | Standard R2 API limits | Shared with R2 storage operations |
| Target file size | 128-512 MB | After compaction |
Public Beta (as of Jan 2026)
Start → Need analytics on object storage data?
│
├─ No → Use R2 directly for object storage
│
└─ Yes → Dataset >1GB with structured schema?
│
├─ No → Too small, use R2 + ad-hoc queries
│
└─ Yes → Need ACID transactions or schema evolution?
│
├─ No → Consider simpler solutions (Parquet on R2)
│
└─ Yes → Need multi-cloud/multi-tool access?
│
├─ No → D1 or external DB may be simpler
│
└─ Yes → ✅ Use R2 Data CatalogQuick check: If you answer “yes” to all:
→ R2 Data Catalog is a good fit.