Skip to content

Array creation

zarrista.ArrayBuilder

A chained, immutable builder for creating Zarr arrays.

Every setter returns a new ArrayBuilder and leaves the receiver unchanged. Start with the constructor or ArrayBuilder.like, chain setters to configure it, then make the array with create or create_async. To make only the metadata, use create_metadata.

Examples:

Create a 1024x1024 int32 array with 256x256 chunks and zstd compression:

from zarrista import ArrayBuilder, ChunkGrid, DataType, FillValue, codec
from zarrista.store import FilesystemStore

grid = ChunkGrid.regular([1024, 1024], chunk_shape=[256, 256])
dtype = DataType.from_string("int32")
fill_value = FillValue((0).to_bytes(4, "little"))

array = (
    ArrayBuilder(grid, dtype, fill_value)
    .dimension_names(["y", "x"])
    .compressors([codec.zstd(3, checksum=False)])
    .create(FilesystemStore("data"), "/temperature")
)

create writes the metadata to the store. Each setter returns a new builder, so you can keep a partly configured builder and reuse it:

base = ArrayBuilder(grid, dtype, fill_value).dimension_names(["y", "x"])
uncompressed = base.create(store, "/raw")
compressed = base.compressors([codec.zstd(3, checksum=False)]).create(
    store, "/compressed"
)

__init__ 

__init__(chunk_grid: ChunkGrid, dtype: DataType, fill_value: FillValue) -> None

Create a builder from a chunk grid, data type, and fill value.

Parameters:

  • chunk_grid (ChunkGrid) –

    The chunk grid of the array. The grid also gives the array shape.

  • dtype (DataType) –

    The data type of the array.

  • fill_value (FillValue) –

    The fill value of the array. This must match dtype.

attrs 

attrs(attrs: Mapping[str, JSONValue]) -> ArrayBuilder

Return a new builder with the given user attributes set.

Parameters:

Returns:

  • ArrayBuilder –

    A new builder with the user attributes set.

chunk_grid 

chunk_grid(chunk_grid: ChunkGrid) -> ArrayBuilder

Return a new builder with the chunk grid set.

This can also change the array shape, because the grid carries one.

Parameters:

  • chunk_grid (ChunkGrid) –

    The chunk grid of the array.

Returns:

chunk_key_encoding 

chunk_key_encoding(chunk_key_encoding: ChunkKeyEncoding) -> ArrayBuilder

Return a new builder with the chunk key encoding set.

Parameters:

  • chunk_key_encoding (ChunkKeyEncoding) –

    How the array maps chunk grid indices to store keys.

Returns:

  • ArrayBuilder –

    A new builder with the chunk key encoding set.

compressors 

compressors(compressors: Sequence[BytesToBytesCodec]) -> ArrayBuilder

Return a new builder with the bytes-to-bytes codecs ("compressors") set.

Parameters:

Returns:

create 

create(store: SyncStore, path: str) -> Array

Build the array in store at path and return it.

This does write to the store. It stores the array's metadata at path, and it overwrites any metadata already there. Use ArrayBuilder.create_metadata to build metadata without a store.

Parameters:

  • store (SyncStore) –

    The store to write the array metadata to.

  • path (str) –

    The absolute path of the array in the store.

Returns:

  • Array –

    The new array.

Raises:

  • ArrayCreateError –

    If path is not a valid absolute node path, if the fill value does not match the data type, or if the number of dimension names does not match the number of dimensions.

create_async async 

create_async(store: AsyncStore, path: str) -> AsyncArray

Build the array in an async store at path and return it.

This does write to the store. It stores the array's metadata at path, and it overwrites any metadata already there. Use ArrayBuilder.create_metadata to build metadata without a store.

Parameters:

  • store (AsyncStore) –

    The async store to write the array metadata to.

  • path (str) –

    The absolute path of the array in the store.

Returns:

Raises:

  • ArrayCreateError –

    If path is not a valid absolute node path, if the fill value does not match the data type, or if the number of dimension names does not match the number of dimensions.

create_metadata 

create_metadata() -> ZarrV3ArrayMetadataJSON

Build the array's Zarr v3 metadata without a store.

This writes nothing. Pass the result to Array.from_metadata to open an in-memory array. To build and write in one step, use ArrayBuilder.create.

Returns:

Raises:

  • ArrayCreateError –

    If the fill value does not match the data type, or if the number of dimension names does not match the number of dimensions.

data_type 

data_type(data_type: DataType) -> ArrayBuilder

Return a new builder with the data type set.

Parameters:

  • data_type (DataType) –

    The data type of the array. The fill value must match this data type.

Returns:

dimension_names 

dimension_names(dimension_names: Sequence[str | None] | None) -> ArrayBuilder

Return a new builder with the dimension names set (or cleared).

Parameters:

  • dimension_names (Sequence[str | None] | None) –

    One name per dimension. A name can be None to leave that dimension unnamed. Give None to clear all the names.

Returns:

  • ArrayBuilder –

    A new builder with the dimension names set.

filters 

filters(filters: Sequence[ArrayToArrayCodec]) -> ArrayBuilder

Return a new builder with the array-to-array codecs ("filters") set.

Parameters:

Returns:

like staticmethod 

like(array: Array | AsyncArray) -> ArrayBuilder

Create a builder that copies the configuration of an existing array.

Parameters:

Returns:

  • ArrayBuilder –

    A new builder with the same configuration as array.

serializer 

serializer(serializer: ArrayToBytesCodec) -> ArrayBuilder

Return a new builder with the array-to-bytes codec ("serializer") set.

Sharding is itself an array-to-bytes codec. Therefore you pass a sharding serializer here too.

Parameters:

Returns:

shape 

shape(shape: Sequence[int]) -> ArrayBuilder

Return a new builder with the array shape set.

This shape replaces the shape that the chunk grid gives.

Parameters:

  • shape (Sequence[int]) –

    The shape of the array, in elements along each dimension.

Returns:

subchunk_shape 

subchunk_shape(subchunk_shape: Sequence[int] | None) -> ArrayBuilder

Return a new builder with the inner (subchunk) shape, enabling sharding.

Parameters:

  • subchunk_shape (Sequence[int] | None) –

    The shape of an inner chunk, in elements along each dimension. Give None to disable sharding.

Returns:

  • ArrayBuilder –

    A new builder with the subchunk shape set.

zarrista.ArrayBytes

Chunk bytes as input to or output from a codec.

The object holds a data buffer. It can also hold the element byte offsets for variable-length data, and a validity mask.

bytes property 

bytes: Buffer

The underlying element bytes (the data buffer for optional bytes).

mask property 

mask: Buffer | None

The validity mask (1 byte per element), or None if not optional.

offsets property 

offsets: list[int] | None

Element byte offsets, or None for fixed-length data.

__init__ 

__init__(
    value: Buffer,
    /,
    *,
    mask: Buffer | None = None,
    offsets: list[int] | None = None,
) -> None

Construct from a data buffer, with an optional mask and offsets.

This does not check mask or offsets against value. The codec pipeline reports an error only when it uses the data.

Parameters:

  • value (Buffer) –

    The element bytes.

Keyword Arguments:

  • mask (Buffer | None) –

    The validity mask, with one byte per element. Give None for data that is not optional.

  • offsets (list[int] | None) –

    The element byte offsets. Give None for fixed-length data.