SearchType.HYBRID_COMPLETION_DECOMPOSITION. Use it when one question asks about several things at once (an order, its delivery date and where the supplier is based) and a single hybrid search under-retrieves some of the parts. The guide prints what a single search and a decomposed search each retrieve for the same question, then answers it with decomposition.
Before You Start
- Complete Quickstart to understand basic operations
- Ensure you have LLM Providers configured
- Read Recall for an overview of
recall()and its search types - Complete Inspecting Hybrid Retrieval Context to see how plain
HYBRID_COMPLETIONbuilds its context and whatonly_contextand the per-lane limits do
Code in Action
What Just Happened
Step 1: Ingest Documents with Metadata
DataItem whose external_metadata carries a source_id and a title. Three of them answer the question: Acme’s order, its delivery date and where Northwind is headquartered. The rest are other orders, deliveries and company profiles that compete for the same search.
Step 2: Limit Each Search to One Passage
Step 3: Retrieve with a Single Search
only_context=True returns the context the completion step would receive, without calling the LLM to answer. HYBRID_COMPLETION embeds the whole three-part question once, so its one passage covers at most one part of the question.
Step 4: Retrieve with Decomposition
HYBRID_COMPLETION_DECOMPOSITION first runs the same hybrid retrieval for the full question. The LLM then reads the question together with that first-pass context and writes at most max_subqueries focused subqueries, such as one about where Northwind is based. Even with only_context=True, this planning step makes one LLM call. Each subquery is retrieved through the hybrid lanes, and the results are merged with the first pass. The printed context therefore holds the first-pass passage plus the ones the subqueries found, typically including “Northwind is headquartered in Rotterdam.” The subqueries are LLM-generated, so the exact passages can vary between runs.
Step 5: Answer with References
only_context, the merged context goes to the LLM, which writes the answer. include_references=True appends an Evidence: block citing the source passages. include_external_metadata with external_metadata_keys adds only the allowlisted metadata keys stored on each document to the context, so the answer can name sources such as po-1042 or note-3.
For what a decomposed search costs, how to replace the planner prompt and which requests it refuses, see HYBRID_COMPLETION_DECOMPOSITION in the SearchType reference.
Inspecting Hybrid Retrieval Context
See what the hybrid lanes put into the context and how to shape them
SearchType
See the HYBRID_COMPLETION retriever_specific_config options this type also takes