Domain Guide — Search and Multi-Phase Ranking

Vespa executes search and ranking across two cooperating subsystems: stateless Java searchers in
container-jdisc (vespa/container-search) and stateful C++ proton engines in content-nodes
(vespa/searchcore, vespa/searchlib, and vespa/eval).

Multi-Phase Ranking Pipeline

1. Matching and First-Phase Ranking (vespa/searchlib, vespa/searchcore):
   • Candidate documents are matched against the query tree (boolean, wand, weakAnd, nearestNeighbor)
     inside each content node’s proton engine (vespa/searchcore/src/vespa/searchcore/proton/).
   • Every matched candidate is scored by the first-phase ranking expression using the Feature
     Execution Framework (fef under vespa/searchlib/src/vespa/searchlib/fef/).
2. Second-Phase Reranking (vespa/searchlib, vespa/eval):
   • The top-K hits per content node (rerank-count) are evaluated by the second-phase expression,
     typically invoking complex tensor expressions, GBDT models, or ONNX models via vespa/eval.
3. Global Phase Reranking (vespa/container-search):
   • After scatter-gather merge in the stateless container, global-phase reranks the merged top hits
     across all content nodes using normalized or cross-hit features.

Tensor and Feature Evaluation

• C++ Tensor Engine (vespa/eval): Compiles and evaluates tensor ranking expressions
  (sum, join, reduce, map, matmul) over dense, mapped (sparse), and mixed tensors.
• Java Tensor Library (vespa/vespajlib): Provides the container-side tensor representation
  and serialization used by stateless Searchers and document processors (see utility-libs).

Related Guides

• Schema definitions and rank-profile syntax: schemas-app-packages
• YQL query formulation and rankfeature overrides: querying-yql
• Hybrid retrieval, HNSW ANN, and ONNX/LLM reranking: ai-rag