The iceberg extension provides the following functions:

The examples on this page use the iceberg_data.zip file; download and unzip it to run them.

iceberg_scan

The iceberg_scan function reads an Iceberg table from a path, without requiring an attached catalog:

SELECT count(*)
FROM iceberg_scan('data/iceberg/lineitem_iceberg', allow_moved_paths = true);

The path can also point directly to a metadata file, or to an object store such as S3 or Azure Blob Storage. See the Iceberg Options page for the parameters accepted by this function.

iceberg_metadata

To access Iceberg metadata, you can use the iceberg_metadata function:

SELECT *
FROM iceberg_metadata('data/iceberg/lineitem_iceberg', allow_moved_paths = true);

iceberg_snapshots

To visualize the snapshots in an Iceberg table, use the iceberg_snapshots function:

SELECT *
FROM iceberg_snapshots('data/iceberg/lineitem_iceberg');

iceberg_snapshots does not take allow_moved_paths, snapshot_from_id or snapshot_from_timestamp as parameters.

iceberg_column_stats

The iceberg_column_stats function returns the statistics stored in the manifests for every data file and column. Its columns include file_path, column_name, column_type, lower_bound, upper_bound, value_count, null_value_count and nan_value_count.

SELECT *
FROM iceberg_column_stats('data/iceberg/lineitem_iceberg', allow_moved_paths = true);

iceberg_partition_stats

The iceberg_partition_stats function returns statistics per partition field. Its columns include partition_field_name, partition_source_columns, partition_field_transform, lower_bound and upper_bound.

SELECT *
FROM iceberg_partition_stats(my_datalake.default.t);

iceberg_load_table_response

The iceberg_load_table_response function is an advanced function that only works with an attached Iceberg REST Catalog. It returns the raw LoadTable response of the catalog with the columns metadata_location, metadata (VARIANT), config (MAP), storage_credentials and request_url.

SELECT *
FROM iceberg_load_table_response(my_datalake.default.t);

Metadata Operations on Attached Catalogs

The functions iceberg_metadata and iceberg_snapshots are also available to use with an attached Iceberg catalog using a fully qualified path, e.g.:

SELECT * FROM iceberg_metadata(my_datalake.default.t)

-- Or
SELECT * FROM iceberg_snapshots(my_datalake.default.t)

This functionality enables the user to do time traveling.

-- Using a snapshot id
SELECT * FROM my_datalake.default.t AT (VERSION => SNAPSHOT_ID)

-- Or using a timestamp
SELECT * FROM my_datalake.default.t AT (TIMESTAMP => TIMESTAMP '2025-09-22 12:32:43.217')

Table Properties Functions

DuckDB provides functions to view and modify Iceberg table properties:

You can also use ALTER TABLE ... SET and ALTER TABLE ... RESET to modify table properties:

-- View table properties
SELECT *
FROM iceberg_table_properties(iceberg_catalog.default.my_table);

-- Set table properties
ALTER TABLE iceberg_catalog.default.my_table SET (
    'write.update.mode'='merge-on-read', 
    'write.delete.mode'='merge-on-read',
    'format-version'=3
);

-- Remove table properties
ALTER TABLE iceberg_catalog.default.my_table RESET (
    'write.update.mode',
    'owner'
);

The set_iceberg_table_properties and remove_iceberg_table_properties functions take the table name as a string and cannot change reserved Iceberg table properties. In particular, format-version can only be changed with ALTER TABLE ... SET.

CALL set_iceberg_table_properties('iceberg_catalog.default.my_table', {
    'write.update.mode': 'merge-on-read'
});

CALL remove_iceberg_table_properties(
    'iceberg_catalog.default.my_table',
    ['write.update.mode']
);

Schema Properties Functions

Iceberg catalogs allow arbitrary key-value properties to be attached at the schema (namespace) level. These properties are typically used to record ownership, descriptions, default storage locations, or any other metadata that applies to every table in a schema.

