Promoted listings that survive page two
A search feature that looked like a one-line Elasticsearch flag, and wasn't.
The problem
Promoted listings had to be mixed into organic search results at a fixed ratio — one promoted item for every two organic ones — on every page, not just the first. Elasticsearch ships a feature called Pinned Query, and the name promised exactly that.
What I did
- Discovered mid-implementation that Pinned Query only lifts documents to the top of page one. Past that, pagination drops them entirely.
- Rebuilt the mix in application code: two separate pools, and pagination math that tracks how many promoted and organic items have already been shown before fetching the next batch.
- Handled the edge case that broke the naive version — when the promoted pool is smaller than the ratio demands, the remaining slots fill with organic results instead of going blank.
The ratio now holds on page five the same way it holds on page one. The more durable outcome was a rule I now apply to any third-party feature on a critical path: spend an hour on a throwaway spike testing pagination and empty results before committing a timeline.
The outcome
Read more
I wrote this one up in full: Elasticsearch Pinned Query Does Not Work Like I Expected.
