> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebolt.io/llms.txt
> Use this file to discover all available pages before exploring further.

> Reference and syntax for the CREATE ICEBERG DATABASE command.

# CREATE ICEBERG DATABASE

For an overview of querying, tuning, and exporting Iceberg tables, see the [Iceberg guide](/guides/iceberg-and-data-lake/iceberg).

Creates an Iceberg database that mounts an external Iceberg catalog. Once created, you can query every table the catalog exposes using a fully qualified three-part name, without registering each table individually with [`CREATE ICEBERG TABLE`](/reference-sql/commands/data-definition/create-iceberg-table).

An Iceberg database stores only a pointer to an [Iceberg LOCATION](/reference-sql/commands/data-definition/create-location-iceberg) and a freshness setting. Each query resolves the table against the upstream catalog at run time, so any table added to the catalog becomes visible on the next query.

## Syntax

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
CREATE ICEBERG DATABASE [ IF NOT EXISTS ] <database_name> WITH
  LOCATION = '<location_name>'
  [ MAX_STALENESS = '<interval>' ]
  [ DESCRIPTION = '<description>' ]
```

## Parameters

| Parameter         | Description                                                                                                                                                                                                                                                                                                                                                                          |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<database_name>` | The name of the new Iceberg database.                                                                                                                                                                                                                                                                                                                                                |
| `LOCATION`        | The name of an existing Iceberg [LOCATION](/reference-sql/commands/data-definition/create-location-iceberg). The LOCATION must be warehouse-/catalog-scoped: its `CATALOG_OPTIONS` must not set `NAMESPACE` (REST), `DATABASE` (AWS\_GLUE), `SCHEMA` (DATABRICKS\_UNITY), or `TABLE`.                                                                                                |
| `MAX_STALENESS`   | (Optional) An interval string (for example, `'30 seconds'`, `'5 minutes'`, `'1 hour'`). Controls how long Firebolt can serve queries from cached catalog metadata. The default is `'0'` (no caching). For details, see [Configurable data freshness with MAX\_STALENESS](/performance-and-observability/runtime/iceberg-performance#configurable-data-freshness-with-max_staleness). |
| `DESCRIPTION`     | (Optional) A description of up to 64 characters.                                                                                                                                                                                                                                                                                                                                     |

## Supported catalog types

`CREATE ICEBERG DATABASE` works with any Iceberg LOCATION object that targets one of the following catalog types:

* `FILE_BASED`
* `REST`
* `AWS_GLUE`
* `SNOWFLAKE_OPEN_CATALOG`
* `DATABRICKS_UNITY`

## Name resolution

A fully qualified table name has three parts: `<database>.<schema>.<table>`.

* `<database>` is the Iceberg database created with `CREATE ICEBERG DATABASE`.
* `<schema>` maps to the upstream Iceberg namespace.
* `<table>` maps to the Iceberg table within that namespace.

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
SELECT * FROM lake."analytics.sales.q1".orders;
```

## Examples

### REST catalog

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
CREATE LOCATION rest_loc WITH
  SOURCE = ICEBERG
  CATALOG = REST
  CATALOG_OPTIONS = (
    URL = 'https://catalog.example.com/v1'
    WAREHOUSE = 'analytics'
  )
  CREDENTIALS = (
    OAUTH_CLIENT_ID = '<client_id>'
    OAUTH_CLIENT_SECRET = '<client_secret>'
  );

CREATE ICEBERG DATABASE lake WITH
  LOCATION = 'rest_loc'
  MAX_STALENESS = '30 seconds';

SELECT * FROM lake.sales.orders LIMIT 10;
```

### AWS Glue catalog

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
CREATE LOCATION glue_loc WITH
  SOURCE = ICEBERG
  CATALOG = AWS_GLUE
  CATALOG_OPTIONS = (
    URL = 'https://glue.us-east-1.amazonaws.com/iceberg'
    CATALOG_ID = '123456789012'
  )
  CREDENTIALS = ( AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/GlueAccess' AWS_ROLE_EXTERNAL_ID = 'my-external-id' );

CREATE ICEBERG DATABASE lake WITH
  LOCATION = 'glue_loc'
  MAX_STALENESS = '5 minutes';

SELECT * FROM lake.sales.orders LIMIT 10;
```

<Note>
  For role-based AWS access you can additionally set an external ID. An external ID is a value you choose and control that AWS checks when Firebolt assumes your role, adding a second condition on top of your account's unique IAM principal. Configuring one is a recommended best practice. See [IAM roles](/security#iam-roles).
</Note>

### File-based catalog

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
CREATE LOCATION file_loc WITH
  SOURCE = ICEBERG
  CATALOG = FILE_BASED
  CATALOG_OPTIONS = ( URL = 's3://my-bucket/iceberg-warehouse' )
  CREDENTIALS = ( AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/IcebergAccess' AWS_ROLE_EXTERNAL_ID = 'my-external-id' );

CREATE ICEBERG DATABASE lake WITH
  LOCATION = 'file_loc'
  MAX_STALENESS = '5 minutes';

SELECT * FROM lake.sales.orders LIMIT 10;
```

## Limitations

* The LOCATION must be warehouse-/catalog-scoped. A LOCATION that pins `NAMESPACE` (REST), `DATABASE` (AWS\_GLUE), `SCHEMA` (DATABRICKS\_UNITY), or `TABLE` fails at `CREATE ICEBERG DATABASE` time.
* Tables in a mounted database are resolved on demand by name. `SHOW TABLES` and `information_schema.tables` do not list them.

## See also

* [`CREATE LOCATION (Iceberg)`](/reference-sql/commands/data-definition/create-location-iceberg)
* [`CREATE ICEBERG TABLE`](/reference-sql/commands/data-definition/create-iceberg-table)
* [`READ_ICEBERG`](/reference-sql/functions-reference/iceberg/read_iceberg)
* [`DROP DATABASE`](/reference-sql/commands/data-definition/drop-database)