For AI agents: this page is also available as Markdown at /docs/graph.md. Every docs page is: add .md to its URL. llms.txt lists them all.

Graph search

Graph search queries a knowledge graph stored in an ordinary collection. Most graph retrieval is a few hops from a handful of seed entities: find the entities a question is about, walk to their neighbors, score what you reached by how close it is to the seeds, and fetch the passages that mention them. WarpSearch does this inside one collection, in one request, against one consistent snapshot, with the same filters, facets and vector search as any other search.

#Modeling a graph

A graph lives in an ordinary collection. A node is a document, identified by its id. Edges come in two forms, and you can use both in one collection and mix them in one request.

#Adjacency fields

The simplest edge is a multi-valued string field on the node that holds neighbor ids:

{"id": "svc-pay", "kind_s": "entity", "type_s": "service", "name_t": "Payments Service",
 "aliases_ss": ["payments", "pay-svc"], "related_ss": ["team-core", "svc-ledger"],
 "ancestors_ss": ["org", "eng", "platform"], "pagerank_f": 0.9, "acl_ss": ["eng"],
 "embedding_v": [0.12, 0.98, 0.04]}
{"id": "ch1", "kind_s": "chunk", "text_t": "payments outage postmortem",
 "mentions_ss": ["svc-pay", "team-core"], "acl_ss": ["eng"]}

• Following an edge outward reads the node's field: svc-pay points at team-core.
• Following it inward finds the documents whose field holds a node's id: team-core is pointed at by svc-pay. This uses the field's index, so reverse edges need not be stored.
• Keyword string fields (_s, _ss) work both ways. A field must be indexed to follow it inward and have a column to follow it outward; the default string fields have both.

#Edge documents

When an edge needs a type, a weight, a validity window or provenance, store one document per edge:

{"id": "e1", "kind_s": "edge", "src_s": "alice", "dst_s": "svc-pay", "type_s": "WORKS_ON",
 "weight_f": 0.9, "source_chunk_s": "ch7", "valid_from_dt": "2024-01-01", "valid_to_dt": "2030-01-01"}

src_s and dst_s hold node ids (rename them per request), the weight is any numeric field, and any other field can be filtered on or returned as evidence. Edge and node documents can share the collection, told apart by a field such as kind_s.

#Which to use

Two more modeling patterns need no graph feature at all:

• Hierarchies: store the ancestor path (ancestors_ss: ["org", "eng", "platform"]). Descendants of X are a filter on ancestors_ss, and a facet on it rolls counts up the tree.
• Importance priors: store a score such as PageRank (pagerank_f) and multiply it in at query time with a rescore expression.

#lookup: one hop as a query

lookup selects the documents whose field holds any value of from_field across the documents matching from. It is a query in the native warpsearch language, usable in query or filters, combined with AND, or nested inside another lookup. Native expressions run unsigned on dedicated collections without row filters or field restrictions; on restricted collections, replay a signed translation (see Query languages).

{"language": "warpsearch",
 "query": "lookup(id, from=id:=$seed, from_field=related_ss)",
 "vars": {"seed": "svc-pay"}}

Both fields are string-valued (keyword and id fields) or both integer-valued (integer and date fields). The values come from the same snapshot as the rest of the search, and the inner query sees every live document, not the request's other filters. A repeated lookup, such as the same user's ACL filter on every search, is cached as one entry however many values it resolves.

#Graph expand

POST /v1/collections/{collection}/graph/expand starts from seed documents, follows up to 3 hops, scores every node it reaches and returns them best first:

curl -s https://api.warpsearch.io/v1/collections/kg/graph/expand \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seeds": {"query": "name_t:\"payments outage\"", "limit": 20},
    "hops": [
      {"field": "related_ss", "direction": "out", "decay": 0.5,
       "max_per_node": 25, "max_frontier": 500, "filter": "type_s:(service OR team)"},
      {"field": "mentions_ss", "direction": "in", "filter": "kind_s:chunk"}
    ],
    "propagate": "sum",
    "limit": 50,
    "fields": ["id", "name_t", "type_s"],
    "facets": {"types": {"field": "type_s"}}
  }'

