GitHub

API Reference

Arrays

Zarrs.ZarrsArray — Type
ZarrsArray{T,N} <: DiskArrays.AbstractDiskArray{T,N}

A Zarr array backed by the zarrs Rust library. Supports the full AbstractArray interface via DiskArrays.jl, including slicing, broadcasting, and reductions.

source
Zarrs.zopen — Function
zopen(path::AbstractString; kwargs...) -> ZarrsArray{T,N} or ZarrsGroup

Open an existing Zarr array or group. Auto-detects V2/V3 format.

path is a URL pipeline string:

# Local filesystem
zopen("/tmp/data.zarr")

# HTTP (read-only)
zopen("https://example.com/data.zarr")

# S3 (read/write)
zopen("s3://bucket/data.zarr")

# GCS (read/write)
zopen("gs://bucket/data.zarr")

# Icechunk over S3 (read-only)
zopen("s3://bucket/repo|icechunk://branch.main/")

Keyword Arguments

  • anonymous::Bool=false: Use anonymous credentials for S3/GCS.
  • region::String="": AWS region for S3.
  • endpoint_url::String="": Custom S3 endpoint URL.
source
zopen(session::Session) -> ZarrsArray or ZarrsGroup

Open the root of an Icechunk session as a Zarr array or group.

source
Zarrs.zcreate — Function
zcreate(T, dims...; chunks, path, compressor="zstd", compressor_level=3,
        fill_value=nothing, zarr_version=3, shard_shape=nothing,
        dimension_names=nothing) -> ZarrsArray{T,N}

Create a new Zarr array at path with the given element type and dimensions.

source
zcreate(path::AbstractString, data::AbstractArray; kwargs...) -> ZarrsArray

Create a new Zarr array at path and write data into it.

source
Zarrs.zzeros — Function
zzeros(T, dims...; kwargs...) -> ZarrsArray

Create a new zero-filled Zarr array.

source
Zarrs.zinfo — Function
zinfo(z::ZarrsArray)

Print detailed metadata information about the array.

source

Groups

Zarrs.ZarrsGroup — Type
ZarrsGroup

A Zarr group backed by the zarrs Rust library. Supports hierarchical navigation.

source
Zarrs.zgroup — Function
zgroup(path::AbstractString; attrs=Dict{String,Any}()) -> ZarrsGroup

Create a new Zarr V3 group at path.

source
Base.keys — Method
Base.keys(g::ZarrsGroup) -> Vector{String}

List child array and group names.

source
Base.getindex — Method
Base.getindex(g::ZarrsGroup, key::AbstractString)

Open a child array or subgroup by name.

source

Metadata

Zarrs.dimnames — Function
dimnames(z::ZarrsArray{T,N}) -> Union{Nothing, NTuple{N, Union{String, Nothing}}}

Return the dimension names of the array, or nothing if unset. Names are returned in Julia column-major order (reversed from Zarr C-order).

source
Zarrs.get_attributes — Function
get_attributes(z::ZarrsArray) -> Dict{String,Any}

Return the array's user attributes as a dictionary.

source
get_attributes(g::ZarrsGroup) -> Dict{String,Any}

Return the group's user attributes as a dictionary.

source
Zarrs.set_attributes! — Function
set_attributes!(z::ZarrsArray, attrs::Dict)

Replace the array's user attributes and persist to storage.

source
set_attributes!(g::ZarrsGroup, attrs::Dict)

Replace the group's user attributes and persist to storage.

source

Resize

Base.resize! — Method
resize!(z::ZarrsArray, dims...) -> ZarrsArray

Resize the array to new dimensions. Existing data within the new bounds is preserved.

source

Zarrs.Icechunk

The Zarrs.Icechunk submodule provides Icechunk integration. Access with using Zarrs.Icechunk.

Storage Types

Zarrs.Icechunk.S3Storage — Type
S3Storage(; bucket, prefix="", region="", anonymous=false,
          endpoint_url="", allow_http=false,
          access_key_id="", secret_access_key="", session_token="")

Configuration for an Icechunk repository stored on Amazon S3 (or S3-compatible services like MinIO).

source
Zarrs.Icechunk.GCSStorage — Type
GCSStorage(; bucket, prefix="", credential_type=:from_env, credential_value="")

