Skip to main content

agrag.retrieval.methods.traversal.find_entity

find_entity(name:str, *, graph_store:GraphStore, embedder:Embedder, vector_store:VectorStore | None, settings:RetrievalSettings, entity_labels:Sequence[str], filters:SearchFilters | None = None, tracer:Tracer | None = None) -> SearchResult | None

Resolve a named entity to its top search hit, or None.

Runs one entity search and returns its best result, which callers keep whole rather than unwrapping: the item renders as evidence, and the result itself is what extract_entity_ids can turn into traversal seeds.

Parameters:

  • name (str) – The entity name (or description) to resolve.
  • graph_store (GraphStore) – Backs entity search when vector_store is absent.
  • embedder (Embedder) – Produces the query vector.
  • vector_store (VectorStore | None) – Optional vector store for hybrid search.
  • settings (RetrievalSettings) – Retrieval configuration.
  • entity_labels (Sequence[str]) – The labels native entity search runs against by default, one vector index each.
  • filters (SearchFilters | None) – Scope to resolve within. Labels, document ids, and properties are projected through, matching the projection that a plain search's own entity step applies. A filters.labels value replaces entity_labels rather than narrowing within it, so a scope carrying only unrelated fields must not be mistaken for a deliberate label override. An entity that exists only outside this scope resolves to None, the same as one that does not exist.
  • tracer (Tracer | None) – Opens the root span and flows to the entity retriever. None opens no recorded span.

Returns:

  • SearchResult | None – The top-ranked SearchResult, or None when nothing matched.