SearchType

Enum of the search modes you can pass to cognee.search().

SearchType

Enum defining the available search modes for cognee.search().

from cognee import SearchType

results = await cognee.search("query", query_type=SearchType.GRAPH_COMPLETION)

Values

The Retrieval source column shows what each type reads from: Vector (semantic similarity over embeddings), Graph (knowledge-graph traversal / Cypher), Vector + Graph (semantic seeds plus graph context — the “semantics + graph” combination), or Lexical (keyword matching, no embeddings). Types marked Varies pick or combine sources at runtime.

Value	Retrieval source	Description
SearchType.SUMMARIES	Vector	Pre-generated hierarchical summaries of content.
SearchType.CHUNKS	Vector	Raw text segments matching semantically.
SearchType.CHUNKS_LEXICAL	Lexical	Token-based lexical chunk search (BM25-style keyword ranking, no embeddings).
SearchType.RAG_COMPLETION	Vector	Traditional RAG: retrieve chunks by semantic similarity, then LLM answer.
SearchType.HYBRID_COMPLETION	Vector + Graph	Default. Hybrid answer combining semantic chunk and summary search with graph/entity context.
SearchType.TRIPLET_COMPLETION	Vector	Semantic search over triplet embeddings, then LLM answer (needs TRIPLET_EMBEDDING=true).
SearchType.GRAPH_COMPLETION	Vector + Graph	Semantic seeds expanded into graph context, then LLM completion.
SearchType.GRAPH_COMPLETION_DECOMPOSITION	Vector + Graph	Decomposes a complex query into focused subqueries, retrieves graph context per subquery, then synthesizes a final answer.
SearchType.GRAPH_SUMMARY_COMPLETION	Vector + Graph	Graph context condensed via summaries before completion.
SearchType.GRAPH_COMPLETION_COT	Vector + Graph	Graph completion with iterative chain-of-thought reasoning.
SearchType.GRAPH_COMPLETION_CONTEXT_EXTENSION	Vector + Graph	Graph completion that iteratively feeds each answer back as a new query to widen subgraph coverage.
SearchType.TEMPORAL	Vector + Graph	Time-aware search: reads a time window from the question, then reranks hybrid results so content dated inside it comes first.
SearchType.CYPHER	Graph	Direct Cypher query against the graph database.
SearchType.NATURAL_LANGUAGE	Graph	Natural language translated to Cypher, then executed against the graph.
SearchType.CODING_RULES	Graph	Retrieves coding rules stored in a graph node set.
SearchType.CODE	Graph	Deterministic operations over a code graph built by the code-graph pipeline: code_query selects one operation (query_facts, explore, traverse, find_path, impact_analysis, insights, architecture, delta). No LLM or embedding call; see CODE below for every operation and its arguments.
SearchType.GRAPH_REPORT	Graph	Ignores the query and reports on the whole graph: hub nodes, cross-node-set connections, edge provenance, and suggested questions. See report().
SearchType.BROAD	Graph + Vector	Questions that need the whole dataset — counts, totals, lists, lookups. Each question builds a temporary SQLite record store of the dataset; a small dataset is also shown to the LLM whole. The answer comes directly from that, from one model-written read-only SELECT over the store, or from reading the chunks most similar to the question. The answer ends with a note on how it was reached. No top_k; see BROAD below.
SearchType.SKILLS	Vector	Semantic discovery of the skill playbooks scoped to one dataset. Returns skill metadata only — never the procedure body. Requires exactly one explicit dataset.
SearchType.AGENTIC_COMPLETION	Varies	Agentic completion that chooses sources via skills and tools.
SearchType.FEELING_LUCKY	Varies	Auto-selects the best search type (and its source) for the query.

Speed, cost, and recall depth

Two things drive the cost of a search type: how many LLM calls it makes and how much retrieved context it puts into each prompt. The tabs below give measured reference numbers from one benchmark run: Search speed & recall depth compares every type on latency, call counts, and recall depth, and Session speed and overhead shows what the default session settings add on top, including the prompt-token cost of each type.

Methodology. Measured on cognee 1.4 (dev) with openai/gpt-5-mini, LanceDB and Kuzu, against a small knowledge base (10 short documents → 99 nodes / 191 edges), 3 questions × 2 runs per type (1 run for the iterative modes), default top_k=15. Token counts are provider-reported and summed over all LLM calls in the query. Absolute values scale with your corpus, model, and hardware — read them as ratios and orders of magnitude, not guarantees. On larger corpora token costs grow with chunk size: a single chunk can hold up to ~8,191 tokens, and no layer truncates the assembled context by default.

Search speed & recall depth

