> ## 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.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.firebolt.io/feedback

```json
{
  "path": "/reference-sql/commands/data-definition/create-iceberg-table-as-select",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

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

# CREATE ICEBERG TABLE AS SELECT

<Note>
  Firebolt's Apache Iceberg write capabilities are currently in public preview. We are gathering feedback and expanding support for this feature.
</Note>

Creates an Apache Iceberg table in object storage, and exports data into it based on the [SELECT](/reference-sql/commands/queries/select) query. The table column names and types are automatically inferred based on the output columns of the [SELECT](/reference-sql/commands/queries/select).

## Syntax

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE ICEBERG TABLE <table_name>
[PARTITION BY (<partition_expression> [, ...])]
AS <select_query>
WITH LOCATION = <location_name> [<setting_name> = <setting_value> ...]
```

## Parameters

| Parameter         | Description                                                                                                                              |
| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `<table_name>`    | Table name. Currently not used, but a value must be provided.                                                                            |
| `<select_query`>  | Any valid select query.                                                                                                                  |
| `<location_name>` | The name of an [Iceberg `LOCATION`](/reference-sql/commands/data-definition/create-location-iceberg) object with `CATALOG = FILE_BASED`. |
| `<setting_name>`  | The name of a [system setting](/reference-sql/system-settings).                                                                          |
| `<setting_value>` | The value to assign to system setting `<setting_name>`.                                                                                  |

### PARTITION BY

The `PARTITION BY` clause defines how the Iceberg table is partitioned. You can partition by column names or by [Iceberg partition transform functions](/reference-sql/functions-reference/iceberg#partition-transform-functions).

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
PARTITION BY (<column_name> | <partition_transform_expression>[, ...])
```

The following Iceberg partition transform functions can be used in `PARTITION BY` expressions:

* [`ICEBERG_YEAR`](/reference-sql/functions-reference/iceberg/partitioning/iceberg_year)
* [`ICEBERG_MONTH`](/reference-sql/functions-reference/iceberg/partitioning/iceberg_month)
* [`ICEBERG_DAY`](/reference-sql/functions-reference/iceberg/partitioning/iceberg_day)
* [`ICEBERG_HOUR`](/reference-sql/functions-reference/iceberg/partitioning/iceberg_hour)
* [`ICEBERG_BUCKET`](/reference-sql/functions-reference/iceberg/partitioning/iceberg_bucket)
* [`ICEBERG_TRUNCATE`](/reference-sql/functions-reference/iceberg/partitioning/iceberg_truncate)

## Examples

The following example writes the results of a `SELECT` query into a new Iceberg table at `s3://my-bucket/path/to/iceberg/output`.

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE LOCATION my_location
WITH 
  SOURCE = ICEBERG
  CATALOG = FILE_BASED
  CATALOG_OPTIONS = (
    URL = 's3://my-bucket/path/to/iceberg/output'
  )
  CREDENTIALS = ( ... );

CREATE ICEBERG TABLE my_iceberg_table
  AS SELECT * FROM my_firebolt_table
    WHERE timestamp_col >= TIMESTAMP '2025-10-01'
WITH LOCATION = my_location;
```

The following example creates an Iceberg table partitioned by the column `region`:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE ICEBERG TABLE my_partitioned_table
  PARTITION BY region
  AS SELECT * FROM my_firebolt_table
WITH LOCATION = my_location;
```

The following example uses a [partition transform function](/reference-sql/functions-reference/iceberg#partition-transform-functions) to partition by month:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE ICEBERG TABLE my_monthly_table
  PARTITION BY iceberg_month(timestamp_col)
  AS SELECT * FROM my_firebolt_table
WITH LOCATION = my_location;
```

You can combine column names and partition transform functions:

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE ICEBERG TABLE my_multi_partitioned_table
  PARTITION BY region, iceberg_year(timestamp_col), iceberg_bucket(user_id, 16)
  AS SELECT * FROM my_firebolt_table
WITH LOCATION = my_location;
```

## Remarks

You can use the [`iceberg_insert_sharding`](/reference-sql/system-settings#iceberg-insert-sharding) setting to control the trade-off between parallelism and the number of output files per partition. By default, Firebolt tries to group files of the same partition on the same nodes, resulting in less load per node and fewer output files, which is usually preferred for query performance.

## Limitations:

* Catalogs: only supports a FILE\_BASED catalog in AWS S3 object storage. I.e. the data and metadata files will be written to the specified location in S3.

* Data types: supports the Iceberg equivalents of [Firebolt's data types](/reference-sql/data-types), except `GEOGRAPHY`.

* Metadata: only writes limited metadata that is optional per the Iceberg spec. Does not write column statistics, etc.

* DML operations on Iceberg tables are not supported. Only the `CREATE ICEBERG TABLE AS SELECT` and `SELECT` from [`READ_ICEBERG(...)`](/reference-sql/functions-reference/iceberg/read_iceberg) operations are supported for Iceberg tables.