zarr

752 downloads this week 66 stars Extension descriptor

Query Zarr array stores (v2 and v3) with SQL — read xarray-convention datasets as tables

Compatibility Matrix

This table covers all DuckDB releases that have not reached end-of-life, including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

Installing and Loading

INSTALL zarr FROM community;
LOAD zarr;

Example

INSTALL zarr FROM community;
LOAD zarr;

-- Read a local Zarr store as a table
SELECT time, lat, lon, temperature
FROM read_zarr('path/to/store.zarr')
LIMIT 10;

-- Inspect and query a multiscale OME-Zarr bioimage
SELECT name, dims, shape
FROM read_zarr_metadata('image.ome.zarr');

SELECT c, AVG("0") AS mean_intensity
FROM read_zarr('image.ome.zarr', array_path = '0')
GROUP BY c;

About zarr

The duckdb-zarr extension exposes Zarr array stores as SQL tables, following the xarray dimension convention used by climate science, geospatial, and bioimaging datasets.

Functions

• read_zarr(path) — scan all rows from a single-group Zarr store.
• read_zarr(path, table_name := 'time_lat_lon') — select one table when a group has several (by the name read_zarr_tables gives it; dims := [...] selects by its dimensions).
• read_zarr(path, group_path := 'a/b') — read a nested group, as xarray's group=.
• read_zarr_metadata(path) — inspect array names, dtypes, shapes, and roles.
• read_zarr_tables(path) — list every group's tables, with the schema and table name each maps to (read_zarr_groups is the 0.1.x name).
• read_zarr_views(path, 'db') — the statements that mount every table as a view in database db (view_names := MAP {...} renames them); run them to get db.main.time_lat_lon and so on.

Automatic path interception

Any path ending in .zarr is automatically routed to read_zarr:

SELECT * FROM 'era5.zarr' LIMIT 5;
SELECT * FROM 'https://example.org/data.zarr' LIMIT 5;

Supported formats

• Zarr v2 and v3
• Codecs: gzip, zstd, blosc, crc32c, sharding, transpose, bytes (big/little endian)
• CF conventions: scale_factor/add_offset packed integers, _FillValue/missing_value null masking
• Local filesystem, HTTP/HTTPS, S3, GCS, and Azure Blob Storage. Remote stores must carry consolidated metadata — a Zarr v2 .zmetadata object or a Zarr v3 consolidated_metadata block — because object stores cannot list directories. S3/GCS/Azure credentials are read from DuckDB's secrets manager — CREATE SECRET ... TYPE S3 etc.

Bioimage and OME-Zarr

OME-Zarr images commonly contain multiple resolution levels and nested label arrays. Use read_zarr_metadata to discover store-relative array paths, then pass array_path to select a level or label image:

SELECT name, dims, shape, dtype
FROM read_zarr_metadata('image.ome.zarr');

SELECT c, AVG("0") AS mean_intensity
FROM read_zarr('image.ome.zarr', array_path = '0')
WHERE y BETWEEN 100 AND 199
  AND x BETWEEN 200 AND 299
GROUP BY c;

SELECT "labels/nuclei/0" AS label, COUNT(*) AS pixels
FROM read_zarr('image.ome.zarr', array_path = 'labels/nuclei/0')
WHERE "labels/nuclei/0" > 0
GROUP BY label;

Added Functions

Overloaded Functions

This extension does not add any function overloads.

Added Types

This extension does not add any types.

Added Settings