Configuration for an Icechunk repository stored on Google Cloud Storage.

Credential types

  • :from_env — use application default credentials (default)
  • :anonymous — no authentication
  • :service_account_path — path to service account JSON file (pass as credential_value)
  • :service_account_key — service account JSON string (pass as credential_value)
  • :bearer_token — bearer token string (pass as credential_value)
source
Zarrs.Icechunk.AzureStorage — Type
AzureStorage(; account, container, prefix="",
               credential_type=:from_env, credential_value="")

Configuration for an Icechunk repository stored on Azure Blob Storage.

Credential types

  • :from_env — use credentials from environment (default)
  • :access_key — Azure access key (pass as credential_value)
  • :sas_token — SAS token (pass as credential_value)
  • :bearer_token — bearer token (pass as credential_value)
source

Repository & Session

Zarrs.Icechunk.Repository — Type
Repository

An Icechunk repository handle. Create with Repository(storage; mode=:open).

Modes

  • :open — open an existing repository (default)
  • :create — create a new repository
  • :open_or_create — open if exists, otherwise create

Examples

using Zarrs.Icechunk
storage = S3Storage(bucket="my-bucket", prefix="my-repo", region="us-west-2")
repo = Repository(storage)
repo = Repository(storage; mode=:create)
source
Zarrs.Icechunk.Session — Type
Session

A session on an Icechunk repository. Created via readonly_session or writable_session. Pass to zopen to access Zarr data.

Examples

using Zarrs.Icechunk
repo = Repository(S3Storage(bucket="b", prefix="p", region="us-west-2"))
session = readonly_session(repo; branch="main")
g = zopen(session)
source
Zarrs.Icechunk.readonly_session — Function
readonly_session(repo::Repository; branch="main", tag=nothing) -> Session

Create a read-only session on the repository.

Specify either branch (default: "main") or tag to select which version to read.

source

Commit & Changes

Zarrs.Icechunk.commit — Function
commit(session::Session, message::AbstractString) -> String

Commit changes in a writable session. Returns the snapshot ID string.

source

Branch & Tag Management

Zarrs.Icechunk.create_branch — Function
create_branch(repo::Repository, name::AbstractString, snapshot_id::AbstractString)

Create a new branch pointing at the given snapshot ID.

source
Zarrs.Icechunk.create_tag — Function
create_tag(repo::Repository, name::AbstractString, snapshot_id::AbstractString)

Create a new tag pointing at the given snapshot ID.

source

Storage

Zarrs.create_storage — Function
create_storage(path::AbstractString; kwargs...) -> ZarrsStorageHandle

Create a storage handle from a URL pipeline string.

Supports the URL pipeline syntax where stages are separated by |.

Root schemes (direct access, read/write)

  • "/path/to/store" or "file:///path" — local filesystem
  • "s3://bucket/prefix" — Amazon S3
  • "gs://bucket/prefix" — Google Cloud Storage
  • "http://..." / "https://..." — HTTP (read-only)

Adapter schemes

  • "| icechunk:" — Icechunk versioned storage (read-only via pipeline)
  • "| icechunk://branch.main/" — specific branch
  • "| icechunk://tag.v1/" — specific tag

Examples

# Direct access
create_storage("/tmp/data.zarr")
create_storage("s3://bucket/data.zarr")
create_storage("gs://bucket/data.zarr")
create_storage("https://example.com/data.zarr")

# Icechunk over S3
create_storage("s3://bucket/repo|icechunk://branch.main/")

# Icechunk over memory (for testing)
create_storage("memory:|icechunk:")

Keyword Arguments

  • anonymous::Bool=false: Use anonymous credentials for S3/GCS.
  • region::String="": AWS region for S3.
  • endpoint_url::String="": Custom endpoint URL for S3-compatible services.
source
Zarrs.ZarrsArrayHandle — Type
ZarrsArrayHandle

Opaque wrapper around a zarrs array pointer. Holds a reference to its ZarrsStorageHandle to prevent GC of storage while the array is alive.

source
Zarrs.ZarrsGroupHandle — Type
ZarrsGroupHandle