The single-call types (upper block) were measured with session memory disabled (AUTO_FEEDBACK=false): a query costs exactly its retrieval plus at most one completion. The iterative multi-call modes (lower block) were measured with default session settings — subtract one LLM call for their sessions-off cost, small relative to these totals. Prompt-token costs are in the Session speed and overhead tab.

Search type	Median latency	LLM calls	Embedding calls	What the LLM sees (recall depth)
CHUNKS_LEXICAL	~10 ms	0	0	— (returns top 15 chunks, BM25-ranked)
CYPHER (estimated)	~1 ms	0	0	— (returns raw rows from your Cypher query)
CODING_RULES (estimated)	~1 ms	0	0	— (returns rules stored in a graph node set)
CODE (estimated)	scales with the code graph on the first call, then ~ms from the cached snapshot	0	0	— (returns the operation’s structured result: facts, nodes and edges, a path, an impact report, or a diagram)
SUMMARIES	~0.3 s	0	1	— (returns top 15 pre-generated summaries)
CHUNKS	~0.3 s	0	1	— (returns top 15 chunks, semantic)
RAG_COMPLETION	~3.9 s	1	1	Top 15 chunks (~1.7k chars here)
TRIPLET_COMPLETION (estimated)	~4 s	1	1	Top triplet matches; requires TRIPLET_EMBEDDING=true at cognify time
GRAPH_COMPLETION	~3.9 s	1	1	Top 15 triplets plus their nodes’ text (~7.5k chars here)
HYBRID_COMPLETION (default)	~3.8 s	1	1	15 chunks (fused chunk + summary search), 15 entities × ≤10 edges, ≤15 facts (~14k chars here)
GRAPH_REPORT (estimated)	scales with graph size	1	0	First 2,000 chars of the report; the one LLM call only generates the suggested questions, everything else is computed deterministically over the whole graph
BROAD (estimated)	scales with dataset size (the store is rebuilt per question)	1–3	0–6	The whole dataset up to context_tokens; otherwise the store’s schema and samples, then a query result (≤200 rows) or reading_tokens of the most similar chunks
TEMPORAL	~40 s	3	1	Hybrid candidates reranked by in-window Timestamps (time-extraction call first; falls back to plain hybrid results when no window is found)
FEELING_LUCKY	~40 s	2–5	0–5	Whatever the LLM-chosen type retrieves, after one type-selection call
NATURAL_LANGUAGE	~50 s	4	0	Raw rows from the generated Cypher (up to max_attempts=3 generation attempts; no embeddings involved). Measured before v1.6.3, so the 4 calls include a session-turn call it no longer makes
GRAPH_SUMMARY_COMPLETION	~50 s	3	1	Same triplet context as GRAPH_COMPLETION, condensed by a summarization call before answering
GRAPH_COMPLETION_DECOMPOSITION	~60 s	5–8	1–5	Triplet context per subquery (query split into 1–5 subqueries, one retrieval sweep each), merged in a final synthesis
GRAPH_COMPLETION_CONTEXT_EXTENSION	~60 s	6	≤5	Triplet context accumulated over up to context_extension_rounds=4 retrieve-and-generate rounds
GRAPH_COMPLETION_COT	~200 s	14	5	Accumulated triplet context re-sent every round — max_iter=4 rounds × (answer + validation + follow-up) calls
AGENTIC_COMPLETION (estimated)	60–200 s	varies, ≤ max_iter=6 tool rounds	varies	Whatever the loaded skills and tools return; budget for the GRAPH_COMPLETION_DECOMPOSITION-to-COT range

Rows marked (estimated) were not measured — they are derived from how the retriever is built (CYPHER, CODING_RULES, and CODE are direct graph reads with no LLM or embedding call — CODE loads the dataset’s code subgraph once and caches the parsed snapshot for 60 seconds, so only the first call scales with graph size; TRIPLET_COMPLETION has the same shape as RAG_COMPLETION; GRAPH_REPORT reads every node and edge via get_graph_data(), so its latency grows with the graph rather than with top_k; AGENTIC_COMPLETION is bounded by the measured iterative modes; BROAD makes one decision call, one more if its query fails, and one answer call unless the decision already answered, and embeds only on the reading route (one search per question phrasing) and when the dataset exceeds store_mb). Embedding-call counts for the multi-call modes are likewise derived rather than measured: each retrieval sweep embeds the query once, and FEELING_LUCKY inherits whatever the chosen type embeds — anywhere from 0 for the direct graph readers up to 5 if the selector picks GRAPH_COMPLETION_COT.

