How to Use API Results

POST /query returns structured JSON. Before you can pass it to an LLM, you need to convert the retrieval payload into a plain string. This page shows how. The same pattern works regardless of whether you set type: "knowledge", type: "memory", or type: "all" - the response shape is identical.

1. What the response looks like

The SDKs return the full response envelope from POST /query; the retrieval payload is on its data field (e.g. result.data). Raw HTTP responses use the same envelope, with the payload under data. The build_string / buildString helper accepts either the full envelope or just the data payload, so you can pass the SDK return value to it directly. The retrieval payload has the same core shape regardless of type or query_by:

{
  "chunks": [
    {
      "chunk_uuid": "doc-001_chunk_0",
      "source_title": "my_document.pdf",
      "chunk_content": "Text content of the retrieved chunk...",
      "relevancy_score": 1.09,
      "extra_context_ids": ["ctx-id-1"],
      "additional_metadata": {
        "author": "Support Team"
      }
    }
  ],
  "graph_context": {
    "query_paths": [
      {
        "triplets": [
          {
            "source": { "name": "EntityA" },
            "target": { "name": "EntityB" },
            "relation": {
              "canonical_predicate": "DEPENDS_ON",
              "context": "reason text",
              "temporal_details": "2024-01"
            }
          }
        ]
      }
    ],
    "chunk_id_to_group_ids": {
      "doc-001_chunk_0": ["group-1"]
    },
    "chunk_relations": [
      {
        "group_id": "group-1",
        "triplets": [
          {
            "source": { "name": "EntityA" },
            "target": { "name": "EntityB" },
            "relation": {
              "canonical_predicate": "DEPENDS_ON",
              "context": "reason text"
            }
          }
        ]
      }
    ]
  },
  "additional_context": {
    "ctx-id-1": {
      "source_title": "related_doc.pdf",
      "chunk_content": "Extra related content..."
    }
  }
}

Four things matter for prompt construction:

chunks - the primary retrieval output. Ranked by relevance; preserve the order HydraDB returns.
graph_context.query_paths - entity traversal paths derived from your query. Useful for relational reasoning. See Context Graphs.
graph_context.chunk_relations + chunk_id_to_group_ids - per-chunk graph relations grouped by group_id, so you can attach the right triplets to each chunk.
additional_context - a map keyed by chunk_uuid. When a chunk includes extra_context_ids, use those IDs to look up related chunks here.

The raw object has too much noise for an LLM - IDs, timestamps, metadata. Section 2 shows how to convert it into a clean string.

2. Transforming the response into LLM context

Use build_string / buildString from the SDK. It takes any POST /query result and returns a formatted plain string.

from hydra_db import HydraDB
from hydra_db.helpers import build_string

client = HydraDB(token="YOUR_API_KEY")

result = client.query(
    database="your-database",
    collection="your-collection",
    query="How does authentication work?",
    type="knowledge",
    query_by="hybrid",
    max_results=5,
    mode="fast",
    graph_context=True,
)

context = build_string(result)

import { HydraDBClient, buildString } from "@hydradb/sdk";

const client = new HydraDBClient({ token: process.env.HYDRA_DB_API_KEY });

const result = await client.query({
  database: "your-database",
  collection: "your-collection",
  query: "How does authentication work?",
  type: "knowledge",
  queryBy: "hybrid",
  maxResults: 5,
  mode: "fast",
  graphContext: true,
});

const context = buildString(result);

from hydra_db import AsyncHydraDB
from hydra_db.helpers import build_string

client = AsyncHydraDB(token="YOUR_API_KEY")

result = await client.query(
    database="your-database",
    collection="your-collection",
    query="How does authentication work?",
    type="knowledge",
    query_by="hybrid",
    max_results=5,
    mode="fast",
    graph_context=True,
)

context = build_string(result)

3. Feeding the context into your LLM

from hydra_db import HydraDB
from hydra_db.helpers import build_string
from openai import OpenAI

hydra = HydraDB(token="YOUR_HYDRA_DB_API_KEY")
openai_client = OpenAI(api_key="YOUR_OPENAI_API_KEY")

question = "How does authentication work?"

result = hydra.query(
    database="your-database",
    query=question,
    type="knowledge",
    query_by="hybrid",
    mode="fast",
    graph_context=True,
)

context = build_string(result)

completion = openai_client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant. Answer the user's question using only the context provided. If the answer is not in the context, say you don't know.",
        },
        {
            "role": "user",
            "content": f"Context:\n{context}\n\nQuestion: {question}",
        },
    ],
)

print(completion.choices[0].message.content)

import { HydraDBClient, buildString } from "@hydradb/sdk";
import OpenAI from "openai";

const hydra = new HydraDBClient({ token: process.env.HYDRA_DB_API_KEY });
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const question = "How does authentication work?";

