Context Graphs

A context graph records how the things in your context relate: which team owns which service, which policy governs which process, which decision replaced which. POST /query returns the relevant part of it next to the matching passages, so your model can answer “What team owns the service that failed?” when no single passage says so. HydraDB builds the graph while it indexes your context. The named things are entities. One relationship between two of them is a triplet of source, relation, and target, such as Payments team, owns, billing service. Following relationships from one entity to the next is traversal; each step is a hop, and a question that needs two or more is multi-hop. In this guide:

Get relationships with your results: the graph_context field, using a billing question as the example.
Turn the graph off: when you only need chunks.
Where the relationships come from: extraction, declared links, and your own graph.
Walk the items around one result: the Connected Subgraph endpoint.
Put graph context in your prompt.

1. Get relationships with your results

graph_context is on by default, so this is an ordinary knowledge query. It sets mode: "thinking" because thinking mode does the most graph work; in "fast" mode the graph slice is shallower.

Query with graph context: Python, TypeScript, or cURL

result = client.query(
    database="acme_corp",
    query="How does the billing system handle failed payments?",
    type="knowledge",
    query_by="hybrid",
    mode="thinking",
    graph_context=True,
)

if result.data.graph_context:
    for path in result.data.graph_context.query_paths:
        for t in path.triplets:
            print(t.source.name, t.relation.canonical_predicate, t.target.name)

const result = await client.query({
  database: "acme_corp",
  query: "How does the billing system handle failed payments?",
  type: "knowledge",
  queryBy: "hybrid",
  mode: "thinking",
  graphContext: true,
});

const data = result.data;
if (data && typeof data !== "string" && data.graphContext) {
  for (const path of data.graphContext.queryPaths) {
    for (const t of path.triplets) {
      console.log(t.source.name, t.relation.canonicalPredicate, t.target.name);
    }
  }
}

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "query": "How does the billing system handle failed payments?",
    "type": "knowledge",
    "query_by": "hybrid",
    "mode": "thinking",
    "graph_context": true
  }'

The data payload of a response with graph context looks like this (chunks trimmed):

{
  "chunks": [ /* ranked chunks */ ],
  "graph_context": {
    "query_paths": [
      {
        "triplets": [
          {
            "source": { "name": "billing_policy", "type": "POLICY" },
            "relation": { "canonical_predicate": "governs" },
            "target": { "name": "failed_payment_handling", "type": "PROCESS" }
          }
        ],
        "relevancy_score": 0.84,
        "group_id": "p_0",
        "source_chunk_ids": ["chunk_abc", "chunk_def"]
      }
    ],
    "chunk_relations": [],
    "chunk_id_to_group_ids": { "chunk_abc": ["p_0"] }
  }
}

The full schema is on the Query API reference.

What each field in `graph_context` means

Field	What it is
`query_paths`	Chains of triplets that connect your query to the retrieved chunks. Each path carries a `relevancy_score`, a `group_id`, and the `source_chunk_ids` whose traversal produced it.
`chunk_relations`	Paths that describe how the returned chunks relate to one another. Same shape as `query_paths`; the anchor is a chunk rather than the query.
`chunk_id_to_group_ids`	Maps each chunk id to the path groups (`p_0`, `p_1`) it belongs to, so you can attach the right relationships to each passage.
`source`, `relation`, `target`	The three parts of a triplet. Each is an object, not a string: an entity has a `name` and `type`, and the relation has a `canonical_predicate` plus the `context` sentence it was extracted from.

Empty arrays mean no relationships were found for that query. That is not an error; there is no structure to show.

2. Turn the graph off

Set graph_context: false when your code only reads chunks; the response gets smaller and the traversal is skipped. This takes effect only in "fast" mode (explicit, or "auto" routed to fast). "thinking" always includes the graph. Direct factual lookups rarely need the graph. Questions about ownership, cause and effect, sequence, or dependencies usually do, and so does anything that needs to combine information across several chunks.

3. Where the relationships come from

Extracted at ingestion: HydraDB reads each source, finds the entities and the relationships between them, and stores the triplets. A source is searchable at the graph_creation status; completed means its graph work is done too, which is what full traversal needs. See Knowledge.
Declared by you: links between whole sources that belong together but whose text does not say so, set with relations.ids at ingest. A query in thinking mode returns the linked text in additional_context. Knowledge shows how. App sources also connect through fields such as thread_id and parent_id; see App Sources.
Supplied by you: Bring Your Own Graph replaces extraction for a source with the entities and relations you send. They appear in graph_context alongside extracted ones, tagged origin: "byog".

4. Walk the items around one result

The graph also holds relations between items rather than between entities: a Slack reply and the message it answers, a page and the pages it links to, a comment and its ticket. Given one item’s id, Connected Subgraph follows those links, nearest items first, and returns the connected items up to the requested depth and result limit, with the relations among them: the rest of the thread, the hierarchy above and below, the items it references. Use it when one query result is not enough and you need what surrounds it. The dashboard’s Subgraph button opens the same view.

5. Put graph context in your prompt

Pass the whole query result to build_string (Python) or buildString (TypeScript). After the chunks, the helper renders each path as one line per triplet: the source entity, the predicate, the target entity, and the relation’s context sentence. It reads query_paths, chunk_relations, and chunk_id_to_group_ids for you. How to Use API Results shows the full flow.

Query: how chunks and graph context are retrieved together
Bring Your Own Graph: supply your own entities and relations instead of auto-extraction
Knowledge: ingesting the documents the graph is built from, and linking the ones that belong together
App Sources: threads, replies, and relations between app sources
How to Use API Results: formatting graph context for model prompts
Query API Reference: full graph response schema
Connected Subgraph: everything connected to one item

Get Started

Usage

Organize

Understand

Plugins

For Agents

1. Get relationships with your results

What each field in `graph_context` means

2. Turn the graph off

3. Where the relationships come from

4. Walk the items around one result

5. Put graph context in your prompt

​1. Get relationships with your results

​What each field in graph_context means

​2. Turn the graph off

​3. Where the relationships come from

​4. Walk the items around one result

​5. Put graph context in your prompt

​Related

1. Get relationships with your results

What each field in `graph_context` means

2. Turn the graph off

3. Where the relationships come from

4. Walk the items around one result

5. Put graph context in your prompt

Related