Basin Catalog API Selection
Use the Iceberg REST catalog through an engine for table reads and writes; use the Cloudflare control-plane API for catalog administration. Copy the catalog connection values from the actual environment as described in configuration.
| Task | Documentation |
|---|---|
| Enable or disable catalogs; inspect status, credentials, namespaces, tables, and maintenance configuration | Basin Catalog control-plane API — select the affected operation for its schema, pagination, and namespace encoding |
| Connect and create tables through Python | PyIceberg configuration |
| Connect, create, write, and query through Spark | PySpark configuration |
| Plan automatic compaction and snapshot expiration | Table maintenance |
| Delete rows, tables, or associated files | Deleting data |
For engine-specific operations beyond these Cloudflare examples, follow the upstream engine documentation linked from the relevant configuration guide and check the installed version. Do not infer engine method signatures from the control-plane API.
Get Table (repository-specific metadata introspection note)
This existing repository note is retained because the published control-plane API reference does not document this operation or its snapshot-pruning response. Verify availability and response behavior against the target service or authoritative implementation before relying on it; it is not a documented API guarantee. Do not substitute the documented list-tables response for this metadata response.
GET /namespaces/{ns}/tables/{table} returns schema, partition spec, sort order, and snapshot info — like Iceberg "load table" but on the control plane, with snapshots pruned to the most recent 10.
curl -s "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/r2-catalog/$BUCKET/namespaces/live/tables/earthquakes" \
-H "Authorization: Bearer $API_TOKEN"{"result": {
"identifier": {"namespace": ["live"], "name": "earthquakes"},
"table_uuid": "019edccf-3ac8-73e3-...",
"metadata_location": "s3://live-data/__r2_data_catalog/.../metadata/01225-....metadata.json",
"total_snapshots": 1225,
"returned_snapshots": 10,
"metadata": { /* standard Iceberg TableMetadata: schemas, partition-specs, sort-orders,
properties, current-snapshot-id, snapshots (≤10), snapshot-log, refs */ }
}, "success": true}| Field | Description |
|---|---|
identifier |
{namespace: [...], name} |
table_uuid |
Iceberg table UUID |
metadata_location |
R2 path to current metadata file |
total_snapshots |
Total before pruning |
returned_snapshots |
Count in metadata.snapshots (max 10) |
metadata |
Standard Iceberg TableMetadata, arrays pruned to 10 |
See patterns for engine selection and troubleshooting for diagnosis.