导航|地址|刷新
Manage catalogs

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/r2/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

R2

/

Overview

Get started

Overview

Workers API

S3

CLI

How R2 works

Data migration

Overview

Super Slurper

Sippy

Migration Strategies

Buckets

Overview

Create new buckets

Public buckets

Configure CORS

Local uploadsBeta

Delete buckets

Bucket locks

Event notifications

Object lifecycles

Storage classes

Objects

Overview

Upload objects

Download objects

Delete objects

API

Overview

Authentication

Workers API

Use R2 from Workers

Use the R2 multipart API from Workers

Workers API reference

S3

S3 API compatibility

Extensions

Presigned URLs

Temporary credentials

Error codes

R2 Data CatalogBeta

Overview

Getting started

Manage catalogs

Table maintenance

Connect to Iceberg engines

DuckDB

PyIceberg

Snowflake

Spark (PySpark)

Spark (Scala)

StarRocks

Trino

Deleting data

Observability

Metrics and analytics

Platform

Pricing

R2 SQL ↗Beta

Examples

Overview

Multi-cloud setup ↗

Authenticate against R2 API using auth tokens

Authenticate against R2 with temporary credentials

Rclone

S3 SDKs

aws CLI

aws-sdk-go

aws-sdk-java

aws-sdk-js

aws-sdk-js-v3

aws-sdk-kotlin

aws-sdk-net

aws-sdk-php

aws-sdk-ruby

aws-sdk-rust

aws4fetch

boto3

Configure custom headers

s3mini

Terraform

Terraform (AWS)

Use SSE-C

Use the Cache API

Tutorials

Videos ↗

Demos and architectures

Platform

Choose a storage product ↗

Event subscriptions

Audit Logs

Limits

Metrics and analytics

Release notes

Troubleshooting

Reference

Consistency model

Data location

Data security

Durability

Unicode interoperability

Wrangler commands

Pricing

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

R2 llms.txt ↗

R2 llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/R2

/R2 Data Catalog

/Manage catalogs

Manage catalogs

Last updated Jul 13, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewEnable R2 Data Catalog on a bucketDisable R2 Data Catalog on a bucketEnable compactionDisable compactionEnable snapshot expirationDisable snapshot expirationAuthenticate your Iceberg engine Create API token in the dashboard Create API token via APIR2 Local UploadsLimitationsLearn more

Learn how to:

Enable and disable R2 Data Catalog on your buckets.

Enable and disable table maintenance features like compaction and snapshot expiration.

Authenticate Iceberg engines using API tokens.

Enable R2 Data Catalog on a bucket

Enabling the catalog on a bucket turns on the REST catalog interface and provides a Catalog URI and Warehouse name required by Iceberg clients. Once enabled, you can create and manage Iceberg tables in that bucket.

In the Cloudflare dashboard, go to the R2 Data Catalog page.
Go to R2 Data Catalog ↗

Select Create catalog.

Enter an R2 bucket name. You can select an existing bucket or enter a new bucket name to create one. If creating a new bucket, optionally select a location hint.

Select Next to configure table maintenance. Optionally enable compaction and snapshot expiration during setup.

Review your configuration and select Create catalog.

Once created, the catalog detail page displays your Catalog URI and Warehouse name.

To enable the catalog on your bucket, run the r2 bucket catalog enable command:
npx wrangler r2 bucket catalog enable <BUCKET_NAME>
After enabling, Wrangler will return your catalog URI and warehouse name.

Disable R2 Data Catalog on a bucket

When you disable the catalog on a bucket, it immediately stops serving requests from the catalog interface. Any Iceberg table references stored in that catalog become inaccessible until you re-enable it.

In the Cloudflare dashboard, go to the R2 Data Catalog page.
Go to R2 Data Catalog ↗

Select the catalog you want to disable.

Go to the Settings tab and scroll to the Disable section.

Select Disable and confirm.

To disable the catalog on your bucket, run the r2 bucket catalog disable command:
npx wrangler r2 bucket catalog disable <BUCKET_NAME>

Enable compaction

Compaction improves query performance by combining the many small files created during data ingestion into fewer, larger files according to the set target file size. For more information about compaction and why it is valuable, refer to About compaction.

API token permission requirements

Table maintenance operations such as compaction and snapshot expiration require a Cloudflare API token with both R2 storage and R2 Data Catalog read/write permissions to act as a service credential.

Refer to Authenticate your Iceberg engine for details on creating a token with the required permissions.