{"took_ms": 6, "collection": "kg", "total": 31,
 "hits": [
   {"id": "svc-pay", "score": 7.2, "hop": 0, "fields": {"name_t": "Payments Service", "type_s": "service"}},
   {"id": "team-core", "score": 3.6, "hop": 1, "via": "svc-pay", "fields": {"name_t": "Core Team", "type_s": "team"}},
   {"id": "ch1", "score": 2.1, "hop": 2, "via": "team-core", "fields": {}}
 ],
 "facets": {"types": {"buckets": [{"val": "service", "count": 9}, {"val": "team", "count": 4}]}}}

#How it works

1. seeds is a search, or a list of node ids. Its matches start the walk, and their search scores are their starting scores (ids start at 1, or at the group's weight). Use any query, including a kNN search over entity names ("language": "es" with an ES knn body), or several weighted groups combined into one ranked list.
2. Each hop expands the nodes the previous hop reached for the first time. A node is reached once, at its first hop, and is never revisited, so the walk cannot loop.
3. A node's score is the sum (or, with "propagate": "max", the best) over the nodes that reached it of their score x decay x edge weight. Adjacency edges weigh 1. With the default sum, a node many seeds point at outranks one reached once.
4. Every hop can cap its work: how many edges each node may follow, how many new nodes survive the hop, and which hubs are too connected to expand.
5. The reached nodes come back best first, seeds included unless you exclude them, each with how many hops away it is and which node reached it. total counts every node reached, and facets and search run over all of them, not just the returned page. min_hop hides the nodes nearer than that (from hits, total, facets and search) while they still take part in the walk and the scores; include_seeds: false is min_hop: 1 for the seeds alone.

#Request

A hop over an adjacency field:

A hop over edge documents replaces field with edges:

{"edges": {"src": "src_s", "dst": "dst_s", "weight": "weight_f",
           "filter": ["type_s:WORKS_ON", "valid_from_dt:<=2025-06-01", "valid_to_dt:>=2025-06-01"],
           "fields": ["source_chunk_s", "type_s"]},
 "direction": "out", "max_per_node": 20, "decay": 0.5}

#Results

Each hit has the usual id, score and fields, and:

Following via back to a seed shows why a node was returned, and edge cites where the link came from, for example the passage it was extracted from.

The response also carries timed_out (true when timeout_ms cut the walk short) and, with "rank": "ppr", ppr: {"ran_iterations", "converged"}.

#The whole subgraph

"subgraph": true adds edges to the response: every edge the walk traversed, in traversal order, each physical edge once even when both ends reached it. An edge is {"from", "to", "via", "weight", "hop"} plus, for an edge document, its id and the requested evidence fields; from and to are in the stored direction (the node holding the adjacency value to the value, or src to dst), via is the adjacency field or edges, and hop is the hop that traversed it. Edges to nodes hidden by include_seeds or min_hop are included; edges to nodes dropped by max_frontier are not. max_edges bounds the list.

#A size budget

limit keeps the best nodes, which need not connect to each other or to the seeds. budget keeps a connected subgraph instead, before ranking and before anything is returned: starting from the seeds, it repeatedly adds the best-scored node adjacent to the kept set (attached by its heaviest edge) while at most nodes nodes and edges edges are kept and the node scores more than edge_cost (default 0); any edge budget left over takes the heaviest remaining edges among the kept nodes. The choice is greedy, not optimal, and with several seeds the result is a forest whose trees join where the neighborhoods meet. The hits, total, facets, search and the subgraph edges all cover the kept subgraph only; via and edge name the edge that attached each node. Seeds count toward nodes even when hidden.

#Personalized PageRank

With "rank": "ppr", WarpSearch first collects the subgraph the hops reach, then ranks it by personalized PageRank: a random walk that follows edges (weighted by edge weight) and restarts at the seeds in proportion to their scores. Scores sum to 1 over the reached nodes. PPR favors nodes that are well connected to several seeds over nodes that are merely close to one; HippoRAG uses it for multi-hop question answering. hop and via are reported as before, and ppr in the response reports the iterations run and whether the last one moved less than tolerance.

ppr.reset_field names a numeric field whose value multiplies each seed's restart weight (HippoRAG's node specificity: a phrase node weighted by the inverse of the number of passages it occurs in). A seed without a value keeps its weight, a negative value counts as 0, and when every weight is 0 the restart is uniform over the seeds.

#Recipe: GraphRAG passage retrieval

Find the entities a question names, walk to related entities and to the passages that mention them, and rank the passages:

