Search Basics

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

​

Code in Action

await cognee.remember(
    [
        "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.",
    ],
    self_improvement=False,
)

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

​

Parameters Reference

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

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

# OR (default) — results touching any of the listed node sets
await cognee.recall(
    query_text="Summarize procurement rules",
    node_name=["procurement_policies", "purchase_history"],
    node_name_filter_operator="OR",
)

# AND — results that belong to every listed node set
await cognee.recall(
    query_text="What topics span both domains?",
    node_name=["procurement_policies", "purchase_history"],
    node_name_filter_operator="AND",
)

​

Citation and Source Tracking

1. Dataset level — when ENABLE_BACKEND_ACCESS_CONTROL=true, results are wrapped with dataset_name and dataset_id.
2. Chunk/summary level — CHUNKS and SUMMARIES results include an id you can use to look up the item in the graph.

​

Evidence block (include_references)

• Deterministic and in-process: the block is assembled locally from the retrieved payloads or graph context. There is no extra LLM call and no prompt injection — it is appended after completion generation.
• Response schema unchanged: Evidence is added to the answer text only. Return types and result shapes are the same as before, and non-string response_model paths are unaffected.
• Graceful degradation: chunk-level evidence is used when the vector payload carries document_name/document_id. Older indexes that predate these fields fall back to entity → chunk → document graph traversal where the backend supports it, or omit the Evidence block silently (no errors) when neither is available.
• Opting out: set include_references=False to restore the exact previous answer text. This is useful when you compare against stored snapshots or evaluation baselines, which will otherwise diff against the new Evidence block.

# Default: answer text includes an appended "Evidence:" block
await cognee.recall(query_text="What is the refund policy?")

# Restore the exact prior output (no Evidence block)
await cognee.recall(
    query_text="What is the refund policy?",
    include_references=False,
)

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.recall(
        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 ID:    ", chunk["id"])  # UUID for graph lookups
        print()

asyncio.run(main())

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

for summary in results:
    print("Summary:", summary["text"])
    print("ID:     ", summary["id"])

import asyncio
from cognee.infrastructure.databases.graph import get_graph_engine
from cognee.infrastructure.databases.vector import get_vector_engine_async

async def main():
    item_id = "your-chunk-or-summary-uuid"  # the `id` returned by a CHUNKS or SUMMARIES search

    # From the graph: returns the node's properties, or None if not found
    graph_engine = await get_graph_engine()
    node = await graph_engine.get_node(item_id)
    print(node)

    # From the vector store: choose the collection for the search type
    vector_engine = await get_vector_engine_async()
    collection = "DocumentChunk_text"  # CHUNKS results
    # collection = "TextSummary_text"  # SUMMARIES results

    rows = await vector_engine.retrieve(collection, [item_id])
    if rows:
        print(rows[0].payload["text"])

asyncio.run(main())

from cognee.infrastructure.databases.graph import get_graph_engine

graph_engine = await get_graph_engine()

# get_connections returns (source, edge, target) triples for every edge on the node
connections = await graph_engine.get_connections(str(chunk_id))
parent_documents = [
    target
    for source, edge, target in connections
    if edge["relationship_name"] == "is_part_of"
]

import asyncio
import cognee
from cognee import SearchType

async def main():
    results = await cognee.recall(
        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"])
            print("  Chunk ID:", chunk["id"])

asyncio.run(main())

results = await cognee.recall(
    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"))

​

Writing Effective Queries

• Ask a full, natural-language question. recall() and the graph-completion retrievers are LLM-backed, so "What discounts did TechSupply offer in 2023?" works better than a bare keyword like "discounts". Reserve short keyword strings for CHUNKS_LEXICAL or CHUNKS.
• Let phrasing steer auto-routing, or set query_type yourself. When you omit query_type, a rule-based router reads cue words in your query and picks a strategy — summary words (summary, overview, key takeaways) lean toward summary completion, reasoning words (why, explain, step by step) toward chain-of-thought, relationship words (how are X and Y connected, path between) toward context extension, and time words (when, before, after, or a 4-digit year) toward temporal search. If no cue matches, it defaults to GRAPH_COMPLETION. When you know the mode you want, pass query_type explicitly to bypass the router. See Auto-routing behavior and Choosing a Search Type.
• Phrase positively. A negation (not, no, never, without) within ~20 characters before a cue word suppresses that cue, so "summary without dates" will not route to summary. Rephrase or set query_type when a query needs negated wording.
• Scope the query to narrow results. Pass datasets to limit which knowledge base is searched and node_name to restrict retrieval to specific node sets. Tighter scope means less noise and faster answers.
• Tune the call to the task. Lower top_k for concise answers, raise it for broad recall. Use only_context=True when you want the retrieved context without an LLM answer (useful for inspecting retrieval quality or feeding your own prompt). Match the search type to your latency and cost budget using the speed, cost, and recall depth comparison.

​

Full Example

import asyncio
import cognee


async def main():
    # Start clean (optional in your app)
    await cognee.forget(everything=True)
    # Prepare knowledge base
    await cognee.remember(
        [
            "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.",
        ],
        self_improvement=False,
    )

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

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

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.recall(query_text="What are the main themes in my data?")
    for answer in answers:
        print(answer)

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

​

Additional Examples