⌘K ctrl+k
Search Shortcut cmd + k | ctrl + k
S3 Iceberg Import

Prerequisites

Loading an Iceberg file from S3 requires both the httpfs and iceberg extensions. Install them using the INSTALL SQL command. You only need to install extensions once.

INSTALL httpfs;
INSTALL iceberg;

To load the extensions, use the LOAD command:

LOAD httpfs;
LOAD iceberg;

Credentials

After loading the extensions, set up the credentials and S3 region to read data. You may either use an access key and secret, or a token.

CREATE SECRET (
    TYPE s3,
    KEY_ID 'AKIAIOSFODNN7EXAMPLE',
    SECRET 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    REGION 'us-east-1'
);

To fetch credentials automatically instead — or to use a named profile, SSO, or an assumed role — see the aws extension. The default looks like:

CREATE SECRET (
    TYPE s3,
    PROVIDER credential_chain
);

Loading Iceberg Tables from S3

After the extensions are set up and the S3 credentials are correctly configured, Iceberg tables can be read from S3 using the following command:

SELECT *
FROM iceberg_scan('s3://bucket/iceberg_table_folder/metadata/id.metadata.json');

If you pass the table folder instead of the metadata file, DuckDB looks for a version-hint.text file in the table's metadata directory. If there is no such file, you'll get an error like this:

Invalid Configuration Error: Failed to read iceberg table. No version was provided and no version-hint could be found, globbing the filesystem to locate the latest version is disabled by default as this is considered unsafe and could result in reading uncommitted data. To enable this use 'SET unsafe_enable_version_guessing = true;'

In this case, link directly to the metadata file or see Selecting Metadata Versions.

© 2026 DuckDB Foundation, Amsterdam NL
DuckDB Home Code of Conduct Trademark Use Blog