The ordering to remember: latency is nearly identical for the three single-call completion types (the single LLM call dominates; retrieval differs by tens of milliseconds), while token cost and recall depth grow together — on this corpus roughly 1 : 4.7 : 7.5 for RAG : GRAPH : HYBRID (measured sessions-off). GRAPH_COMPLETION does the most retrieval work per query (it fans out one vector search per index collection — 5 collections by default, repeated for each searched dataset and each capped at wide_search_top_k=100 results — plus a graph projection), but that stays cheap next to the completion call.

Session speed and overhead

With the default CACHING=true and AUTO_FEEDBACK=true, most search types pay one extra session-turn LLM call (~1,800 prompt tokens here; CHUNKS, SUMMARIES, CHUNKS_LEXICAL, GRAPH_REPORT, CODE, SKILLS, CYPHER, and NATURAL_LANGUAGE are the exceptions — their retrievers opt out of the session-turn step), and completion types additionally embed and store the Q&A turn and carry conversation history in the prompt. These latencies were measured with the session-turn call serialized ahead of retrieval — the behavior that is now SESSION_SEARCH_MODE=sequential. Under the current concurrent default, RAG_COMPLETION, GRAPH_COMPLETION, HYBRID_COMPLETION, and TRIPLET_COMPLETION overlap that call with answer generation, so their defaults-on latency sits closer to their sessions-off figures (follow-up turns instead add a second retrieval query and its embedding call); the other rows still run sequentially and stand as measured. Token and call counts are unchanged either way. See Sessions and Caching. Same corpus, defaults on:

Search type	Median latency	LLM calls	Embedding calls	Prompt tokens
CHUNKS_LEXICAL	same as sessions-off	0	0	0 (skips the session turn)
CODE (estimated)	same as sessions-off	0	0	0 (skips the session turn)
SUMMARIES	same as sessions-off	0	1	0 (skips the session turn)
CHUNKS	same as sessions-off	0	1	0 (skips the session turn)
CYPHER (estimated)	same as sessions-off	0	0	0 (skips the session turn)
CODING_RULES (estimated)	~10 s	1	0	~1,800
RAG_COMPLETION	~20 s	2	3	~3,300
TRIPLET_COMPLETION (estimated)	~20 s	2	3	~RAG-level + session turn
GRAPH_COMPLETION	~20 s	2	3	~5,400
HYBRID_COMPLETION (default)	~20 s	2	3	~6,600
GRAPH_REPORT (estimated)	scales with graph size	1	0	~600 (skips the session turn)
BROAD (estimated)	scales with dataset size	2–4	2–8	up to ~context_tokens + session turn
TEMPORAL	~40 s	3	3	~6,300
FEELING_LUCKY	~40 s	2–5	0–7	~6,100
NATURAL_LANGUAGE	~50 s	4	0	~5,100
GRAPH_SUMMARY_COMPLETION	~50 s	3	3	~5,900
GRAPH_COMPLETION_DECOMPOSITION	~60 s	5–8	3–7	~13,700
GRAPH_COMPLETION_CONTEXT_EXTENSION	~60 s	6	≤7	~23,100
GRAPH_COMPLETION_COT	~200 s	14	7	~45,700
AGENTIC_COMPLETION (estimated)	60–200 s	varies, ≤ max_iter=6 tool rounds	varies	varies

For the sessions-off cost, subtract one LLM call and ~1,800 prompt tokens — negligible for the multi-call modes, but the whole bill for the retrieval-only types that still run the session turn. Embedding calls are derived rather than measured: completion types add two embedding calls on top of their retrieval embeddings from the first tab — one to vector-recall session history for the prompt, one to embed and store the finished Q&A turn — while retrieval-only types add none. Rows marked (estimated) were not measured; CODING_RULES and TRIPLET_COMPLETION pay the session-turn overhead like the completion types, while CHUNKS, SUMMARIES, CHUNKS_LEXICAL, GRAPH_REPORT, CODE, SKILLS, CYPHER, and NATURAL_LANGUAGE opt out of the session-turn step entirely, so their cost is the same either way. NATURAL_LANGUAGE still makes its own Cypher-generation LLM calls; its measured rows in both tables (4 LLM calls, ~5,100 prompt tokens) were taken before it opted out and include the session-turn call, so expect one call and ~1,800 prompt tokens fewer on current versions. The TEMPORAL rows in both tables were measured on the event-based retriever that v1.6.3 replaced with hybrid search reranked by Timestamps, so treat them as approximate.

If you don’t need conversational memory on a query, pass only_context=True to skip both the completion and the session-turn call; set AUTO_FEEDBACK=false to drop the session-turn call globally while keeping session storage, or CACHING=false to disable sessions entirely. See Sessions and Caching.

