Skip to content

Commit 9e6eeae

Browse files
committed
Add Store.get_many bulk fetch API
Add a public, overridable `Store.get_many` that retrieves many values at once - each request being a whole key or a `(key, byte_range)` pair. It generalizes `Store.get_ranges` (many ranges of one key) to many keys, and yields `(request_index, Buffer | None)` batches in completion order so a store can coalesce reads that land in the same underlying object. The ABC default fetches requests concurrently with `get`, so every store works out of the box; stores with a bulk backend override it (`FsspecStore` coalesces via fsspec's `cat_ranges`). Coalescing tuning is left to each store rather than exposed on the interface. This restores and generalizes the batched-fetch capability of the v2 `getitems` Store API (see zarr-developersgh-1806).
1 parent 1ab9953 commit 9e6eeae

4 files changed

Lines changed: 130 additions & 2 deletions

File tree

‎changes/1806.feature.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Add `zarr.abc.store.Store.get_many`, a bulk counterpart to `Store.get` that
2+
retrieves many values — each a whole key or a `(key, byte_range)` pair — in a
3+
single call. It generalizes `Store.get_ranges` (many ranges of one key) to many
4+
keys, yielding `(request_index, Buffer | None)` batches in completion order so a
5+
store can coalesce reads that land in the same underlying object. The method is
6+
defined on the `Store` ABC with a default implementation that fetches the
7+
requests concurrently with `Store.get`, so every store inherits a working
8+
version; stores whose backend can retrieve many objects together should override
9+
it (`FsspecStore` does, coalescing via `fsspec`'s `cat_ranges`). Coalescing
10+
tuning is left to each store rather than exposed on the interface. This restores
11+
and generalizes the batched-fetch capability of the v2 `getitems` Store API.

‎src/zarr/abc/store.py‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,71 @@ async def get_partial_values(
237237
"""
238238
...
239239

240+
async def get_many(
241+
self,
242+
requests: Sequence[tuple[str, ByteRequest | None] | str],
243+
*,
244+
prototype: BufferPrototype,
245+
) -> AsyncIterator[Sequence[tuple[int, Buffer | None]]]:
246+
"""Retrieve many values, possibly from different keys, at once.
247+
248+
This is the bulk counterpart to :meth:`get`: the whole set of requests
249+
is handed to the store in a single call, so an implementation can fetch
250+
them together — for example by coalescing reads that land in the same
251+
underlying object into fewer requests — rather than one at a time. It
252+
generalizes :meth:`get_ranges` (which reads many ranges from a *single*
253+
key) to many keys, each with an optional byte range.
254+
255+
Yields one batch per underlying I/O operation, each a sequence of
256+
``(request_index, Buffer | None)`` tuples where ``request_index`` is the
257+
position of the request in ``requests``. Every request is reported
258+
exactly once across all batches; a ``None`` buffer means that key is
259+
absent. Batches arrive in completion order, not request order, so
260+
callers use the indices to reassemble results.
261+
262+
The default implementation fetches each request concurrently with
263+
:meth:`get`, so every store gets a working version for free; stores
264+
whose backend can retrieve many objects together (e.g.
265+
:class:`~zarr.storage.FsspecStore`, which coalesces nearby reads via
266+
``fsspec``) should override it. Anything specific to *how* a store
267+
batches or coalesces (concurrency limits, gap thresholds, ...) is an
268+
implementation concern of that store, not part of this interface.
269+
270+
Parameters
271+
----------
272+
requests : Sequence[tuple[str, ByteRequest | None] | str]
273+
The values to retrieve. Each request is either a bare key (the
274+
whole value) or a ``(key, byte_range)`` tuple; a ``byte_range`` of
275+
``None`` also means the whole value. A key may appear more than
276+
once with different ranges.
277+
prototype : BufferPrototype
278+
The prototype of the output buffers. Stores may support a default
279+
buffer prototype.
280+
281+
Yields
282+
------
283+
Sequence[tuple[int, Buffer | None]]
284+
One batch per underlying I/O operation, each a sequence of
285+
``(request_index, Buffer | None)`` tuples.
286+
"""
287+
# Local imports to avoid an import cycle at module load time.
288+
from zarr.core.common import concurrent_map
289+
from zarr.core.config import config
290+
291+
indexed = [
292+
(i, req, None) if isinstance(req, str) else (i, req[0], req[1])
293+
for i, req in enumerate(requests)
294+
]
295+
296+
async def _fetch(
297+
index: int, key: str, byte_range: ByteRequest | None
298+
) -> tuple[int, Buffer | None]:
299+
return index, await self.get(key, prototype, byte_range)
300+
301+
results = await concurrent_map(indexed, _fetch, config.get("async.concurrency"))
302+
for result in results:
303+
yield [result]
304+
240305
@abstractmethod
241306
async def exists(self, key: str) -> bool:
242307
"""Check if a key exists in the store.

‎src/zarr/storage/_fsspec.py‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
logger = getLogger(__name__)
2323

2424
if TYPE_CHECKING:
25-
from collections.abc import AsyncIterator, Iterable
25+
from collections.abc import AsyncIterator, Iterable, Sequence
2626

2727
from fsspec import AbstractFileSystem
2828
from fsspec.asyn import AsyncFileSystem
@@ -459,6 +459,23 @@ async def get_partial_values(
459459

460460
return [None if isinstance(r, Exception) else prototype.buffer.from_bytes(r) for r in res]
461461

462+
async def get_many(
463+
self,
464+
requests: Sequence[tuple[str, ByteRequest | None] | str],
465+
*,
466+
prototype: BufferPrototype,
467+
) -> AsyncIterator[Sequence[tuple[int, Buffer | None]]]:
468+
# docstring inherited
469+
# Hand the whole set of requests to fsspec in one call so it can
470+
# coalesce nearby reads into fewer requests (via
471+
# ``AbstractFileSystem._cat_ranges``), rather than issuing one request
472+
# per key as the default Store.get_many does. get_partial_values
473+
# returns results aligned to the input order, so we can index them
474+
# directly and yield them as a single completed batch.
475+
key_ranges = [(req, None) if isinstance(req, str) else req for req in requests]
476+
values = await self.get_partial_values(prototype, key_ranges)
477+
yield list(enumerate(values))
478+
462479
async def list(self) -> AsyncIterator[str]:
463480
# docstring inherited
464481
allfiles = await self.fs._find(self.path, detail=False, withdirs=False)

‎src/zarr/testing/store.py‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -262,7 +262,7 @@ async def test_get_raises(self, store: S) -> None:
262262
with pytest.raises((ValueError, TypeError), match=r"Unexpected byte_range, got.*"):
263263
await store.get("c/0", prototype=default_buffer_prototype(), byte_range=(0, 2)) # type: ignore[arg-type]
264264

265-
async def test_get_many(self, store: S) -> None:
265+
async def test_get_many_streaming(self, store: S) -> None:
266266
"""
267267
Ensure that multiple keys can be retrieved at once with the _get_many method.
268268
"""
@@ -407,6 +407,41 @@ async def test_get_partial_values(
407407
obs.to_bytes() == exp.to_bytes() for obs, exp in zip(observed, expected, strict=True)
408408
)
409409

410+
async def test_get_many(self, store: S) -> None:
411+
# put a handful of whole values
412+
for key, data in {"c/0/0": b"aaaaa", "c/0/1": b"bb", "c/0/2": b"cccc"}.items():
413+
await self.set(store, key, self.buffer_cls.from_bytes(data))
414+
415+
# mix bare keys, an explicit (key, None) tuple, a partial range, and a
416+
# missing key. Each request must be reported exactly once, by index.
417+
requests: list[tuple[str, ByteRequest | None] | str] = [
418+
"c/0/0",
419+
("c/0/1", None),
420+
("c/0/0", RangeByteRequest(1, 3)),
421+
"c/0/2",
422+
"c/0/missing",
423+
]
424+
collected: dict[int, Buffer | None] = {}
425+
async for batch in store.get_many(requests, prototype=default_buffer_prototype()):
426+
for index, value in batch:
427+
assert index not in collected # reported exactly once
428+
collected[index] = value
429+
430+
assert set(collected) == set(range(len(requests)))
431+
assert collected[4] is None # missing key -> None (not omitted)
432+
expected = {0: b"aaaaa", 1: b"bb", 2: b"aa", 3: b"cccc"} # index 2 is "aaaaa"[1:3]
433+
for index, want in expected.items():
434+
buffer = collected[index]
435+
assert buffer is not None
436+
assert buffer.to_bytes() == want
437+
438+
async def test_get_many_empty(self, store: S) -> None:
439+
# an empty request is valid and yields no results
440+
batches = [
441+
batch async for batch in store.get_many([], prototype=default_buffer_prototype())
442+
]
443+
assert [pair for batch in batches for pair in batch] == []
444+
410445
async def test_exists(self, store: S) -> None:
411446
assert not await store.exists("foo")
412447
await store.set("foo/zarr.json", self.buffer_cls.from_bytes(b"bar"))

0 commit comments

Comments
 (0)