In the Cloudflare dashboard, go to the R2 Data Catalog page.
Go to R2 Data Catalog ↗

Select the catalog you want to enable compaction on.

Go to the Settings tab and scroll to the Table Maintenance section.

Select Enable or Edit next to compaction.

Toggle compaction on and optionally set a target file size. The default is 128 MB.

Select Save.

Note

If no service credential has been generated for this catalog, the dashboard will prompt you to generate one. Compaction requires a credential to access and rewrite files in your bucket.

To enable the compaction on your catalog, run the r2 bucket catalog compaction enable command:
# Enable catalog-level compaction (all tables)npx wrangler r2 bucket catalog compaction enable <BUCKET_NAME> --target-size 128 --token <API_TOKEN># Enable compaction for a specific tablenpx wrangler r2 bucket catalog compaction enable <BUCKET_NAME> <NAMESPACE> <TABLE> --target-size 128

Table-level vs Catalog-level compaction

Catalog-level: Applies to all tables in the bucket; requires an API token as a service credential.

Table-level: Applies to a specific table only.

Once enabled, compaction applies retroactively to all existing tables (for catalog-level compaction) or the specified table (for table-level compaction).

Disable compaction

Disabling compaction will prevent the process from running for all tables (catalog level) or a specific table (table level). You can re-enable it at any time.

In the Cloudflare dashboard, go to the R2 Data Catalog page.
Go to R2 Data Catalog ↗

Select the catalog you want to disable compaction on.

Go to the Settings tab and scroll to the Table Maintenance section.

Select Edit next to compaction.

Toggle compaction off.

Select Save.

To disable the compaction on your catalog, run the r2 bucket catalog compaction disable command:
# Disable catalog-level compaction (all tables)npx wrangler r2 bucket catalog compaction disable <BUCKET_NAME># Disable compaction for a specific tablenpx wrangler r2 bucket catalog compaction disable <BUCKET_NAME> <NAMESPACE> <TABLE>

Enable snapshot expiration

Snapshot expiration automatically removes old table snapshots and any unreferenced data files to reduce metadata overhead and storage costs. You can configure:

Max snapshot age - Snapshots older than this duration are expired. Specify a value followed by a unit (d for days, h for hours, m for minutes, s for seconds). For example, 7d expires snapshots older than 7 days.

Min snapshots to keep - The minimum number of snapshots to retain, regardless of age.

In the Cloudflare dashboard, go to the R2 Data Catalog page.
Go to R2 Data Catalog ↗

Select the catalog you want to enable snapshot expiration on.

Go to the Settings tab and scroll to the Table Maintenance section.

Select Enable or Edit next to snapshot expiration.

Toggle snapshot expiration on.

Set the Max snapshot age and Min snapshots to keep values.

Select Save.

Note

Snapshot expiration commands are available as of Wrangler version 4.56.0.

To enable snapshot expiration on your catalog, run the r2 bucket catalog snapshot-expiration enable command:
# Enable catalog-level snapshot expiration (all tables)npx wrangler r2 bucket catalog snapshot-expiration enable <BUCKET_NAME> \ --token <API_TOKEN> \ --older-than-days 7 \ --retain-last 10# Enable snapshot expiration for a specific tablenpx wrangler r2 bucket catalog snapshot-expiration enable <BUCKET_NAME> <NAMESPACE> <TABLE> \ --older-than-days 2 \ --retain-last 5

Disable snapshot expiration

Disabling snapshot expiration prevents the process from running for all tables (catalog level) or a specific table (table level). You can re-enable snapshot expiration at any time.

In the Cloudflare dashboard, go to the R2 Data Catalog page.
Go to R2 Data Catalog ↗

Select the catalog you want to disable snapshot expiration on.

Go to the Settings tab and scroll to the Table Maintenance section.

Select Edit next to snapshot expiration.

Toggle snapshot expiration off.

Select Save.

# Disable catalog-level snapshot expiration (all tables)npx wrangler r2 bucket catalog snapshot-expiration disable <BUCKET_NAME># Disable snapshot expiration for a specific tablenpx wrangler r2 bucket catalog snapshot-expiration disable <BUCKET_NAME> <NAMESPACE> <TABLE>

Authenticate your Iceberg engine

To connect your Iceberg engine to R2 Data Catalog, you must provide a Cloudflare API token with both R2 Data Catalog permissions and R2 storage permissions. Iceberg engines interact with R2 Data Catalog to perform table operations. The catalog also provides engines with SigV4 credentials, which are required to access the underlying data files stored in R2.

