Graph search (GraphRAG)

Graph search builds a knowledge graph over one collection and answers questions keyword search cannot: "what themes run through this catalogue?", "how do these entities relate?". Three kinds of objects live in it:

• Entities — named things extracted from your documents (products, brands, materials, people…), with a type, description, aliases and the documents that mention them. Relations connect entities that co-occur.
• Claims — structured factual assertions ("covariates") extracted alongside entities, each with a status (confirmed, suspected, disputed, unverified), a subject, an object and a source document.
• Communities — groups of related entities, each with a model-written title and summary, arranged in a hierarchy of levels (level 0 finest, each higher level a coarser merge).

1. Extract entities

generateGraphEntities reads text_fields off each of document_ids (one model call per document) and upserts the named entities and relations it finds. An entity already known by the exact same name gains this document in its source_doc_ids instead of becoming a duplicate; a new name is also resolved semantically against existing entities of the same type, so "iPhone 17" and "Apple iPhone 17" can converge.

await client.graph.generateGraphEntities({
  collectionName: "products",
  body: {
    document_ids: ["sku-4821", "sku-4822", "sku-4823"],
    text_fields: ["title", "description"],
  },
});

Claims are extracted in the same pass. Read the results with listGraphEntities and listGraphClaims (both per collection); delete with deleteGraphEntity (drops the entity's relations too) and deleteGraphClaim (leaves the entity alone).

2. Group entities into communities

generateGraphCommunities clusters the collection's entities with multi-level Louvain modularity optimization and asks the model for a short title and summary per group of at least min_size entities, at every level up to max_levels (0 = finest). Existing reports for the collection are replaced. Clustering stops on its own once a pass merges nothing further.

await client.graph.generateGraphCommunities({
  collectionName: "products",
  body: { min_size: 3, max_levels: 2 },
});

listGraphCommunities shows the reports; deleteGraphCommunity removes one summary without touching the entities it grouped.

3. Ask broad questions

Global search — globalSearchGraph — answers a broad question by map-reduce over community reports: every report at level (default: the coarsest generated, for the fewest, broadest reports and the lowest cost) gets one parallel model call proposing key points with a 0–100 relevance score, capped at max_communities reports chosen by embedding similarity to the question; the best points are then reduced into the final answer.

DRIFT search — driftSearchGraph — goes one level deeper: a primer step (global search over level's reports) proposes an intermediate answer plus follow-up questions the reports cannot answer on their own, and each of the first max_follow_ups follow-ups is answered by a local search over the entities most relevant to it, before a final reduce produces the answer. Use DRIFT when a question needs both the big picture and specific details.

const answer = await client.graph.globalSearchGraph({
  collectionName: "products",
  body: { question: "What winter gear do we carry and how does it differ?" },
});

const detailed = await client.graph.driftSearchGraph({
  collectionName: "products",
  body: { question: "Which brands make down jackets under 15 000 ₽?", max_follow_ups: 3 },
});

Every model on this page can be overridden per call with the model field — extraction, summarization, map, local and reduce steps.

When to use what