Iceberg in the Browser

In this post, we describe the current patterns for interacting with Iceberg Catalogs, after which we ask the question, could it be done from a browser? After elaborating on the DuckDB ecosystem changes required to unlock this capability, we demonstrate our browser only approach to interacting with an Iceberg REST Catalog, no extra setup required.

Interaction Models for Iceberg Catalogs

Iceberg is an Open Table Format, which allows you to capture a mutable database table as a set of static files on object storage (such as AWS S3). Iceberg catalogs allow you to track and organize Iceberg tables. For example, Iceberg REST Catalogs provide these functionalities through a REST API.

There are two common ways to interact with Iceberg catalogs:

• The client–server model, where the compute part of the operation is delegated to a managed infrastructure (such as the cloud). Users can interact with the server by installing a local client or using a lightweight client such as a browser.
• The client-is-the-server model, where the user first installs the relevant libraries, and then performs queries directly on their machine.

Both models have their tradeoffs. In the client–server model, clients can be lightweight, and the server is a central access point to the Iceberg catalog. However, the infrastructure necessitates additional maintenance. In the client-is-the-server model, the query latency is lower, users can leverage local compute resources, and integration between local inputs and external data sources happens at the user level. This requires users to run computation locally, which means transferring part of the burden to your users (e.g., setting up dependencies).

Iceberg engine implementations work using either of those interaction models: they are either run natively in managed compute infrastructure or they are are run locally to the user.

Let's see how things look with DuckDB in the mix!

Iceberg with DuckDB

DuckDB supports both Iceberg interaction models. In the client–server model, DuckDB runs on the server to read the Iceberg datasets. From the user's point of view, the choice of engine is transparent, and DuckDB is just one of many engines that the server could use in the background. The client-is-the-server model is more interesting: here, users install a DuckDB client locally and use it through its SQL interface to query Iceberg catalogs. For example:

CREATE SECRET test_secret (
    TYPE S3, 
    KEY_ID 'AKIAIOSFODNN7EXAMPLE',
    SECRET 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
);

ATTACH 'warehouse' AS db (
    TYPE ICEBERG,
    ENDPOINT_URL 'https://your-iceberg-endpoint',
);

SELECT sum(value)
FROM db.table
WHERE other_column = 'some_value';

You can discover the full DuckDB-Iceberg extension feature set, including insert and update capabilities, in our earlier blog post.

Iceberg with DuckDB in the Browser

While setting up a local DuckDB installation is quite simple, opening a browser tab is even quicker. Therefore, we asked ourselves: could we support the client-is-the-server model directly from within a browser tab? This could provide a zero-setup, no-infrastructure, properly serverless option for interacting with Iceberg catalogs.

Luckily, DuckDB has a client that can run in any browser! DuckDB-Wasm is a WebAssembly port of DuckDB, which supports loading of extensions.

Interacting with an Iceberg REST Catalog requires a number of functionalities; the ability to talk to a REST API over HTTP(S), the ability to read and write avro and parquet files on object storage, and finally, the ability to negotiate authentication to access those resources on behalf of the user. All of these must be done from a within a browser without calling any native components.

To support these functionalities, we implemented the following high-level changes:

• In the core duckdb codebase, we redesigned HTTP interactions, so that extensions and clients have a uniform interface to the networking stack. (PR)
• In duckdb-wasm, we implemented such an interface, which in this case is a wrapper around the available JavaScript network stack. (PR)
• In duckdb-iceberg, we routed all networking through the common HTTP interface, so that native DuckDB and DuckDB-Wasm execute the same logic. (PR)

The result is that you can now query Iceberg with DuckDB running directly in a browser! Now you can access the same Iceberg catalog using client–server, client-is-the-server, or properly serverless from the isolation of a browser tab!

Welcome to Serverless Iceberg Analytics

To see a demo of serverless Iceberg analytics, visit our table visualizer at duckdb.org/visualizer?iceberg.

TODO - add video

The current credentials in the demo are provided via a throwaway account with minimal permissions. If you enter your own credentials and share a link, you will be sharing your credentials.

Access Your Own Data

Substituting your own S3Tables bucket ARN and credentials with policy AmazonS3TablesReadOnlyAccess, you can also access your catalog, metadata and data. Computations are fully local, and the credentials and warehouse ID are only sent to the catalog endpoint specified in your Attach command. Inputs are translated to SQL, and added to the hash segment of the URL.

This means that:

• no sensitive data is handled or sent to duckdb.org
• computations are local, fully in your browser
• you can use the familiar SQL interface with the same code snippets can be run everywhere DuckDB runs
• if you edit the credentials and share the resulting link, you will be be sharing the new credentials

As of today, this works with Amazon S3 Tables. This has been implemented through a collaboration with the Amazon S3 Tables team. To learn more about S3 Tables, how to get started and their feature set, you can take a look at their product page or documentation. A demo of DuckDB querying S3 Tables from a browser was presented at AWS Re:Invent 2025, view the presentation.

Conclusion

The DuckDB-Iceberg extension is now supported in DuckDB-Wasm and it can read and edit Iceberg REST Catalogs. Users can now access Iceberg data from within a browser, without having to install or manage any compute nodes!

If you would like to provide feedback or file issues, please reach out to us on either the DuckDB-Wasm or DuckDB-Iceberg repository. If you are interested in using any part of this within your organization, feel free to reach out.