To go faster: prefer CHUNKS, SUMMARIES, or CHUNKS_LEXICAL (no completion call), pass only_context=True, or disable auto-feedback. To go deeper: start with GRAPH_COMPLETION, escalate to GRAPH_COMPLETION_DECOMPOSITION for multi-part questions or GRAPH_COMPLETION_COT for multi-hop reasoning — the tables above show what that escalation costs (roughly 3× and 10× the latency, 2.5× and 8× the prompt tokens of GRAPH_COMPLETION on this corpus). Lowering max_iter / context_extension_rounds via retriever_specific_config reduces cost proportionally. See Search Basics — Advanced Parameters.

Choosing a Search Type

I want an LLM-generated answer grounded in my data

Use HYBRID_COMPLETION (default) for the best balance of accuracy and context. Use GRAPH_COMPLETION for graph-only context, or RAG_COMPLETION for a simpler chunk-based approach.

I want raw data, not an LLM answer

Use CHUNKS for semantic chunk retrieval or CHUNKS_LEXICAL for keyword-based. Use SUMMARIES for pre-generated summaries.

I want to query the graph directly

Use CYPHER for raw Cypher queries or NATURAL_LANGUAGE to have cognee translate your question to Cypher.

I'm not sure which to use

Just call recall() without query_type: its rule-based router checks two patterns and defaults to HYBRID_COMPLETION, so plain questions get a generated answer. A query that is entirely wrapped in double quotes runs CHUNKS_LEXICAL, and an explicit coding-rules or code-review phrase runs CODING_RULES; both return payloads rather than an answer. CYPHER is never auto-routed — it takes an explicit query_type — and so does every other type. See Auto-routing behavior for the rule table.

FEELING_LUCKY is a different, LLM-based selector. It can choose retrieval-only types such as SUMMARIES or CHUNKS, which return payloads instead of a generated answer, so avoid it when you need an answer on every call.

I need more accurate or comprehensive answers from the graph

All four graph-completion modes retrieve graph triplets and generate an LLM answer, but they differ in depth and latency:

Mode	Strategy	Best for	Trade-off
GRAPH_COMPLETION	Single-pass retrieval + completion	Most queries — good accuracy, low latency	Baseline
GRAPH_COMPLETION_DECOMPOSITION	Decomposes query into 1–5 subqueries, retrieves graph context per subquery, then synthesizes a final answer	Multi-entity or multi-aspect questions (e.g. “Tell me about A and B”)	One extra LLM call for decomposition; slightly higher latency
GRAPH_SUMMARY_COMPLETION	Graph context condensed via summaries before completion	Noisy or large graphs where a tighter context improves coherence	Slightly slower; summary quality matters
GRAPH_COMPLETION_COT	Iterative: retrieve → answer → validate → follow-up (up to max_iter rounds, default 4)	Complex multi-hop questions where stepwise reasoning helps	Higher latency; more LLM calls
GRAPH_COMPLETION_CONTEXT_EXTENSION	Iterative: retrieve → generate → use output as new query (up to context_extension_rounds, default 4)	Open-ended or exploratory queries needing a broader subgraph	Higher latency; early convergence stops extra rounds

See Search Basics — Advanced Parameters and Retrievers for full details.

Per-search-type parameters

Every type accepts the common parameters (query_text, top_k, system_prompt/system_prompt_path, only_context, verbose, include_references, datasets/dataset_ids, user, session_id) documented in Search Basics — Parameters Reference. The graph-completion family additionally honors the graph-ranking knobs (wide_search_top_k, triplet_distance_penalty, feedback_influence, neighborhood_depth, neighborhood_seed_top_k) and node-set filters. wide_search_top_k and triplet_distance_penalty are the two knobs HYBRID_COMPLETION rejects rather than ignores — passing either with the default search type raises InvalidHybridSearchConfig; see Search Basics — Advanced Parameters. With recall(), use node_name and node_name_filter_operator; node_type is only exposed on lower-level search().

The accordions below list each search type’s type-specific parameters. Most entries are passed through retriever_specific_config; when a search type uses a common parameter in a special way, that is noted.

SUMMARIES

Deterministic and non-generative — it makes no LLM call and opts out of the session-turn preparation step, so query_text reaches the vector search verbatim and the call always returns summary records rather than a conversational acknowledgement.

Parameter	Type	Default	Explanation
—	—	—	No retriever_specific_config keys. Uses common parameters only.

CHUNKS

Deterministic and non-generative — it makes no LLM call and opts out of the session-turn preparation step, so query_text reaches the vector search verbatim and the call always returns chunk records rather than a conversational acknowledgement.