{"seeds": {"query": "aliases_ss:(ledger OR payments)", "limit": 10},
 "hops": [{"field": "related_ss", "direction": "both", "max_degree": 1000},
          {"field": "mentions_ss", "direction": "in", "filter": "kind_s:chunk"}],
 "rank": "ppr",
 "include_seeds": false,
 "filters": ["acl_ss:(eng OR all-staff)"],
 "fields": ["id", "text_t"],
 "limit": 20}

Feed the returned passages, with their via chains as context, to your model.

#Recipe: weighted seed groups

HippoRAG 2 seeds the walk with the entities an LLM confirmed, plus the passages a vector search found at a small weight. Both are one seeds array; ids need no query escaping:

{"seeds": [{"ids": ["ent:ledger", "ent:payments"]},
           {"language": "es", "query": {"knn": {"field": "embedding_v", "query_vector": [0.1, 0.9, 0.0], "k": 5}},
            "filters": [{"term": {"kind_s": "chunk"}}], "weight": 0.05}],
 "hops": [{"field": "related_ss", "direction": "both"},
          {"field": "mentions_ss", "direction": "in", "filter": "kind_s:chunk"}],
 "rank": "ppr", "include_seeds": false, "limit": 20}

The same form continues a walk from the ids a previous call returned, after your model picked the ones worth following.

#Recipe: vector search inside a neighborhood

Restrict a kNN search to the graph around the seeds. The restriction applies inside the vector search, so recall holds:

{"seeds": {"ids": ["svc-pay"]},
 "hops": [{"field": "related_ss", "direction": "both"}],
 "limit": 0,
 "search": {"language": "es",
            "query": {"knn": {"field": "embedding_v", "query_vector": [0.1, 0.9, 0.0], "k": 5}},
            "fields": ["id", "name_t"]}}

For one hop, the same works on /v1/search with a lookup filter.

#Recipe: the subgraph for visualization or triple lists

A client that draws the neighborhood, or a retriever that feeds an LLM a list of triples (SubgraphRAG and G-Retriever style), needs the edges, not only the nodes. subgraph returns every traversed edge, with edge-document evidence, beside the hits:

{"seeds": {"ids": ["svc-pay"]},
 "hops": [{"field": "related_ss", "direction": "both"},
          {"edges": {"weight": "weight_f", "filter": "kind_s:edge", "fields": ["type_s"]}, "direction": "both"}],
 "subgraph": true, "max_edges": 2000,
 "fields": ["id", "name_t"], "limit": -1}

Each edges entry has from, to, via, weight and hop, plus id and type_s for the edge documents, so (from, type_s, to) is a triple and the hits supply the node labels.

#Recipe: token-bounded context with budget

For a prompt that can hold about thirty nodes, ask for the best connected thirty rather than the best thirty: budget grows a subgraph from the seeds by score and stops at the caps, so every returned node links back to a seed through returned nodes.

{"seeds": {"query": "aliases_ss:(ledger OR payments)", "limit": 5},
 "hops": [{"field": "related_ss", "direction": "both"},
          {"field": "mentions_ss", "direction": "in", "filter": "kind_s:chunk"}],
 "rank": "ppr",
 "budget": {"nodes": 30, "edges": 40},
 "subgraph": true, "fields": ["id", "name_t", "text_t"], "limit": -1}

The choice is greedy; with several seeds whose neighborhoods do not meet, the result is a forest.

#Recipe: HippoRAG node specificity with reset_field

HippoRAG weights each seed phrase by its specificity (the inverse of how many passages mention it), so a rare entity pulls the walk more than a common one. Store it on the node and name it in ppr.reset_field; the field goes through the same alias and allow-list resolution as any other.

{"seeds": {"query": "aliases_ss:(ledger OR payments)", "limit": 10},
 "hops": [{"field": "related_ss", "direction": "both"},
          {"field": "mentions_ss", "direction": "in", "filter": "kind_s:chunk"}],
 "rank": "ppr", "ppr": {"alpha": 0.5, "reset_field": "specificity_f"},
 "min_hop": 2, "fields": ["id", "text_t"], "limit": 20}

min_hop: 2 returns only the passages; the seeds and the related entities still shape the PageRank. The response's ppr says how many iterations ran and whether they converged.

#Graph paths

POST /v1/collections/{collection}/graph/paths finds how entities are connected:

