Skip to content
Cloudflare API
Start here
API Reference

R2 Data Catalog

List R2 catalogs
r2_data_catalog.list(R2DataCatalogListParams**kwargs) -> R2DataCatalogListResponse
GET/accounts/{account_id}/r2-catalog
Get R2 catalog details
r2_data_catalog.get(strbucket_name, R2DataCatalogGetParams**kwargs) -> R2DataCatalogGetResponse
GET/accounts/{account_id}/r2-catalog/{bucket_name}
Enable R2 bucket as a catalog
r2_data_catalog.enable(strbucket_name, R2DataCatalogEnableParams**kwargs) -> R2DataCatalogEnableResponse
POST/accounts/{account_id}/r2-catalog/{bucket_name}/enable
Disable R2 catalog
r2_data_catalog.disable(strbucket_name, R2DataCatalogDisableParams**kwargs)
POST/accounts/{account_id}/r2-catalog/{bucket_name}/disable
ModelsExpand Collapse
class R2DataCatalogListResponse: …

Contains the list of catalogs.

warehouses: List[Warehouse]

Lists catalogs in the account.

id: str

Use this to uniquely identify the catalog.

formatuuid
bucket: str

Specifies the associated R2 bucket name.

name: str

Specifies the catalog name (generated from account and bucket name).

status: Literal["active", "inactive"]

Indicates the status of the catalog.

One of the following:
"active"
"inactive"
credential_status: Optional[Literal["present", "absent"]]

Shows the credential configuration status.

One of the following:
"present"
"absent"
maintenance_config: Optional[WarehouseMaintenanceConfig]

Configures maintenance for the catalog.

compaction: Optional[WarehouseMaintenanceConfigCompaction]

Configures compaction for catalog maintenance.

state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"
target_size_mb: Literal["64", "128", "256", "512"]

Sets the target file size for compaction in megabytes. Defaults to "128".

One of the following:
"64"
"128"
"256"
"512"
snapshot_expiration: Optional[WarehouseMaintenanceConfigSnapshotExpiration]

Configures snapshot expiration settings.

max_snapshot_age: str

Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d".

min_snapshots_to_keep: int

Specifies the minimum number of snapshots to retain. Defaults to 100.

formatint64
minimum1
state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"
class R2DataCatalogGetResponse: …

Contains R2 Data Catalog information.

id: str

Use this to uniquely identify the catalog.

formatuuid
bucket: str

Specifies the associated R2 bucket name.

name: str

Specifies the catalog name (generated from account and bucket name).

status: Literal["active", "inactive"]

Indicates the status of the catalog.

One of the following:
"active"
"inactive"
credential_status: Optional[Literal["present", "absent"]]

Shows the credential configuration status.

One of the following:
"present"
"absent"
maintenance_config: Optional[MaintenanceConfig]

Configures maintenance for the catalog.

compaction: Optional[MaintenanceConfigCompaction]

Configures compaction for catalog maintenance.

state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"
target_size_mb: Literal["64", "128", "256", "512"]

Sets the target file size for compaction in megabytes. Defaults to "128".

One of the following:
"64"
"128"
"256"
"512"
snapshot_expiration: Optional[MaintenanceConfigSnapshotExpiration]

Configures snapshot expiration settings.

max_snapshot_age: str

Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d".

min_snapshots_to_keep: int

Specifies the minimum number of snapshots to retain. Defaults to 100.

formatint64
minimum1
state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"
class R2DataCatalogEnableResponse: …

Contains response from activating an R2 bucket as a catalog.

id: str

Use this to uniquely identify the activated catalog.

formatuuid
name: str

Specifies the name of the activated catalog.

R2 Data CatalogMaintenance Configs

Get catalog maintenance configuration
r2_data_catalog.maintenance_configs.get(strbucket_name, MaintenanceConfigGetParams**kwargs) -> MaintenanceConfigGetResponse
GET/accounts/{account_id}/r2-catalog/{bucket_name}/maintenance-configs
Update catalog maintenance configuration
r2_data_catalog.maintenance_configs.update(strbucket_name, MaintenanceConfigUpdateParams**kwargs) -> MaintenanceConfigUpdateResponse
POST/accounts/{account_id}/r2-catalog/{bucket_name}/maintenance-configs
ModelsExpand Collapse
class MaintenanceConfigGetResponse: …

Contains maintenance configuration and credential status.

credential_status: Literal["present", "absent"]

Shows the credential configuration status.

One of the following:
"present"
"absent"
maintenance_config: MaintenanceConfig

Configures maintenance for the catalog.

compaction: Optional[MaintenanceConfigCompaction]

Configures compaction for catalog maintenance.

state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"
target_size_mb: Literal["64", "128", "256", "512"]

Sets the target file size for compaction in megabytes. Defaults to "128".

One of the following:
"64"
"128"
"256"
"512"
snapshot_expiration: Optional[MaintenanceConfigSnapshotExpiration]

Configures snapshot expiration settings.

max_snapshot_age: str

Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d".

min_snapshots_to_keep: int

Specifies the minimum number of snapshots to retain. Defaults to 100.

formatint64
minimum1
state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"
class MaintenanceConfigUpdateResponse: …

Configures maintenance for the catalog.

compaction: Optional[Compaction]

Configures compaction for catalog maintenance.

state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"
target_size_mb: Literal["64", "128", "256", "512"]

Sets the target file size for compaction in megabytes. Defaults to "128".

One of the following:
"64"
"128"
"256"
"512"
snapshot_expiration: Optional[SnapshotExpiration]

Configures snapshot expiration settings.

max_snapshot_age: str

Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d".

min_snapshots_to_keep: int

Specifies the minimum number of snapshots to retain. Defaults to 100.

formatint64
minimum1
state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"