Parameter	Type	Default	Explanation
node_name	list[str] | None	None	Common parameter used to filter chunks by node set.
node_name_filter_operator	"OR" | "AND"	"OR"	Common parameter controlling how multiple node_name filters are combined.

CHUNKS_LEXICAL

Deterministic and non-generative — it makes no LLM call and opts out of the session-turn preparation step, so the keywords you pass are the keywords that are scored, and the call always returns chunk records rather than a conversational acknowledgement.

Parameter	Type	Default	Explanation
—	—	—	No retriever_specific_config keys. Uses common parameters only.

RAG_COMPLETION

Parameter	Type	Default	Explanation
response_model	type	str	Output type or Pydantic model for the completion response.
node_name	list[str] | None	None	Common parameter used to filter chunks by node set.
node_name_filter_operator	"OR" | "AND"	"OR"	Common parameter controlling how multiple node_name filters are combined.

HYBRID_COMPLETION

Parameter	Type	Default	Explanation
response_model	type	str	Output type or Pydantic model for the completion response.
chunks_top_k	int	min(top_k, 10)	Max chunks included in context after the chunk and summary searches are fused. It does not limit entities. See how the lanes are ranked and merged.
entities_top_k	int	min(top_k, 10)	Number of matched entities used for graph context.
max_edges_per_entity	int	10	Max connected edges listed per entity.
facts_top_k	int	min(top_k, 10)	Max edge-derived facts included in the related facts context; requires the entity lane on (entities_top_k above 0).
include_global_context_index	bool	False	Adds global-context summaries to the retrieved context.
global_context_index_top_k	int	3	Number of global-context summaries to include when enabled.
text_summaries_top_k	int | None	None	Max summary hits the chunk lane fetches to help rank chunks; defaults to chunks_top_k. Summary text is not added to the context.
use_importance_weight	bool	True	Applies importance weighting when ranking hybrid context.
include_external_metadata	bool	False	Surfaces the source document’s external_metadata on retrieved passages. Off by default, in which case the stored value is stripped from the returned chunks and the prompt is unchanged.
external_metadata_keys	list[str] | None	None	Allowlist of external_metadata keys to surface when include_external_metadata is True. Keys the chunk does not store are skipped; with no keys allowlisted nothing is surfaced.

TRIPLET_COMPLETION

Without node_name, the query is searched directly against the whole Triplet_text collection. With node_name, the candidate triplets are resolved on the graph instead: the requested node sets are expanded into a subgraph, a triplet is in scope only when both endpoints of its edge are in that subgraph — the same rule the graph-completion search types use — and only those triplets are then ranked against the query.

Parameter	Type	Default	Explanation
response_model	type	str	Output type or Pydantic model for the completion response.
node_name	list[str] | None	None	Common parameter used to scope triplets to node sets. Scope is derived from the graph’s node-set subgraph, not from a tag on the triplet itself.
node_name_filter_operator	"OR" | "AND"	"OR"	Common parameter controlling how multiple node_name filters are combined. OR puts members of any listed set in scope, so an edge between two different sets is kept; AND only keeps members belonging to every listed set, so it returns nothing when no node is in all of them.

Scoped triplet search ranks the in-scope triplets through the vector store’s optional id-bounded scoring (score_by_ids), which LanceDB, PGVector, and Turso implement. On an adapter without it — Neptune Analytics, for example — passing node_name to TRIPLET_COMPLETION raises NotImplementedError. Unscoped TRIPLET_COMPLETION works on every adapter.

GRAPH_COMPLETION

Retrieval runs as vector seeds → 1-hop graph traversal → triplet ranking (top_k triplets) → context assembly → LLM completion. See the concrete lookup process for each stage and how top_k and wide_search_top_k shape it.

Parameter	Type	Default	Explanation
response_model	type	str	Output type or Pydantic model for the completion response.
include_global_context_index	bool	False	Adds global-context summaries to the retrieved graph context.
global_context_index_top_k	int	3	Number of global-context summaries to include when enabled.

GRAPH_COMPLETION_DECOMPOSITION

Parameter	Type	Default	Explanation
response_model	type	str	Output type or Pydantic model for the completion response.
decomposition_mode	"answer_per_subquery" | "combined_triplets_context"	"answer_per_subquery"	Controls whether each subquery is answered separately or all retrieved triplets are merged before the final answer.

GRAPH_SUMMARY_COMPLETION

Parameter	Type	Default	Explanation
summarize_prompt_path	str	"summarize_search_results.txt"	Prompt file used to summarize graph context before completion.

GRAPH_COMPLETION_COT

