Geospatial Indexes

## What a Redis geospatial index actually is Redis does not have a separate "geo" data type. `GEOADD` writes into an ordinary **sorted set** — a collection of unique members, each with a numeric score, kept ordered by that score. The geo commands encode a longitude/latitude pair into a single 52-bit integer (a geohash) and store it as the member's score. Everything else — persistence, replication, memory accounting, `TTL` on the key — behaves exactly like a sorted set. ## Writing positions ``` GEOADD drivers:sf -122.4194 37.7749 driver:17 ``` The order is **longitude first, then latitude**. Most mapping APIs and most humans say "lat, lon", so swapping them is the single most common mistake; it will not error (both values are in range) — you just silently index a point somewhere else on the planet. `GEOADD` accepts many triples in one call and supports `NX` (only add new members), `XX` (only update existing), and `CH` (return the count of changed members rather than added ones). Updating a driver's position is simply another `GEOADD` for the same member: the member is unique, so the score is overwritten. There is no separate "move" command. Longitude must be in [-180, 180] and latitude in roughly [-85.05112878, 85.05112878]; out-of-range values are rejected with an error. ## Querying `GEOSEARCH` (Redis 6.2+) is the read command: ``` GEOSEARCH drivers:sf FROMLONLAT -122.4194 37.7749 BYRADIUS 5 km ASC COUNT 20 WITHDIST WITHCOORD ``` - **Centre**: `FROMLONLAT lon lat` for an arbitrary point, or `FROMMEMBER driver:17` to search around something already in the index. - **Shape**: `BYRADIUS r unit` for a circle, or `BYBOX width height unit` for an axis-aligned rectangle. Units are `m`, `km`, `mi`, `ft`. - **Ordering**: results are **not sorted by default**. `ASC` gives nearest-first, `DESC` farthest-first. - **Limiting**: `COUNT n` caps the reply; `COUNT n ANY` returns as soon as `n` matches are found, which is much cheaper but gives you an arbitrary `n`, not the nearest `n`. - **Extras**: `WITHDIST` (distance in the requested unit), `WITHCOORD` (the stored longitude/latitude), `WITHHASH` (the raw 52-bit score). Internally the search picks a geohash precision whose cells are at least as large as the search shape, then range-scans the nine cells around the centre (the containing cell plus its eight neighbours) and filters each candidate by exact distance. That is why the complexity is roughly O(N + log(M)) — logarithmic to locate the ranges, plus linear in the number of members sitting in the scanned area, not in the whole key. ## Reading and removing - `GEOPOS key member [member ...]` → the stored coordinates (approximate — see below), `nil` for unknown members. - `GEODIST key m1 m2 [unit]` → great-circle distance between two stored members; `nil` if either is missing. - `GEOHASH key member` → the standard 11-character geohash string, useful for interoperating with other systems. - **Deletion**: there is no `GEODEL`. Use `ZREM drivers:sf driver:17`. Likewise `ZCARD` counts members, `ZSCORE` shows the raw geohash, and `EXPIRE` sets a TTL on the whole index (never on one member). ## Precision caveats worth stating in an interview The coordinate is quantised into 52 bits, so `GEOPOS` returns a value very close to — but not exactly — what you wrote (worst case about 0.6 m off). `GEODIST` computes a great-circle distance on a sphere, so it is a straight-line "as the crow flies" number with a small percentage error, not a road or routing distance. If the product needs driving time, Redis gives you the cheap candidate set and a routing service ranks it. ## A typical production shape Positions arrive continuously, so the write path is a stream of `GEOADD`s; the read path is a `GEOSEARCH` with `COUNT` and `ASC`. Because a member has no individual TTL, stale drivers are cleaned by an explicit `ZREM` on logout plus a sweeper that removes members not refreshed recently (usually tracked in a parallel sorted set scored by last-seen timestamp).