Skip to main content
Version: 0.0.4

agrag.retrieval.identity.resolve_entity

resolve_entity(graph_store:GraphStore, entity_id:UUID, *, tracer:Tracer | None = None) -> Entity

Return the live Entity behind an id, following merged_into.

Every retrieval path that can produce an entity id must call this before wrapping the id in a SearchResult. This is the single place the merged_into invariant is enforced.

A merge writes a merged_into property on the tombstone rather than a relationship, so the chain is walked one hop per query.

Parameters:

  • graph_store (GraphStore) – Where the entity and its possible tombstone chain live.
  • entity_id (UUID) – The id a retrieval method found, which may or may not still be live.
  • tracer (Tracer | None) – Opens the resolution span. None opens no recorded span.

Returns:

  • Entity – The live Entity, after resolving zero or more hops.

Raises:

  • ValueError – The id does not exist, its node cannot be parsed, the chain points at a missing node, the chain cycles, or it is longer than MAX_MERGE_HOPS.