Why does a field_value_factor boost on raw view counts let one document dominate every query?

## What the function computes `field_value_factor` turns a numeric field into a score multiplier. It takes `field`, an optional `factor` that scales the value, an optional `modifier` that reshapes it, and an optional `missing` value used when the document has no value for the field. The result is `modifier(factor × doc_value)`, and with `function_score`'s default `boost_mode: multiply` that number multiplies the score of the inner query. ## Why raw counts break ranking BM25 scores for a given query occupy a narrow band — a few points between a mediocre and an excellent match is typical. Popularity counts do not. Views, likes and downloads follow a heavy-tailed distribution across many orders of magnitude, so with `modifier: none` (the default) the multiplier for the most popular document can be a hundred thousand times the multiplier for a typical one. Multiplying a narrow band by a very wide one produces a ranking governed entirely by the wide one. The query still filters correctly, but among matching documents the ordering is effectively "most viewed first", regardless of how well the text matches. The symptom in production is unmistakable: one or two evergreen documents appear at the top of unrelated searches, and users learn to distrust the search box. ## Compressing the signal The standard fix is a `modifier` that grows sublinearly, so that the ratio between a popular and an unpopular document becomes comparable to the ratio between a good and a poor text match. `log1p` computes the logarithm of one plus the scaled value, which is the workhorse: it handles zero safely and turns six orders of magnitude of views into a factor of roughly a few. `log` itself is dangerous here, because taking the logarithm of a value at or below zero raises an error, and any document with zero views hits exactly that case — this is why `log1p` exists and why it is the recommended default for counts. `sqrt` and `ln1p` are the other common choices; `sqrt` compresses less aggressively than a logarithm, which suits fields with a narrower range. `reciprocal` inverts the value, which is how you express "smaller is better" for something like load time. `factor` multiplies the raw value before the modifier runs. With a logarithmic modifier it shifts the whole curve rather than steepening it, so it is mostly used to bring very small or very large raw values into a sensible range. ## Capping the result Even a compressed signal is unbounded in principle. `max_boost` on the `function_score` caps the combined function score before `boost_mode` applies it, which converts "unbounded domination" into "at most this much of a nudge". On any production popularity boost, a `max_boost` is cheap insurance. ## The structural fix: add instead of multiply Multiplication couples the two signals: a document with a strong popularity factor gets that factor applied to its text score, so the popularity advantage scales with the text score and compounds. Setting `boost_mode: sum` with a bounded function decouples them — popularity contributes a fixed additive amount, and no amount of popularity can overturn a large enough relevance gap. This is generally the more robust shape for business signals layered onto text relevance, and it is what the purpose-built alternatives do. ## Missing values If a document has no value for the field and no `missing` is configured, the function raises an error rather than silently defaulting. Since new documents typically start with no popularity data at all, always set `missing` — usually 1 with a multiplicative modifier, so a brand-new document is neither boosted nor demoted. A related trap is negative values. Scores must be non-negative, so a field that can go below zero — a net vote count, for example — will fail the query. Store the value pre-shifted into a positive range, or use a modifier and `factor` combination that cannot produce a negative result. ## The purpose-built alternative When the signal is a static per-document popularity number, indexing it as a `rank_feature` field and querying it with the `rank_feature` query gives you a saturating curve out of the box: the score approaches a ceiling as the value grows, so a million views is worth only slightly more than a hundred thousand. That is the shape you were approximating with `log1p` plus `max_boost`, and it is cheaper to execute besides, because the query can skip documents that cannot reach the top hits. ## Diagnosing it When a boost is suspected, run the same query with and without the `function_score` wrapper and compare the top ten. If removing the function restores sensible results, the function is the problem, and the next step is to look at the distribution of the boosted field — the percentiles usually tell the whole story in one glance.