On this page

Retrieve and combine passages

Start with dense search for paraphrases or BM25 for exact terms and codes. If each finds useful passages the other misses, compare fusion with each retriever on the same questions, documents, filters and result depth.

Dense similarity (dense)

Dense retrieval embeds the question and finds nearby stored vectors. Check that the space’s embedding model matches the index, especially for attached data.

The pgvector HNSW defaults are hnsw_m=32 and hnsw_ef_construction=200. They control connections and build search width. An existing index must be rebuilt to apply these settings. Use the preflight report for the deployed index’s state and backend support. hnsw_ef_search controls the query-time probe and follows the requested depth when unset. Increase it only after measuring latency and recall.

Implementation

Lexical search (bm25)

Use BM25 for alarm codes, names and terms spelled in the documents. language="multilingual" by default selects multilingual analysis. Use english or russian for a corpus in one language. k1=1.2 controls term-frequency saturation and b=0.75 normalizes for passage length. sparse_top_k defaults to the shared candidate depth. Changing language, k1 or b requires rebuilding the BM25 representation.

Implementation

Learned sparse search (splade)

SPLADE uses a sparse encoder to add related terms to the query and the indexed passages. Compare it with dense and BM25 when a corpus has lexical conventions alongside synonyms. The default multilingual model is opensearch-project/opensearch-neural-sparse-encoding-multilingual-v1. Ensure its weights are available to the installation. stored_terms keeps the strongest 256 weights per passage by default (1–1000). Changing the model or stored width rebuilds the sparse representation. sparse_top_k defaults to the shared candidate depth.

Implementation

Graph retrieval (graph)

The local graph retriever matches entities in the question and returns linked passages and graph context. Use it for questions about an entity and its relationships. Build a graph for the space first. See Build and query a knowledge graph for compatible storage, build settings and local and global modes.

Implementation

Dense, BM25 and SPLADE are available with pgvector, Qdrant, Chroma and Weaviate. The sparse indexes are held by ContextBase. For attached stores, sparse retrieval depends on the side index being available for the attached corpus. Graph retrieval requires a managed pgvector, Qdrant or Weaviate binding. See Connections and storage for how to choose and verify the binding.

Fusion and candidate depth

Set candidate_top_k on the fusion node. It defaults to 50 and must be at least 5. This sets the candidate pool before reranking. The request’s top_k sets the number of returned sources (default 5, maximum 20). Allow the candidate pool to be deeper than the return limit so reranking can promote a passage from further down. Keep every reranker’s top_n at or below the candidate depth.

One retriever (identity)

A single retriever requires identity. It passes that ranking through. For example, start with dense and {"node": "identity", "params": {"candidate_top_k": 30}}.

Implementation

Merge by rank (rrf)

Reciprocal rank fusion combines candidates by position in each list. Use it when scores from cosine similarity and lexical search have different scales. k defaults to 60. Optional retriever_weights assigns a weight to each retriever in its listed order. Omitting weights gives equal contributions.

Implementation

Merge by normalized score (relative_score)

This node scales each retriever’s list of scores into its own common range before combining them. It preserves how far the leading candidates scored above the rest of each list. Compare it with RRF on your corpus. retriever_weights works as in RRF. Two or more different retriever kinds require one of these merge nodes.

For a dense and lexical baseline, use this fragment of pipeline config. Keep the existing chunker and other settings when applying it:

{
  "retrievers": [{"node": "dense"}, {"node": "bm25"}],
  "fusion": {
    "node": "relative_score",
    "params": {"candidate_top_k": 30, "retriever_weights": [1, 1]}
  }
}

Implementation

Split search into independent branches

For a question about the TR-12, use BM25 on the original wording to keep the equipment code and dense search on rephrased questions to find instructions that use different terms.

Original question

Where is the reset switch on the TR-12?

Exact terms

BM25 searches for terms in the original question.

Expanded meaning

Rephrase the question, run dense search on the new formulations and combine their rankings using RRF.

Merge the branch rankings

Shared RRF builds the candidate pool. Reranking follows if configured.

Configure the two paths and their merge in the pipeline editor. To do the same through the API, apply this configuration fragment.

{
  "query_branches": [
    {
      "id": "exact-terms",
      "retrievers": [{"node": "bm25"}],
      "fusion": {"node": "identity"},
      "weight": 1
    },
    {
      "id": "expanded-meaning",
      "query_transform": [{"node": "rephrase", "params": {"rephrasings": 2}}],
      "retrievers": [{"node": "dense"}],
      "fusion": {"node": "identity"},
      "max_queries": 2,
      "weight": 1
    }
  ],
  "branch_fusion": {"node": "rrf", "params": {"candidate_top_k": 30}},
  "branch_concurrency": 2
}

Each branch starts from the original question and has its own transforms, retrievers and fusion. With query_branches configured, the branch lists replace the top-level transform and retriever lists. The shared rerank, generate and postgeneration run after the final merge. A branch with transforms searches its changed formulations and combines their rankings with RRF. It skips retrieval if no changed formulation remains. Keep an untransformed branch to search the original question. Top-level asked_lead and subquestion_passages ordering applies only without branches.

Keep at least one branch active and give each branch a unique, nonempty ID. A weight of zero disables the branch. max_queries defaults to 1 and limits additional formulations per branch. branch_concurrency defaults to 2. Set final merge weights on the branches themselves, and use rrf (the default) or relative_score for branch_fusion. Branches share physical indexes within the space. If several branches use the same retriever kind, keep its shared-index settings consistent. A successful branch can still return results if another branch fails. When a path seems to contribute nothing, inspect branch_trace in the search or pipeline answer response, or in the stream’s final done event. Each entry identifies branch_id and its status (success, skipped, or failed) and carries queries, hit_count and any error_type.

Branch configuration · Compatibility validation · Branch planning · Branch outcomes

ContextBase0.1.0

Search the documentation