You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4a1a441
Browse filesBrowse the repository at this point in the historyBrowse files
docs(blog): render post list and fill in release-post details
Configure the Material blog plugin so docs/blog/index.md renders a
reverse-chronological post list instead of a blank page. The plugin ships
with mkdocs-material, which is already pinned, so no new dependency is
needed. Archive and category indexes are disabled -- one post doesn't
justify the extra navigation.
Fill in the [NEEDS INPUT] placeholders in the 3.3.0 post from the release
notes and user guide: the zarr-developers#3524 regression report, the zarr-developers#3885 / zarr-developers#3925 /
zarr-developers#3987 / zarr-developers#3004 pull requests, runnable config examples for both
FusedCodecPipeline and the coalescing knobs, and links to the release
notes and config guide.
Also correct two accuracy issues: FusedCodecPipeline is opt-in and
experimental (not on by default, unlike coalescing), and the sharding
example now consistently says four inner chunks rather than switching to
three mid-paragraph.
Assisted-by: ClaudeCode:claude-opus-5
We're happy to announce the release of version 3.3.0 of Zarr-Python. It's been a while since our last release,
4
-
and we're bringing some exciting additions in 3.3.0. For the full release notes, see [NEEDS INPUT], otherwise stick around for an overview of two performance-centric highlights of this release.
12
+
and we're bringing some exciting additions in 3.3.0. For the full release notes, see the [3.3.0 release notes](../../release-notes.md), otherwise stick around for an overview of two performance-centric highlights of this release.
13
+
14
+
<!-- more -->
5
15
6
16
## Faster low-latency storage
7
17
8
-
[NEEDS INPUT]
9
-
<listissuesandPRsrelatedtothisfeature>
18
+
Relevant issues and pull requests:
19
+
20
+
-[#3524](https://github.com/zarr-developers/zarr-python/issues/3524) -- the performance report that started this work
21
+
-[#3885](https://github.com/zarr-developers/zarr-python/pull/3885) -- synchronous codec APIs and the `FusedCodecPipeline`
10
22
11
23
### The cost of async overhead
12
24
13
25
Zarr-Python 3.x uses async routines for fetching data and decoding chunks. In terms of code, this means our store (data fetching) and codec (chunk decoding) APIs are both async. This makes
14
26
I/O against high-latency storage backends like cloud object storage efficient. But for *low-latency* storage, like in-process memory or the file system, async routines add measurable overhead and offer no benefit. Async only adds value when there's work to be done while waiting for I/O to complete, but when I/O latency is low, it completes too quickly to run anything while waiting, and we are left paying the performance bill for obligatory async task scheduling that offered no value.
15
27
16
-
This performance problem became acute when Zarr-Python users reported that in-memory array indexing workloads ran *slower* in Zarr-Python 3.x relative to Zarr-Python 2.18 (issue [NEEDS INPUT]). Fortunately this performance regression had a straightforward fix (I don't say "easy" because it was a lot of work).
28
+
This performance problem became acute when Zarr-Python users reported that in-memory array indexing workloads ran *slower* in Zarr-Python 3.x relative to Zarr-Python 2.18 ([#3524](https://github.com/zarr-developers/zarr-python/issues/3524)). Fortunately this performance regression had a straightforward fix (I don't say "easy" because it was a lot of work).
17
29
18
30
### Synchronous execution restores performance
19
31
20
32
If async overhead makes low-latency storage slow, does *removing* that overhead restore performance? Yes, it does!
21
33
22
-
In a series of PRs ([NEEDS INPUT]) we defined synchronous versions of our storage and codec APIs, and then combined them in a new codec orchestration class called `FusedCodecPipeline`. The `FusedCodecPipeline` is an alternative to the default (the `BatchedCodecPipeline`) that gives large speedups for low-latency storage.
34
+
In [#3885](https://github.com/zarr-developers/zarr-python/pull/3885) we defined synchronous versions of our storage and codec APIs -- the `SyncByteGetter` and `SyncByteSetter` protocols, plus a `get_ranges_sync` method on the `Store` ABC -- and then combined them in a new codec orchestration class called `FusedCodecPipeline`. The `FusedCodecPipeline` is an opt-in alternative to the default (the `BatchedCodecPipeline`) that gives large speedups for low-latency storage. It is currently marked [experimental](../../user-guide/experimental.md), so we may change it as we learn more; the default pipeline is untouched, and existing code keeps working unless you opt in.
35
+
36
+
The win here is *not* a faster compressor or a different on-disk format -- the bytes written are byte-for-byte identical. It is the removal of async scheduling overhead (including some [nasty `asyncio.to_thread` overhead](https://github.com/python/cpython/issues/136084)), plus a few vectorized fast paths for dense, uncompressed shards.
23
37
24
38
On this author's 10-core Apple M4 laptop, the `FusedCodecPipeline` delivers the following results against memory-backed arrays:
39
+
25
40
- uncompressed writes are *~4 times faster*
26
41
- uncompressed reads are *~5 times faster*
27
42
- compressed writes are *~2 times faster*
@@ -34,23 +49,102 @@ thread-based parallelism is worse than useless and slows things down. But for co
34
49
35
50
### How to use it
36
51
37
-
[NEEDS INPUT] code example showing how to set the global config or use the `config` attribute of an array
52
+
Select the pipeline through the [runtime configuration](../../user-guide/config.md) by setting `codec_pipeline.path`. Set it globally to affect every array created or opened afterwards:
Or scope it to a block of code by using `zarr.config.set` as a context manager, which is the safer choice if you only want the new pipeline for part of your program:
Thread-based parallelism is configured separately, via `codec_pipeline.max_workers`. It defaults to `None`, meaning a pool sized to `os.cpu_count()`. As noted above, memory-backed and uncompressed workloads often do better with a single worker:
-[#3925](https://github.com/zarr-developers/zarr-python/pull/3925) -- `Store.get_ranges` for concurrent, coalesced multi-range reads
113
+
-[#3987](https://github.com/zarr-developers/zarr-python/pull/3987) -- control coalescing through `ArrayConfig` and the runtime config
42
114
43
115
### How sharding works
44
116
45
-
Chunks encoded with the `sharding_indexed` contain subchunks, or "inner chunks". For example, if the `chunk_grid` field of the array metadata declares an "outer chunk" size of, say `(10, 10)`, a `sharding_indexed` codec in the `codecs` field could declare an "inner chunk" size of `(5, 5)`. Readers accessing such a chunk will observe a stored object (a stream of bytes) that decodes to an array with size `(10, 10)` (the "outer chunk"), which is comprised of four separate, contiguous byte ranges that each decode to a `(5, 5)` inner chunk. Each inner chunk occupies its own byte range in the outer chunk. A reader can satisfy a request for 3 inner chunks by issuing 3 separate byte-range requests. That's what previous versions of Zarr-Python did.
117
+
Chunks encoded with the `sharding_indexed`codec contain subchunks, or "inner chunks". For example, if the `chunk_grid` field of the array metadata declares an "outer chunk" size of, say `(10, 10)`, a `sharding_indexed` codec in the `codecs` field could declare an "inner chunk" size of `(5, 5)`. Readers accessing such a chunk will observe a stored object (a stream of bytes) that decodes to an array with size `(10, 10)` (the "outer chunk"), which is comprised of four separate, contiguous byte ranges that each decode to a `(5, 5)` inner chunk. Each inner chunk occupies its own byte range in the outer chunk. A reader can satisfy a request for all four inner chunks by issuing four separate byte-range requests. That's what previous versions of Zarr-Python did.
46
118
47
119
### Interval equivalence
48
120
49
-
Byte ranges, being intervals, obey some combination rules: the values in two half-open intervals `[a, b), [b, c)` can be captured by the single interval `[a, c)`. That means a reader could get all three inner chunks with *one* byte-range request by requesting a range of bytes starting with the first byte of the first subchunk and ending with the last byte of the last subchunk. When individual requests are expensive, this kind of optimization is worth a lot; we could use one request instead of three, in the previous example.
121
+
Byte ranges, being intervals, obey some combination rules: the values in two half-open intervals `[a, b), [b, c)` can be captured by the single interval `[a, c)`. That means a reader could get all four inner chunks with *one* byte-range request by requesting a range of bytes starting with the first byte of the first subchunk and ending with the last byte of the last subchunk. When individual requests are expensive, this kind of optimization is worth a lot; we could use one request instead of four, in the previous example.
50
122
51
123
### Byte range coalescing
52
124
53
-
We call this procedure -- rewriting `N` byte range requests into `M` byte range requests, where `M` <= `N` -- "byte range coalescing", and it's a new performance optimization shipping in Zarr-Python 3.3.0. It's on by default with base settings we think are good, so most users won't need to tune anything. If you do need to adjust some settings, see the full documentation of the feature: [NEEDS INPUT] link to official docs
125
+
We call this procedure -- rewriting `N` byte range requests into `M` byte range requests, where `M` <= `N` -- "byte range coalescing", and it's a new performance optimization shipping in Zarr-Python 3.3.0. Unlike the `FusedCodecPipeline`, this one is on by default with base settings we think are good, so most users won't need to tune anything.
126
+
127
+
Two knobs control it, both documented in the [runtime configuration guide](../../user-guide/config.md). Nearby byte ranges in the same shard are merged into a single request when the gap between them is no larger than `array.sharding_coalesce_max_gap_bytes` (default 1 MiB) and the merged read stays within `array.sharding_coalesce_max_bytes` (default 16 MiB). The gap threshold is what trades wasted bytes against saved requests: raising it reads more data you didn't ask for, in exchange for fewer round trips.
128
+
129
+
You can set them globally, or per array by passing `config={...}` to [`zarr.create_array`][]:
0 commit comments