Parameter	Type	Default	Explanation
max_iter	int	4	Number of follow-up reasoning rounds after the initial retrieval.
response_model	type	str	Output type or Pydantic model for the completion response.
validation_system_prompt_path	str	"cot_validation_system_prompt.txt"	System prompt used to validate the current answer.
validation_user_prompt_path	str	"cot_validation_user_prompt.txt"	User prompt used to validate the current answer.
followup_system_prompt_path	str	"cot_followup_system_prompt.txt"	System prompt used to generate follow-up questions.
followup_user_prompt_path	str	"cot_followup_user_prompt.txt"	User prompt used to generate follow-up questions.

GRAPH_COMPLETION_CONTEXT_EXTENSION

Parameter	Type	Default	Explanation
context_extension_rounds	int	4	Max rounds for extending context by using the previous output as the next query.
response_model	type	str	Output type or Pydantic model for the completion response.

TEMPORAL

Hybrid retrieval reranked by the Timestamp nodes the default pipeline extracts; works on every built-in graph store (a community adapter needs get_graph_data and get_neighborhood). See Temporal Knowledge Graph.

Parameter	Type	Default	Explanation
response_model	type	str	Output type or Pydantic model for the completion response.
candidate_top_k	int | None	None (4 × top_k)	Size of the hybrid candidate set that is reranked by time before the cut to top_k. Must be at least top_k.
max_edges_per_entity	int	10	Max connected edges listed per entity.
use_importance_weight	bool	True	Applies importance weighting when ranking hybrid context.
use_truth_weight	bool	False	Applies truth weighting when ranking hybrid context.
include_external_metadata	bool	False	Surfaces the source document’s external_metadata on retrieved passages.
external_metadata_keys	list[str] | None	None	Allowlist of external_metadata keys to surface when include_external_metadata is True.

CYPHER

Requires a Cypher-capable graph backend (Kuzu or Neo4j); on a backend that cannot run Cypher, such as the Postgres graph demo backend, the search raises SearchTypeNotSupported.

CYPHER opts out of the session-turn preparation step, so query_text is executed exactly as written, with no pre-retrieval LLM call, even under the default CACHING=true / AUTO_FEEDBACK=true. (Before v1.6.3 the turn analysis could rewrite the statement into prose that failed to parse, or gate the turn into an acknowledgement instead of rows.) See Sessions and Caching.

Parameter	Type	Default	Explanation
user_prompt_path	str	"context_for_question.txt"	Prompt file used to format Cypher results.
system_prompt_path	str	"answer_simple_question.txt"	System prompt file used for result formatting.

NATURAL_LANGUAGE

Generates and executes Cypher, so it requires a Cypher-capable graph backend (Kuzu or Neo4j); on a backend that cannot run Cypher, such as the Postgres graph demo backend, the search raises SearchTypeNotSupported.

Like CYPHER, it opts out of the session-turn preparation step, so the question is not rewritten or gated before Cypher generation. It still makes its own LLM calls to generate the Cypher (up to max_attempts). The rows the generated query returns are the search result, the same shape CYPHER returns.

Parameter	Type	Default	Explanation
system_prompt_path	str	"natural_language_retriever_system.txt"	System prompt file used to translate natural language to Cypher.
max_attempts	int	3	Max attempts to generate and run a useful graph query.

CODING_RULES

Returns the stored rules and ignores query_text, but does not opt out of the session-turn preparation step: under the default session settings it still pays a pre-retrieval LLM call, and the analysis can gate the turn into a short acknowledgement instead of the rules. Set AUTO_FEEDBACK=false to avoid both.

Parameter	Type	Default	Explanation
node_name	list[str] | None	None	Common parameter interpreted as the coding-rules node set name.

CODE

Runs one deterministic operation over the code graph the code-graph pipeline built — no LLM, embedding, or vector call. Its arguments arrive through the dedicated code_query dict on search() and recall() rather than retriever_specific_config; passing code_query with any other search type raises InvalidCodeSearchConfig. top_k and the prompt parameters have no effect, query_text is read only as a seed or name filter when the dict carries no other filter, and batched queries are not supported. Searching several datasets at once treats a seed that one dataset cannot resolve as an empty result for that dataset rather than a failed call, with the reason on that entry’s error key.

operation selects exactly one graph operation; anything else in the dict is that operation’s arguments. Omitting operation runs explore. An unknown name raises CodeSearchValidationError. max_depth, max_nodes and limit are clamped to the maximum shown, and a non-positive value falls back to the default.

