# Reading and Writing Iceberg Tables from Data Workbench

info
This feature is not enabled on accounts by default. Contact Technical Support or your Customer Success representative to enable it.

This guide explains how to read and write Iceberg tables using the Trino query engine in Data Workbench.

## Overview

Data Workbench provides access to an Iceberg catalog alongside the standard Data Workbench catalog. Iceberg tables written through Data Workbench are stored in Apache Iceberg format, enabling seamless integration with external Cloud Data Warehouses (e.g., Databricks, Snowflake) via zero-copy access.

**Key characteristics:**

- Iceberg tables are accessed using the `iceberg` catalog in Trino
- Only the Trino engine supports reading and writing Iceberg tables (Hive is not supported)
- Data is stored in Apache Parquet format (Iceberg table format Version 2)


## Prerequisites

1. **Iceberg catalog permissions** granted by an admin user (see [Database-Level Access Control for Iceberg Catalog](/ja/products/customer-data-platform/composable-publish/permission-management))
2. Familiarity with running Trino queries in Data Workbench (see [Data Workbench Trino Quickstart](/products/customer-data-platform/data-workbench/queries/trino/quickstart))


## Table Naming Convention

Iceberg tables use a three-part fully-qualified name:

```
iceberg.<database>.<table>
```

| Component | Description | Example |
|  --- | --- | --- |
| Catalog | Always `iceberg` | `iceberg` |
| Database | `td{account_id}_{site}_export` | `td10000_us01_export` |
| Table | User-defined table name | `my_table` |


**Example fully-qualified table name:** `iceberg.td10000_us01_export.my_table`

## Supported SQL Commands

For detailed syntax, see [Trino SQL Statement Syntax](https://trino.io/docs/423/sql.html) and [Trino Iceberg Connector SQL Support](https://trino.io/docs/423/connector/iceberg.html#sql-support).

**Note:** Commands not listed here are not guaranteed to work and may be unsupported or behave unexpectedly.

### DDL (Data Definition Language)

| Command | Description | Required Permission |
|  --- | --- | --- |
| `CREATE TABLE` | Create a new table with column definitions | `WRITE` or `FULL` |
| `CREATE TABLE AS SELECT` | Create a table from query results | `WRITE` or `FULL` |
| `ALTER TABLE SET PROPERTIES` | Modify table properties (e.g., partitioning) | `FULL` |
| `ALTER TABLE EXECUTE optimize` | Compact data files for better query performance | `FULL` |
| `DROP TABLE` | Delete a table and its data | `FULL` |
| `COMMENT ON TABLE` | Add a comment to a table | `WRITE` or `FULL` |
| `COMMENT ON COLUMN` | Add a comment to a column | `WRITE` or `FULL` |


### DML (Data Manipulation Language)

| Command | Description | Required Permission |
|  --- | --- | --- |
| `INSERT INTO` | Insert rows into a table | `WRITE` or `FULL` |
| `UPDATE` | Update existing rows (see warning below) | `WRITE` or `FULL` |
| `DELETE` | Delete rows matching a condition (see warning below) | `WRITE` or `FULL` |
| `MERGE` | Upsert rows (insert or update based on condition, see warning below) | `WRITE` or `FULL` |


Warning: DELETE/UPDATE/MERGE and Databricks Compatibility
Trino writes row-level deletes using Iceberg v2 position delete files, which Databricks does not support. After running `DELETE`, `UPDATE`, or `MERGE` operations, you must run `ALTER TABLE EXECUTE optimize` to rewrite the affected data files. Until optimization is performed, the table may not be readable from Databricks.

### Query

| Command | Description | Required Permission |
|  --- | --- | --- |
| `SELECT` | Query data with filtering, aggregation, joins, etc. | `READ` or `FULL` |
| `EXPLAIN` | Show query execution plan | `READ` or `FULL` |
| `EXPLAIN ANALYZE` | Show query plan with execution statistics | `READ` or `FULL` |


### Metadata

| Command | Description | Required Permission |
|  --- | --- | --- |
| `SHOW SCHEMAS` | List available databases | `READ`, `WRITE`, or `FULL` |
| `SHOW TABLES` | List tables in a database | `READ`, `WRITE`, or `FULL` |
| `SHOW COLUMNS` | List columns of a table | `READ`, `WRITE`, or `FULL` |
| `SHOW CREATE TABLE` | Show the CREATE TABLE statement | `READ`, `WRITE`, or `FULL` |
| `DESCRIBE` | Show table schema | `READ`, `WRITE`, or `FULL` |
| `ANALYZE` | Compute table statistics | `FULL` |


### Information Schema

You can query `information_schema` to discover databases, tables, and columns programmatically.

| Table | Description |
|  --- | --- |
| `iceberg.information_schema.schemata` | List all accessible databases |
| `iceberg.information_schema.tables` | List all accessible tables |
| `iceberg.information_schema.columns` | List columns of all accessible tables |


Only resources belonging to your own account are visible.

### Unsupported Commands

| Command | Reason |
|  --- | --- |
| `CREATE SCHEMA` | Database creation is managed by TD |
| `DROP SCHEMA` | Database deletion is managed by TD |
| `TRUNCATE TABLE` | Not supported by the Iceberg connector |
| `CREATE VIEW` | Not supported |
| `CREATE MATERIALIZED VIEW` | Not supported |


## Examples

### Writing Iceberg Tables

#### Create a Table by Copying Data from Data Workbench

Use `CREATE TABLE AS SELECT` (CTAS) to copy data from a Data Workbench table into an Iceberg table:

```sql
CREATE TABLE iceberg.td10000_us01_export.customer_segments
AS
SELECT * FROM my_database.customer_segments;
```

#### Create an Empty Table

```sql
CREATE TABLE iceberg.td10000_us01_export.events (
    event_id VARCHAR,
    user_id BIGINT,
    event_type VARCHAR,
    event_time TIMESTAMP(6) WITH TIME ZONE
)
WITH (
    partitioning = ARRAY['day(event_time)']
);
```

#### Insert Data

```sql
INSERT INTO iceberg.td10000_us01_export.events
SELECT event_id, user_id, event_type, event_time
FROM my_database.raw_events
WHERE td_interval(time, '-1d');
```

### Reading Iceberg Tables

#### Query a Table

```sql
SELECT * FROM iceberg.td10000_us01_export.customer_segments
LIMIT 100;
```

#### List Tables in a Database

```sql
SHOW TABLES FROM iceberg.td10000_us01_export;
```

#### View Table Schema

```sql
DESCRIBE iceberg.td10000_us01_export.customer_segments;
```

## Restrictions

### Restricted Table Properties

The following table properties cannot be specified by users:

| Property | Reason |
|  --- | --- |
| `location` | Data location is automatically assigned per account |
| `format` | Always Parquet; cannot be changed |


### Unsupported Features

The following Trino Iceberg features are not supported in Data Workbench:

- Views and materialized views
- System procedures


### Engine Limitation

- Only the **Trino** engine can read and write Iceberg tables
- The Hive engine does not support Iceberg table operations


### Data Format

- Only Apache Parquet is supported as the underlying data format


### Quotas

| Resource | Limit |
|  --- | --- |
| Tables per database | 200,000 |


## Further Reference

- [Trino SQL Statement Syntax](https://trino.io/docs/423/sql.html)
- [Trino Iceberg Connector SQL Support](https://trino.io/docs/423/connector/iceberg.html#sql-support)