`getRanges` on `AsyncReadable`

[wietzesuijker]

From #347 (discussion with @kylebarron).

Where this helps today

1. Sharding codec (sharding.ts#L38-L76): two sequential getRange calls per shard (index suffix + chunk data). These are sequential, so a wrapper like feat: add BatchedFetchStore for request batching and range merging #347 can't batch them.

2. Chunk indexing (get.ts#L53-L61): concurrent chunk fetches hit the same shard file. feat: add BatchedFetchStore for request batching and range merging #347 intercepts this at the wrapper level, but a store-level method would let backends optimize natively (S3 multipart GET, local FS single file handle).

Proposal

interface AsyncReadable<Options = unknown> {
  get(key: AbsolutePath, opts?: Options): Promise<Uint8Array | undefined>;
  getRange?(key: AbsolutePath, range: RangeQuery, opts?: Options): Promise<Uint8Array | undefined>;
  getRanges?(key: AbsolutePath, ranges: RangeQuery[], opts?: Options): Promise<(Uint8Array | undefined)[]>;
}

Optional, like getRange. A defaultGetRanges utility could provide the coalescing fallback (reusing groupRequests from #347) for stores that don't override. Same pattern as Rust object_store::get_ranges, but narrower: just this method, not the full list/put/delete surface.

Open questions

• Single-path (getRanges(key, ranges[])) or multi-path (getRanges(requests[]{key, range}))? Single-path is simpler and matches object_store.
• Should the sharding codec call getRanges directly, or is that a follow-up?

[manzt]

Thanks for opening this.

I'm in favor of adding getRanges as an optional method on AsyncReadable:

interface AsyncReadable<Options = unknown> {
  get(key: AbsolutePath, opts?: Options): Promise<Uint8Array | undefined>;
  getRange?(key: AbsolutePath, range: RangeQuery, opts?: Options): Promise<Uint8Array | undefined>;
  getRanges?(key: AbsolutePath, ranges: RangeQuery[], opts?: Options): Promise<(Uint8Array | undefined)[]>;
}

Single-path (getRanges(key, ranges[])) seems right to me, matching object_store.

I think it would also be useful to have a helper that normalizes a store by polyfilling getRange (from get) and getRanges (from getRange, using coalescing). Something like:

function normalizeStore(store: AsyncReadable): AsyncReadable & {
  getRange: NonNullable<AsyncReadable["getRange"]>;
  getRanges: NonNullable<AsyncReadable["getRanges"]>;
}

This could be reused in the sharding codec (which currently does two sequential getRange calls) and in withRangeBatching (which has its own coalescing via groupRequests). Both would call store.getRanges if available, falling back to the polyfill otherwise.

[manzt]

btw, I've been working on a composable middleware system for stores (#384) that I think this would layer onto nicely:

export const withRangeBatching = wrapStore.generic<RangeBatchingOptsFor>()(
  (store, opts = {}) => {
    // ...
    return {
      getRange(key, range, options) { /* batching logic */ },
      getRanges(key, ranges, options) {
        // use native getRanges if available, otherwise coalesce via getRange
        if (store.getRanges) {
          return store.getRanges(key, ranges, options);
        }
        let groups = groupRequests(ranges, coalesceSize);
        // ...
      },
      get stats() { /* ... */ },
    };
  },
);

Then downstream consumers (like the sharding codec) could always call getRanges without checking:

let store = await zarr.createStore(
  new zarr.FetchStore("https://..."),
  zarr.withRangeBatching(),
);

await store.getRanges("/data/shard.0.0", [
  { offset: 0, length: 100 },
  { offset: 5000, length: 200 },
]);

[keller-mark]

I think it would also be useful to have a helper that normalizes a store by polyfilling getRange (from get) and getRanges (from getRange, using coalescing)

You could consider thinking about the reverse: Rather than implementing a default getRanges that calls getRange, the user would only need to implement getRanges. Then, Zarrita can provide a default implementation of the singular getRange which internally calls getRanges(key, [singleRange])[0]. This would be analogous to get_partial_many in zarrs and its default get_partial implementation. In other words, as a developer of a custom zarrs store, I only need to define get_partial_many.

On the other hand, perhaps in most cases there will be no benefit to doing it this way, and it would add a bigger breaking change than the alternative. Perhaps in the small number of cases where the plural getRanges can be optimized further, it makes sense for it to be a bit more verbose for a developer to opt into it.

I agree that it should be easier to specify that I want to polyfill getRange(s) with a "dumb" implementation based on get. Several times now in custom stores, I have implemented this type of getRange that simply calls get and extracts a subset of the array corresponding to the range, similar to the comment here #319 (comment)

(I still need to do a review of #384 but from a first glance it looks like a very promising mechanism to do all of this)

[manzt]

Rather than implementing a default getRanges that calls getRange, the user would only need to implement getRanges.

Oh i like this idea.

[kylebarron]

Then downstream consumers (like the sharding codec) could always call getRanges without checking:

I like letting downstream consumers always call getRanges.

Then, Zarrita can provide a default implementation of the singular getRange which internally calls getRanges(key, [singleRange])[0].

There's no primitive for getRanges (at least as long as you assume that no backend supports the HTTP multi-range fetch spec).

The base implementations of stores should define the primitives that make the store possible. I don't think of getRanges as a feature of the store. Except for the "coalesce size" which may differ based on the expected latency, there's no physical difference about the fetch used for HTTP and the fetch used for S3, etc.

Maybe it's just because I'm used to object-store, but I like having getRange be the core functionality, and then getRanges is a higher-level construct on top of it.

[keller-mark]

I don't feel super strongly that the plural is better (I don't have any current personal use-case that would benefit from the plural over coalescing multiple of the singular). However, for what it is worth, zarr-python uses the plural in its get_partial_values, so getRanges would align more closely to both zarrs and zarr-python.

https://github.com/zarr-developers/zarr-python/blob/9681cf998a006f4a5f50f90a4ff288b1e3bba606/src/zarr/abc/store.py#L427

My latter point was more important to my personal usage of zarrita: for stores that do not support any type of Range operation, it should be easy to fall back to a trivial default based only on get being implemented.

[keller-mark]

I think there are only three scenarios:

• A user who only wants to implement the singular getRange, and wants zarrita to fill-in the plural getRanges by internally calling getRange multiple times.
• A user who only wants to implement the plural getRanges, and wants zarrita to fill-in the singular getRange by internally calling getRanges with a one-element array.
• A user who does not want to implement either getRange or getRanges because the underlying storage does not support range/partial reading

I don't imagine there is a case in which the user wants to define both a custom getRange and getRanges. So maybe it is possible for Zarrita to detect which of these cases it is?

# pseudocode
if custom_store_implements_singular(store):
  store.getRanges = plural_from_singular(store.getRange)
else if custom_store_implements_plural(store):
  store.getRange = singular_from_plural(store.getRanges)
else:
  store.getRanges = get_range_from_get(store.get)
  store.getRange = singular_from_plural(store.getRanges)

[kylebarron]

I think we're kinda saying similar things but coming from different perspectives.

I feel that a store should implement as close to the primitives defined by the physical thing it's binding to. In this case, the primitive is for making one request, not for making multiple requests. There's no way to make a multi-fetch.

So the required method should be getRange and the provided method with a default should be getRanges (with a default to coalesce multiple requests that are closer than some gap, where that gap is ideally configurable).

I definitely don't think we should allow sometimes implementing only getRange and sometimes only implementing getRanges.

[d-v-b]

I don't feel super strongly that the plural is better (I don't have any current personal use-case that would benefit from the plural over coalescing multiple of the singular). However, for what it is worth, zarr-python uses the plural in its get_partial_values, so getRanges would align more closely to both zarrs and zarr-python.

https://github.com/zarr-developers/zarr-python/blob/9681cf998a006f4a5f50f90a4ff288b1e3bba606/src/zarr/abc/store.py#L427

My latter point was more important to my personal usage of zarrita: for stores that do not support any type of Range operation, it should be easy to fall back to a trivial default based only on get being implemented.

please don't treat the zarr-python store API as some kind of authority here. there are plenty of things I wish we had done differently, including get_partial_values.

[keller-mark]

Ok, it seems like my initial comment took this thread down a rabbit hole. The initial issue and the subsequent comments from @manzt seemed to be agreeing on the solution of adding getRanges? to the AsyncReadable interface, so maybe the later discussion of how to fill in the missing parts should be ignored so that we can move forward.

[manzt]

Sorry for the radio silence here. I'm focused on getting out v0.7 with some important improvements and changes. I'd like to prioritize getting this resolved and fixscaleoffset for the following release.