Iceberg Functions

Search Shortcut cmd + k | ctrl + k

Documentation / Core Extensions / Iceberg

Iceberg Functions

The iceberg extension provides the following functions:

Function	Description
`iceberg_scan(source)`	Reads an Iceberg table from a path.
`iceberg_metadata(source)`	Returns the manifest entries of an Iceberg table.
`iceberg_snapshots(source)`	Returns the snapshots of an Iceberg table.
`iceberg_table_properties(table)`	Returns all properties of the specified table.
`iceberg_schema_properties(schema)`	Returns all properties of the specified schema.
`set_iceberg_schema_properties(schema, properties)`	Sets properties on the specified schema.
`remove_iceberg_schema_properties(schema, property_list)`	Removes properties from the specified schema.
`iceberg_to_ducklake(iceberg_catalog, ducklake_catalog)`	Copies the Iceberg metadata of a catalog to a DuckLake catalog.

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

count_star()
51793

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

manifest_path	manifest_sequence_number	manifest_content	status	content	file_path	file_format	record_count
lineitem_iceberg/metadata/10eaca8a-1e1c-421e-ad6d-b232e5ee23d3-m1.avro	2	DATA	ADDED	EXISTING	lineitem_iceberg/data/00041-414-f3c73457-bbd6-4b92-9c15-17b241171b16-00001.parquet	PARQUET	51793
lineitem_iceberg/metadata/10eaca8a-1e1c-421e-ad6d-b232e5ee23d3-m0.avro	2	DATA	DELETED	EXISTING	lineitem_iceberg/data/00000-411-0792dcfe-4e25-4ca3-8ada-175286069a47-00001.parquet	PARQUET	60175

`iceberg_snapshots`

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

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

sequence_number	snapshot_id	timestamp_ms	manifest_list
1	3776207205136740581	2023-02-15 15:07:54.504	lineitem_iceberg/metadata/snap-3776207205136740581-1-cf3d0be5-cf70-453d-ad8f-48fdc412e608.avro
2	7635660646343998149	2023-02-15 15:08:14.73	lineitem_iceberg/metadata/snap-7635660646343998149-1-10eaca8a-1e1c-421e-ad6d-b232e5ee23d3.avro

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

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:

Function	Description
`iceberg_table_properties(table)`	Returns all properties of the specified table.

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

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.

Function	Description
`iceberg_schema_properties(schema)`	Returns all properties of the specified schema.
`set_iceberg_schema_properties(schema, properties)`	Sets properties on the specified schema.
`remove_iceberg_schema_properties(schema, property_list)`	Removes properties from the specified 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']);

DuckDB Home Code of Conduct Trademark Use Blog