Operation	What it returns	Arguments
query_facts	Facts matching the filters, plus total, offset, limit, has_more	kind / kinds, name (substring) or names (exact), file / files / file_prefix, repo, relation_types, property (alias prop) with property_value (alias prop_value), offset, limit (default 100, max 500)
explore	One fact’s focus plus the nodes, edges and stats around it	name (or focus, or the query text) or id, repo, direction (default both), node_types, relation_types, max_depth (default 1, max 2), max_nodes (default 100, max 500)
traverse	Nodes, edges and stats reached from one or more seeds in one direction	node_ids / id / start_id(s), names / name / start(s), repo, direction (default forward), node_types, relation_types, max_depth (default 5, max 20), max_nodes (default 100, max 500), type_rollup
find_path	found, the shortest forward path, and the edges along it	source / from or source_id / from_id, target / to or target_id / to_id, source_repo, target_repo, relation_types, max_depth (default 10, max 20), target_rollup
impact_analysis	Dependents grouped by_depth, with total_dependents, cross_repo_impact and a summary	target(s) / name(s) / id / node_ids, repo, node_types, relation_types, max_depth (default 3, max 10), max_nodes (default 200, max 500), include_dependencies
insights	Explainer findings, each with the evidence facts it cites, plus by_source counts	source / sources, min_confidence (0–1), informational, repo, name (title substring), offset, limit (default 50, max 500)
architecture	Module-level nodes and counted, rolled-up edges, with stats	node_types (default module, route, storage, service), repo, relation_types, max_nodes (default 80, max 300)
delta	Per repository, the last ingestion’s delta record and the snapshot receipt	repo

diagram works on every operation ("mermaid", "dot", or true for Mermaid); architecture sets it to Mermaid by itself. Seeds resolve by exact name first, then by short name and substring — an ambiguous name raises, so pass an id or narrow with repo. The rollup flags (type_rollup on a reverse traverse, target_rollup on find_path, both on by default) widen a type seed to its methods and constructor, so a dependent that only calls a method still counts; set them to false for the literal node. impact_analysis always rolls up its targets and has no flag.

Fact kinds. Every extracted fact carries a kind. query_facts filters on it with kind (one) or kinds (several); explore, traverse, impact_analysis and architecture restrict the nodes they return with node_types. Both fields accept either the kind below or the node type it maps to ("symbol" and "CodeSymbol" are the same filter). find_path and delta take neither, and insights always returns insight facts.

Kind	Node type	What it is
module	CodeModule	A module or package.
symbol	CodeSymbol	A declared symbol; which one is on symbol_kind (function, method, getter, struct, interface, type, class, variable, constant, enum, and descriptive values newer extractors add).
route	ApiEndpoint	An API route the code exposes.
storage	StorageResource	A storage resource such as a table or a bucket.
service	CodeService	A deployable service.
dependency	ExternalDependency	An external dependency; the packages declared in the repository’s manifests carry type: package.
insight	CodeInsight	A finding from one of enola’s explainers (cycles, layers, hotspots, god-class, dependency-depth, exported-surface, complexity-outliers, …), linked to the facts it cites by evidences edges.
intent	CodeIntent	Architecture declared in enola-intent.yaml rather than measured from the source.
association	CodeAssociation	A framework model relationship such as Rails has_many / belongs_to.
lint	CodeLintFinding	A finding an external linter reported through enola’s provider seam.
extraction	CodeExtractionAccount	One extractor’s coverage account for a repository (<extractor>:<account>, e.g. ruby:calls), so a thin graph can be told apart from a thin extraction.
test_ref	CodeTestReference	A test-to-symbol reference.
file_ref	CodeFileReference	A file-level reference.

Which kinds a repository actually produces depends on its languages and on what enola’s extractors found, so a filter on a kind the snapshot has none of returns an empty page rather than an error. Repositories themselves (CodeRepository) are deliberately not facts — they appear only in delta.

HTTP call relations. Two relation names connect an HTTP call to the code on either side of it, and both are valid relation_types values wherever that argument is accepted:

Relation	Connects	Notes
makes_request	The symbol that makes a call → the route node for that call	Built from the calling route’s caller / caller_id properties, so it is present with ordinary per-repository ingestion.
reaches_route	A call’s route node → the server route it reaches	Only written when the calling and serving repositories were ingested in one snapshot (see Query across repositories). Carries the confidence enola recorded for the match: verified for an exact path match, probable when a server path parameter absorbed a literal segment. A call its own repository serves under the same path shares that route’s node, so no edge is written.

Both resolve their target by fact id first, then by name inside the repository the reference names. A reference that resolves to neither is skipped and included in the skipped N count the run logs. With handled_by (route → handler), unchanged, these let impact_analysis cross a client→server call: a handler’s dependents chain back through handled_by → reaches_route → makes_request to the calling symbol in the other repository, and that repository then appears in cross_repo_impact. The chain is three hops, the default max_depth, so a lower max_depth stops before the caller.

