Downloads 36this week

GitHub stars 18

Extension repository on GitHub

Extension descriptor (YAML)

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

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 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) scans all rows from a single-group Zarr store.
• read_zarr(path, dims=['time','lat','lon']) selects one dim group from a multi-group store.
• read_zarr_metadata(path) inspects array names, dtypes, shapes, and roles.
• read_zarr_groups(path) enumerates distinct dimension groups in a store.

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 (consolidated metadata required for remote array listing; 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

This extension does not add any settings.