> ## 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.

# Rust SDK Search

> search in cognee-rust: the 17 retrieval strategies, result shapes, triplet ranking and structured answers.

## What is the search operation

`search` runs one retrieval strategy (a `SearchType`) over the stored memory. [recall](https://docs.cognee.ai/rust/core-concepts/main-operations/recall.md) picks the strategy for you and adds session sources. Call `search` directly when you want a specific strategy and its options.

## Search types

Unified orchestration across 17 retrieval strategies selected by `SearchType`
([`crates/search/src/types/search_type.rs`](https://github.com/topoteretes/cognee-rs/blob/main/crates/search/src/types/search_type.rs)):
`GraphCompletion`, `GraphCompletionCot`, `GraphCompletionContextExtension`,
`GraphCompletionDecomposition`, `GraphSummaryCompletion`, `GraphReport`,
`RagCompletion`, `Chunks`,
`Summaries`, `Temporal`, `Cypher`, `NaturalLanguage`, `FeelingLucky`, `Feedback`,
`CodingRules`, `ChunksLexical`, `HybridCompletion` (default; combines vector search over
chunks/summaries/entities/edge-facts and 1-hop graph-neighborhood expansion
around matched entities, then answers via LLM completion; tuning knobs in
[Configuration: hybrid retriever knobs](https://docs.cognee.ai/rust/configuration/search.md#hybrid-retriever-knobs)).
`TRIPLET_COMPLETION` and its `TripletRetriever` were removed with no alias:
`"TRIPLET_COMPLETION"` is now an unknown search type in serde, the bindings
(validation error) and the CLI; use `GRAPH_COMPLETION` or `HYBRID_COMPLETION`
instead. A database that still holds a `Triplet_text` collection keeps serving
every other type.
A hybrid search falls back to `GraphCompletion` (with a warning) when it sets
`node_type` (other than `NodeSet`), `neighborhood_depth` or a positive
`feedback_influence` (an unset one takes `DEFAULT_FEEDBACK_INFLUENCE`, so a
positive default falls back too), or when neither the `DocumentChunk_text` nor the
`DltRow_text` collection exists (checked only on a non-empty graph);
setting `wide_search_top_k` or `triplet_distance_penalty` with hybrid is an
error. The CLI's `-t/--query-type` exposes only a subset — see
[CLI Reference](https://docs.cognee.ai/rust/tools/cli.md#lower-level-pipeline). Entry: [`cognee-search`](https://github.com/topoteretes/cognee-rs/blob/main/crates/search/)
(`SearchBuilder` / `SearchOrchestrator`).

## Result shapes

Two results changed shape, a breaking change. With `only_context`, the
completion types return the prompt the completion would have sent — the user
prompt as the `Text` result, with `user_prompt` / `system_prompt` on the
response (and `prompts`, one per dataset, for a multi-dataset search that does
not combine context) — while other types still return their bare context
(`GraphReport` returns the bare report text).
`GraphCompletion` and `GraphSummaryCompletion` over an empty graph, and
`ChunksLexical` with no chunks, now fail with `SearchError::NotFound`. The
bindings also forward `node_name_filter_operator` (`nodeNameFilterOperator` in
TypeScript and Java) to combine `node_name` filters with `"OR"` (default) or
`"AND"`.

## Triplet ranking

The graph retrievers (`GraphCompletion` and its CoT, context-extension and
summary variants) rank triplets around the vector-search hits. A triplet's
score sums its source node's, target node's and edge's cosine
distances, each scaled by `2 - importance_weight` (0.5 when absent) and, with
`feedback_influence > 0`, blended with its `feedback_weight` (higher feedback
ranks better). An element with no vector match takes `triplet_distance_penalty`
(6.5) before that scaling — 9.75 at the default weight — and is not blended.
`importance_weight` is not clamped: above about 1.69 the scaled
penalty is blended like a real match, and above 2 it turns negative and ranks
first. Both are breaking changes to the ranking.

## Neighborhood projection

By default the graph retrievers rank only the edges touching a hit.
`neighborhood_depth` (a positive integer; the CLI's `--neighborhood-depth`, the
bindings' `neighborhoodDepth` search and recall option, `neighborhood_depth` in
the Python binding) switches to neighborhood projection: load the `depth`-hop
neighborhood of the nearest `neighborhood_seed_top_k` hits
(`--neighborhood-seed-top-k` / `neighborhoodSeedTopK`; all of them when unset),
score the nodes the expansion found against the query (`VectorDB::score_by_ids`;
an adapter without it leaves them at the distance penalty), and rank every
loaded edge. Larger depths load more of the graph. Combined with `node_name`,
which disables the seed search, it returns no triplets. The graph
retrievers used to ignore `neighborhood_depth`, so a request that sets it now
ranks differently, and a non-positive `neighborhood_depth` or
`neighborhood_seed_top_k` is rejected for every search type.

## References

`include_references` (`SearchRequest::include_references`; the bindings'
`includeReferences` search and recall option; default off, and anything but a
JSON `true` is off) turns on references: RAG and the graph
completion family then attach structured `evidence` references to each result
(the chunks, graph nodes and edges placed in the completion's context, in rank
order), and RAG text answers gain an `Evidence:` block; a recall puts them in
each result's `metadata.evidence`. Graph edges are cited through the
[edge-evidence ledger](https://docs.cognee.ai/rust/configuration/cognify.md#edge-evidence). Off leaves
the answer unchanged. The CLI has no flag for it. A binding's recall result
also carries `normalizedResults`: one entry (kind, text, score, metadata, …)
per graph item, in order.

## Structured answers

`response_schema` (`SearchRequest::response_schema`, and now
`RecallOptions::response_schema` for `recall()`) is a JSON Schema
the completion retrievers (RAG, hybrid and the graph completion family) shape
their answer to, returned as `SearchOutput::Structured`. Only a structural
subset is supported (a root `type: "object"`
with non-empty `properties`; primitives, arrays, enums, unions via `anyOf` or
a `type` list, and `$defs` references; at most 10 levels deep and 200
properties in total). A schema outside it is refused before anything is
searched, with `SearchError::InvalidResponseSchema` and a
`response_schema: <reason>` message, where it used to reach the LLM as-is.
This is a breaking change, as are the new `SearchError` variant (exhaustive
matches need an arm) and the new `RecallOptions` field (struct literals need
`..Default::default()`).
The answer is conformed to the schema: absent optional fields
become `null` (a schema `default` is not applied) and undeclared
keys are dropped. An answer that does not match is re-asked inside the
structured-output retry budget; if it still does not match, the search fails
with `SearchError::LlmError`. Checking is strict: a string is never coerced
to a number or a boolean. A recall with a schema returns the answer itself as its one graph
item (score 1.0). Neither the CLI nor the bindings expose `response_schema`,
so set it from the Rust API; a binding's `normalizedResults` therefore never
holds the `STRUCTURED` entry (answer in `structured`, no score) that
`cognee_search::build_structured_entry` builds for such an answer.

## Batch triplet search

`brute_force_triplet_search_batch` (in `cognee_search::graph_retrieval`) is
a batch mode: several queries share one graph load and
come back as one ranked list each. It searches every vector
collection without a limit and loads the whole graph (or the NodeSet subgraph),
so it costs far more than a single search on a large store —
`search.triplet_neighbor_cap` does not bound it, `wide_search_top_k` and
`node_name` (in the vector search) do not apply, and with `neighborhood_depth`
set it returns no triplets. It skips `Triplet_text`, whose ids are
never graph nodes. It runs batch mode even for one query; call
`brute_force_triplet_search` for a single query.

## Decomposition

`GraphCompletionDecomposition` (`GraphCompletionDecompositionRetriever`) is the batch search's main caller. One structured LLM
call splits the question into at most five sub-questions (falling back to the
question itself when the call fails), one batch search fetches their triplets, and
the batches are merged without duplicates. With
`retriever_specific_config.decomposition_mode` `"answer_per_subquery"` (the
default) each sub-question is answered over its own triplets, concurrently, and
the question is answered over those answers; `"combined_triplets_context"` answers
once over the merged triplets. Each context item carries a `decomposition` entry
(the sub-questions and the triplet's rank in each) so the completion can rebuild
the per-sub-question contexts. An empty graph is `NotFound`, and a batch of
queries is rejected.

## Graph report

`GraphReport` (`GraphReportRetriever`) ignores the query and reports on the whole graph from `get_graph_data`: the
top-`top_k` hubs (default 10) by normalised degree plus normalised PageRank
(networkx's defaults, computed here), entity-to-entity edges across different node
sets, and EXTRACTED vs DERIVED edge counts, followed by LLM-suggested questions.
`NodeSet` containers and `belongs_to_set` edges are left out and parallel edges
count once. Its context is one item holding the Markdown report and the
structured hubs, connections and counts. An empty graph gets a fixed report,
not `NotFound`. PageRank is always computed, falling back to degree alone only
if it does not converge.

## Temporal

`Temporal` is `HybridCompletion` reranked by the time window the question asks
about (`TemporalHybridRetriever`; it
replaces the Event-based `TemporalRetriever`, a breaking change). The hybrid
candidate fetch — chunks and entities at `candidate_top_k`, default `4 × top_k`,
settable as `retriever_specific_config.candidate_top_k` — runs concurrently with
an LLM call that extracts the window (UTC, start inclusive, end exclusive;
relative dates are not resolved, so no clock is read). The chunks attached to the
`Timestamp` nodes inside the window join the candidates, the candidates attached
to one — directly, or for a chunk through an entity it `contains` — move to the
front, tightest date first (for "18 March 1965" a chunk dated that day beats one
that only says "1965"; dates at least as precise as the question keep their
similarity order), and the same cut plain hybrid uses keeps `top_k`. With nothing
to rerank by it answers with the plain hybrid result and records why:
`empty_graph`, `no_time_constraint` / `invalid_interval` (no window),
`no_temporal_match`, `no_candidate_overlap` (`TemporalHybridRetriever::retrieve`
returns these diagnostics with the context). An LLM or transport failure while
extracting the window fails the search instead of falling back, an empty graph
returns an empty context rather than `NotFound`, batch queries are rejected, and
`search.triplet_neighbor_cap` no longer applies to `Temporal` (`search.hybrid`
does). The `Timestamp` nodes are default cognify's. A graph an older build
wrote with the removed event-graph [temporal cognify](https://docs.cognee.ai/rust/guides/temporal-cognify.md)
pipeline holds `Event` nodes nothing reads, so it gets plain hybrid answers. Under an attached
`AclDb`, `Temporal` results are no longer filtered by dataset membership: with
[per-dataset storage](https://docs.cognee.ai/rust/configuration/datasets-and-access.md#per-dataset-storage) it runs in each
dataset's own databases, and over the shared store it runs unscoped like every
other type.

## Related

> [card] [Recall](https://docs.cognee.ai/rust/core-concepts/main-operations/recall.md)
>
> Auto-routed search

> [card] [Search configuration](https://docs.cognee.ai/rust/configuration/search.md)
>
> Retriever settings

> [card] [Cognify](https://docs.cognee.ai/rust/core-concepts/main-operations/legacy-operations/cognify.md)
>
> What builds the graph


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.