Supabase Analytics Buckets
An Analytics Bucket is an Iceberg warehouse in a Supabase project. Send2Bucket commits to it through the project's Iceberg REST catalog and writes data files through the project's S3-compatible storage endpoint. Any Supabase project works; it does not need to be related to Send2Bucket.
What you provide
| Field | Kind | Where to find it |
|---|---|---|
project_ref | setting | The <ref> in https://<ref>.supabase.co |
warehouse | setting | The Analytics Bucket's name |
region | setting | The project's region, for example us-east-1 |
namespace | setting | An existing namespace, for example s2b |
table | setting | For example events |
catalog_token | credential | The bearer token for the Iceberg catalog, from the bucket's connection details |
access_key_id, secret_access_key | credential | Storage settings, S3 access keys |
The catalog token and the S3 keys are separate credentials. Supabase's connection instructions use the project's service role key as the catalog token, so treat it as a secret and rotate it if it leaks.
Setup
- In the Supabase dashboard, open Storage, create an Analytics Bucket and note its name.
- Create S3 access keys under the Storage settings.
- Add the destination in the Send2Bucket dashboard and select Verify. Send2Bucket creates the table in the namespace with the columns in Delivery format if it is missing. An incompatible existing table is left untouched, and setup fails with
incompatible table: ….
Delivery
A batch is delivered when the catalog confirms its append snapshot. Read the table with any Iceberg client, for example DuckDB, PyIceberg or Spark, using the same catalog endpoint and warehouse. See Supabase's guide to connecting.
Query your data
- DuckDB: attaches the bucket's catalog.
- PostgreSQL: from the same Supabase project.
- MySQL: load with DuckDB.
- Trino: Iceberg connector with a REST catalog.
- Python: Polars, PyIceberg or the duckdb package.
- R: the duckdb package.
- ClickHouse
- Apache Spark
- StarRocks
To explore in a notebook or BI tool, see Integrations. The querying overview compares engines.