Expand rank() operator reference: composite conditions, matches(), negations

[zoharsan]

What

Expands the rank operator section in en/reference/querying/yql.html, which previously only stated the first-argument-matches rule with two examples. Prompted by a customer case about boosting on filter criteria without re-writing the filter logic in rank expressions, where the current documentation left the key questions unanswered.

New content, each with a YQL example and the matching rank profile:

• Variadic semantics — any number of arguments; arguments after the first never add or exclude documents; any query operator is usable (in, ranges, grouped conditions).
• Observing ranking-only arguments — matches(field) as the match indicator; in/ranges are visible to matches() but not to text features like bm25.
• Several conditions on the same field — matches(field, n) with term numbering, including the caveat that indexes follow query structure.
• Grouped conditions are evaluated as a unit — terms inside a grouped argument expose match information only for documents where the whole condition is true, making a group usable as a single boost rule.
• Negations are not observable — a negation-only argument matches correctly but produces no match information; documents the invert-in-the-ranking-expression alternative.
• Note — arguments not read by any rank feature are pruned from execution (no cost, but also no effect).

The hybrid-search/nearestNeighbor example was replaced by a worked boost example, since the section now centers on the boost-without-filtering use case.

Verification

All documented behavior was verified against master (vespaengine/vespa:latest, July 2026) with a minimal test application — every example pattern in the section has a corresponding live query result. Key implementation anchors:

• Unit evaluation of grouped arguments: searchlib/src/vespa/searchlib/queryeval/multisearch.cpp (doUnpack only unpacks a child that matches the docid)
• Negations invisible to ranking: searchlib/src/vespa/searchlib/queryeval/andnotsearch.cpp (doUnpack unpacks the positive child only)
• Pruning of unused arguments: RankBlueprint::createIntermediateSearch in searchlib/src/vespa/searchlib/queryeval/intermediate_blueprints.cpp
• Phrase counts as one term for matches(field, n) numbering (verified empirically)

For reviewers

This promotes currently-undocumented implementation behavior (unit evaluation, negation invisibility, pruning) to documented behavior — flagging for search-core owners to confirm these are semantics we want to commit to.

🤖 Generated with Claude Code

[bratseth]

This is a reference document, the purpose of those is to document every element of the topic in question. Explanation of how to use features should instead go into guide documents (anything outside the reference/ directory). Maybe this belongs in the text matching guide?