Search Basics

A minimal guide to using cognee.search() to ask questions against your processed datasets. This guide shows the basic call and what each parameter does so you know which knob to turn. Before you start:

Complete Quickstart to understand basic operations
Ensure you have LLM Providers configured for LLM-backed search types
Run cognee.cognify(...) to build the graph before searching
Keep at least one dataset with read permission for the user running the search

Code in Action

import asyncio
import cognee

async def main():
    # Make sure you've already run cognee.cognify(...) so the graph has content
    answers = await cognee.search(
        query_text="What are the main themes in my data?"
    )
    for answer in answers:
        print(answer)

asyncio.run(main())

SearchType.GRAPH_COMPLETION is the default, so you get an LLM-backed answer plus supporting context as soon as you have data in your graph.

What Just Happened

The search call uses the default SearchType.GRAPH_COMPLETION mode to provide LLM-backed answers with supporting context from your knowledge graph. The results are returned as a list that you can iterate through and process as needed.

Parameters Reference

Most examples below assume you are inside an async function. Import helpers when you need them:

from cognee import SearchType
from cognee.modules.engine.models.node_set import NodeSet

Core Parameters

query_text (str, required): The question or phrase you want answered.
```
answers = await cognee.search(query_text="Who owns the rollout plan?")
```
query_type (SearchType, optional, default: SearchType.GRAPH_COMPLETION): Switch search modes without changing your code flow. See Search Types for the complete list.
```
await cognee.search(
    query_text="List coding guidelines",
    query_type=SearchType.CODING_RULES,
)
```
top_k (int, optional, default: 10): Cap how many ranked results you want back.
```
await cognee.search(query_text="Summaries please", top_k=3)
```

Prompt & Generation Parameters

system_prompt_path (str, optional, default: "answer_simple_question.txt"): Point to a prompt file packaged with your project.

await cognee.search(
    query_text="Explain the roadmap in bullet points",
    system_prompt_path="prompts/bullets.txt",
)

system_prompt (Optional[str]): Inline override for experiments or dynamically generated prompts.

await cognee.search(
    query_text="Give me a confident answer",
    system_prompt="Answer succinctly and state confidence at the end.",
)

only_context (bool, optional, default: False): Skip LLM generation and just fetch supporting context chunks.

context = await cognee.search(
    query_text="What did we promise the client?",
    only_context=True,
)

use_combined_context (bool, optional, default: False): Collapse results into a single combined response when you query multiple datasets.

combined = await cognee.search(
    query_text="Quarterly financial highlights",
    datasets=["finance_q1", "finance_q2"],
    use_combined_context=True,
)

Node Sets & Filtering Parameters

These options filter the graph down to the node sets you care about. In most workflows you set both: keep node_type=NodeSet and pass one or more set names in node_name—the same labels you used when calling cognee.add(..., node_set=[...]).

node_type (Optional[Type], optional, default: NodeSet): Controls which graph model to search. Leave this as NodeSet unless you’ve built a custom node model.

node_name (Optional[List[str]]): Names of the node sets to include. Cognee treats each string as a logical bucket of memories.

await cognee.search(
    query_text="What discounts did TechSupply offer?",
    node_type=NodeSet,
    node_name=["vendor_conversations"],
)

await cognee.search(
    query_text="Summarize procurement rules",
    node_type=NodeSet,
    node_name=["procurement_policies", "purchase_history"],
)

Interaction & History Parameters

save_interaction (bool, optional, default: False): Persist the Q&A as a graph interaction for auditing or later review.
```
await cognee.search(
    query_text="Draft the release note",
    save_interaction=True,
)
```
last_k (Optional[int], optional, default: 1): When using SearchType.FEEDBACK, choose how many recent interactions to update with your feedback.
```
await cognee.search(
    query_text="Please improve the last answer",
    query_type=SearchType.FEEDBACK,
    last_k=3,
)
```

Datasets & Users

datasets (Optional[Union[list[str], str]]): Limit search to dataset names you already know.

await cognee.search(
    query_text="Key risks",
    datasets=["risk_register", "exec_summary"],
)

dataset_ids (Optional[Union[list[UUID], UUID]]): Same as datasets, but with explicit UUIDs when names collide.

from uuid import UUID
await cognee.search(
    query_text="Customer feedback",
    dataset_ids=[UUID("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")],
)

user (Optional[User]): Provide a user object when running multi-tenant flows or background jobs.

from cognee.modules.users.methods import get_user
user = await get_user(user_id)
await cognee.search(query_text="Team OKRs", user=user)

Multiple Datasets Cheat Sheet

Access control OFF (ENABLE_BACKEND_ACCESS_CONTROL=false), use_combined_context=False:
- What gets searched? Cognee does one search across every dataset you passed (and any others you can access) because access control is disabled.
- What comes back? A Python list, e.g. ['answer 1', 'answer 2'].
Access control OFF, use_combined_context=True:
- What gets searched? Same single search as above.
- What comes back? A CombinedSearchResult. Because no dataset boundaries are enforced, the datasets field holds a placeholder entry labelled “all available datasets”.
Access control ON, use_combined_context=False:
- What gets searched? Cognee validates each dataset ID, then runs the query separately against each permitted dataset.
- What comes back? A list of dictionaries, one per dataset, for example:
  [ {"search_result": ["answer from dataset A"], "dataset_id": UUID(...), "dataset_name": "dataset_a"}, {"search_result": ["answer from dataset B"], "dataset_id": UUID(...), "dataset_name": "dataset_b"}, ]
Access control ON, use_combined_context=True:
- What gets searched? Same per-dataset queries as the previous case.
- What comes back? A single CombinedSearchResult where datasets lists each contributing dataset and context aggregates their snippets. Use this when you prefer one blended answer.

Custom Prompts

Learn about custom prompts for tailored answers

Permission Snippets

Multi-tenant deployment patterns

API Reference

Explore all search types and parameters

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

Code in Action

What Just Happened

Parameters Reference

Custom Prompts

Permission Snippets

API Reference

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

​Code in Action

​What Just Happened

​Parameters Reference

Custom Prompts

Permission Snippets

API Reference

Code in Action

What Just Happened

Parameters Reference