Lookup speed (vs. 1.x)
Version 2.0 introduced an R-tree spatial index (TzWorld.Backend.SpatialIndex) that replaces the linear bounding-box scan used by every 1.x backend. Lookups are faster on every measured workload, with the largest wins on no-match queries (e.g. ocean points) where the previous algorithm had to walk every shape's bounding box. Speedups versus the 1.x backends, by input category:
| Input category | Speedup vs. 1.x |
|---|---|
ocean (no-match) | 18.2× |
sparse_or_large | 1.64× |
dense (cities) | 1.43× |
| random uniform | 1.42× |
small_or_thin | 1.08× |
Lookups also bypass the GenServer mailbox and read directly from :persistent_term, so they are lock-free under concurrent load and scale linearly with cores. Numbers above were collected with benchee/backend.exs on the without-oceans dataset; reproduce locally with mix run benchee/backend.exs.
mix tz_world.update memory (vs. 1.x)
Version 2.0 also rewrote the data-update pipeline to stream end-to-end. The source zip is downloaded straight to a temp file (no in-memory body), unzipped to disk (no in-memory JSON), parsed in 64 KiB chunks via OTP's built-in :json module with a feature-diverting decoder callback, and each Geo.Polygon / Geo.MultiPolygon is written to the on-disk index as it is decoded. The full GeoJSON is never resident in memory at any point.
Measured BEAM peak memory of mix tz_world.update on the without-oceans dataset (158 MB GeoJSON, 419 shapes, post-GC sampled):
| Version | Peak BEAM memory during update |
|---|---|
| 1.x | ≈ 920 MB |
| 2.x | ≈ 70 MB |
About a 13× reduction. The 2.x peak is bounded by one in-flight feature's coordinate buffer plus the parser's per-chunk state, not by the dataset size — so the with-oceans dataset (~ 3× larger) lands at sub-300 MB peak in 2.x where 1.x peaked at multiple GB.
The on-disk format itself (priv/timezones-geodata.tzw1) is also incrementally consumable: backends stream shapes one at a time at startup rather than loading the full file into memory before iterating it. TzWorld.Backend.DetsWithIndexCache rebuild on update was reduced from O(all shapes resident) to O(one shape) for the same reason.