Does query length vary between candidate documents?

No. It is fixed for a given query under a fixed counting rule.

Can query features be learned?

Yes. A classifier or embedding model can derive a representation, but its errors become part of the ranking system.

Why did adding a query feature change nothing?

A purely additive value shared by every candidate cannot change their relative order.

AI Glossary / AI and machine learning / Advanced

Query-level feature

Definition

A query-level feature is a measurable property of a search query, rather than a property of an individual candidate document or of the match between the two. Examples include query length and a predicted query category. Ranking systems can use such features to adapt how they evaluate candidate results.

What it means

The query “annual leave policy” and the query “printer” may call for different ranking behavior. A query-level feature describes something about the request that stays the same while the system compares its candidate documents. By contrast, a document's age is a document feature, and the number of matching query terms depends on both query and document. Some implementations also pass user or session context through query-time feature interfaces. That broader engineering usage should be distinguished from features derived solely from the query text.

How it works

Extract or infer properties of the request, then make them available to the ranking function alongside document and matching signals. Vespa's documentation illustrates query-time inputs and ranking expressions that combine different feature types. A model can use a query category to change which document signals matter, or interact query properties with matching features. There is a mathematical limitation: adding the same query-only constant to every document's score cannot change their order for that query. Useful within-query effects require interaction, branching or another mechanism that changes relative document scores.

Three practical examples

A hypothetical business search system identifies a request as seeking a policy and uses that information when evaluating document type and relevance.
A product-search model uses query length as one input while learning how to balance exact matching with broader similarity signals.
An analytics team groups evaluation queries by whether they contain a model number, checking if the ranking system performs differently on precise and exploratory requests.

Think of it this way

Think of the query-level feature as a note attached to a shopping list: “I need an exact replacement” or “I am exploring options.” The note applies to the whole search, while individual products have their own properties. The analogy is limited because an inferred note may be wrong and must be tested rather than treated as a perfect statement of intent.

Worked example

Two candidate documents have base relevance scores of 8 and 6. A query-length feature has value 3. If the ranking formula simply adds twice that value, the scores become 14 and 12; their order is unchanged. Now suppose the query has an exact-item flag of 1 and the first document has an exact-code match of 0 while the second has 1. An illustrative interaction bonus of 4 × query flag × code match gives scores 8 and 10, reversing the order. The invented formula demonstrates why a query-level feature can matter through interaction. It is not a recommended production weighting rule.

Illustrative case study

A fictional knowledge-management team investigates why employees struggle to find specific forms. It defines a query feature indicating whether a request appears to contain a form identifier, then tests interactions with exact identifier matches. Review shows that some everyday words resemble identifiers, so the team includes those cases in evaluation and provides a fallback when the signal is uncertain. It compares ranked results across different query groups and tracks successful retrieval, not just aggregate clicks. The feature is retained only if it improves the intended search tasks without creating unacceptable failures elsewhere.

Common misconceptions and mistakes

A query-level feature is not the same as query-level normalization, which changes feature values relative to a query's candidate set. A query identifier is not automatically a useful generalizable description of intent. Do not confuse query-only information with a query-document match score. Inferring categories from post-click behavior unavailable at serving time can introduce leakage into training. Also remember that an additive query constant can influence cross-query score interpretation while leaving within-query ordering unchanged; the intended use determines whether it provides value.

Business use

Query-level features help teams organize search behavior and evaluate distinct kinds of requests. Define each feature, its source and its availability when a query arrives. Keep extraction consistent in training and production, and use sensible handling for missing or uncertain values. Compare performance by query group so an improvement for common requests does not conceal failures for important rare ones. Where session or user information is passed through the same interface, document that distinction and use only information appropriate for the search experience.

Check your understanding

Is document popularity a query-level feature?

Answer: No, it describes the document independently of the particular query.

Is semantic similarity between query and document query-only?

Answer: No, it depends on both.

In the worked example, what enables the second document to move ahead?

Answer: The query flag interacts with a document-specific match signal, producing different bonuses for the candidates.

Related terms

Learning to rank
Query understanding
Feature engineering
document feature
query-document feature
ranking evaluation

Learn next

Classify ranking inputs by whether they depend on the query, document or both. Then study feature interactions and query-group evaluation. Examine how training-time information can leak into features that cannot be reproduced when serving a real search request.

Feature interactions

Sources

Vespa, generating and using training data, including query and document features: https://learn.vespa.ai/reranking-ltr/training-data/ Vespa, ranking expressions and features: https://docs.vespa.ai/en/ranking/ranking-expressions-features.html The score calculations and knowledge-management case are original illustrations, not measured search improvements. Independent review consulted Vespa's query-feature, document-feature and ranking-expression documentation, including query-time variables and interactions. The two score calculations were independently checked; the article distinguishes query-derived properties from broader context passed through query interfaces.

Previous: Query language Next: Query likelihood model