# CREATE ICEBERG CATALOG

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [cloud-data-platform-full.txt](https://docs.redpanda.com/cloud-data-platform-full.txt)

---
title: CREATE ICEBERG CATALOG
latest-operator-version: v26.1.4
latest-console-tag: v3.7.3
latest-connect-version: 4.93.0
latest-redpanda-tag: v26.1.9
docname: sql/sql-statements/create-iceberg-catalog
page-component-name: cloud-data-platform
page-version: master
page-component-version: master
page-component-title: Cloud
page-relative-src-path: sql/sql-statements/create-iceberg-catalog.adoc
page-edit-url: https://github.com/redpanda-data/cloud-docs/edit/main/modules/reference/pages/sql/sql-statements/create-iceberg-catalog.adoc
description: The CREATE ICEBERG CATALOG statement creates a named connection to an Iceberg REST catalog, enabling Redpanda SQL to query Iceberg-committed topic data.
page-topic-type: reference
page-git-created-date: "2026-05-26"
page-git-modified-date: "2026-05-26"
---

<!-- Source: https://docs.redpanda.com/cloud-data-platform/reference/sql/sql-statements/create-iceberg-catalog.md -->

The `CREATE ICEBERG CATALOG` statement creates a named connection to an Iceberg REST catalog. Link the Iceberg catalog to a Redpanda catalog with `USING CATALOG` so that queries against the linked Redpanda catalog return both live and Iceberg-committed records. Standalone querying against an Iceberg catalog is not supported. See [Query Iceberg-enabled Topics](https://docs.redpanda.com/cloud-data-platform/sql/query-data/query-iceberg-topics/) for the end-to-end workflow.

The statement requires an existing [storage connection](https://docs.redpanda.com/cloud-data-platform/reference/sql/sql-statements/create-storage/) that holds the object-storage credentials for the Iceberg warehouse.

## [](#syntax)Syntax

```sql
CREATE ICEBERG CATALOG [IF NOT EXISTS] catalog_name STORAGE storage_name
  WITH (option = 'value' [, ...]);
```

-   `catalog_name`: Name for the new Iceberg catalog.

-   `IF NOT EXISTS`: Optional. Prevents an error if an Iceberg catalog with the same name already exists.

-   `storage_name`: Name of an existing storage connection. Create it first with [CREATE STORAGE](https://docs.redpanda.com/cloud-data-platform/reference/sql/sql-statements/create-storage/).


> 📝 **NOTE**
>
> Catalogs are created in the current schema (`public` by default). To create a catalog in a different schema, qualify the name as `schema.catalog_name`. The auto-created `default_iceberg_catalog` is in `public`.

## [](#options)Options

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| uri | STRING | Yes | REST catalog endpoint URI. |
| warehouse | STRING | No | Iceberg warehouse identifier or location. |
| auth_type | STRING | No | Authentication type for the REST catalog. One of oauth2, basic, or aws_sigv4. If omitted, the catalog connects without authentication. Providing an auth-specific option (such as username or aws_region) without auth_type is rejected. |
| oauth2_client_id | STRING | Required when auth_type = 'oauth2' | OAuth2 client ID. |
| oauth2_client_secret | STRING | Required when auth_type = 'oauth2' | OAuth2 client secret. |
| oauth2_scope | STRING | No | OAuth2 scope to request. |
| oauth2_token_endpoint_url | STRING | No | OAuth2 token endpoint URL. Use to override the catalog’s default token endpoint. |
| oauth2_token_refresh_margin_seconds | INTEGER | No | Number of seconds before token expiry to refresh. Must be between 0 and 2147483647. |
| username | STRING | Required when auth_type = 'basic' | Basic authentication username. |
| password | STRING | Required when auth_type = 'basic' | Basic authentication password. |
| aws_region | STRING | Required when auth_type = 'aws_sigv4' | AWS region for SigV4 request signing (for example, us-west-2). |
| aws_access_key_id | STRING | No | AWS access key ID for SigV4 signing. Must be set together with aws_secret_access_key. If both are omitted, the catalog uses the AWS default credential chain (environment variables, shared config, STS web identity, IMDSv2/ECS). |
| aws_secret_access_key | STRING | No | AWS secret access key for SigV4 signing. See aws_access_key_id for credential-chain behavior. |
| ssl_verify | STRING | No | 'true' (default) or 'false'. Whether to verify the REST catalog’s TLS certificate. |
| ssl_ca_info | STRING | No | Path to a CA certificate file used to verify the REST catalog’s TLS certificate. |
| ssl_ca_path | STRING | No | Path to a directory containing CA certificates. |
| ssl_crl_file | STRING | No | Path to a certificate revocation list (CRL) file. |

## [](#examples)Examples

### [](#create-a-basic-iceberg-catalog)Create a basic Iceberg catalog

Connect to a REST catalog without authentication. The catalog uses TLS verification by default.

```sql
CREATE ICEBERG CATALOG lakehouse_catalog STORAGE iceberg_storage
  WITH (
    uri = 'https://catalog.example.com',
    warehouse = 's3://warehouse/'
  );
```

### [](#create-an-iceberg-catalog-with-oauth2-authentication)Create an Iceberg catalog with OAuth2 authentication

```sql
CREATE ICEBERG CATALOG lakehouse_catalog STORAGE iceberg_storage
  WITH (
    uri = 'https://catalog.example.com',
    warehouse = 's3://lakehouse-data/',
    auth_type = 'oauth2',
    oauth2_client_id = '<client-id>',
    oauth2_client_secret = '<client-secret>',
    oauth2_scope = 'PRINCIPAL_ROLE:ALL',
    oauth2_token_endpoint_url = 'https://auth.example.com/token',
    oauth2_token_refresh_margin_seconds = 300
  );
```

### [](#create-an-iceberg-catalog-with-basic-authentication)Create an Iceberg catalog with basic authentication

```sql
CREATE ICEBERG CATALOG lakehouse_catalog STORAGE iceberg_storage
  WITH (
    uri = 'https://catalog.example.com',
    warehouse = 's3://warehouse/',
    auth_type = 'basic',
    username = '<username>',
    password = '<password>'
  );
```

### [](#create-an-iceberg-catalog-with-aws-sigv4-authentication)Create an Iceberg catalog with AWS SigV4 authentication

Use for REST catalogs fronted by AWS services (such as AWS Glue).

```sql
CREATE ICEBERG CATALOG lakehouse_catalog STORAGE iceberg_storage
  WITH (
    uri = 'https://catalog.example.com',
    warehouse = 's3://warehouse/',
    auth_type = 'aws_sigv4',
    aws_region = 'us-west-2',
    aws_access_key_id = '<access-key-id>',
    aws_secret_access_key = '<secret-access-key>'
  );
```

To use the AWS default credential chain (for example, an EC2 instance-profile role), omit `aws_access_key_id` and `aws_secret_access_key`. They must be set together or omitted together.

### [](#create-an-iceberg-catalog-with-custom-tls-settings)Create an Iceberg catalog with custom TLS settings

```sql
CREATE ICEBERG CATALOG lakehouse_catalog STORAGE iceberg_storage
  WITH (
    uri = 'https://catalog.example.com',
    warehouse = 's3://warehouse/',
    ssl_verify = 'true',
    ssl_ca_info = '/etc/ssl/certs/catalog-ca.pem'
  );
```

## [](#related-statements)Related statements

| Statement | Description |
| --- | --- |
| ALTER ICEBERG CATALOG | Modify connection properties of an existing Iceberg catalog. |
| DROP ICEBERG CATALOG | Remove an Iceberg catalog. |
| CREATE STORAGE | Create the storage connection that backs the Iceberg catalog. |
| CREATE REDPANDA CATALOG | Create a Redpanda catalog. Use USING CATALOG to link a Redpanda catalog to an Iceberg catalog so that queries return both live and Iceberg-committed records. |