const result = await hydra.query({
  database: "your-database",
  query: question,
  type: "knowledge",
  queryBy: "hybrid",
  mode: "fast",
  graphContext: true,
});

const context = buildString(result);

const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "system",
      content: "You are a helpful assistant. Answer the user's question using only the context provided. If the answer is not in the context, say you don't know.",
    },
    {
      role: "user",
      content: `Context:\n${context}\n\nQuestion: ${question}`,
    },
  ],
});

console.log(completion.choices[0].message.content);

from hydra_db import AsyncHydraDB
from hydra_db.helpers import build_string
from openai import AsyncOpenAI

hydra = AsyncHydraDB(token="YOUR_HYDRA_DB_API_KEY")
openai_client = AsyncOpenAI(api_key="YOUR_OPENAI_API_KEY")

question = "How does authentication work?"

result = await hydra.query(
    database="your-database",
    query=question,
    type="knowledge",
    query_by="hybrid",
    mode="fast",
    graph_context=True,
)

context = build_string(result)

completion = await openai_client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant. Answer the user's question using only the context provided. If the answer is not in the context, say you don't know.",
        },
        {
            "role": "user",
            "content": f"Context:\n{context}\n\nQuestion: {question}",
        },
    ],
)

print(completion.choices[0].message.content)

4. Combining Knowledge and Memories

The simplest path is one POST /query with type: "all" - HydraDB queries both stores in parallel and returns one merged, ranked result set.

from hydra_db import HydraDB
from hydra_db.helpers import build_string
from openai import OpenAI

hydra = HydraDB(token="YOUR_HYDRA_DB_API_KEY")
openai_client = OpenAI(api_key="YOUR_OPENAI_API_KEY")

question = "What is our refund policy?"

result = hydra.query(
    database="acme_corp",
    collection="user_123",
    query=question,
    type="all",
    query_by="hybrid",
    mode="thinking",
)

context = build_string(result)

completion = openai_client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "Answer using only the context provided."},
        {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}"},
    ],
)

print(completion.choices[0].message.content)

import { HydraDBClient, buildString } from "@hydradb/sdk";
import OpenAI from "openai";

const hydra = new HydraDBClient({ token: process.env.HYDRA_DB_API_KEY });
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const question = "What is our refund policy?";

const result = await hydra.query({
  database: "acme_corp",
  collection: "user_123",
  query: question,
  type: "all",
  queryBy: "hybrid",
  mode: "thinking",
});

const context = buildString(result);

const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "Answer using only the context provided." },
    { role: "user", content: `Context:\n${context}\n\nQuestion: ${question}` },
  ],
});

console.log(completion.choices[0].message.content);

from hydra_db import AsyncHydraDB
from hydra_db.helpers import build_string
from openai import AsyncOpenAI

hydra = AsyncHydraDB(token="YOUR_HYDRA_DB_API_KEY")
openai_client = AsyncOpenAI(api_key="YOUR_OPENAI_API_KEY")

question = "What is our refund policy?"

result = await hydra.query(
    database="acme_corp",
    collection="user_123",
    query=question,
    type="all",
    query_by="hybrid",
    mode="thinking",
)

context = build_string(result)

completion = await openai_client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "Answer using only the context provided."},
        {"role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}"},
    ],
)

print(completion.choices[0].message.content)

If you need to format knowledge and memories in separate labeled sections, call POST /query twice in parallel:

import asyncio
from hydra_db import AsyncHydraDB
from hydra_db.helpers import build_string

hydra = AsyncHydraDB(token="YOUR_HYDRA_DB_API_KEY")

knowledge_result, memory_result = await asyncio.gather(
    hydra.query(
        database="acme_corp",
        query="refund policy",
        type="knowledge",
        query_by="hybrid",
        mode="thinking",
    ),
    hydra.query(
        database="acme_corp",
        collection="user_123",
        query="answer style preferences",
        type="memory",
        query_by="hybrid",
    ),
)

prompt = (
    f"User preferences:\n{build_string(memory_result)}\n\n"
    f"Relevant docs:\n{build_string(knowledge_result)}\n\n"
    f"Question: {question}"
)

import { HydraDBClient, buildString } from "@hydradb/sdk";

const hydra = new HydraDBClient({ token: process.env.HYDRA_DB_API_KEY });

const [knowledgeResult, memoryResult] = await Promise.all([
  hydra.query({
    database: "acme_corp",
    query: "refund policy",
    type: "knowledge",
    queryBy: "hybrid",
    mode: "thinking",
  }),
  hydra.query({
    database: "acme_corp",
    collection: "user_123",
    query: "answer style preferences",
    type: "memory",
    queryBy: "hybrid",
  }),
]);