-- Set schema properties
CALL set_iceberg_schema_properties(iceberg_catalog.default, {
    'owner': 'analytics-team',
    'description': 'Default analytics schema'
});

-- Read schema properties
SELECT * FROM iceberg_schema_properties(iceberg_catalog.default);

-- Remove schema properties
CALL remove_iceberg_schema_properties(
    iceberg_catalog.default,
    ['description']
);

Schema properties are written through the Iceberg REST Catalog, so any other Iceberg-aware engine attached to the same catalog will see the updates immediately. remove_iceberg_schema_properties returns the number of remaining schema properties.

Metadata Table Functions

The following functions expose the Iceberg metadata tables. Like iceberg_metadata and iceberg_snapshots, they accept either a table path (along with the scan options metadata_compression_codec, version and version_name_format) or a table in an attached catalog.

SELECT file_path, record_count, file_size_in_bytes
FROM iceberg_files(my_datalake.default.t);

SELECT *
FROM iceberg_partition_specs(my_datalake.default.t);

iceberg_scan_plan

The iceberg_scan_plan(table) function is an advanced function that returns the scan tasks DuckDB would read for a table, i.e., one row per data file together with its partition values and the delete files that apply to it. The table argument is the fully qualified name of a table in an attached Iceberg REST Catalog as a string (e.g., 'my_datalake.default.t'), or a table location. It accepts the following named parameters:

If the iceberg_use_server_side_scan_planning setting is enabled and the catalog supports it, the planning is performed by the REST Catalog.

iceberg_view_metadata

The iceberg_view_metadata(view) function is the counterpart of iceberg_load_table_response for views: it returns the raw LoadView response of an attached Iceberg REST Catalog with the columns metadata_location, metadata (VARIANT), config (MAP) and request_url. This is useful for inspecting views, including views defined in a SQL dialect DuckDB cannot parse.

SELECT *
FROM iceberg_view_metadata('my_datalake.default.my_view');

Table Maintenance Functions

iceberg_rollback_to_snapshot

The iceberg_rollback_to_snapshot(table, snapshot_id) function sets the current snapshot of a table in an attached Iceberg catalog to an earlier snapshot. The table name is passed as a string and the snapshot ID can be taken from iceberg_snapshots. The function returns the previous_snapshot_id and the new current_snapshot_id.

CALL iceberg_rollback_to_snapshot('my_datalake.default.t', snapshot_id);

iceberg_rewrite_data_files

The iceberg_rewrite_data_files(table) function compacts the data files of a table in an attached Iceberg catalog: it rewrites small (and overly large) data files into files close to the target file size, applying any pending position and equality deletes. It returns the columns rewritten_data_files_count, added_data_files_count, rewritten_bytes_count, failed_data_files_count and removed_delete_files_count.

CALL iceberg_rewrite_data_files('my_datalake.default.t', min_input_files => 2);

iceberg_to_ducklake

The DuckDB iceberg extension exposes a function to do metadata only copies of the Iceberg metadata to DuckLake, which enables users to query Iceberg tables as if they were DuckLake tables.

-- Given that we have an Iceberg catalog attached aliased to iceberg_datalake
ATTACH 'ducklake:my_ducklake.ducklake' AS my_ducklake;

CALL iceberg_to_ducklake('iceberg_datalake', 'my_ducklake');

It is also possible to skip a set of tables provided the skip_tables parameter.

CALL iceberg_to_ducklake('iceberg_datalake', 'my_ducklake', skip_tables := ['table_to_skip']);

Partition Transform Functions

The iceberg_bucket and iceberg_truncate scalar functions implement the Iceberg partition transforms of the same name. They are most often used implicitly through the PARTITIONED BY clause (see Partitioning), but they can also be called directly:

SELECT iceberg_bucket(16, 'duckdb');
SELECT iceberg_truncate(10, 1234);