> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hybrid Decomposition

> Answer multi-part questions with HYBRID_COMPLETION_DECOMPOSITION, which splits the question into focused subqueries after a first retrieval pass

A minimal guide to answering a multi-part question with `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](https://docs.cognee.ai/getting-started/quickstart.md) to understand basic operations
* Ensure you have [LLM Providers](https://docs.cognee.ai/setup-configuration/llm-providers.md) configured
* Read [Recall](https://docs.cognee.ai/core-concepts/main-operations/recall.md) for an overview of `recall()` and its search types
* Complete [Inspecting Hybrid Retrieval Context](https://docs.cognee.ai/guides/hybrid-retrieval-recall.md) to see how plain `HYBRID_COMPLETION` builds its context and what `only_context` and the per-lane limits do

## Code in Action

```python theme={null}
import asyncio

import cognee
from cognee import SearchType
from cognee.tasks.ingestion.data_item import DataItem

QUERY = "What did Acme order from Northwind, when is delivery due, and where is Northwind based?"


def document(source_id, title, text):
    return DataItem(text, external_metadata={"source_id": source_id, "title": title})


DOCUMENTS = [
    document("po-1042", "Acme order", "Acme ordered 40 pumps from Northwind on March 3."),
    document("mail-77", "Acme delivery", "Northwind will deliver Acme's pumps on April 15."),
    document("po-1043", "Globex order", "Globex ordered 12 fans from Northwind on March 5."),
    document("mail-81", "Globex delivery", "Northwind will deliver Globex's fans on March 28."),
    document("po-1044", "Initech order", "Initech ordered 300 valves from Contoso on March 9."),
    document("memo-15", "Initech approval", "Sam Lee approved Initech's valve order."),
    document("note-3", "Northwind profile", "Northwind is headquartered in Rotterdam."),
    document("note-4", "Contoso profile", "Contoso is headquartered in Lyon."),
]

# Passages only, one per search, so the printed contexts are easy to compare: a single search
# returns one passage, a decomposed one up to one per subquery.
LIMITS = {"chunks_top_k": 1, "entities_top_k": 0, "facts_top_k": 0}


async def main():
    await cognee.remember(DOCUMENTS, self_improvement=False)

    context_single_search = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.HYBRID_COMPLETION,
        only_context=True,
        retriever_specific_config=LIMITS,
    )
    print(context_single_search)

    context_decomposed = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.HYBRID_COMPLETION_DECOMPOSITION,
        only_context=True,
        retriever_specific_config={**LIMITS, "max_subqueries": 3},
    )
    print(context_decomposed)

    answer = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.HYBRID_COMPLETION_DECOMPOSITION,
        include_references=True,
        retriever_specific_config={
            **LIMITS,
            "max_subqueries": 3,
            "include_external_metadata": True,
            "external_metadata_keys": ["source_id", "title"],
            # Optional: "decomposition_system_prompt": "Your use-case instructions..."
        },
    )
    print(answer)


if __name__ == "__main__":
    asyncio.run(main())
```

## What Just Happened

### Step 1: Ingest Documents with Metadata

```python theme={null}
def document(source_id, title, text):
    return DataItem(text, external_metadata={"source_id": source_id, "title": title})
```

```python theme={null}
await cognee.remember(DOCUMENTS, self_improvement=False)
```

Each of the eight documents is one short sentence wrapped in a `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

```python theme={null}
LIMITS = {"chunks_top_k": 1, "entities_top_k": 0, "facts_top_k": 0}
```

Both searches use the same limits: one passage, and no entity or fact sections. That keeps the printed contexts short enough to compare. A decomposed search applies these limits to every retrieval it runs, so it can return up to one passage per subquery.

### Step 3: Retrieve with a Single Search

```python theme={null}
context_single_search = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.HYBRID_COMPLETION,
    only_context=True,
    retriever_specific_config=LIMITS,
)
print(context_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

```python theme={null}
context_decomposed = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.HYBRID_COMPLETION_DECOMPOSITION,
    only_context=True,
    retriever_specific_config={**LIMITS, "max_subqueries": 3},
)
print(context_decomposed)
```

`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

```python theme={null}
answer = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.HYBRID_COMPLETION_DECOMPOSITION,
    include_references=True,
    retriever_specific_config={
        **LIMITS,
        "max_subqueries": 3,
        "include_external_metadata": True,
        "external_metadata_keys": ["source_id", "title"],
        # Optional: "decomposition_system_prompt": "Your use-case instructions..."
    },
)
print(answer)
```

Without `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](https://docs.cognee.ai/python-api/search-type.md#per-search-type-parameters) in the SearchType reference.

> [card] [Inspecting Hybrid Retrieval Context](https://docs.cognee.ai/guides/hybrid-retrieval-recall.md)
>
> See what the hybrid lanes put into the context and how to shape them

> [card] [SearchType](https://docs.cognee.ai/python-api/search-type.md#per-search-type-parameters)
>
> See the HYBRID\_COMPLETION retriever\_specific\_config options this type also takes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.