R2 Data CatalogCredentials

Store catalog credentials
r2_data_catalog.credentials.create(strbucket_name, CredentialCreateParams**kwargs) -> object
POST/accounts/{account_id}/r2-catalog/{bucket_name}/credential

R2 Data CatalogNamespaces

List namespaces in catalog
r2_data_catalog.namespaces.list(strbucket_name, NamespaceListParams**kwargs) -> NamespaceListResponse
GET/accounts/{account_id}/r2-catalog/{bucket_name}/namespaces
ModelsExpand Collapse
class NamespaceListResponse: …

Contains the list of namespaces with optional pagination.

namespaces: List[List[str]]

Lists namespaces in the catalog.

details: Optional[List[Detail]]

Contains detailed metadata for each namespace when return_details is true. Each object includes the namespace, UUID, and timestamps.

namespace: List[str]

Specifies the hierarchical namespace parts as an array of strings. For example, ["bronze", "analytics"] represents the namespace "bronze.analytics".

namespace_uuid: str

Contains the UUID that persists across renames.

formatuuid
created_at: Optional[datetime]

Indicates the creation timestamp in ISO 8601 format.

formatdate-time
updated_at: Optional[datetime]

Shows the last update timestamp in ISO 8601 format. Null if never updated.

formatdate-time
namespace_uuids: Optional[List[str]]

Contains UUIDs for each namespace when return_uuids is true. The order corresponds to the namespaces array.

next_page_token: Optional[str]

Use this opaque token to fetch the next page of results. A null or absent value indicates the last page.

R2 Data CatalogNamespacesTables

List tables in namespace
r2_data_catalog.namespaces.tables.list(strnamespace, TableListParams**kwargs) -> TableListResponse
GET/accounts/{account_id}/r2-catalog/{bucket_name}/namespaces/{namespace}/tables
ModelsExpand Collapse
class TableListResponse: …

Contains the list of tables with optional pagination.

identifiers: List[Identifier]

Lists tables in the namespace.

name: str

Specifies the table name.

namespace: List[str]

Specifies the hierarchical namespace parts as an array of strings. For example, ["bronze", "analytics"] represents the namespace "bronze.analytics".

details: Optional[List[Detail]]

Contains detailed metadata for each table when return_details is true. Each object includes identifier, UUID, timestamps, and locations.

identifier: DetailIdentifier

Specifies a unique table identifier within a catalog.

name: str

Specifies the table name.

namespace: List[str]

Specifies the hierarchical namespace parts as an array of strings. For example, ["bronze", "analytics"] represents the namespace "bronze.analytics".

table_uuid: str

Contains the UUID that persists across renames.

formatuuid
created_at: Optional[datetime]

Indicates the creation timestamp in ISO 8601 format.

formatdate-time
location: Optional[str]

Specifies the base S3 URI for table storage location.

metadata_location: Optional[str]

Contains the S3 URI to table metadata file. Null for staged tables.

updated_at: Optional[datetime]

Shows the last update timestamp in ISO 8601 format. Null if never updated.

formatdate-time
next_page_token: Optional[str]

Use this opaque token to fetch the next page of results. A null or absent value indicates the last page.

table_uuids: Optional[List[str]]

Contains UUIDs for each table when return_uuids is true. The order corresponds to the identifiers array.

R2 Data CatalogNamespacesTablesMaintenance Configs

Get table maintenance configuration
r2_data_catalog.namespaces.tables.maintenance_configs.get(strtable_name, MaintenanceConfigGetParams**kwargs) -> MaintenanceConfigGetResponse
GET/accounts/{account_id}/r2-catalog/{bucket_name}/namespaces/{namespace}/tables/{table_name}/maintenance-configs
Update table maintenance configuration
r2_data_catalog.namespaces.tables.maintenance_configs.update(strtable_name, MaintenanceConfigUpdateParams**kwargs) -> MaintenanceConfigUpdateResponse
POST/accounts/{account_id}/r2-catalog/{bucket_name}/namespaces/{namespace}/tables/{table_name}/maintenance-configs
ModelsExpand Collapse
class MaintenanceConfigGetResponse: …

Contains table maintenance configuration.

maintenance_config: MaintenanceConfig

Configures maintenance for the table.

compaction: Optional[MaintenanceConfigCompaction]

Configures compaction settings for table optimization.

state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"
target_size_mb: Literal["64", "128", "256", "512"]

Sets the target file size for compaction in megabytes. Defaults to "128".

One of the following:
"64"
"128"
"256"
"512"
snapshot_expiration: Optional[MaintenanceConfigSnapshotExpiration]

Configures snapshot expiration settings.

max_snapshot_age: str

Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d".

min_snapshots_to_keep: int

Specifies the minimum number of snapshots to retain. Defaults to 100.

formatint64
minimum1
state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"
class MaintenanceConfigUpdateResponse: …

Configures maintenance for the table.

compaction: Optional[Compaction]

Configures compaction settings for table optimization.

state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"
target_size_mb: Literal["64", "128", "256", "512"]

Sets the target file size for compaction in megabytes. Defaults to "128".

One of the following:
"64"
"128"
"256"
"512"
snapshot_expiration: Optional[SnapshotExpiration]

Configures snapshot expiration settings.

max_snapshot_age: str

Specifies the maximum age for snapshots. The system deletes snapshots older than this age. Format: where unit is d (days), h (hours), m (minutes), or s (seconds). Examples: "7d" (7 days), "48h" (48 hours), "2880m" (2,880 minutes). Defaults to "7d".

min_snapshots_to_keep: int

Specifies the minimum number of snapshots to retain. Defaults to 100.

formatint64
minimum1
state: Literal["enabled", "disabled"]

Specifies the state of maintenance operations.

One of the following:
"enabled"
"disabled"