What is .embed_query()?
.embed_query() encodes a single string into a dense floating-point vector using the same model and configuration on the embedding instance. It is intentionally separate from .embed_documents() because some embedding providers (notably InstructorEmbedding and some fine-tuned models) apply different internal instruction prefixes for queries versus documents — for example, "Represent this sentence for searching relevant passages" for queries versus a retrieval-oriented prefix for corpus documents. Keeping the two methods distinct lets providers optimize each direction independently.
When you call vector_store.similarity_search(query), LangChain internally calls .embed_query(query) on the retriever's configured embedder and compares the resulting vector against the stored document vectors using cosine similarity or inner product, depending on the backend. You call .embed_query() directly only when you need the raw vector — for example, to pre-compute and cache it, to run your own similarity calculation, or to debug what representation a query produces.
The output is a single List[float] whose length equals the embedding model's dimensionality. That dimensionality must exactly match the dimensionality of the vectors already stored in the vector store. If you index with one model and query with another — or use different dimensions= settings on the same OpenAI v3 model — similarity scores become meaningless. There is no runtime error; retrieval just returns random-looking results.
Use Cases
- • Encode a user query for real-time vector store similarity search
- • Pre-compute and cache query vectors for repeated searches
- • Debug embedding quality by inspecting raw query vectors
- • Compute cosine similarity between a query and specific documents
- • Async query encoding in FastAPI or async LangChain pipelines
- • Pass raw vectors to custom ANN indices bypassing the vector store abstraction
Key Features
- ✓ Encodes a single query string into a dense vector
- ✓ May apply query-specific instruction prefix (provider-dependent)
- ✓ Used internally by similarity_search() on all vector stores
- ✓ Async variant aembed_query() for non-blocking pipelines
- ✓ Output dimensionality matches embed_documents() for the same model
- ✓ Returns a flat List[float] — no batching overhead for one-off queries
When NOT to Use
When embedding multiple texts — use embed_documents([t1, t2, ...]) in a single batched call. Never call embed_query() in a loop.
Notes
Model mismatch is a silent bug
The query vector must come from the exact same model, dimensions setting, and configuration as the vectors stored in your vector store. Mixing models or dimensions produces similarity scores that are numerically valid but semantically meaningless — retrieval appears to work but returns wrong results. There is no runtime error to catch this.
Some models treat queries and documents differently
InstructorEmbedding and similar instruction-tuned models prepend different prompts for query encoding versus document encoding. This is why LangChain keeps embed_query() and embed_documents() as separate methods. Most OpenAI and HuggingFace sentence-transformer models treat both the same, but always check the model documentation.
Use aembed_query() in async code paths
In FastAPI endpoints, async LangChain chains, or async agents, call await embeddings.aembed_query(query) instead of the sync version. The sync version blocks the event loop, which causes latency spikes under concurrent load.
Do not use in a loop for multiple queries
Calling embed_query() N times in a loop issues N separate API calls. If you need to embed multiple queries (e.g., for evaluation or batch retrieval), pass them all to embed_documents([q1, q2, ...]) in one call instead.
Method Signature
vector = embeddings.embed_query(query)Parameters
| Parameter | Type | Required | Purpose |
|---|---|---|---|
| query | str | Yes | Single text string to convert into a dense vector |
Return Value
Type:
List[float]
Description:
A single embedding vector with length equal to the model dimensionality
Example Output:
[0.012, -0.034, 0.078, ..., 0.005] # 1536 floats for text-embedding-3-smallCode Examples
Embed a single query string
from langchain_openai import OpenAIEmbeddings
embeddings = OpenAIEmbeddings(model='text-embedding-3-small')
query_vec = embeddings.embed_query('What is LangChain used for?')
print(f'Vector dimension: {len(query_vec)}') # 1536
print(f'First 5 values: {query_vec[:5]}')Compute cosine similarity between query and document
import numpy as np
from langchain_openai import OpenAIEmbeddings
embeddings = OpenAIEmbeddings(model='text-embedding-3-small')
query = 'How do agents work in LangChain?'
doc = 'LangChain agents use tools and LLM reasoning to complete tasks.'
q_vec = embeddings.embed_query(query)
d_vec = embeddings.embed_documents([doc])[0]
# Cosine similarity
cosine = np.dot(q_vec, d_vec) / (np.linalg.norm(q_vec) * np.linalg.norm(d_vec))
print(f'Similarity: {cosine:.4f}')Async query embedding for FastAPI endpoints
import asyncio
from langchain_openai import OpenAIEmbeddings
embeddings = OpenAIEmbeddings(model='text-embedding-3-small')
async def get_query_vector(query: str):
return await embeddings.aembed_query(query)
# Use in a FastAPI endpoint or async LangChain chain
vec = asyncio.run(get_query_vector('What is RAG?'))
print(len(vec)) # 1536Common Mistakes
❌ for q in queries: embeddings.embed_query(q) # N separate API calls
✅ vectors = embeddings.embed_documents([q1, q2, q3]) # one batched call
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 .embed_query() and the wider framework.
.embed_query() FAQ
What does .embed_query() do in LangChain?
Encode a single query string into a dense embedding vector for real-time similarity search. .embed_query() encodes a single string into a dense floating-point vector using the same model and configuration on the embedding instance. It is intentionally separate from .embed_documents() because some embedding providers (notably InstructorEmbedding and some fine-tuned models) apply different internal instruction prefixes for queries versus documents — for example, "Represent this sentence for searching relevant passages" for queries versus a retrieval-oriented prefix fo…
Which LangChain classes support .embed_query()?
.embed_query() is available on Embedding models. Pin your installed LangChain version and verify the method exists in that release before deploying.
When should I use .embed_query()?
Use .embed_query() when your LangChain chains, agents, or pipelines need the behavior described in this guide.
What does .embed_query() return?
.embed_query() returns a List[float]. A single embedding vector with length equal to the model dimensionality
Does .embed_query() have an async equivalent?
Yes — use aembed_query() for async contexts such as FastAPI handlers or asyncio-based pipelines. It is the non-blocking counterpart to .embed_query().
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.