Zarr Python

Quando usar

Use para arrays científicos fragmentados (chunked), armazenamentos hierárquicos, codecs, sharding, leituras parciais, armazenamento de objetos na nuvem e interoperabilidade com NumPy/Dask/Xarray. Este guia comunitário é voltado para Zarr-Python 3.4.0, lançado em 2026-09-15, com Python 3.12+. A versão do pacote e o formato no disco são separados: esta versão lê/escreve os formatos 2 e 3; novos arrays usam o formato 3 por padrão. Mantenha pacotes dependentes que exigem zarr<3 em seus próprios ambientes.

Instalar

uv pip install "zarr==3.4.0" "numpy==2.5.3"
# Optional remote backends and migration CLI:
uv pip install "zarr[remote,cli]==3.4.0" "fsspec==2026.9.0" "s3fs==2026.9.0" "gcsfs==2026.8.1"

Confirme o arquivo de lock resolvido do projeto. Versões de integração opcionais exercitadas aqui: Dask 2026.8.0, Xarray 2026.9.0, h5py 3.16.0, NumCodecs 0.17.0, obstore 0.11.1. Exemplos locais abaixo e nas referências usam arrays sintéticos pequenos; trechos remotos são ilustrativos e requerem um armazenamento autorizado real. Isso não estabelece permissões de nuvem, taxa de transferência de produção ou compatibilidade de todos os leitores dependentes.

Fluxo de trabalho

1. Inspecione forma (shape), tipo de dado (dtype), nomes de eixos, coordenadas, unidades, convenção de valor ausente, formato, disponibilidade de codec e leitores pretendidos. Preserve IDs de amostra e ordem dos eixos.
2. Escolha fragmentos (chunks) para seleções reais e um orçamento de memória. Para sharding, escolha dimensões de shard que sejam múltiplos das dimensões dos fragmentos. Faça benchmark de dados representativos.
3. Crie um novo destino (overwrite=False ou mode="w-"). Use mode="r" para inspeção; "a" pode criar um armazenamento ausente e "w" destrói o conteúdo existente.
4. Escreva blocos delimitados. Atribua um escritor por fragmento armazenado, ou por shard quando fragmentado (sharded); serialize metadados, anexe e redimensione operações.
5. Reabra em modo somente leitura e compare valores, dtype, shape, coordenadas, unidades, máscaras e metadados. Um fragmento não escrito ou ausente normalmente é lido como fill_value; uma abertura bem-sucedida sozinha não prova a completude dos dados.
6. Para uma hierarquia de grupo concluída, opcionalmente consolide metadados. A consolidação do formato 3 é experimental; atualize-a após alterações nos metadados e verifique os consumidores reais. Publique um armazenamento concluído somente após a validação.

Ida e volta básica de array

import numpy as np
import zarr
from zarr.codecs import BloscCodec

expected = np.arange(96, dtype="float32").reshape(12, 8)
z = zarr.create_array(
    "array.zarr", shape=expected.shape, dtype=expected.dtype,
    chunks=(4, 4), zarr_format=3,
    compressors=BloscCodec(cname="zstd", clevel=5, shuffle="bitshuffle"),
    dimension_names=("sample", "feature"),
    attributes={"units": "arbitrary", "source": "synthetic example"},
)
for start in range(0, z.shape[0], 4):
    z[start:start + 4] = expected[start:start + 4]

reopened = zarr.open_array("array.zarr", mode="r")
np.testing.assert_array_equal(reopened[:], expected)
assert reopened.dtype == expected.dtype
assert reopened.metadata.dimension_names == ("sample", "feature")
assert reopened.attrs["units"] == "arbitrary"
subset = reopened[2:6, 1:4]  # Only this selection is materialized.

create_array aceita data= ou shape= mais dtype=; não combine data= com shape/dtype explícitos. O padrão numérico do formato 3 é um serializador de bytes seguido por ZstdCodec, não Blosc. Defina um codec explicitamente para reprodutibilidade.

Criação e indexação

import numpy as np
import zarr

z = zarr.create_array(None, data=np.arange(80).reshape(10, 8), chunks=(2, 4))
zeros = zarr.zeros((10, 8), chunks=(2, 4), dtype="f4")
ones = zarr.ones((10, 8), chunks=(2, 4), dtype="f4")
filled = zarr.full((10, 8), fill_value=42, chunks=(2, 4), dtype="i4")
like = zarr.zeros_like(z)
np.testing.assert_array_equal(filled[:], np.full((10, 8), 42))

# Coordinate indexing pairs corresponding coordinates; orthogonal indexing is a product.
np.testing.assert_array_equal(z.vindex[[0, 5], [2, 7]], [2, 47])
np.testing.assert_array_equal(z.get_coordinate_selection(([0, 5], [2, 7])), [2, 47])
assert z.oindex[[0, 5], [2, 7]].shape == (2, 2)
assert z.blocks[0, 0].shape == (2, 4)
z[0, :] = np.arange(8)

Fatias com passo negativo não são suportadas. Leituras de array retornam dados NumPy na configuração padrão da CPU. np.asarray(z), np.sum(z), z[:], ou um .compute() Dask de um array completo podem materializar todo o conjunto de dados lógico; use seleções delimitadas ou reduções preguiçosas (lazy).

Redimensionamento e anexação

import numpy as np
import zarr


…