AGENTIC_COMPLETION

Requires the resolved scope to contain exactly one dataset.

Parameter	Type	Default	Explanation
skills	list[str | Skill] | None	None	Skill names or Skill objects to load into the agentic retriever.
tools	list[str] | None	None	Optional whitelist of tool names available to the agent.
max_iter	int	6	Max tool-call iterations before forcing a final answer.
agentic_system_prompt_path	str	"agentic_system.txt"	System prompt file used inside the agent loop.
agentic_user_prompt_path	str	"agentic_user.txt"	User prompt file used inside the agent loop.
response_model	type	str	Output type or Pydantic model for the final response.

GRAPH_REPORT

Ignores query_text — the report always covers the whole graph — and opts out of the session-turn preparation step, since there is no query to analyse.

Parameter	Type	Default	Explanation
top_k	int	15	Common parameter passed through as the retriever’s top_n: how many hub nodes and cross-set connections to surface.

For the file-writing equivalent with its own top_n argument, see cognee.report().

SKILLS

Deterministic and non-generative — it makes no LLM call and opts out of the session-turn preparation step. Scoped to exactly one dataset: pass a single entry in datasets/dataset_ids, or the call raises CogneeValidationError (InvalidSkillsDatasetScope).

Parameter	Type	Default	Explanation
top_k	int	15	Common parameter: how many in-scope skills to return.

Only skills that are active and whose dataset_scope contains the requested dataset are returned; a skill with an empty dataset_scope never matches. Each result carries the skill’s metadata — id, name, description, maintainer, maintainer_url, version, tags, license, declared_tools, dataset_scope, is_active, source_repo_url, source_dir — and the raw vector score, a backend distance where lower is better. The procedure body is deliberately withheld to preserve progressive disclosure; load it with the load_skill tool or GET /api/v1/skills/{skill_id}.

When no skills have been ingested yet the collection does not exist, and the search returns an empty result rather than raising NoDataError — unlike SUMMARIES.

BROAD

Takes no top_k: it reads every chunk and dlt row of the dataset being searched (up to store_mb), and rebuilds a temporary SQLite record store for each question.

Parameter	Type	Default	Explanation
context_tokens	int	30000	Largest dataset, in tokens, that is shown to the LLM whole. Above it, the LLM sees only the record store’s schema.
reading_tokens	int	12000	Size of the prompt the reading route fills with the chunks most similar to the question.
batch_mb	float	256	Megabytes of text held in memory at once while the store is built. A single document larger than this raises BroadLimitError, which names the setting to raise.
store_mb	float	32	A dataset up to this size is loaded into the store whole, so counts are exact. A larger one is represented only by its chunks most similar to the question, up to this size; counts then cover only that part, and the answer says what was covered.
response_model	type	str	Output type or Pydantic model for the final response. Only applies when the answer model runs (after a query or reading); an answer given directly from the whole dataset stays a string, and a non-str response gets no note appended.

context_tokens, reading_tokens, batch_mb and store_mb must be positive, or the retriever raises ValueError.

results = await cognee.search(
    "How many orders shipped to Germany in 2024?",
    query_type=SearchType.BROAD,
    datasets=["orders"],
    retriever_specific_config={"store_mb": 64, "reading_tokens": 20000},
)

Answer format. After the answer comes a note saying how it was reached: (Answered from the whole dataset.), (Computed by a SQL query over the whole dataset: <sql>), or (Answered from the N parts of the dataset most similar to the question; …). When a SQL result has more than one row, the full result table is appended too.

Limits. The model-written query is limited to one read-only SELECT (an SQLite authorizer denies anything else), 1,000 result rows, and 120 seconds. Only the first 200 rows are shown to the answer model. A failing query is sent back to the model once, with the error. BROAD returns no include_references evidence. When the dataset is larger than context_tokens and the question needs the text read, a dataset without chunk embeddings raises BroadLimitError naming context_tokens as the setting to raise.

only_context=True returns the user prompt built over the query result or the parts read, but it is not free: the decision call (and a retry, if the query fails) and the query itself run during retrieval. When the decision answers directly from the whole dataset, the prompt is built around that answer.

FEELING_LUCKY

Parameter	Type	Default	Explanation
—	—	—	No direct retriever_specific_config keys. It selects another search type and inherits that type’s parameters.

# Example: tune the chain-of-thought depth and request typed output
await cognee.recall(
    query_text="How did the incident propagate across services?",
    query_type=SearchType.GRAPH_COMPLETION_COT,
    retriever_specific_config={"max_iter": 2},
)

See Search Basics — Advanced Parameters for retriever_specific_config usage and Retrievers for per-retriever behavior.