---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: zarr
excerpt: |
  DuckDB Community Extensions
  Query Zarr array stores (v2 and v3) with SQL — read xarray-convention datasets as tables

extension:
  name: zarr
  description: Query Zarr array stores (v2 and v3) with SQL — read xarray-convention datasets as tables
  version: 0.2.1
  language: Rust
  build: cargo
  requires_toolchains: "rust;python3"
  excluded_platforms: "linux_amd64_musl"
  license: MIT
  maintainers:
    - alxmrs
    - d33bs

repo:
  github: xqlsystems/duckdb-zarr
  ref: 473cb3b203ff0c2f7f330bc6a4c0cbe4ed5c6474
  variegata: 473cb3b203ff0c2f7f330bc6a4c0cbe4ed5c6474

docs:
  hello_world: |
    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;
  extended_description: |
    The duckdb-zarr extension exposes [Zarr](https://zarr.dev/) array stores as SQL tables,
    following the [xarray](https://xarray.dev/) 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`:

    ```sql
    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:

    ```sql
    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;
    ```

extension_star_count: 66
extension_star_count_pretty: 66
extension_download_count: 752
extension_download_count_pretty: 752
image: '/images/community_extensions/social_preview/preview_community_extension_zarr.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), 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.

<div class="extension_compatibility_table"></div>

| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ❌ | ❌ | ✅ | ❌ | ✅ |
| Linux ARM64 | ❌ | ❌ | ✅ | ❌ | ✅ |
| macOS AMD64 | ❌ | ❌ | ✅ | ❌ | ❌ |
| macOS ARM64 | ❌ | ❌ | ✅ | ❌ | ✅ |
| Windows AMD64 | ❌ | ❌ | ✅ | ❌ | ✅ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ❌ | ❌ | ❌ | ❌ | ✅ |

### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

|   function_name    | function_type | description | comment | examples |
|--------------------|---------------|-------------|---------|----------|
| read_zarr          | table         | NULL        | NULL    |          |
| read_zarr_groups   | table         | NULL        | NULL    |          |
| read_zarr_metadata | table         | NULL        | NULL    |          |
| read_zarr_tables   | table         | NULL        | NULL    |          |
| read_zarr_views    | table         | NULL        | NULL    |          |

### Overloaded Functions

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

This extension does not add any types.

### Added Settings

<div class="extension_settings_table"></div>

|      name      |                       description                       | input_type | scope  | aliases | typed_value |
|----------------|---------------------------------------------------------|------------|--------|---------|-------------|
| temp_directory | Set the directory to which temporary files are written. | VARCHAR    | GLOBAL | []      | post.db.tmp |