What is Retriever?
Retriever is a query-to-evidence component that applies a declared search contract and returns ranked, attributable candidates or an explicit failure for downstream RAG and agent stages.
Quick Facts
| Specification | Official Specification |
|---|
How It Works
Define Request and Result Contracts
Inputs should make query text, user scope, tenant, language, filters, topK, deadline and requested index revision explicit. Outputs should be ordered and include immutable candidate ID, source URI, chunk locator, content, score type, raw score, branch and revision. Eino v0.9.21, for example, defines Retrieve(context.Context, query, options...), returns ordered documents with metadata, and states that score threshold filters candidates rather than sorting them. Backend-specific options must not silently change common semantics.
Make Failure Semantics Deliberate
Propagate cancellation and deadlines to every backend. Return no evidence only when the query completed successfully with no eligible matches; do not collapse timeout or permission-service failure into an empty list. Optional relevance branches may degrade under a documented partial-result policy, but tenant and authorization checks should fail closed. Retries need bounded backoff, a remaining-time budget and idempotent read behavior. A response must reveal which branches completed, failed or were skipped.
Version, Observe, and Evaluate the Boundary
Treat analyzer, query encoder, document encoder, index, filters and fusion configuration as one retrieval revision. Record trace ID, normalized request attributes, branch latency, candidate count, filter selectivity, deduplication and final provenance without logging protected content. Evaluate candidate Recall@K, MRR or nDCG, no-result rate, permission leaks, stale evidence, timeout rate and p95 latency. Answer quality is a downstream signal and cannot replace retrieval-level judgments.
Key Characteristics
- Separates an application's query-to-evidence contract from any storage backend
- Carries scope, filters, revision, result budget and deadline into retrieval
- Returns ordered candidates with stable identity, provenance and declared score semantics
- Distinguishes successful emptiness from timeout, authorization and backend errors
- Supports composition with query rewriting, fusion, reranking and evidence validation
- Provides the observability boundary for quality, latency, freshness and access-control metrics
Common Use Cases
- Supplying attributable enterprise evidence to a grounded-answer pipeline
- Searching source code, issues, logs and documentation for a coding agent
- Federating several knowledge stores under one typed result contract
- Applying tenant, permission, version and freshness constraints before generation
- Exposing retrieval as a reusable component in a graph, workflow, API or MCP tool
Example
Loading code...Frequently Asked Questions
Is a Retriever the same as a vector database?
No. A vector database is one possible backend. The Retriever owns the application-facing request, scope, filters, deadline, result identity, provenance and failure contract, and it may coordinate several non-vector backends.
What fields should a retrieval result preserve?
At minimum preserve stable candidate ID, source or citation locator, content, metadata, retrieval branch, index revision, rank and named score semantics. Without provenance and revision, downstream citation, deduplication, debugging and replay become unreliable.
Should a Retriever return an empty list when a backend times out?
No. Empty success means no eligible evidence matched. Timeout, cancellation, invalid configuration and authorization failure need explicit errors or typed statuses so the caller can abstain, retry within budget, or apply a deliberate degradation policy.
Can a score threshold be shared across retriever implementations?
Not safely by default. BM25, cosine, dot product, reranker logits and normalized scores have different meanings and distributions. Thresholds belong to a named model, index, query and calibration contract; they should not be copied between backends.
How should a Retriever be evaluated?
Use query-level relevance and permission judgments to measure Recall@K, MRR or nDCG, no-result and stale-result rates, access violations, p95 latency, timeout rate and revision consistency. Evaluate downstream answers separately to avoid hiding candidate-stage failures.