LlamaIndex — Retrieval & Query Engines¶

retriever = index.as_retriever(similarity_top_k=5)          # default top_k is 2
hits = retriever.retrieve("how long does express shipping take")   # list[NodeWithScore]
for hit in hits:
    print(hit.node_id, round(hit.score, 3), hit.metadata["topic"], hit.get_content()[:60])

hits = await retriever.aretrieve("...")                     # async variant

from llama_index.core.vector_stores import FilterCondition, FilterOperator, MetadataFilter, MetadataFilters

filters = MetadataFilters(
    filters=[
        MetadataFilter(key="visibility", value="public", operator=FilterOperator.EQ),
        MetadataFilter(key="topic", value=["billing", "shipping"], operator=FilterOperator.IN),
        MetadataFilter(key="year", value=2025, operator=FilterOperator.GTE),
    ],
    condition=FilterCondition.AND,          # AND, OR, NOT
)
retriever = index.as_retriever(similarity_top_k=6, filters=filters)
engine = index.as_query_engine(similarity_top_k=6, filters=filters)

from llama_index.core.retrievers import QueryFusionRetriever
from llama_index.retrievers.bm25 import BM25Retriever

nodes = list(index.docstore.docs.values())                      # in-memory index; use your own node list otherwise
bm25 = BM25Retriever.from_defaults(nodes=nodes, similarity_top_k=5)
fusion = QueryFusionRetriever(
    [index.as_retriever(similarity_top_k=5), bm25],
    llm=llm,                       # resolved even when num_queries=1
    similarity_top_k=5,
    num_queries=1,                 # 1 = no LLM query rewriting; >1 calls the LLM
    mode="reciprocal_rerank",      # simple, reciprocal_rerank, relative_score, dist_based_score
    use_async=False,
)
engine = RetrieverQueryEngine.from_args(fusion, llm=llm)

from llama_index.core.postprocessor import LLMRerank, SimilarityPostprocessor

engine = index.as_query_engine(
    similarity_top_k=10,
    node_postprocessors=[
        SimilarityPostprocessor(similarity_cutoff=0.2),
        LLMRerank(llm=llm, top_n=3, choice_batch_size=5),      # scores replace similarity scores
    ],
)

from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.core.response_synthesizers import get_response_synthesizer

synth = get_response_synthesizer(llm=llm, response_mode="tree_summarize", use_async=True)
engine = RetrieverQueryEngine(
    retriever=index.as_retriever(similarity_top_k=8),
    response_synthesizer=synth,
    node_postprocessors=[SimilarityPostprocessor(similarity_cutoff=0.2)],
)
response = engine.query("Summarise our shipping options")

engine = index.as_query_engine(streaming=True, similarity_top_k=3)
response = engine.query("express shipping time")            # StreamingResponse
for token in response.response_gen:                          # or response.print_response_stream()
    print(token, end="")

response = await index.as_query_engine().aquery("...")       # async; Response
response.source_nodes          # list[NodeWithScore]
response.metadata              # {node_id: node metadata}

from llama_index.core.query_engine import RouterQueryEngine
from llama_index.core.selectors import LLMSingleSelector, PydanticSingleSelector
from llama_index.core.tools import QueryEngineTool

tools = [
    QueryEngineTool.from_defaults(billing.as_query_engine(), name="billing", description="Refund and billing policy"),
    QueryEngineTool.from_defaults(shipping.as_query_engine(), name="shipping", description="Shipping times and costs"),
]
router = RouterQueryEngine(selector=LLMSingleSelector.from_defaults(), query_engine_tools=tools)
response = router.query("how fast is express?")
response.metadata["selector_result"]          # which tool was chosen and why

from llama_index.core.query_engine import SubQuestionQueryEngine
from llama_index.core.question_gen import LLMQuestionGenerator

engine = SubQuestionQueryEngine.from_defaults(
    query_engine_tools=tools,
    question_gen=LLMQuestionGenerator.from_defaults(llm=llm),   # without this, from_defaults raises ImportError
    use_async=True,
)
engine.query("Compare the express delivery time with the refund window")

from llama_index.core.memory import Memory

chat = index.as_chat_engine(
    chat_mode="condense_plus_context",
    llm=llm,
    memory=Memory.from_defaults(session_id="user-42", token_limit=3000),
    system_prompt="You are a support assistant. Answer only from the context.",
    similarity_top_k=3,
    node_postprocessors=[SimilarityPostprocessor(similarity_cutoff=0.2)],
)
r = chat.chat("express shipping time?")
r = await chat.achat("and the cost?")          # condensed to a standalone question first
print(r.response, [n.node_id for n in r.source_nodes])
for token in chat.stream_chat("thanks").response_gen:
    print(token, end="")
chat.chat_history                                  # list[ChatMessage]
chat.reset()                                       # clear this conversation

from pydantic import BaseModel

from llama_index.core.query_engine import CitationQueryEngine

cite = CitationQueryEngine.from_args(index, llm=llm, similarity_top_k=3, citation_chunk_size=512)
response = cite.query("express shipping time")
print(response)                                   # "Express takes 1 to 2 days [1]."
for n in response.source_nodes:                   # numbered "Source 1:\n..." chunks, new node ids
    print(n.node.get_content()[:80])


class Shipping(BaseModel):
    days_min: int
    days_max: int
    price_usd: float | None = None


engine = index.as_query_engine(llm=llm, output_cls=Shipping, similarity_top_k=1)
response = engine.query("express shipping")       # PydanticResponse
response.response                                 # Shipping(days_min=1, days_max=2, price_usd=15.0)

from llama_index.core import VectorStoreIndex
from llama_index.core.node_parser import SentenceWindowNodeParser
from llama_index.core.postprocessor import MetadataReplacementPostProcessor

window_parser = SentenceWindowNodeParser.from_defaults(window_size=1, window_metadata_key="window")
nodes = window_parser.get_nodes_from_documents(documents)         # text = one sentence; metadata["window"] = three
index = VectorStoreIndex(nodes, embed_model=embed_model)
engine = index.as_query_engine(
    llm=llm,
    similarity_top_k=3,
    node_postprocessors=[MetadataReplacementPostProcessor(target_metadata_key="window")],
)

from llama_index.core import StorageContext
from llama_index.core.node_parser import HierarchicalNodeParser, get_leaf_nodes
from llama_index.core.retrievers import AutoMergingRetriever

all_nodes = HierarchicalNodeParser.from_defaults(chunk_sizes=[2048, 512, 128]).get_nodes_from_documents(documents)
storage = StorageContext.from_defaults()
storage.docstore.add_documents(all_nodes)                          # parents must be in the docstore
base = VectorStoreIndex(get_leaf_nodes(all_nodes), storage_context=storage, embed_model=embed_model)
retriever = AutoMergingRetriever(base.as_retriever(similarity_top_k=6), storage, simple_ratio_thresh=0.5)