const prompt =
  `User preferences:\n${buildString(memoryResult)}\n\n` +
  `Relevant docs:\n${buildString(knowledgeResult)}\n\n` +
  `Question: ${question}`;

If memory query fails or times out, fall back to the knowledge-only prompt.

5. Practical guidance

Preserve server order. Don’t re-sort chunks client-side.
Start small on chunks. max_results: 10 is a reasonable default. Drop to 5 if you hit token limits, raise to 20 if you rerank downstream.
Use graph context selectively. It improves relational queries and bloats simple lookups. See Context Graphs.
Always give the model a grounding instruction. A system prompt like “answer only from the provided context” prevents the model from inventing answers when retrieval is thin.
Format consistently. Whatever section delimiters you choose (=== CONTEXT ===, Chunk N, Source:), keep them stable across calls so the model learns the structure.
type: "all" is the simplest path when you need both knowledge and memories. One call, one result set, one build_string call.

6. Common mistakes

Mistake	What goes wrong	Fix
Passing the raw result object to the LLM	Wastes tokens on IDs and metadata	Use `build_string` / `buildString`.
Not including `collection` (formerly `sub_tenant_id`) when querying memories	Queries the default collection instead of the user’s	Always pass the same `collection` used at ingestion.
Including too many chunks	Token overflow or answer quality drops	Start at `max_results: 10`; reduce if needed.
Re-sorting chunks client-side	Overrides HydraDB’s ranking	Preserve the server-returned order.
Missing a grounding instruction	The model invents answers when retrieval is thin	System prompt: answer only from the provided context.
Setting `graph_context: false` and expecting graph fields	Graph context will be omitted	`graph_context` is on by default; only set it to `false` when you explicitly don’t want graph data.
Using `query_forceful_relations` with `mode: "fast"`	Flag is silently ignored	`query_forceful_relations` only takes effect when `mode: "thinking"`.
Looking up `chunk_relations` without `chunk_id_to_group_ids`	The right relations don’t attach to the right chunk	Use `chunk_id_to_group_ids[chunk_uuid]` to find the `group_id`s, then filter `chunk_relations` by them.

Query - request parameters and response shape
Memories - what POST /query with type: "memory" queries
Knowledge - what POST /query with type: "knowledge" queries
Context Graphs - what graph_context fields contain

Full flow without SDK

If you are not using the SDK, use the helper below to call POST /query, format the response, and pass the result to your LLM.

from __future__ import annotations
from typing import Any

import httpx


def _format_path_chain(path: Any) -> str:
    triplets = path.get("triplets") or []
    parts = []
    for t in triplets:
        src  = t.get("source", {}).get("name", "")
        tgt  = t.get("target", {}).get("name", "")
        rel  = t.get("relation", {})
        pred = rel.get("canonical_predicate", "")
        line = f"[{src}] -> {pred} -> [{tgt}]"
        ctx  = rel.get("context")
        if ctx:
            line += f": {ctx}"
        temporal = rel.get("temporal_details")
        if temporal:
            line += f" [Time: {temporal}]"
        parts.append(line)
    return "\n  ↳ ".join(parts)


def build_context_string(result: dict) -> str:
    lines: list[str] = []
    gc = result.get("graph_context") or {}

    query_paths = gc.get("query_paths") or []
    if query_paths:
        lines.append("=== ENTITY PATHS ===")
        for path in query_paths:
            lines.append(_format_path_chain(path))
        lines.append("")

    chunks = result.get("chunks") or []
    additional_context = result.get("additional_context") or {}
    chunk_id_to_group_ids = gc.get("chunk_id_to_group_ids") or {}
    chunk_relations = gc.get("chunk_relations") or []

    if chunks:
        lines.append("=== CONTEXT ===")
        for i, chunk in enumerate(chunks):
            lines.append(f"Chunk {i + 1}")
            source = chunk.get("source_title", "")
            if source:
                lines.append(f"Source: {source}")
            lines.append(chunk.get("chunk_content", ""))

            chunk_uuid = chunk.get("chunk_uuid", "")
            if chunk_uuid and chunk_id_to_group_ids and chunk_relations:
                group_ids = chunk_id_to_group_ids.get(chunk_uuid, [])
                relevant = [r for r in chunk_relations if r.get("group_id") in group_ids]
                if relevant:
                    lines.append("Graph Relations:")
                    for rel in relevant:
                        for triplet in rel.get("triplets") or []:
                            src  = triplet.get("source", {}).get("name", "")
                            tgt  = triplet.get("target", {}).get("name", "")
                            pred = triplet.get("relation", {}).get("canonical_predicate", "")
                            ctx  = triplet.get("relation", {}).get("context", "")
                            line = f"  [{src}] -> {pred} -> [{tgt}]: {ctx}"
                            temporal = triplet.get("relation", {}).get("temporal_details")
                            if temporal:
                                line += f" [Time: {temporal}]"
                            lines.append(line)

            extra_ids = chunk.get("extra_context_ids") or []
            if extra_ids and additional_context:
                extras = [additional_context[eid] for eid in extra_ids if eid in additional_context]
                if extras:
                    lines.append("Extra Context:")
                    for extra in extras:
                        lines.append(f"  Related Context ({extra.get('source_title', '')}): {extra.get('chunk_content', '')}")

            lines.append("---")
            lines.append("")

    return "\n".join(lines)


