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

Iceberg catalog permissions granted by an admin user (see Database-Level Access Control for Iceberg Catalog)
Familiarity with running Trino queries in Data Workbench (see Data Workbench 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 and Trino Iceberg Connector 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:

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

Create an Empty Table

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

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

SELECT * FROM iceberg.td10000_us01_export.customer_segments
LIMIT 100;

List Tables in a Database

SHOW TABLES FROM iceberg.td10000_us01_export;

View Table Schema

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