What a learned-range index is, briefly

A learned-range index is a small neural network, typically an MLP of one or two hidden layers, that learns the cumulative distribution function (CDF) of sorted keys and predicts the leaf-page offset of any given key from that CDF. The reference is Kraska et al. (2017), “The Case for Learned Index Structures,” and the headline result, measured on specific in-memory integer-key benchmarks with the paper’s own caveats, was up to an order of magnitude faster than a B-tree on point lookups and up to 70% smaller in memory footprint; later work (Ferragina et al., 2020) showed those gains were workload-sensitive and that the win was real but smaller for general-purpose data, so we treat the headline numbers as upper bounds rather than the floor. The model replaced the tree with two or three multiply-adds per lookup; the B-tree existed only as a fallback when the model’s error term exceeded the leaf size.

In MongrelDB the learned-range index is implemented as a recency-weighted CDF: incremental updates nudge the model on hot inserts, full retraining happens at segment and compaction boundaries rather than per row, and the loss is weighted toward recent keys so the high-traffic part of the keyspace stays accurately modelled even as the tail grows. The shape is the same MLP, the loss and the update cadence are what changed.

What it bought us on the path we cared about

The path that mattered was sorted range scans on data larger than memory, and the query shape that kept appearing in our traces was WHERE event_at BETWEEN ? AND ? against an events table that had outgrown the host’s RAM. A B-tree over a 200 GB cold column on a 64 GB host pays roughly log(N) / log(fanout) random reads per query, where N is the leaf-page count, and that random-read pattern is what dominates p99 on the workloads we kept getting bug reports for, where the column was the company’s events table and the query was “everything between Tuesday and Wednesday last week.” A learned-range index over the same data collapses most of the random reads into sequential reads, because the model’s prediction lands the seek in the right column block on the first try more often than not, and the cold read degrades to “load the leaf and scan” rather than “walk the tree and load the leaf.”

We measured this on a customer trace with the kind of WHERE event_at BETWEEN ? AND ? query above against an 180 GB events table on a 64 GB host at roughly a 3-4x speedup on p99 for the cached-leaf case and a 1.5-2x speedup on p99 for the cold-leaf case; those numbers are honest, they hold over a multi-day window, and a benchmark fixture in the kit/tests directory reproduces them so anyone can re-run them on their own hardware without trusting ours.

The second thing the learned-range index bought us was a smaller working set, and that part mattered more than the latency number in the traces we cared about: a learned index holds each key distribution in a few kilobytes of model weights, where a B-tree holds the same key distribution in a few megabytes of pointers and page metadata, and the difference in cache pressure showed up as a higher hit rate on the rest of the workload, because there was more cache left over for the leaf pages the model was pointing at.

What we had to give up to get there

Unconditional correctness at the index boundary. A B-tree places every key at a known offset, so WHERE k BETWEEN 100 AND 200 returns exactly the keys whose value is in [100, 200], every time, with no error term to reason about. A learned-range index has a model error that defines a “delta band” around each prediction, and a query that lands in that band has to fall back to a leaf scan; on data with sharp CDF cliffs (compressed keys, monotonic timestamps) the delta band is narrow and the scan is short, but on data with heavy tail skew (event sources, sparse UUIDs) the delta band is wider and the scan turns into the worst case the model was supposed to prevent. The default IndexBuildPolicy::Learned configures the model for the common recency-heavy case; on data that is not recency-heavy, you fall back to IndexBuildPolicy::BTree and the B-tree beats the learned index. We chose that on purpose rather than papering over it.

Engineering cost. Training a model per index is not a one-line addition to a B-tree codepath; it is a separate subsystem with its own CI fixtures, its own drift detection (model error as measured against held-out data is a real signal we monitor in the catalog), its own rebuild policy on schema change, and its own failure mode when the loss function does not converge on a degenerate distribution (uniform UUIDs, for example). That cost is real, and it is the kind of cost that makes a database team ask whether the speedup justifies the cognitive load; we think it does, but we are not going to pretend that a B-tree was simpler.

Where it shows up in the wire format

WHERE k BETWEEN ? AND ? against a typed numeric, decimal, timestamp, or date column dispatches through index_plan = LearnedRange(model_id = X, delta = 8KB) to /kit/query, and the fallback path is index_plan = BTree. The choice is per-index at build time, not per-query at runtime, which means a single table can hold a B-tree on its primary key and a learned-range index on its events column, and you pick the right tool per column rather than per query. The wire format is the same either way:

CREATE TABLE events (
  id            INT64,
  event_at      TIMESTAMP,
  payload       JSON,
  INDEX event_at_idx USING LEARNED ON event_at,
  INDEX id_pk     USING BTREE   ON id
);

SELECT count(*), avg(latency_ms)
FROM events
WHERE event_at BETWEEN '2026-07-01 00:00:00' AND '2026-07-08 00:00:00';

Same WHERE clause you would write for a B-tree, same planner, same transactional commit at the end of the statement, same WAL coverage for both index and row update on any INSERT INTO events. The learned-range index is the right shape for event_at, the B-tree is the right shape for id, and we ship both because they are the right tool for each column rather than because we had an academic result to justify.

When this is the wrong tradeoff

If your column is small enough to fit in cache, the B-tree wins anyway, because the random-read cost of the B-tree is small relative to the cache-hit latency of the learned-range index. If your column is wider than memory and your queries are equality lookups (WHERE k = ?) rather than range scans, the B-tree wins by a wider margin, because the learned-range index’s prediction error buys you nothing when you are not sweeping across a key range. If your data has no recency structure at all (a uniformly-distributed synthetic key, an auto-increment surrogate id), the learned-range model’s loss never improves past the prior, and the B-tree is the right answer with no hesitation. The learned-range index is a tool for one specific shape of query on one specific shape of data; the B-tree is the universal tool that covers the rest, and we ship both as first-class index options in the same engine, on the same wire format, with the same transaction model.