> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Graph retrieval

> Use graph-aware vector stores for questions that connect facts across documents.

Use graph retrieval to gather connected evidence for a [Response](/docs/responses). 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](/docs/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`.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  import { SDK } from '@meetkai/mka1';

  const sdk = new SDK({ bearerAuth: 'Bearer <mka1-api-key>' });

  const graphStore = await sdk.llm.vectorStores.create({
    xOnBehalfOf: '<end-user-id>',
    createVectorStoreRequest: {
      name: 'Support knowledge graph',
      description: 'Support manuals indexed for multi-hop retrieval',
      fileIds: ['file-abc123'],
      retrievalMode: 'graph',
      extractionModel: 'auto',
      maxHops: 2,
    },
  });
  ```

  ```python Python SDK theme={null}
  from meetkai_mka1 import SDK

  sdk = SDK(bearer_auth="Bearer <mka1-api-key>")

  graph_store = sdk.llm.vector_stores.create(
      name="Support knowledge graph",
      description="Support manuals indexed for multi-hop retrieval",
      file_ids=["file-abc123"],
      retrieval_mode="graph",
      extraction_model="auto",
      max_hops=2,
  )
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;
  using MeetKai.MKA1.Types.Requests;

  var sdk = new SDK(bearerAuth: "Bearer <mka1-api-key>");

  // Graph stores are created via the VectorStores.Create method's RetrievalMode,
  // ExtractionModel, and MaxHops parameters.
  // Refer to the API reference for the full method signature.
  ```

  ```bash CLI theme={null}
  mka1 llm vector-stores create --body '{
    "name": "Support knowledge graph",
    "description": "Support manuals indexed for multi-hop retrieval",
    "file_ids": ["file-abc123"],
    "retrieval_mode": "graph",
    "extraction_model": "auto",
    "max_hops": 2
  }'
  ```

  ```bash Bash theme={null}
  curl https://apigw.mka1.com/api/v1/llm/vector_stores \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --data '{
      "name": "Support knowledge graph",
      "description": "Support manuals indexed for multi-hop retrieval",
      "file_ids": [
        "file-abc123"
      ],
      "retrieval_mode": "graph",
      "extraction_model": "auto",
      "max_hops": 2
    }'
  ```
</CodeGroup>

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](/docs/vector-stores#search-the-vector-store) 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](/docs/vector-stores#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](/docs/vector-stores) as other vector stores. See the [GraphRAG benchmark](/docs/graphrag) for evaluation methodology and measured results.