Skip to main content
A minimal guide to using cognee.search() to query your processed datasets. Covers the basic call, core parameters, and result shapes. 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():
    answers = await cognee.search(
        query_text="What are the main themes in my data?"
    )
    for answer in answers:
        print(answer)

if __name__ == "__main__":
    asyncio.run(main())
SearchType.GRAPH_COMPLETION is the default. It returns an LLM-generated answer backed by context retrieved from your knowledge graph.

​
What Just Happened

cognee.search() retrieved relevant context from the knowledge graph and passed it to the LLM to generate an answer. Results are returned as a list.

​
Parameters Reference

All examples below assume you are inside an async function. Import helpers when needed: 
from cognee import SearchType
from cognee.modules.engine.models.node_set import NodeSet

Core Parameters

  • query_text (str, required): The question or phrase to search for. 
    answers = await cognee.search(query_text="Who owns the rollout plan?")
  • query_type (SearchType, optional, default: SearchType.GRAPH_COMPLETION): Sets the search mode. See Search Types for the full list and Retrievers for how each type maps to a retriever. 
    await cognee.search(
    query_text="List coding guidelines",
    query_type=SearchType.CODING_RULES,
)
  • top_k (int, optional, default: 10): Maximum number of results to return. 
    await cognee.search(query_text="Summaries please", top_k=3)
  • system_prompt_path (str, optional, default: "answer_simple_question.txt"): Path 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 prompt string. Overrides system_prompt_path when set. 
    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): Return the retrieved context without passing it to the LLM. 
    context = await cognee.search(
    query_text="What did we promise the client?",
    only_context=True,
)
  • wide_search_top_k (int, optional, default: 100): Caps initial candidate retrieval for graph-completion retrievers before ranking. Increase for broader recall on large graphs.
  • triplet_distance_penalty (float, optional, default: 3.5): Penalty applied in graph retrieval ranking. Controls how triplet distance influences final result ordering.
  • retriever_specific_config (dict, optional): Per-retriever options. Examples: response_model for typed LLM output; max_iter for GRAPH_COMPLETION_COT; context_extension_rounds for GRAPH_COMPLETION_CONTEXT_EXTENSION. See the API reference for full keys.
  • verbose (bool, optional, default: False): When true, results include text_result, context_result, and objects_result fields alongside the answer.
These options scope the search to specific node sets. Set both node_type and node_name to filter — use the same names you passed to cognee.add(..., node_set=[...]).
  • node_type (Optional[Type], optional, default: NodeSet): The graph model to search. Leave as NodeSet unless you have a custom node model.
  • node_name (Optional[List[str]]): Names of the node sets to include. 
    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]): Links this search to a conversation session. When the same session_id is reused, previous Q&A turns are included in the LLM prompt. Only effective for GRAPH_COMPLETION, RAG_COMPLETION, and TRIPLET_COMPLETION; other search types do not read or write session history. If omitted while caching is enabled, Cognee writes to default_session. 
    await cognee.search(
    query_text="Where does Alice live?",
    session_id="conversation_1"
)
# Later — the LLM has access to the previous answer
await cognee.search(
    query_text="What does she do for work?",
    session_id="conversation_1"
)
    See Sessions Guide for complete examples. To record feedback on answers, see the Feedback System.
  • datasets (Optional[Union[list[str], str]]): Limit search to specific dataset names. 
    await cognee.search(
    query_text="Key risks",
    datasets=["risk_register", "exec_summary"],
)
  • dataset_ids (Optional[Union[list[UUID], UUID]]): Same as datasets, using UUIDs instead of names. 
    from uuid import UUID
await cognee.search(
    query_text="Customer feedback",
    dataset_ids=[UUID("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")],
)
  • user (Optional[User]): The user to run the search as. Required for 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. Results are returned as a list of per-dataset objects (dataset_name, dataset_id, search_result). Use verbose=True to include text_result, context_result, and objects_result in each item.
    • Parallel execution: Multiple datasets are searched concurrently using asyncio.gather() — total time is roughly that of the slowest single-dataset search.
    • If no user is given, get_default_user() is used (created if missing); an error is raised only if this user lacks dataset permissions.
    • If datasets is not set, all datasets readable by the user are searched. An error is raised if none are accessible or if a requested dataset is 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 — all data is searched.
    • Results are returned as a plain list (e.g. ["answer1", "answer2"]). If only one dataset is searched and the retriever returns a list, Cognee may unwrap one level for backwards compatibility.

Citation and Source Tracking

Provenance is available at two levels:
  1. Dataset level — when ENABLE_BACKEND_ACCESS_CONTROL=true, every result is wrapped with dataset_name and dataset_id.
  2. LLM-completion modes — use verbose=True to receive the raw retrieved objects alongside the generated answer.
SearchType.CHUNKS returns a list of dicts with these fields:
FieldTypeDescription
idstrUnique ID of this chunk
textstrRaw chunk text
chunk_indexintPosition of this chunk within the source document
chunk_sizeintToken count of this chunk
cut_typestrHow the boundary was chosen (sentence_end, paragraph_end, etc.)
import asyncio
import cognee
from cognee import SearchType

async def main():
    await cognee.add("path/to/policy.pdf", dataset_name="docs")
    await cognee.cognify(datasets=["docs"])

    results = await cognee.search(
        query_text="What is the refund policy?",
        query_type=SearchType.CHUNKS,
    )

    for chunk in results:
        print("Text:        ", chunk["text"])
        print("Chunk index: ", chunk["chunk_index"])
        print("Chunk size:  ", chunk["chunk_size"])
        print()

asyncio.run(main())
SearchType.SUMMARIES returns a list of dicts with these fields:
FieldTypeDescription
idstrUnique ID of this summary
textstrSummary text
results = await cognee.search(
    query_text="What is the refund policy?",
    query_type=SearchType.SUMMARIES,
)

for summary in results:
    print("Summary:", summary["text"])
When ENABLE_BACKEND_ACCESS_CONTROL=true, every result is wrapped with dataset information:
import asyncio
import cognee
from cognee import SearchType

async def main():
    results = await cognee.search(
        query_text="What is the refund policy?",
        query_type=SearchType.CHUNKS,
        datasets=["docs"],
    )

    for dataset_result in results:
        print("Dataset:   ", dataset_result["dataset_name"])
        print("Dataset ID:", dataset_result["dataset_id"])
        for chunk in dataset_result["search_result"]:
            print("  Text:", chunk["text"])

asyncio.run(main())
For modes that return a generated answer (GRAPH_COMPLETION, RAG_COMPLETION, etc.), use verbose=True to receive the raw retrieved objects alongside the answer:
results = await cognee.search(
    query_text="Summarize the launch timeline",
    verbose=True,
)

for result in results:
    print("Answer:         ", result.get("text_result"))
    print("Context passed: ", result.get("context_result"))
    print("Source objects: ", result.get("objects_result"))

​
Additional Examples

A complete runnable script: 
import asyncio
import cognee

async def main():
    # Start clean (optional)
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)

    await cognee.add(
        [
            "Alice moved to Paris in 2010. She works as a software engineer.",
            "Bob lives in New York. He is a data scientist.",
            "Alice and Bob met at a conference in 2015.",
        ]
    )
    await cognee.cognify()

    answers = await cognee.search(query_text="What are the main themes in my data?")
    for answer in answers:
        print(answer)

if __name__ == "__main__":
    asyncio.run(main())
Additional examples are available on our GitHub.

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