curl -s https://api.warpsearch.io/v1/collections/kg/graph/paths \
  -H "Authorization: Bearer $WARPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "alice", "to": ["svc-pay", "svc-ledger"],
    "edges": [
      {"field": "related_ss"},
      {"edges": {"weight": "weight_f", "filter": "type_s:(WORKS_ON OR OWNS)", "fields": ["source_chunk_s"]}}
    ],
    "max_depth": 4, "k": 3,
    "fields": ["name_t"]
  }'

{"took_ms": 3, "collection": "kg",
 "paths": [
   {"nodes": ["alice", "svc-pay"], "length": 1, "cost": 1,
    "edges": [{"from": "alice", "to": "svc-pay", "via": "edges", "id": "e1", "weight": 0.9, "source_chunk_s": "ch7"}]},
   {"nodes": ["alice", "team-core", "svc-pay"], "length": 2, "cost": 2,
    "edges": [{"from": "alice", "to": "team-core", "via": "related_ss"},
              {"from": "team-core", "to": "svc-pay", "via": "related_ss"}]},
   {"nodes": ["alice", "team-core", "svc-ledger"], "length": 2, "cost": 2,
    "edges": [{"from": "alice", "to": "team-core", "via": "related_ss"},
              {"from": "team-core", "to": "svc-ledger", "via": "related_ss"}]}
 ],
 "documents": {"alice": {"name_t": "Alice"}, "team-core": {"name_t": "Core Team"},
               "svc-pay": {"name_t": "Payments Service"}, "svc-ledger": {"name_t": "Ledger Service"}},
 "truncated": false, "timed_out": false, "explored": 23}

Each path lists its nodes in order and each edge it uses: via names the adjacency field or edges, and edge documents add their id, weight and requested fields as evidence. The search explores from both ends at once and stops when they meet (for one unweighted path) or at max_depth; in mode: "all" it explores to the full depth. A node past a frontier or degree cap is still reached, so it can end or join a path, but it is not expanded. truncated: true means a work cap cut the exploration short (a frontier or node cap, more than max_paths paths in mode: "all", or its internal cap on path prefixes), so a path may exist beyond it; timed_out: true means the same for timeout_ms. explored counts the nodes explored. The path search is one engine call and fields one more; a plan allows 20 per request.

#Recipe: all paths between two entities up to length 3

To list how two entities are related rather than only the closest link, ask for every simple path in a length range. The paths come shortest first, so the first ones are the direct links and the later ones the indirect ones.

{"from": "svc-pay", "to": "team-core",
 "edges": [{"field": "related_ss"}, {"field": "mentions_ss"}],
 "mode": "all", "min_depth": 1, "max_depth": 3, "max_paths": 200,
 "fields": ["name_t"]}

truncated: true means more than max_paths paths exist; raise it (up to 10000), narrow the edge specs with a filter, or lower max_depth.

#Recipes with plain search

Many graph questions need no graph endpoint. All of these run on /v1/search:

#Access control

Graph requests follow the collection's access control like any search: row filters and field restrictions apply to every node a walk or a path may reach. A node the caller cannot see is not returned, not counted in total or facets, and not used as a step toward other nodes. For document-level permissions, store the allowed groups on each document (acl_ss) and filter with a lookup from the user's document; the filter stays small and cached however many groups the user has.

#MCP tools

Agents get three read-role tools over the same operations (see Agents). describe_collection first shows the adjacency fields.

Every tool description links this guide, so an agent that only has the tool list can find the request shapes. Clause arguments are strings in the tool's language (Lucene by default; ES clauses are JSON objects as text). For example, the people who exchanged mail with a person in the Enron demo:

{"collection": "enron", "ids": ["person:jeff.skilling@enron.com"],
 "field": "participant_ids_ss", "direction": "in", "filter": "kind:email", "limit": 20}

#Limits

Memory used by a walk counts against the request's memory budget like any search. Each engine call is metered like a search.

#Errors

#Not supported yet

• Hops across collections, and walks deeper than 3 hops (6 for paths) in one request.
• Cypher or GQL graph queries.
• Community detection and community summaries, and scheduled graph jobs such as computing PageRank priors.
• Entity and relation extraction, and entity merging.

Until then, chain graph requests from your application (the ids a request returns are the seeds of the next), and write computed priors back as fields.

View this page as Markdown