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 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'
);

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.

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);