This page covers connecting to Iceberg REST Catalogs: authentication, the full set of ATTACH options, and setup instructions for specific catalogs. For the basics of attaching a catalog and querying it, see Catalog Managed Tables; for write operations, see Writing to Iceberg.

If you are attaching to an Iceberg REST Catalog managed by Amazon, please see the instructions for attaching to Amazon S3 Tables or Amazon SageMaker Lakehouse.

For all other Iceberg REST Catalogs, you can follow the instructions below. Please see the Examples section for questions about specific catalogs.

Most Iceberg REST Catalogs authenticate via OAuth2. You can use the existing DuckDB secret workflow to store login credentials for the OAuth2 service.

CREATE SECRET iceberg_secret (
    TYPE iceberg,
    CLIENT_ID 'admin',
    CLIENT_SECRET 'password',
    OAUTH2_SERVER_URI 'http://iceberg_rest_catalog_url.com/v1/oauth/tokens'
);

If you already have a Bearer token, you can pass it directly to your CREATE SECRET statement

CREATE SECRET iceberg_secret (
    TYPE iceberg,
    TOKEN 'bearer_token'
);

You can attach the Iceberg catalog with the following ATTACH statement.

LOAD httpfs;
ATTACH 'warehouse' AS iceberg_catalog (
   TYPE iceberg,
   SECRET iceberg_secret, -- pass a specific secret name to prevent ambiguity
   ENDPOINT 'https://rest_endpoint.com'
);

To see the available tables run

SHOW ALL TABLES;

ATTACH Options

A REST Catalog with OAuth2 authorization can also be attached with just an ATTACH statement. See the complete list of ATTACH options for a REST Catalog below.

The following options can only be passed to a CREATE SECRET statement and they require AUTHORIZATION_TYPE to be OAUTH2:

Working with an Attached Catalog

Once a catalog is attached, you can run the full set of read and write operations against its tables:

• Reading and metadata: SELECT, time travel with the AT clause, and the iceberg_metadata, iceberg_snapshots, and statistics functions. See the Functions and Settings Reference.
• Writing: CREATE/DROP SCHEMA and TABLE, partitioning, INSERT, UPDATE, DELETE, MERGE INTO, ALTER TABLE, table properties, and COPY FROM DATABASE. See Writing to Iceberg.

Metadata functions accept a fully qualified table name, e.g.:

SELECT * FROM iceberg_snapshots(my_catalog.default.t);

Specific Catalog Examples

Cloudflare R2 Catalog

To attach to an R2 Cloudflare managed catalog follow the attach steps below.

CREATE SECRET r2_secret (
    TYPE iceberg,
    TOKEN 'r2_token'
);

You can create a token by following the create an API token steps in getting started. Then, attach the catalog with the following commands.

ATTACH 'warehouse' AS my_r2_catalog (
    TYPE iceberg,
    ENDPOINT 'catalog-uri'
);

The variables for warehouse and catalog-uri are available under the settings of the R2 Object Storage Catalog (R2 Object Store, Catalog name, Settings).

Once you attached to the R2 Data Catalog, create a schema. You can set it as default with the USE command:

CREATE SCHEMA my_r2_catalog.my_schema;
USE my_r2_catalog.my_schema;

Polaris

To attach to a Polaris catalog, use the following commands:

CREATE SECRET polaris_secret (
    TYPE iceberg,
    CLIENT_ID 'admin',
    CLIENT_SECRET 'password',
);

ATTACH 'quickstart_catalog' AS polaris_catalog (
    TYPE iceberg,
    ENDPOINT 'polaris_rest_catalog_endpoint',
    ACCESS_DELEGATION_MODE 'vended_credentials'
);

Lakekeeper

To attach to a Lakekeeper catalog the following commands will work.

CREATE SECRET lakekeeper_secret (
    TYPE iceberg,
    CLIENT_ID 'admin',
    CLIENT_SECRET 'password',
    OAUTH2_SCOPE 'scope',
    OAUTH2_SERVER_URI 'lakekeeper_oauth_url'
);

ATTACH 'warehouse' AS lakekeeper_catalog (
    TYPE iceberg,
    ENDPOINT 'lakekeeper_irc_url',
    SECRET 'lakekeeper_secret'
);

Google Cloud BigLake

To attach to a Google Cloud BigLake catalog, you can use extra HTTP headers to specify the GCP project for billing purposes.

First, get your Google Cloud access token:

gcloud auth application-default print-access-token

Then create a secret with the token and extra headers:

CREATE SECRET biglake_secret (
    TYPE iceberg,
    TOKEN 'your_access_token',
    EXTRA_HTTP_HEADERS MAP {
        'x-goog-user-project': 'your_gcp_project_id'
    }
);

Attach to the BigLake catalog:

ATTACH 'gs://your-biglake-bucket' AS biglake_catalog (
    TYPE iceberg,
    ENDPOINT 'https://biglake.googleapis.com/iceberg/v1/restcatalog',
    SECRET biglake_secret
);

Example using the BigLake public dataset:

CREATE SECRET biglake_public_secret (
    TYPE iceberg,
    TOKEN 'your_access_token',
    EXTRA_HTTP_HEADERS MAP {
        'x-goog-user-project': 'your_gcp_project_id'
    }
);

ATTACH 'gs://biglake-public-nyc-taxi-iceberg' AS biglake_public (
    TYPE iceberg,
    ENDPOINT 'https://biglake.googleapis.com/iceberg/v1/restcatalog',
    SECRET biglake_public_secret
);

-- Query the data
SELECT count(*) FROM biglake_public.public_data.nyc_taxicab;

Note: Google Cloud access tokens expire after 1 hour. For long-running sessions, you'll need to refresh the token periodically.

Catalogs with Limited REST Spec Support

Some catalogs implement a subset of the Iceberg REST Catalog specification. Use the compatibility options below to adjust DuckDB's behavior for these catalogs.

For example, to attach a Unity Catalog Horizon endpoint that does not support staged creates, rejects the transactions/commit endpoint, and manages its own metadata and storage cleanup:

ATTACH 'warehouse' AS horizon_catalog (
    TYPE iceberg,
    ENDPOINT 'catalog_endpoint',
    STAGE_CREATE_TABLES false,
    DISABLE_MULTI_TABLE_COMMIT true,
    SKIP_CREATE_TABLE_METADATA_UPDATES true,
    REMOVE_FILES_ON_DELETE false
);

Limitations

DuckDB supports Iceberg REST Catalogs backed by S3, S3 Tables, and Google Cloud Storage (GCS). Support for other storage backends is not yet available.