Skip to main content
Use graph retrieval to gather connected evidence for a Response. Create and search the store through its resource API, then pass the retrieved context to the model. Graph retrieval is a vector-store mode, not a separate API. Start with Files and keep the uploaded file IDs.

​
Create a graph store

Set retrieval_mode to "graph" to get graph-aware retrieval instead of plain vector similarity. On a graph store, entities and relations are extracted from every chunk at ingest to build a knowledge graph, and search traverses that graph to collect connected evidence rather than returning the nearest chunks alone. The gains show up on questions that require linking facts across several documents. Two options apply only to graph stores:
  • extraction_model — the model used for entity and relation extraction. It follows the same contract as embedding_model: optional, defaults to auto, and resolved to a concrete model at creation.
  • max_hops — how far to expand through the graph on each query, from 1 to 4. The default is 2.
The response echoes retrieval_mode, extraction_model, and max_hops back, with extraction_model resolved to the concrete model rather than auto. You search a graph store with the same search call as any other vector store — the mode is a property of the store, not of the request.

​
What changes on a graph store

  • The mode is frozen at creation. There is no way to convert a store between vector and graph afterward; the update endpoint does not accept retrieval_mode. Switching means creating a new store and re-attaching the files.
  • Extraction is metered against your usage. Entities and relations are extracted from every chunk at ingest, and each query also runs an extraction pass to identify the entities to expand from. Both are billed as normal model usage, so a graph store costs more to fill and more to query than a vector store over the same files.
  • Graph search returns at most 20 results. max_num_results accepts up to 50, but graph queries clamp to 20. A higher value is truncated rather than rejected.
  • Attribute filters can under-fill. As noted under Filter search by file attributes, filtering on a graph store is partly applied after retrieval, so a filtered search can return fewer than max_num_results matches.
  • extraction_model and max_hops are graph-only. Sending either without retrieval_mode: "graph" returns 400.

​
Search and maintain the store

Use the same indexing and search workflow as other vector stores. See the GraphRAG benchmark for evaluation methodology and measured results.