Storage

Iceberg Catalog

Analytics buckets require authentication with two distinct services:

Architecture overview

Iceberg REST Catalog serves as the metadata management system for your Iceberg tables. It enables Iceberg clients such as PyIceberg and Apache Spark to perform critical operations:

  • Creating and managing tables and namespaces
  • Tracking schemas and handling schema evolution
  • Managing partitions and table snapshots
  • Ensuring transactional consistency and isolation

The REST Catalog only stores metadata describing your data's structure, schema, and partitioning strategy—not the actual data itself.

S3-Compatible Storage Endpoint handles the actual data storage and retrieval. It's optimized for reading and writing large analytical datasets stored in Parquet format, separate from the metadata management layer.

Authentication setup

To connect to an analytics bucket, you need:

1. S3 credentials

Create S3 credentials through Project Settings > Storage. See the S3 Authentication Guide for detailed instructions.

You'll obtain:

  • Access Key ID
  • Secret Access Key
  • Region (e.g., us-east-1)

2. Supabase service key

Retrieve your Service Key from Project Settings > API. This key authenticates requests to the Iceberg REST Catalog.

3. Project reference

Your Supabase project reference is the subdomain in your project URL (e.g., your-project-ref in https://your-project-ref.supabase.co).

Testing your connection

You can verify your setup by making a direct request to the Iceberg REST Catalog. Provide your Service Key as a Bearer token:

1
2
3
4
curl \  --request GET -sL \  --url 'https://<your-project-ref>.supabase.co/storage/v1/iceberg/v1/config?warehouse=<bucket-name>' \  --header 'Authorization: Bearer <your-service-key>'

A successful response returns the catalog configuration including warehouse location and settings.

Next steps