There is no neural network hiding in the storage directory. There is no recency-weighted loss function learning from customer traffic. The public index kind is LearnedRange, the implementation is a PGM-style model, and the reason to use it is that sorted numeric and time keys can often be described with much less metadata than a general-purpose tree.

The problem is locating a range

A query such as created_at BETWEEN a AND b needs two positions: where qualifying keys begin and where they end. If the column is sorted in a run, a model can approximate the mapping from key to position, then search a bounded window around each prediction and verify the actual values.

The epsilon parameter controls that bound. Smaller epsilon means more line segments and a tighter correction window; larger epsilon means a smaller model and more local scanning. That is the useful trade, because it is explicit and because correctness does not depend on the prediction being perfect.

An index prediction is only a starting position. The engine checks the candidate range against the real values, so model error changes work, not query truth.

How the shrinking-cone model is built

Imagine walking sorted (key, position) points from left to right. A line segment is valid while one slope can keep every observed point within the configured positional error. Each new point narrows the set of slopes that still satisfy that bound, like a cone shrinking around the valid lines; when the cone becomes empty, the current segment closes and a new one begins.

The stored result is a sequence of segment anchors and slopes. Lookup chooses the segment covering the key, predicts a position, then searches within the bounded correction interval. Monotonic, smooth distributions need few segments. Irregular distributions need more. The index adapts its size to the key distribution without changing query correctness.

Why this belongs beside page pruning

MongrelDB sorted runs already store per-page minimum and maximum statistics. A range predicate can skip pages whose bounds do not overlap the query, and encrypted columns keep those statistics inside an authenticated envelope so the same pruning remains available after open.

The PGM index narrows where the relevant key region should begin; page statistics eliminate unrelated pages; MVCC visibility and exact predicate checks remove versions that do not belong in the snapshot. None of those layers has to carry the whole optimization alone.

A native condition looks like this:

Condition::RangeF64 {
    column_id: 3,
    lo: 50.0,
    lo_inclusive: true,
    hi: 200.0,
    hi_inclusive: false,
}

SQL comparisons and BETWEEN can push down to the same range path when the planner recognizes the predicate.

The measurement we can defend

On the current published one-million-row benchmark fixture, integer range lookup measured 8.8231 milliseconds and a Bitmap plus range intersection measured 14.224 milliseconds on the documented Intel Core Ultra 9 386H host. Those are whole query-path measurements for one data distribution and one machine, not proof that a learned index beats every B-tree by a fixed multiplier.

The repository does not publish a current cross-engine PGM-versus-B-tree claim, so neither should this article. A uniform integer fixture, a timestamp stream, a clustered price distribution, and a pathological sparse keyspace produce different model sizes and correction work; the only useful comparison holds data, projection, cache state, durability, and hardware constant.

Where PGM is the wrong index

Equality on a low-cardinality status belongs in a Roaring Bitmap, not a range model. Exact substring containment belongs in the FM-index. Primary-key lookup uses the implicit primary-key surface, whose current in-memory implementation is an ordered-map stand-in rather than a completed HOT trie. Dense similarity belongs in ANN.

A range model also becomes less attractive when keys have no useful order, when the distribution creates too many short segments, or when a mature tree implementation and its ecosystem matter more than saving model space. MongrelDB does not expose a general secondary B-tree today, and pretending otherwise would make the schema promise a path the engine does not have.

Why the shared RowId matters

The range result is not an isolated row stream. It is a RowId candidate set that can intersect with a tenant Bitmap, an FM substring, or another hard condition before row decoding. That is where a specialized range index earns its place in a mixed engine: it does one job, returns the same identity type as every other index, and lets the query combine strengths instead of forcing every predicate through one universal tree.

Learned indexing is useful here because the model has a bounded, verifiable job. It predicts position in ordered data, the engine corrects and checks the answer, and if a workload does not benefit, the right response is to benchmark a different access path rather than write another paragraph about artificial intelligence.

The implementation and options are documented in docs/06-indexes.md, while the current range measurements and commands live in BENCHMARKS.md.