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	Hybrid answer combining lexical chunks, semantic chunks, and graph/entity context.
`SearchType.TRIPLET_COMPLETION`	Vector	Semantic search over triplet embeddings, then LLM answer (needs `TRIPLET_EMBEDDING=true`).
`SearchType.GRAPH_COMPLETION`	Vector + Graph	Default. 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: extracts time constraints, then combines graph events with semantic retrieval.
`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.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.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
Session speed and overhead

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)
`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` (default)	~3.9 s	1	1	Top 15 triplets plus their nodes’ text (~7.5k chars here)
`HYBRID_COMPLETION`	~3.8 s	1	1	15 fused lexical+semantic chunks, 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
`TEMPORAL`	~40 s	3	1	Top time-filtered events (time-extraction call first; falls back to triplet context when no time constraint 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)
`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 and CODING_RULES are direct graph reads with no LLM or embedding call; 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). 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.

With the default CACHING=true and AUTO_FEEDBACK=true, every search type — including retrieval-only ones — pays one extra session-turn LLM call (~1,800 prompt tokens here; GRAPH_REPORT is the one exception — it skips the session-turn step because there is no query to analyse), 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`	~10 s	1	0	~1,800
`CYPHER` (estimated)	~10 s	1	0	~1,800
`CODING_RULES` (estimated)	~10 s	1	0	~1,800
`SUMMARIES`	~10 s	1	1	~1,800
`CHUNKS`	~10 s	1	1	~2,300
`RAG_COMPLETION`	~20 s	2	3	~3,300
`TRIPLET_COMPLETION` (estimated)	~20 s	2	3	~RAG-level + session turn
`GRAPH_COMPLETION` (default)	~20 s	2	3	~5,400
`HYBRID_COMPLETION`	~20 s	2	3	~6,600
`GRAPH_REPORT` (estimated)	scales with graph size	1	0	~600 (skips the 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. 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; CYPHER, CODING_RULES, and TRIPLET_COMPLETION pay the session-turn overhead like every other type, while GRAPH_REPORT opts out of the session-turn step entirely, so its cost is the same either way.

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 GRAPH_COMPLETION (default) for the best balance of accuracy and context. Use 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 picks a strategy from cues in your query and defaults to GRAPH_COMPLETION, so plain questions get a generated answer. Queries with exact-phrase, coding-vocabulary, or Cypher-shaped cues route to payload-returning types (CHUNKS_LEXICAL, CODING_RULES, CYPHER) — see Auto-routing behavior for the full mapping.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. 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

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

CHUNKS

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

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`	`top_k`	Max merged lexical and semantic chunks included in context.
`entities_top_k`	`int`	`top_k`	Number of matched entities used for graph context.
`max_edges_per_entity`	`int`	`10`	Max connected edges listed per entity.
`facts_top_k`	`int`	`top_k`	Max edge-derived facts included in the related facts context.
`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`	Optional limit for text summaries included by the hybrid retriever.
`use_importance_weight`	`bool`	`True`	Applies importance weighting when ranking hybrid context.

TRIPLET_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 triplets by node set.
`node_name_filter_operator`	`"OR" \| "AND"`	`"OR"`	Common parameter controlling how multiple `node_name` filters are combined.

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

Parameter	Type	Default	Explanation
`response_model`	`type`	`str`	Output type or Pydantic model for the completion response.
`user_prompt_path`	`str`	`"graph_context_for_question.txt"`	Prompt file used to format temporal graph context for the question.
`system_prompt_path`	`str`	`"answer_simple_question.txt"`	System prompt file used for the final answer.
`time_extraction_prompt_path`	`str`	`"extract_query_time.txt"`	Prompt file used to extract temporal constraints from the query.

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.

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.

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

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

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().

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.

​SearchType

​Values

​Speed, cost, and recall depth

​Choosing a Search Type

​Per-search-type parameters

SearchType

Values

Speed, cost, and recall depth

Choosing a Search Type

Per-search-type parameters