What is .similarity_search_with_score()?
.similarity_search_with_score() behaves identically to .similarity_search() except that it returns a list of (Document, float) tuples instead of a plain list of Documents. The float is the raw distance or similarity score produced by the vector store backend for each retrieved document. Accessing this score lets you implement quality gates — discarding documents below a relevance threshold — rather than blindly passing all k results to the language model.
The critical thing to know is that the score direction and scale differ across backends. For FAISS with an L2 index, the score is a distance — lower means more similar, and 0.0 is a perfect match. For Chroma with cosine similarity, the score is a distance between 0 and 2, where 0 is a perfect match. For Pinecone, the score is a cosine similarity between -1 and 1, where 1 is a perfect match. You cannot apply the same threshold across different backends without normalizing the scores first.
In practice, a common production pattern is to retrieve k documents with scores, discard any below your backend-specific threshold, and only send the surviving documents to the LLM. This prevents the model from hallucinating answers from weakly relevant chunks. The VectorStoreRetriever returned by .as_retriever(search_type="similarity_score_threshold", search_kwargs={"score_threshold": 0.8}) automates this pattern in LCEL chains, although the threshold must still be calibrated per backend.
Use Cases
- • Relevance-ranked results
- • Confidence-aware retrieval
- • Threshold filtering
- • Quality assurance
- • Result ranking
- • Score-based filtering
Key Features
- ✓ Similarity scores
- ✓ Better ranking
- ✓ Threshold support
- ✓ Quality control
- ✓ Transparency
- ✓ Score normalization
When NOT to Use
When you don't care about scores—use similarity_search().
Notes
Score direction is backend-specific — lower or higher is better depending on the store
FAISS L2 index: lower score = more similar (0 = perfect). Chroma cosine: lower distance = more similar (0 = perfect, max = 2). Pinecone cosine: higher score = more similar (1 = perfect). You must know your backend's convention before setting a threshold — applying an L2 threshold to a Pinecone index will either pass everything or nothing.
Use as_retriever(search_type="similarity_score_threshold") for automatic filtering in chains
Rather than calling similarity_search_with_score() and filtering manually, configure the threshold in the retriever: vector_store.as_retriever(search_type="similarity_score_threshold", search_kwargs={"score_threshold": 0.8}). This is composable with LCEL pipes and handles the filtering before documents reach the prompt.
Returning zero documents is a valid outcome you must handle
If no document scores above the threshold, the filtered list is empty. LLMs given an empty context tend to hallucinate or reply "I don't know." Build an explicit fallback in your chain — either lower the threshold, do a fallback similarity_search(), or return a canned no-results message.
Performance overhead vs similarity_search() is negligible
The scores are computed as part of the same ANN lookup that similarity_search() performs — the only difference is whether the scores are returned to Python. Calling similarity_search_with_score() instead of similarity_search() adds no extra network round trips or embedding calls.
Method Signature
docs_with_scores = vector_store.similarity_search_with_score(query, k=4)Parameters
| Parameter | Type | Required | Purpose |
|---|---|---|---|
| query | str | Yes | Query text |
Return Value
Type:
List[Tuple[Document, float]]
Description:
Documents with scores
Example Output:
[(doc, 0.89), (doc, 0.75), ...]Code Examples
Basic search with scores
results = vector_store.similarity_search_with_score(
"what is retrieval augmented generation", k=3
)
for doc, score in results:
print(f"score={score:.4f}: {doc.page_content[:80]}")Threshold filtering for quality control
THRESHOLD = 0.75 # Tune per backend
results = vector_store.similarity_search_with_score(
query, k=6
)
good_docs = [
doc for doc, score in results
if score >= THRESHOLD # cosine: higher is better
]
if not good_docs:
return "No relevant documents found."Automated threshold via as_retriever()
retriever = vector_store.as_retriever(
search_type="similarity_score_threshold",
search_kwargs={"k": 8, "score_threshold": 0.8}
)
docs = retriever.invoke('LangChain agents')Common Mistakes
❌ Ignore scores and use all results
✅ Filter by score threshold for quality control
Related LangChain References
Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with .similarity_search_with_score() and the wider framework.
.similarity_search_with_score() FAQ
What does .similarity_search_with_score() do in LangChain?
Find similar documents with relevance scores. .similarity_search_with_score() behaves identically to .similarity_search() except that it returns a list of (Document, float) tuples instead of a plain list of Documents. The float is the raw distance or similarity score produced by the vector store backend for each retrieved document. Accessing this score lets you implement quality gates — discarding documents below a relevance threshold — rather than blindly passing all k results to the language model. The critical thing …
Which LangChain classes support .similarity_search_with_score()?
.similarity_search_with_score() is available on Vector stores. Pin your installed LangChain version and verify the method exists in that release before deploying.
When should I use .similarity_search_with_score()?
Use .similarity_search_with_score() when your LangChain chains, agents, or pipelines need the behavior described in this guide.
What does .similarity_search_with_score() return?
.similarity_search_with_score() returns a List[Tuple[Document, float]]. Documents with scores
Does .similarity_search_with_score() have an async equivalent?
.similarity_search_with_score() does not have a documented async variant. Avoid .similarity_search_with_score() When you don't care about scores—use similarity_search().
Where can I explore more LangChain API reference pages?
Open the LangChain API reference index on DevShelfHub to browse classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.