Glossary¶

This page defines key terms used throughout the zarr-python documentation and API.

Array Structure¶

Array¶

An N-dimensional typed array stored in a Zarr store. An array's metadata defines its shape, data type, chunk layout, and codecs.

Group¶

A container for arrays and other groups, enabling hierarchical organization of data — similar to directories in a file system, or groups in HDF5. Like arrays, each group has its own metadata and attributes. See the groups documentation.

Chunk¶

The fundamental unit of data in a Zarr array. An array is divided into chunks along each dimension according to the chunk grid. Each chunk is independently compressed and encoded through the array's codec pipeline.

When sharding is used, "chunk" refers to the inner chunks within each shard, because those are the compressible units. The chunks are the smallest units that can be read independently.

Convention specific to zarr-python

The use of "chunk" to mean the inner sub-chunk within a shard is a convention adopted by zarr-python's Array API. In the Zarr V3 specification and in other Zarr implementations, "chunk" may refer to the top-level grid cells (which zarr-python calls "shards" when the sharding codec is used). Be aware of this distinction when working across libraries.

API: Array.chunks returns the chunk shape. When sharding is used, this is the inner chunk shape.

Chunk Grid¶

The partitioning of an array's elements into chunks. In Zarr V3, the chunk grid is defined in the array metadata and determines the boundaries of each storage object.

Zarr V3 supports two chunk grid types:

Regular: All chunks have the same shape (the last chunk along each dimension may be smaller than the declared size).
Rectilinear (experimental): Each dimension can have different chunk sizes, specified as a list of edge lengths per dimension. Enable with zarr.config.set({'array.rectilinear_chunks': True}).

When sharding is used, the chunk grid defines the shard boundaries, not the inner chunk boundaries. The inner chunk shape is defined within the sharding codec.

API: The chunk_grid field in array metadata contains the storage-level grid. Array.chunks returns the chunk shape for regular grids. For all grid types, Array.read_chunk_sizes and Array.write_chunk_sizes return the per-dimension chunk sizes in dask-style tuple[tuple[int, ...], ...] format. Note that while the chunk grid is a public concept of the Zarr format, the classes zarr-python uses to model chunk grids are currently private API.

Shard¶

A storage object that contains one or more chunks. Sharding reduces the number of objects in a store by grouping chunks together, which improves performance on file systems and object storage.

Within each shard, chunks are compressed independently and can be read individually. However, writing requires updating the full shard for consistency, making shards the unit of writing and chunks the unit of reading.

Sharding is implemented as a codec (the sharding indexed codec). When sharding is used:

The chunk grid in metadata defines the shard boundaries
The sharding codec's chunk_shape defines the inner chunk size
Each shard contains shard_shape / chunk_shape chunks per dimension

API: Array.shards returns the shard shape, or None if sharding is not used. Array.chunks returns the inner chunk shape.

Storage¶

Store¶

A key-value storage backend that holds Zarr data and metadata. Stores implement the zarr.abc.store.Store interface. Examples include local file systems, cloud object storage (S3, GCS, Azure), zip files, and in-memory dictionaries.

Each chunk or shard is stored as a single value (object or file) in the store, addressed by a key derived from its grid coordinates.

Metadata¶

The JSON document that describes an array or group. In Zarr format 3 this is a single zarr.json document; Zarr format 2 stores the equivalent information in separate .zarray, .zgroup, and .zattrs documents. For arrays, metadata includes the shape, data type, chunk grid, fill value, and codec pipeline. Metadata is stored alongside the data in the store. Zarr-Python does not yet expose its internal metadata representation as part of its public API.

Attributes¶

User-defined key-value pairs (any JSON-serializable values) attached to an array or group. Attributes are stored in the metadata document. See the attributes documentation.

Consolidated Metadata¶

A copy of the metadata of every array and group in a hierarchy, stored in the metadata of the root group so that the entire hierarchy can be inspected with a single read from the store. See the consolidated metadata documentation.

Codecs¶

Codec¶

A transformation applied to array data during reading and writing. Codecs are chained into a pipeline and come in three types:

Array-to-array: Transforms like transpose that rearrange array elements
Array-to-bytes: Serialization that converts an array to a byte sequence (exactly one required)
Bytes-to-bytes: Compression or checksums applied to the serialized bytes

The sharding indexed codec is a special array-to-bytes codec that groups multiple chunks into a single storage object.

API Properties¶

The following properties are available on zarr.Array:

Property	Description
`.chunks`	Chunk shape — the inner chunk shape when sharding is used. Raises for rectilinear grids
`.shards`	Shard shape, or `None` if no sharding
`.read_chunk_sizes`	Per-dimension chunk data sizes (`tuple[tuple[int, ...], ...]`). Works for all grid types
`.write_chunk_sizes`	Per-dimension storage chunk sizes (`tuple[tuple[int, ...], ...]`). Works for all grid types
`.nchunks`	Total number of independently compressible units across the array
`.cdata_shape`	Number of independently compressible units per dimension