CREATE ICEBERG DATABASE

For an overview of querying, tuning, and exporting Iceberg tables, see the Iceberg guide. 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. An Iceberg database stores only a pointer to an Iceberg LOCATION 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

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. The LOCATION must be warehouse-/catalog-scoped: its `CATALOG_OPTIONS` must not set `NAMESPACE` (REST, SNOWFLAKE_OPEN_CATALOG, S3_TABLES), `SCHEMA` (DATABRICKS_UNITY), `DATABASE` (AWS_GLUE), 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.
`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
SNOWFLAKE_OPEN_CATALOG
DATABRICKS_UNITY
AWS_GLUE
S3_TABLES Nightly Feature

Supported vendor catalogs without a dedicated keyword use one of these types. For example, Snowflake Horizon Catalog uses REST.

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.

SELECT * FROM lake."analytics.sales.q1".orders;

Example (REST catalog)

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;

For how to create an Iceberg database backed by a FILE_BASED, DATABRICKS_UNITY (as syntactic sugar on top of REST), SNOWFLAKE_OPEN_CATALOG (a REST-shaped catalog), AWS_GLUE, or S3_TABLES location, see CREATE LOCATION (Iceberg).

Limitations

The LOCATION must be warehouse-/catalog-scoped. A LOCATION that pins NAMESPACE (REST, SNOWFLAKE_OPEN_CATALOG, S3_TABLES), SCHEMA (DATABRICKS_UNITY), DATABASE (AWS_GLUE), 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.

Overview

Performance and Observability

Security

Self-Managed

Managed service

Guides

SQL reference

Release notes

API reference

Legal

Syntax

Parameters

Supported catalog types

Name resolution

Example (REST catalog)

Limitations

See also

​Syntax

​Parameters

​Supported catalog types

​Name resolution

​Example (REST catalog)

​Limitations

​See also

Syntax

Parameters

Supported catalog types

Name resolution

Example (REST catalog)

Limitations

See also