Skip to main content
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)
  • 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,
)
use_combined_context should only be set when ENABLE_BACKEND_ACCESS_CONTROL is turned on. When access control is disabled, this parameter has no meaningful effect on dataset scoping.
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"],
)
  • session_id (Optional[str]): Maintain conversation history across searches. When you use the same session_id, Cognee includes previous interactions in the LLM prompt, enabling contextual follow-up questions. 
    await cognee.search(
    query_text="Where does Alice live?",
    session_id="conversation_1"
)
# Later, same session remembers previous context
await cognee.search(
    query_text="What does she do for work?",
    session_id="conversation_1"  # "she" refers to Alice
)
    See Sessions Guide for complete examples.
  • 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 (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)
    When ENABLE_BACKEND_ACCESS_CONTROL=true:
    • Result shape: Searches run only on datasets the user can access and return either:
      • Per dataset: list of {dataset_name, dataset_id, search_result}
      • Combined: single CombinedSearchResult with merged snippets (use_combined_context=True)
    • If no user is given, get_default_user() is used (created if missing); errors only if this user lacks dataset permissions.
    • If datasets is not set, all datasets readable by the user are searched; errors if none are accessible or if requested datasets are forbidden.
    PermissionDeniedError will be raised unless you search with the same user that added the data or grant access to the default user.
    When ENABLE_BACKEND_ACCESS_CONTROL=false
    • Dataset filters (datasets, dataset_ids) are ignored — everything is searched.
    • Results normally come back as a plain list (["answer1", "answer2"]).
    • Setting use_combined_context=True here just wraps the same results in a CombinedSearchResult without changing them.

Custom Prompts

Learn about custom prompts for tailored answers

Permission Snippets

Multi-tenant deployment patterns

API Reference

Explore all search types and parameters

Sessions

Enable conversational memory with sessions