> ## 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.
# Search
> Query your AI memory with vectors, graphs, and LLMs
`search()` is a legacy operation. In Cognee v1.0, most users should use [recall()](/core-concepts/main-operations/recall) instead. Legacy `search()` remains useful when you need explicit control over retrievers and lower-level retrieval parameters.
## What is search
`search` lets you ask questions over everything you've ingested and cognified.\
Under the hood, Cognee blends **vector similarity**, **graph structure**, and **LLM reasoning** to return answers with context and provenance.
## The big picture
* **Dataset-aware**: searches run against one or more datasets you can read *(requires `ENABLE_BACKEND_ACCESS_CONTROL=true`)*
* **Multiple modes**: from simple chunk lookup to graph-aware Q\&A
* **Hybrid retrieval**: vectors find relevant pieces; graphs provide structure; LLMs compose answers
* **Conversational memory**: for GRAPH\_COMPLETION, RAG\_COMPLETION, and TRIPLET\_COMPLETION, use `session_id` to maintain conversation history across searches *(requires caching enabled)*. When caching is on, omitting `session_id` uses `default_session` and still stores history. Other search types do not use session history.
* **Safe by default**: permissions are checked before any retrieval
* **Observability**: telemetry is emitted for query start/completion
**Dataset scoping** requires specific configuration. See [permissions system](/core-concepts/multi-user-mode/permissions-system/datasets#dataset-isolation-how-access-is-enforced) for details on access control requirements and supported database setups.
## Where search fits
Use `search` after you've run `.add` and `.cognify`.
At that point, your dataset has chunks, summaries, embeddings, and a knowledge graph—so queries can leverage both **similarity** and **structure**.
If you see `DatabaseNotCreatedError: please call await setup() first`, Cognee has not been initialized yet. In practice, that usually means you are trying to search or use an operation that resolves the default user before initialization has happened. Run `cognee.add(...)` or `cognee.remember(...)` first, then retry your operation.
## How it works (conceptually)
1. **Scope & permissions**\
Resolve target datasets (by name or id) and enforce read access.
2. **Mode dispatch**\
Pick a search mode (default: **graph-aware completion**) and route to its retriever.
3. **Retrieve → (optional) generate**\
Collect context via vectors and/or graph traversal; some modes then ask an LLM to compose a final answer.
4. **Return results**\
Depending on mode: a natural-language answer string, chunk/summary dicts with metadata, graph records, or Cypher results.
For a practical guide to using search with examples and detailed parameter explanations, see [Search Basics](/guides/search-basics).
## Retrievers
Each search type is handled by a **retriever**. The pipeline is: `get_retrieved_objects` → `get_context_from_objects` → `get_completion_from_context` (skipped when `only_context=True`).
| Search type | Retriever |
| ------------------------------------- | ---------------------------------------- |
| GRAPH\_COMPLETION | GraphCompletionRetriever |
| RAG\_COMPLETION | CompletionRetriever |
| CHUNKS | ChunksRetriever |
| SUMMARIES | SummariesRetriever |
| GRAPH\_SUMMARY\_COMPLETION | GraphSummaryCompletionRetriever |
| GRAPH\_COMPLETION\_COT | GraphCompletionCotRetriever |
| GRAPH\_COMPLETION\_CONTEXT\_EXTENSION | GraphCompletionContextExtensionRetriever |
| TRIPLET\_COMPLETION | TripletRetriever |
| CHUNKS\_LEXICAL | JaccardChunksRetriever |
| CODING\_RULES | CodingRulesRetriever |
| TEMPORAL | TemporalRetriever |
| CYPHER | CypherSearchRetriever |
| NATURAL\_LANGUAGE | NaturalLanguageRetriever |
You can register a custom retriever for a search type via `use_retriever(SearchType, RetrieverClass)`; the class must implement the same three-step interface (`BaseRetriever`). See the API reference for `BaseRetriever` and `register_retriever`.
### Multi-query (batch)
**GraphCompletionRetriever**, **GraphCompletionCotRetriever**, and **GraphCompletionContextExtensionRetriever** support **batch mode**: pass `query_batch` (a non-empty list of strings) instead of `query`. You get one result per query; session cache is not used in batch mode. The public `cognee.search()` API accepts only a single `query_text`; batch is available when you use the retrievers directly (e.g. in custom pipelines).
Graph-aware question answering.
* **What it does**: Finds relevant graph triplets using vector hints across indexed fields, resolves them into readable context, and asks an LLM to answer your question grounded in that context.
* **Why it’s useful**: Combines fuzzy matching (vectors) with precise structure (graph) so answers reflect relationships, not just nearby text.
* **Typical output**: A natural-language answer with references to the supporting graph context.
Retrieve-then-generate over text chunks.
* **What it does**: Pulls top-k chunks via vector search, stitches a context window, then asks an LLM to answer.
* **When to use**: You want fast, text-only RAG without graph structure.
* **Output**: An LLM answer grounded in retrieved chunks.
Direct chunk retrieval.
* **What it does**: Returns the most similar text chunks to your query via vector search.
* **When to use**: You want raw passages/snippets to display or post-process.
* **Output**: Chunk dicts with `id`, `text`, `chunk_index`, `chunk_size`, and `cut_type`. With `ENABLE_BACKEND_ACCESS_CONTROL=true`, results are wrapped with `dataset_name` and `dataset_id`. See [Citation and Source Tracking](/guides/search-basics#citation-and-source-tracking) for details and examples.
Search over precomputed summaries.
* **What it does**: Vector search on `TextSummary` content for concise, high-signal hits.
* **When to use**: You prefer short summaries instead of full chunks.
* **Output**: Summary dicts with `id` and `text`. With `ENABLE_BACKEND_ACCESS_CONTROL=true`, results are wrapped with `dataset_name` and `dataset_id`. See [Citation and Source Tracking](/guides/search-basics#citation-and-source-tracking) for details and examples.
Graph-aware summary answering.
* **What it does**: Builds graph context like GRAPH\_COMPLETION, then condenses it before answering.
* **When to use**: You want a tighter, summary-first response.
* **Output**: A concise answer grounded in graph context.
Chain-of-thought over the graph.
* **What it does**: Iterative rounds of graph retrieval and LLM reasoning to refine the answer.
* **When to use**: Complex questions that benefit from stepwise reasoning.
* **Output**: A refined answer produced through multiple reasoning steps.
Iterative context expansion.
* **What it does**: Starts with initial graph context, lets the LLM suggest follow-ups, fetches more graph context, repeats.
* **When to use**: Open-ended queries that need broader exploration.
* **Output**: An answer assembled after expanding the relevant subgraph.
Natural language to Cypher to execution.
* **What it does**: Infers a Cypher query from your question using the graph schema, runs it, returns the results.
* **When to use**: You want structured graph answers without writing Cypher.
* **Output**: Executed graph results.
Run Cypher directly.
* **What it does**: Executes your Cypher query against the graph database.
* **When to use**: You know the schema and want full control.
* **Output**: Raw query results.
**CYPHER** and **NATURAL\_LANGUAGE** are disabled when `ALLOW_CYPHER_QUERY=false` (environment variable).
Code-focused retrieval (coding rules / codebase search).
* **What it does**: Retrieves rules or code context from the `coding_agent_rules` nodeset and returns structured code information.
* **When to use**: Codebases or coding guidelines indexed by Cognee (e.g. via memify).
* **Output**: Structured code contexts and related graph information.
* **Prereq**: The `coding_agent_rules` nodeset must be populated (e.g. via [memify](/guides/memify-quickstart)).
Triple-based retrieval with LLM completion (no full graph traversal).
* **What it does**: Retrieves graph triplets by vector similarity, resolves them to text, and asks an LLM to answer.
* **When to use**: You want triplet-level context without full graph expansion.
* **Output**: An LLM answer grounded in retrieved triplets.
* **Prereq**: Triplet embeddings must exist—set `TRIPLET_EMBEDDING=true` before running [cognify](/core-concepts/main-operations/legacy-operations/cognify) or run the [`create_triplet_embeddings`](/guides/memify-triplet-embeddings) memify pipeline (retriever uses the `Triplet_text` collection).
Lexical (keyword-style) chunk search.
* **What it does**: Returns chunks that match your query using token-based similarity (e.g. Jaccard), not semantic embeddings.
* **When to use**: Exact-term or keyword-style lookups; stopword-aware search.
* **Output**: Ranked text chunks, optionally with scores.
Time-aware retrieval.
* **What it does**: Retrieves and ranks content by temporal relevance (dates, events) and answers with time context.
* **When to use**: Queries about "before/after X", "in 2020", or event timelines.
* **Output**: An answer grounded in time-filtered graph context. See [Time-awareness](/guides/time-awareness) for setup.
Automatic mode selection.
* **What it does**: Uses an LLM to choose the most suitable search type for your query, then runs it. Falls back to `RAG_COMPLETION` if mode selection fails.
* **When to use**: Exploratory or one-off queries when you are unsure which mode fits best. For production or latency-sensitive workloads, prefer a specific search type.
* **Output**: Results in whatever format the chosen search type returns.
Graph-edge result format specific to the Cognee MCP server.
* **What it does**: Runs search in the Cognee MCP server and formats the raw triplet results as readable relationship lines instead of asking an LLM to compose an answer.
* **When to use**: You want to inspect raw graph edges in MCP rather than receive a natural-language response.
* **Output**: A newline-separated list of relationship statements. `INSIGHTS` is MCP-only and is not available through the Python `SearchType` enum.
**Feedback** is handled via [Sessions](/core-concepts/sessions-and-caching) and the [Feedback System](/guides/feedback-system)—use `cognee.session.add_feedback` and `cognee.session.delete_feedback`. See the [Sessions Guide](/guides/sessions) and [Feedback System](/guides/feedback-system) for full details.
## Further details
Every retriever follows the same three-step internal pipeline:
* **`get_retrieved_objects`** — fetches raw graph triplets (edges + nodes) or vector chunks from the store
* **`get_context_from_objects`** — formats those objects into a context string (e.g. `"Nodes: … Connections: …"` for graph modes)
* **`get_completion_from_context`** — sends context to the LLM to produce a natural-language answer *(skipped when `only_context=True`)*
**Completion modes** (`GRAPH_COMPLETION`, `RAG_COMPLETION`, `TRIPLET_COMPLETION`, etc.) run all three steps and return a **string answer**. That is why `GRAPH_COMPLETION` returns a plain string by default: the raw graph objects are consumed internally to assemble the LLM prompt.
**Retrieval-only modes** (`CHUNKS`, `SUMMARIES`) skip the LLM step and return **structured dicts** directly.
**Inspecting the raw retrieved objects**: add `verbose=True` to receive `text_result` (LLM answer), `context_result` (formatted context string), and `objects_result` (raw graph edges/nodes or chunk objects) together. Use `only_context=True` to skip LLM generation and return the formatted context string directly. For structured chunk dicts with no LLM call at all, use `SearchType.CHUNKS`. See [Search Basics — raw source objects](/guides/search-basics#citation-and-source-tracking) for code examples.
First bring data into Cognee
Build the knowledge graph that search queries
Understand how vector and graph stores work together
Enable conversational memory with sessions