Context Graphs

1. What it is

A context graph is a structured map of relationships between stored pieces of context in your database. It represents those relationships as triplets: source → relation → target. Each triplet is a directional connection between two pieces of context, with source, relation, and target returned as structured objects - not plain strings. Context graphs augment retrieval. They do not replace it.

2. What it does

When graph_context: true is set on a query call (the default), HydraDB returns relationship data alongside the retrieved chunks - showing how those chunks connect to each other and to your query. Set graph_context: false to drop the graph slice when you only need ranked chunks. This helps your LLM reason about questions that require connecting information across multiple chunks or sources. Similarity query returns relevant content; the context graph surfaces how that content fits together.

3. When to use it

Use context graphs when:

Answers require synthesising information across multiple chunks.
Relational context matters for correctness - cause and effect, ownership, sequence, dependency.
You need multi-hop reasoning (“What team owns the service that failed?”, “What depends on this API?”).

Skip them for direct factual lookups. Graph traversal adds response size and can add latency, so reserve it for queries where relational structure materially improves the answer.

4. How it works

Context graphs are hybrid: relationships are extracted at ingestion time and traversed at query time. At ingestion, HydraDB extracts relationships from your data and stores them in the graph. Sources can also declare explicit relationships to other sources via a relations payload at ingestion. Or skip extraction for a document and supply the entities and relations yourself with Bring Your Own Graph. At query, when graph_context: true is set (the default):

HydraDB runs hybrid retrieval to find relevant chunks.
It traverses the graph to discover relevant relationships between retrieved context.
It returns multi-hop paths from the query (query_paths), relationship paths between retrieved chunks (chunk_relations), and a chunk-to-path-group mapping (chunk_id_to_group_ids).

When no relevant relationships are found, graph fields may be empty.

5. Key concepts

Triplets. The unit of the graph. Each triplet is source → relation → target, where source and target are entity objects and relation describes the connection between them. Example: billing_policy → governs → failed_payment_handling query_paths. Multi-hop chains of triplets connecting the query to retrieved chunks. Each path carries a relevancy score and the chunk IDs whose traversal produced it. chunk_relations. Paths describing how returned chunks relate to one another. Same shape as query_paths; the difference is the anchor - query-driven vs chunk-to-chunk. chunk_id_to_group_ids. Maps each chunk ID to the path-group identifiers (e.g. p_0, p_1) it belongs to. Use it to group retrieved chunks by which graph path produced them. For full field schemas, see the Query API Reference.

6. Minimal working example

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
  }'

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,
});

if (result.data?.graphContext) {
  for (const path of result.data.graphContext.queryPaths) {
    for (const t of path.triplets) {
      console.log(
        `${t.source.name} - ${t.relation.canonicalPredicate} → ${t.target.name}`,
      );
    }
  }
}

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,
            )

A response with graph context looks like:

{
  "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"] }
  }
}

When no relevant relationships are found, graph fields may be empty.

7. Using graph context in your prompt

To include graph relationships in your LLM prompt, use the buildContextString / build_context_string helper from How to Use API Results. It handles query_paths, chunk_relations, and chunk_id_to_group_ids automatically. The helper formats triplets as:

[billing_policy] -> governs -> [failed_payment_handling]: policy covering retry logic
  ↳ [failed_payment_handling] -> triggers -> [notification_service]: sends customer alert

8. Common mistakes

Setting graph_context: false and then expecting the graph slice. Graph context is on by default - only set the flag to false if you explicitly don’t want graph data. Assuming the graph replaces retrieval. It doesn’t. chunks is still the primary result; the graph enriches it with relationships. Use both. Forgetting to disable when you don’t need it. Graph context adds response size and a small traversal cost. If your code path only consumes chunks, set graph_context: false to drop it. Treating triplets as flat strings. source, relation, and target are objects with their own fields. Read them as structured data. Expecting relationships that don’t exist. If the retrieved chunks don’t share entities or declared relations, the graph fields will be empty. That’s not an error - it’s the absence of structure for that query.

Query - how chunks and graph context are retrieved together
Bring Your Own Graph - supply your own entities and relations instead of auto-extraction
Memories - user-scoped context for personalization
Knowledge - document-level context for shared retrieval
How to Use API Results - formatting graph context for LLM prompts
Full Query API Reference - full graph response schema

Get Started

Usage

Concepts

Plugins

For Agents

1. What it is

2. What it does

3. When to use it

4. How it works

5. Key concepts

6. Minimal working example

7. Using graph context in your prompt

8. Common mistakes

​1. What it is

​2. What it does

​3. When to use it

​4. How it works

​5. Key concepts

​6. Minimal working example

​7. Using graph context in your prompt

​8. Common mistakes

​Related

1. What it is

2. What it does

3. When to use it

4. How it works

5. Key concepts

6. Minimal working example

7. Using graph context in your prompt

8. Common mistakes

Related