# Call the API and format the result
response = httpx.post(
    "https://api.hydradb.com/query",
    headers={
        "Authorization": "Bearer YOUR_HYDRA_DB_API_KEY",
        "API-Version": "2",
    },
    json={
        "database": "your-database",
        "query": "How does authentication work?",
        "type": "knowledge",
        "query_by": "hybrid",
        "mode": "fast",
        "graph_context": True,
    },
)

response.raise_for_status()
envelope = response.json()
if not envelope.get("success"):
    error = envelope.get("error") or {}
    raise RuntimeError(error.get("message", "HydraDB search failed"))

context = build_context_string(envelope["data"])

# Pass context to your LLM
print(context)

function formatPathChain(path: any): string {
  return (path.triplets || [])
    .map((t: any) => {
      let str = `[${t.source?.name}] -> ${t.relation?.canonical_predicate} -> [${t.target?.name}]`;
      if (t.relation?.context) str += `: ${t.relation.context}`;
      if (t.relation?.temporal_details) str += ` [Time: ${t.relation.temporal_details}]`;
      return str;
    })
    .join("\n  ↳ ");
}

function buildContextString(result: any): string {
  const lines: string[] = [];
  const gc = result.graph_context;

  if (gc?.query_paths?.length) {
    lines.push("=== ENTITY PATHS ===");
    for (const path of gc.query_paths) lines.push(formatPathChain(path));
    lines.push("");
  }

  if (result.chunks?.length) {
    lines.push("=== CONTEXT ===");
    for (let i = 0; i < result.chunks.length; i++) {
      const chunk = result.chunks[i];
      lines.push(`Chunk ${i + 1}`);
      lines.push(`Source: ${chunk.source_title}`);
      lines.push(chunk.chunk_content);

      if (gc?.chunk_id_to_group_ids && gc.chunk_relations) {
        const groupIds = gc.chunk_id_to_group_ids[chunk.chunk_uuid] || [];
        const relations = gc.chunk_relations.filter(
          (r: any) => r.group_id && groupIds.includes(r.group_id)
        );
        if (relations.length) {
          lines.push("Graph Relations:");
          for (const rel of relations) {
            for (const t of rel.triplets) {
              let line = `  [${t.source.name}] -> ${t.relation.canonical_predicate} -> [${t.target.name}]: ${t.relation.context}`;
              if (t.relation.temporal_details) line += ` [Time: ${t.relation.temporal_details}]`;
              lines.push(line);
            }
          }
        }
      }

      if (chunk.extra_context_ids?.length && result.additional_context) {
        const extras = chunk.extra_context_ids
          .map((id: string) => result.additional_context[id])
          .filter(Boolean);
        if (extras.length) {
          lines.push("Extra Context:");
          for (const extra of extras) {
            lines.push(`  Related Context (${extra.source_title}): ${extra.chunk_content}`);
          }
        }
      }

      lines.push("---");
      lines.push("");
    }
  }
  return lines.join("\n");
}

// Call the API and format the result
const res = await fetch("https://api.hydradb.com/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_HYDRA_DB_API_KEY",
    "API-Version": "2",
  },
  body: JSON.stringify({
    database: "your-database",
    query: "How does authentication work?",
    type: "knowledge",
    query_by: "hybrid",
    mode: "fast",
    graph_context: true,
  }),
});

const envelope = await res.json();
if (!res.ok || !envelope.success) {
  throw new Error(envelope.error?.message ?? "HydraDB search failed");
}

const context = buildContextString(envelope.data);

// Pass context to your LLM
console.log(context);

Get Started

Usage

Concepts

Plugins

For Agents

How to Use API Results

1. What the response looks like

2. Transforming the response into LLM context

3. Feeding the context into your LLM

4. Combining Knowledge and Memories

5. Practical guidance

6. Common mistakes

​1. What the response looks like

​2. Transforming the response into LLM context

​3. Feeding the context into your LLM

​4. Combining Knowledge and Memories

​5. Practical guidance

​6. Common mistakes

​Related

1. What the response looks like

2. Transforming the response into LLM context

3. Feeding the context into your LLM

4. Combining Knowledge and Memories

5. Practical guidance

6. Common mistakes

Related