R2 Data Catalog supports both read-only and read-write tokens:

Read-only operations (for example, listing namespaces, loading tables, and querying data) require a token with read access to R2 Data Catalog and R2 storage.

Write operations (for example, creating or dropping tables and committing transactions) require a token with read and write access to R2 Data Catalog and R2 storage.

Use a read-only token for query engines and clients that only read data (such as R2 SQL, DuckDB, or PyIceberg readers), and a read-write token for engines and pipelines that create tables or write data.

Vended credentials inherit your token's R2 storage permissions

When an engine loads credentials from the catalog, R2 Data Catalog returns SigV4 credentials that inherit the R2 storage permissions of the API token used to authenticate. A token with read-only R2 Data Catalog access but read-write R2 storage access can still be used to write objects (including catalog metadata files) to the underlying bucket. To ensure read-only access to your data, scope the R2 storage permission to read-only as well.

Create API token in the dashboard

Create an R2 API token with the permissions matching your workload:

Admin Read & Write — for engines and pipelines that read and write data. Includes read and write access to both R2 Data Catalog and R2 storage.

Admin Read only — for query engines and clients that only read data. Includes read access to both R2 Data Catalog and R2 storage.

Providing the resulting token value to your Iceberg engine gives it the ability to manage catalog metadata and handle data operations (reads or writes to R2).

Create API token via API

To create an API token programmatically for use with R2 Data Catalog, you need to specify both R2 Data Catalog and R2 storage permission groups in your Access Policy.

Example read-write Access Policy

Use read and write permission groups for engines and pipelines that create tables or write data:
[ { "id": "f267e341f3dd4697bd3b9f71dd96247f", "effect": "allow", "resources": { "com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_default_my-bucket": "*", "com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_eu_my-eu-bucket": "*" }, "permission_groups": [ { "id": "d229766a2f7f4d299f20eaa8c9b1fde9", "name": "Workers R2 Data Catalog Write" }, { "id": "2efd5506f9c8494dacb1fa10a3e7d5b6", "name": "Workers R2 Storage Bucket Item Write" } ] }]

Example read-only Access Policy

Use read permission groups for query engines and clients that only read data:
[ { "id": "f267e341f3dd4697bd3b9f71dd96247f", "effect": "allow", "resources": { "com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_default_my-bucket": "*", "com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_eu_my-eu-bucket": "*" }, "permission_groups": [ { "id": "45db74139a62490b9b60eb7c4f34994b", "name": "Workers R2 Data Catalog Read" }, { "id": "6a018a9f2fc74eb6b293b0c548f38b39", "name": "Workers R2 Storage Bucket Item Read" } ] }]
To learn more about how to create API tokens for R2 Data Catalog using the API, including required permission groups and usage examples, refer to the Create API tokens via API documentation.

R2 Local Uploads

Local Uploads writes object data to a nearby location, then asynchronously copies it to your bucket. Data is queryable immediately and remains strongly consistent. This can significantly improve latency of writes from Apache Iceberg clients outside of the region of the respective R2 Data Catalog bucket.

To enable R2 Local Uploads, you can use the following Wrangler command:
npx wrangler r2 bucket catalog local-uploads enable <R2_Data_Catalog_BUCKET_NAME>

Limitations

R2 Data Catalog does not currently support R2 buckets in a non-default jurisdiction.

Learn more

Get started

Learn how to enable the R2 Data Catalog on your bucket, load sample data, and run your first query.

Connect to Iceberg engines

Find detailed setup instructions for Apache Spark and other common query engines.

PreviousGetting startedNextTable maintenance

Was this helpful?

YesNo

Edit pageReport issue

On this page

Overview

Enable R2 Data Catalog on a bucket

Disable R2 Data Catalog on a bucket

Enable compaction

Disable compaction

Enable snapshot expiration

Disable snapshot expiration

Authenticate your Iceberg engine

Create API token in the dashboard

Create API token via API

R2 Local Uploads

Limitations

Learn more

Edit pageReport issue

Getting started
PlansContact salesPartnersFind a partnerStartupsUnder attack?Domain name search

Company
AboutCareersInvestorsPressPress kitGlobal network

Public interest
Project GalileoAthenian ProjectCloudflare for CampaignsProject Fairshot
…(内容过长已截断)

------
导航页打开网址