Opaque wrapper around a zarrs group pointer. Holds a reference to its ZarrsStorageHandle to prevent GC of storage while the group is alive.

source

URL Pipeline

Zarrs.parse_url_pipeline — Function
parse_url_pipeline(s::AbstractString) -> URLPipeline

Parse a URL pipeline string into its root and adapter components. Supports the | delimiter between pipeline stages.

Supported root schemes

  • file:///path or bare filesystem paths
  • s3://bucket/prefix
  • gs://bucket/prefix
  • http://... / https://...
  • memory:

Supported adapter schemes

  • icechunk: with optional authority like icechunk://branch.main/
source
Zarrs.URLPipeline — Type
URLPipeline

A parsed URL pipeline consisting of a root scheme and zero or more adapter schemes.

Examples

"s3://bucket/prefix"                           → root only (direct S3)
"s3://bucket/prefix|icechunk://branch.main/" → S3 + Icechunk adapter
"memory:|icechunk:"                          → memory + Icechunk adapter
source
Zarrs.RootScheme — Type
RootScheme

Parsed root scheme from a URL pipeline string.

Fields

  • scheme::Symbol — one of :file, :s3, :gs, :http, :https, :memory
  • bucket::String — bucket/container name (S3, GCS) or empty
  • prefix::String — path within bucket, or filesystem path, or full URL
  • query::Dict{String,String} — query parameters (e.g. region, endpoint_url)
source
Zarrs.AdapterScheme — Type
AdapterScheme

Parsed adapter scheme from a URL pipeline string.

Fields

  • scheme::Symbol — e.g. :icechunk
  • authority::String — e.g. "branch.main", "tag.v1"
  • path::String — path component after authority
  • query::Dict{String,String} — query parameters
source
Zarrs.has_adapter — Function
has_adapter(pipeline::URLPipeline, scheme::Symbol) -> Bool

Check if the pipeline contains an adapter with the given scheme.

source
Zarrs.get_adapter — Function
get_adapter(pipeline::URLPipeline, scheme::Symbol) -> AdapterScheme

Get the first adapter with the given scheme, or error if not found.

source
Zarrs.parse_icechunk_authority — Function
parse_icechunk_authority(authority::AbstractString) -> Tuple{Symbol, String}

Parse an Icechunk authority string like "branch.main" or "tag.v1" into a (type, name) tuple. Returns (:branch, "main") if authority is empty.

source

Internals

Zarrs.julia_shape — Function
julia_shape(zarrs_shape) -> Tuple

Convert a C-order shape vector from zarrs to Julia column-major order by reversing.

source
Zarrs.zarrs_subset — Function
zarrs_subset(indices::NTuple{N,UnitRange{Int}}) -> (starts, shapes)

Convert Julia 1-based column-major index ranges to zarrs 0-based C-order starts and shapes.

source
Zarrs.build_v3_metadata — Function
build_v3_metadata(; T, shape, chunks, ...) -> String

Build a Zarr V3 metadata JSON string with dimensions reversed for C-order storage.

source
Zarrs.numpy_dtype_str — Function
numpy_dtype_str(T::DataType) -> String

Return the NumPy-style dtype string for Julia type T (for V2 metadata).

source
Zarrs._try_load_consolidated! — Function
_try_load_consolidated!(storage::ZarrsStorageHandle)

Attempt to load consolidated metadata from the store. Tries V3 zarr.json (with inline consolidated_metadata) first, then V2 .zmetadata. Sets storage.consolidated to a Dict if found, nothing if not found or invalid.

source
Zarrs._flatten_v3_consolidated — Function
_flatten_v3_consolidated(metadata) -> Dict{String,Any}

Flatten V3 consolidated metadata (which uses nested path keys mapping to node metadata) into V2-style flat keys for use with _keys_from_consolidated.

V3 consolidated metadata has the form: {"childname" => {"zarrformat" => 3, "node_type" => "array", ...}, ...}

We convert to flat keys like: {"childname/zarr.json" => ..., "childname/nested/zarr.json" => ...}

source
Zarrs._keys_from_consolidated — Function
_keys_from_consolidated(metadata::Dict, zarr_path::AbstractString) -> Vector{String}

Extract direct child names from consolidated metadata for the given zarr path.

source