> ## Documentation Index
> Fetch the complete documentation index at: https://firebolt-aggregate-helm-docs-pr-4.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Reference and syntax for the CREATE ICEBERG TABLE SQL command.

# CREATE ICEBERG TABLE

Creates an Iceberg table that is registered in Firebolt's catalog and backed by an [Apache Iceberg](https://iceberg.apache.org/) table in external storage. Once created, you can query it with regular `SELECT` statements just like a managed table, without needing to use the [`READ_ICEBERG`](/reference-sql/functions-reference/iceberg/read_iceberg) table-valued function.

The table's schema is automatically inferred from the Iceberg metadata at creation time. Firebolt reads the Iceberg catalog to determine column names and types.

<Note>
  To export data from Firebolt into a new Iceberg table, use [`CREATE ICEBERG TABLE AS SELECT`](/reference-sql/commands/data-definition/create-iceberg-table-as-select) instead.
</Note>

## Syntax

```sql theme={null}
CREATE ICEBERG TABLE <table_name>
(<column_name> <column_type>[, <column_name> <column_type>[, ...]])
LOCATION = '<location_name>'
```

## Parameters

| Parameter         | Description                                                                                                                                                       |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<table_name>`    | An identifier that specifies the name of the table. This name must be unique within the database.                                                                 |
| `<column_name>`   | An identifier that specifies the name of a column.                                                                                                                |
| `<column_type>`   | Specifies the [data type](/reference-sql/data-types) for the column. Must match the types inferred from the Iceberg metadata.                                     |
| `<location_name>` | The name of an [Iceberg `LOCATION`](/reference-sql/commands/data-definition/create-location-iceberg) object that points to the Iceberg table in external storage. |

## Examples

### Creating an Iceberg table

The following example creates a `LOCATION` pointing to an Iceberg table in S3, then creates an Iceberg table that you can query directly.

```sql theme={null}
CREATE LOCATION my_iceberg_location WITH
  SOURCE = ICEBERG
  CATALOG = FILE_BASED
  CATALOG_OPTIONS = (
    URL = 's3://my-bucket/path/to/iceberg/table'
  )
  CREDENTIALS = ( AWS_ACCESS_KEY_ID = '...' AWS_SECRET_ACCESS_KEY = '...' );

CREATE ICEBERG TABLE my_iceberg_table
  (order_id INTEGER, customer_name TEXT, order_date DATE, amount DOUBLE)
  LOCATION = 'my_iceberg_location';
```

### Querying an Iceberg table

Once created, an Iceberg table can be queried like any other table in Firebolt:

```sql theme={null}
SELECT * FROM my_iceberg_table LIMIT 10;

SELECT customer_name, SUM(amount) AS total
FROM my_iceberg_table
GROUP BY customer_name
ORDER BY total DESC;
```

You can also join Iceberg tables with Firebolt-managed tables:

```sql theme={null}
SELECT o.order_id, o.amount, c.region
FROM my_iceberg_table o
JOIN customers c ON o.customer_name = c.name;
```

### Dropping an Iceberg table

Iceberg tables are dropped using the standard [`DROP TABLE`](/reference-sql/commands/data-definition/drop-table) command. Dropping an Iceberg table removes it from Firebolt's catalog but does not delete the underlying data in external storage.

```sql theme={null}
DROP TABLE my_iceberg_table;
```

If a view depends on the Iceberg table, use `CASCADE`:

```sql theme={null}
DROP TABLE my_iceberg_table CASCADE;
```

## Comparison with other approaches

Firebolt provides multiple ways to work with Iceberg data:

| Approach                                                                                                   | Use case                                                                                            |
| :--------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| `CREATE ICEBERG TABLE` (this page)                                                                         | Register an external Iceberg table in Firebolt's catalog so it can be queried like a regular table. |
| [`READ_ICEBERG`](/reference-sql/functions-reference/iceberg/read_iceberg)                                  | Query an Iceberg table ad hoc using a table-valued function, without registering it in the catalog. |
| [`CREATE ICEBERG TABLE AS SELECT`](/reference-sql/commands/data-definition/create-iceberg-table-as-select) | Export data from Firebolt into a new Iceberg table in external storage.                             |

## Remarks

* The `LOCATION` must reference an Iceberg source (`SOURCE = ICEBERG`). Using a non-Iceberg location will result in an error.
* The table schema must be specified explicitly in the `CREATE` statement and must be compatible with the schema in the Iceberg metadata.
* All Firebolt query optimizations for Iceberg tables apply, including [caching](/performance-and-observability/iceberg-and-external-data#iceberg-caching), [pruning](/performance-and-observability/iceberg-and-external-data#understanding-pruning), and [co-located joins](/performance-and-observability/iceberg-and-external-data#co-located-joins-and-aggregations-on-iceberg-tables).
* Iceberg tables support [aggregating indexes](/performance-and-observability/storage-and-indexing/aggregating-index), which can be created with [`CREATE AGGREGATING INDEX`](/reference-sql/commands/data-definition/create-aggregating-index) to accelerate repeated aggregation queries.
* Firebolt can automatically collect [Automated Column Statistics (ACS)](/performance-and-observability/query-planning/automated-column-statistics) for Iceberg tables, enabling the query planner to generate more efficient execution plans.

## Limitations

* DML operations (`INSERT`, `UPDATE`, `DELETE`) on Iceberg tables are not supported. The table is read-only from Firebolt's perspective.
* `CREATE OR REPLACE` is not supported for Iceberg tables.
* `IF NOT EXISTS` is not supported for Iceberg tables.
* Only [Iceberg `LOCATION`](/reference-sql/commands/data-definition/create-location-iceberg) objects are supported. The location must point to a valid Iceberg catalog.