Query

result = client.query(
    database="acme_corp",
    collection="user_alex",
    query="What is our refund policy, and how should I explain it to this user?",

    # What to query: "knowledge", "memory", or "all".
    type="all",

    # How to match: "hybrid" (default) or "text" (BM25).
    query_by="hybrid",

    # "thinking" improves quality; use "fast" for lowest latency.
    mode="thinking",

    # Ranking and response controls.
    max_results=10,
    alpha="auto",
    recency_bias=0.2,
    graph_context=True,

    # Pull author-declared related sources into additional_context.
    # Only applies when mode="thinking".
    query_forceful_relations=True,

    # Top-level keys match metadata; additional_metadata is per-source.
    metadata_filters={
        "department": "support",
        "additional_metadata": {
            "source": "policy",
        },
    },

    # Short factual hint; not a hard filter.
    additional_context="User is asking from the billing help center.",
)

const result = await client.query({
  database: "acme_corp",
  collection: "user_alex",
  query: "What is our refund policy, and how should I explain it to this user?",

  // What to query: "knowledge", "memory", or "all".
  type: "all",

  // How to match: "hybrid" (default) or "text" (BM25).
  queryBy: "hybrid",

  // "thinking" improves quality; use "fast" for lowest latency.
  mode: "thinking",

  // Ranking and response controls.
  maxResults: 10,
  alpha: "auto",
  recencyBias: 0.2,
  graphContext: true,

  // Pull author-declared related sources into additional_context.
  // Only applies when mode: "thinking".
  queryForcefulRelations: true,

  // Top-level keys match metadata; additional_metadata is per-source.
  metadataFilters: {
    department: "support",
    additional_metadata: {
      source: "policy",
    },
  },

  // Short factual hint; not a hard filter.
  additionalContext: "User is asking from the billing help center.",
});

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "user_alex",
    "query": "What is our refund policy, and how should I explain it to this user?",
    "type": "all",
    "query_by": "hybrid",
    "mode": "thinking",
    "max_results": 10,
    "alpha": "auto",
    "recency_bias": 0.2,
    "graph_context": true,
    "query_forceful_relations": true,
    "metadata_filters": {
      "department": "support",
      "additional_metadata": {
        "source": "policy"
      }
    },
    "additional_context": "User is asking from the billing help center."
  }'

{
  "success": true,
  "data": {
    "chunks": [
      {
        "chunk_uuid": "policy_main_chunk_3",
        "id": "policy_main",
        "chunk_content": "Refunds are issued within 30 days...",
        "source_type": "pdf",
        "source_title": "Compliance Policy",
        "source_upload_time": "2026-05-12T08:14:00Z",
        "source_last_updated_time": "2026-05-12T08:14:00Z",
        "layout": "{\"offsets\":{\"document_level_start_index\":1024},\"page\":3}",
        "relevancy_score": 0.91,
        "extra_context_ids": ["pref-tone"],
        "metadata": { "department": "legal" },
        "additional_metadata": { "author": "Legal Team" }
      }
    ],
    "sources": [
      {
        "id": "policy_main",
        "title": "Compliance Policy",
        "type": "pdf",
        "description": "",
        "url": "",
        "timestamp": "2026-05-12T08:14:00Z",
        "metadata": { "department": "legal" },
        "additional_metadata": { "author": "Legal Team" },
        "app_kind": null,
        "app_provider": null,
        "app_external_id": null
      }
    ],
    "graph_context": {
      "query_paths": [
        {
          "triplets": [
            {
              "source": {
                "name": "Compliance Policy",
                "type": "DOCUMENT",
                "namespace": "default",
                "entity_id": "entity_compliance_policy",
                "identifier": "https://api.hydradb.com/docs/compliance_policy"
              },
              "relation": {
                "canonical_predicate": "GOVERNS",
                "raw_predicate": "governs and regulates",
                "context": "The compliance policy governs the refund processing timeline of 30 days.",
                "confidence": 0.95,
                "temporal_details": null,
                "timestamp": 1778573640.0,
                "relationship_id": "rel_governs_refunds",
                "chunk_id": "policy_main_chunk_3",
                "source_entity_id": "entity_compliance_policy",
                "target_entity_id": "entity_refund_processing"
              },
              "target": {
                "name": "Refund Processing",
                "type": "PROCESS",
                "namespace": "default",
                "entity_id": "entity_refund_processing",
                "identifier": null
              }
            }
          ],
          "relevancy_score": 0.89,
          "combined_context": "The Compliance Policy governs the Refund Processing, which regulates refunds.",
          "group_id": null,
          "source_chunk_ids": ["policy_main_chunk_3"]
        }
      ],
      "chunk_relations": [
        {
          "triplets": [
            {
              "source": {
                "name": "Refund Processing",
                "type": "PROCESS",
                "namespace": "default",
                "entity_id": "entity_refund_processing",
                "identifier": null
              },
              "relation": {
                "canonical_predicate": "MANAGED_BY",
                "raw_predicate": "is managed by",
                "context": "Refund processing is managed by the Finance Department.",
                "confidence": 0.9,
                "temporal_details": "Q2 2026 onwards",
                "timestamp": 1778573640.0,
                "relationship_id": "rel_managed_by_finance",
                "chunk_id": "policy_main_chunk_3",
                "source_entity_id": "entity_refund_processing",
                "target_entity_id": "entity_finance_dept"
              },
              "target": {
                "name": "Finance Department",
                "type": "ORGANIZATION",
                "namespace": "default",
                "entity_id": "entity_finance_dept",
                "identifier": "[email protected]"
              }
            }
          ],
          "relevancy_score": 0.82,
          "combined_context": "Refund Processing is managed by the Finance Department.",
          "group_id": "p_0",
          "source_chunk_ids": ["policy_main_chunk_3"]
        }
      ],
      "chunk_id_to_group_ids": {
        "policy_main_chunk_3": ["p_0"]
      }
    },
    "additional_context": {
      "pref-tone": {
        "chunk_uuid": "pref-tone",
        "id": "mem_user_alex_tone",
        "chunk_content": "Prefers concise answers.",
        "source_type": "memory",
        "source_title": "User preferences",
        "source_upload_time": "2026-05-12T08:14:00Z",
        "source_last_updated_time": "2026-05-12T08:14:00Z"
      }
    }
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": true,
  "data": {
    "chunks": [],
    "sources": [],
    "graph_context": {
      "query_paths": [],
      "chunk_relations": [],
      "chunk_id_to_group_ids": {}
    },
    "additional_context": {}
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "query must not be empty"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

POST

query

result = client.query(
    database="acme_corp",
    collection="user_alex",
    query="What is our refund policy, and how should I explain it to this user?",

    # What to query: "knowledge", "memory", or "all".
    type="all",

    # How to match: "hybrid" (default) or "text" (BM25).
    query_by="hybrid",

    # "thinking" improves quality; use "fast" for lowest latency.
    mode="thinking",

    # Ranking and response controls.
    max_results=10,
    alpha="auto",
    recency_bias=0.2,
    graph_context=True,

    # Pull author-declared related sources into additional_context.
    # Only applies when mode="thinking".
    query_forceful_relations=True,

    # Top-level keys match metadata; additional_metadata is per-source.
    metadata_filters={
        "department": "support",
        "additional_metadata": {
            "source": "policy",
        },
    },

    # Short factual hint; not a hard filter.
    additional_context="User is asking from the billing help center.",
)

const result = await client.query({
  database: "acme_corp",
  collection: "user_alex",
  query: "What is our refund policy, and how should I explain it to this user?",

  // What to query: "knowledge", "memory", or "all".
  type: "all",

  // How to match: "hybrid" (default) or "text" (BM25).
  queryBy: "hybrid",

  // "thinking" improves quality; use "fast" for lowest latency.
  mode: "thinking",

  // Ranking and response controls.
  maxResults: 10,
  alpha: "auto",
  recencyBias: 0.2,
  graphContext: true,

  // Pull author-declared related sources into additional_context.
  // Only applies when mode: "thinking".
  queryForcefulRelations: true,

  // Top-level keys match metadata; additional_metadata is per-source.
  metadataFilters: {
    department: "support",
    additional_metadata: {
      source: "policy",
    },
  },

  // Short factual hint; not a hard filter.
  additionalContext: "User is asking from the billing help center.",
});

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "user_alex",
    "query": "What is our refund policy, and how should I explain it to this user?",
    "type": "all",
    "query_by": "hybrid",
    "mode": "thinking",
    "max_results": 10,
    "alpha": "auto",
    "recency_bias": 0.2,
    "graph_context": true,
    "query_forceful_relations": true,
    "metadata_filters": {
      "department": "support",
      "additional_metadata": {
        "source": "policy"
      }
    },
    "additional_context": "User is asking from the billing help center."
  }'

{
  "success": true,
  "data": {
    "chunks": [
      {
        "chunk_uuid": "policy_main_chunk_3",
        "id": "policy_main",
        "chunk_content": "Refunds are issued within 30 days...",
        "source_type": "pdf",
        "source_title": "Compliance Policy",
        "source_upload_time": "2026-05-12T08:14:00Z",
        "source_last_updated_time": "2026-05-12T08:14:00Z",
        "layout": "{\"offsets\":{\"document_level_start_index\":1024},\"page\":3}",
        "relevancy_score": 0.91,
        "extra_context_ids": ["pref-tone"],
        "metadata": { "department": "legal" },
        "additional_metadata": { "author": "Legal Team" }
      }
    ],
    "sources": [
      {
        "id": "policy_main",
        "title": "Compliance Policy",
        "type": "pdf",
        "description": "",
        "url": "",
        "timestamp": "2026-05-12T08:14:00Z",
        "metadata": { "department": "legal" },
        "additional_metadata": { "author": "Legal Team" },
        "app_kind": null,
        "app_provider": null,
        "app_external_id": null
      }
    ],
    "graph_context": {
      "query_paths": [
        {
          "triplets": [
            {
              "source": {
                "name": "Compliance Policy",
                "type": "DOCUMENT",
                "namespace": "default",
                "entity_id": "entity_compliance_policy",
                "identifier": "https://api.hydradb.com/docs/compliance_policy"
              },
              "relation": {
                "canonical_predicate": "GOVERNS",
                "raw_predicate": "governs and regulates",
                "context": "The compliance policy governs the refund processing timeline of 30 days.",
                "confidence": 0.95,
                "temporal_details": null,
                "timestamp": 1778573640.0,
                "relationship_id": "rel_governs_refunds",
                "chunk_id": "policy_main_chunk_3",
                "source_entity_id": "entity_compliance_policy",
                "target_entity_id": "entity_refund_processing"
              },
              "target": {
                "name": "Refund Processing",
                "type": "PROCESS",
                "namespace": "default",
                "entity_id": "entity_refund_processing",
                "identifier": null
              }
            }
          ],
          "relevancy_score": 0.89,
          "combined_context": "The Compliance Policy governs the Refund Processing, which regulates refunds.",
          "group_id": null,
          "source_chunk_ids": ["policy_main_chunk_3"]
        }
      ],
      "chunk_relations": [
        {
          "triplets": [
            {
              "source": {
                "name": "Refund Processing",
                "type": "PROCESS",
                "namespace": "default",
                "entity_id": "entity_refund_processing",
                "identifier": null
              },
              "relation": {
                "canonical_predicate": "MANAGED_BY",
                "raw_predicate": "is managed by",
                "context": "Refund processing is managed by the Finance Department.",
                "confidence": 0.9,
                "temporal_details": "Q2 2026 onwards",
                "timestamp": 1778573640.0,
                "relationship_id": "rel_managed_by_finance",
                "chunk_id": "policy_main_chunk_3",
                "source_entity_id": "entity_refund_processing",
                "target_entity_id": "entity_finance_dept"
              },
              "target": {
                "name": "Finance Department",
                "type": "ORGANIZATION",
                "namespace": "default",
                "entity_id": "entity_finance_dept",
                "identifier": "[email protected]"
              }
            }
          ],
          "relevancy_score": 0.82,
          "combined_context": "Refund Processing is managed by the Finance Department.",
          "group_id": "p_0",
          "source_chunk_ids": ["policy_main_chunk_3"]
        }
      ],
      "chunk_id_to_group_ids": {
        "policy_main_chunk_3": ["p_0"]
      }
    },
    "additional_context": {
      "pref-tone": {
        "chunk_uuid": "pref-tone",
        "id": "mem_user_alex_tone",
        "chunk_content": "Prefers concise answers.",
        "source_type": "memory",
        "source_title": "User preferences",
        "source_upload_time": "2026-05-12T08:14:00Z",
        "source_last_updated_time": "2026-05-12T08:14:00Z"
      }
    }
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": true,
  "data": {
    "chunks": [],
    "sources": [],
    "graph_context": {
      "query_paths": [],
      "chunk_relations": [],
      "chunk_id_to_group_ids": {}
    },
    "additional_context": {}
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "query must not be empty"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

The single retrieval endpoint for everything. Use it any time you need to feed an LLM with grounded context, surface user preferences, or fetch chunks ranked by relevance. Three independent dimensions control behavior:

type picks what to query: "knowledge", "memory", or "all" (both, merged and re-ranked together).
query_by picks how to match: "hybrid" (semantic + BM25, the default) or "text" (BM25 only - pair with operator).
mode picks how to rank results: "fast" (single-pass, low-latency), "thinking" (expands query, reranks, and can include forceful-relation context), or "auto" (scores the query and routes to "fast" or "thinking" automatically, defaulting to "thinking" when the signal is inconclusive - the default if mode is omitted).

Read more about choosing the perfect mode for your use case here.

database and collection are the current field names (formerly tenant_id and sub_tenant_id). The old names remain accepted as deprecated aliases for full backward compatibility.

result = client.query(
    database="acme_corp",
    collection="user_alex",
    query="What is our refund policy, and how should I explain it to this user?",

    # What to query: "knowledge", "memory", or "all".
    type="all",

    # How to match: "hybrid" (default) or "text" (BM25).
    query_by="hybrid",

    # "thinking" improves quality; use "fast" for lowest latency.
    mode="thinking",

    # Ranking and response controls.
    max_results=10,
    alpha="auto",
    recency_bias=0.2,
    graph_context=True,

    # Pull author-declared related sources into additional_context.
    # Only applies when mode="thinking".
    query_forceful_relations=True,

    # Top-level keys match metadata; additional_metadata is per-source.
    metadata_filters={
        "department": "support",
        "additional_metadata": {
            "source": "policy",
        },
    },

    # Short factual hint; not a hard filter.
    additional_context="User is asking from the billing help center.",
)

const result = await client.query({
  database: "acme_corp",
  collection: "user_alex",
  query: "What is our refund policy, and how should I explain it to this user?",

  // What to query: "knowledge", "memory", or "all".
  type: "all",

  // How to match: "hybrid" (default) or "text" (BM25).
  queryBy: "hybrid",

  // "thinking" improves quality; use "fast" for lowest latency.
  mode: "thinking",

  // Ranking and response controls.
  maxResults: 10,
  alpha: "auto",
  recencyBias: 0.2,
  graphContext: true,

  // Pull author-declared related sources into additional_context.
  // Only applies when mode: "thinking".
  queryForcefulRelations: true,

  // Top-level keys match metadata; additional_metadata is per-source.
  metadataFilters: {
    department: "support",
    additional_metadata: {
      source: "policy",
    },
  },

  // Short factual hint; not a hard filter.
  additionalContext: "User is asking from the billing help center.",
});

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "user_alex",
    "query": "What is our refund policy, and how should I explain it to this user?",
    "type": "all",
    "query_by": "hybrid",
    "mode": "thinking",
    "max_results": 10,
    "alpha": "auto",
    "recency_bias": 0.2,
    "graph_context": true,
    "query_forceful_relations": true,
    "metadata_filters": {
      "department": "support",
      "additional_metadata": {
        "source": "policy"
      }
    },
    "additional_context": "User is asking from the billing help center."
  }'

Querying multiple collections

Use collections when one query should fan out across multiple user, workspace, or team scopes. The field accepts either a list or a weighted object:

Equal weighting

{
  "database": "acme_corp",
  "collections": ["workspace_42", "user_alex"],
  "query": "What renewal risks should I know about?",
  "type": "all"
}

Weighted ranking

{
  "database": "acme_corp",
  "collections": {
    "workspace_42": 2,
    "user_alex": 1
  },
  "query": "What renewal risks should I know about?",
  "type": "all"
}

A list gives every collection equal normalized weight. An object treats values as positive relative ranking weights with at most one decimal place and normalizes them server-side. You can send at most 100 collections. When max_results is omitted, HydraDB uses up to 10 results per collection, capped at 1000 fanout candidates before the final ranked response is shaped. When max_results is set, it is the final global response cap across the merged fanout result set.

Caching tip: collections list order is not semantically significant for fanout selection. Sort list values before constructing cache keys; for weighted objects, sort keys and keep weights at the documented one-decimal precision so equivalent calls share the same cache entry.

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

Common use-cases and their configurations

1. Knowledge RAG - answer from shared documents

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "query": "What is our refund policy?",
    "type": "knowledge",
    "query_by": "hybrid",
    "mode": "thinking",
    "max_results": 10,
    "graph_context": true
  }'

const result = await client.query({
  database: "acme_corp",
  query: "What is our refund policy?",
  type: "knowledge",
  queryBy: "hybrid",
  mode: "thinking",
  maxResults: 10,
  graphContext: true,
});

result = client.query(
    database="acme_corp",
    query="What is our refund policy?",
    type="knowledge",
    query_by="hybrid",
    mode="thinking",
    max_results=10,
    graph_context=True,
)

2. Personalized answer - combine knowledge with user memories

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "user_alex",
    "query": "What is our refund policy, and how should I explain it to this user?",
    "type": "all",
    "query_by": "hybrid",
    "mode": "thinking"
  }'

const result = await client.query({
  database: "acme_corp",
  collection: "user_alex",
  query: "What is our refund policy, and how should I explain it to this user?",
  type: "all",
  queryBy: "hybrid",
  mode: "thinking",
});

result = client.query(
    database="acme_corp",
    collection="user_alex",
    query="What is our refund policy, and how should I explain it to this user?",
    type="all",
    query_by="hybrid",
    mode="thinking",
)

3. Retrieve user preferences - query only user memories

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "user_alex",
    "query": "Does the user have any specific preferences for tone or response length?",
    "type": "memory",
    "query_by": "hybrid",
    "query_apps": true
  }'

const result = await client.query({
  database: "acme_corp",
  collection: "user_alex",
  query: "Does the user have any specific preferences for tone or response length?",
  type: "memory",
  queryBy: "hybrid",
  queryApps: true,
});

result = client.query(
    database="acme_corp",
    collection="user_alex",
    query="Does the user have any specific preferences for tone or response length?",
    type="memory",
    query_by="hybrid",
    query_apps=True,
)

4. Exact phrase lookup - BM25 for legal terms, SKUs, or IDs

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "query": "GDPR Article 17",
    "type": "knowledge",
    "query_by": "text",
    "operator": "phrase"
  }'

const result = await client.query({
  database: "acme_corp",
  query: "GDPR Article 17",
  type: "knowledge",
  queryBy: "text",
  operator: "phrase",
});

result = client.query(
    database="acme_corp",
    query="GDPR Article 17",
    type="knowledge",
    query_by="text",
    operator="phrase",
)

5. Let HydraDB decide - auto-route between fast and thinking

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "query": "How does the Q2 partnership between Acme and Globex affect our SLA with Initech?",
    "type": "knowledge",
    "query_by": "hybrid",
    "mode": "auto"
  }'

const result = await client.query({
  database: "acme_corp",
  query: "How does the Q2 partnership between Acme and Globex affect our SLA with Initech?",
  type: "knowledge",
  queryBy: "hybrid",
  mode: "auto",
});

result = client.query(
    database="acme_corp",
    query="How does the Q2 partnership between Acme and Globex affect our SLA with Initech?",
    type="knowledge",
    query_by="hybrid",
    mode="auto",
)

HydraDB scores the query before retrieval and routes it to "fast" or "thinking" - a query naming several distinct entities like this one is likely to route to "thinking". Use "auto" for traffic where query complexity varies call-to-call and you don’t want to hand-pick per request. This is also the default: an omitted mode field behaves exactly like mode: "auto". Set mode to "fast" or "thinking" explicitly if you want a deterministic pipeline instead.

Request body

Name	Description
	Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).
	Single collection scope. Required for per-user memory queries. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated). (default=default collection)
	Multi-collection scope. Send a list of collection IDs for equal weighting, or an object mapping collection ID to a positive relative weight (at most one decimal place, e.g. `{"finance": 1.5, "legal": 0.8}`) to bias ranking. Up to 100 collections. Do not combine with `collection`/`sub_tenant_id`. Formerly `sub_tenant_ids`; the `sub_tenant_ids` alias is still accepted (deprecated since 2.0.1).
	Query terms or natural-language question. Cannot be empty.
	What collection to query. `"all"` runs knowledge and memory in parallel and merges by `relevancy_score`. (default=`"knowledge"`)
	Retrieval method. See Query methods. (default=`"hybrid"`)
	Adds an app-aware retrieval lane for app sources while still querying the full selected knowledge scope. Set `true` for better app-source matching, thread/relation traversal, exact IDs, and actor/provider hints. It does not limit query to only app sources. (default=`false`)
	BM25 operator for `query_by: "text"`. Ignored for `hybrid`. (default=`"or"`)
	Retrieval pipeline. Applies to `hybrid` only; ignored for `text`. `"auto"` scores the query before retrieval and resolves it to `"fast"` or `"thinking"`, defaulting to `"thinking"` when the signal is inconclusive; it also overrides whatever `graph_context` you sent to match that resolved mode. (default=`"auto"`)
	Maximum chunks to return. Default `10`; maximum `50`. Start with `10`, use `5` for tight prompts, and increase only when reranking downstream.
	Hybrid weight (`1.0` = pure semantic, `0.0` = pure BM25). Applies to `query_by: "hybrid"` only. (default=`0.8`)
	Boost newer content. (default=`0.0`)
	When `true`, includes the entity/relation graph slice in the response under `graph_context`. Set to `false` when you only need ranked chunks. Relations you supplied via Bring Your Own Graph appear here identically to extracted ones. (default=`true`) - under `mode: "auto"`, this value is overridden by the resolved mode regardless of what you send.
	Pull author-declared related sources into `additional_context`. Only takes effect when `mode` resolves to `"thinking"` - silently ignored in `fast` mode, and under `mode: "auto"` whether it takes effect depends on the automatic routing decision. (default=`true`)
	Request-time hint to guide retrieval (e.g., “user is on the billing page”). This is different from the response `additional_context` map. (default=`null`)
	Deterministic narrowing before ranking. See Filters. (default=`null`)

Tuning heuristics.

alpha: start at 0.8. Lower toward 0.3–0.5 when the query contains literal tokens (error codes, SKUs, product names). Raise toward 0.9 for conceptual questions. Use “auto” when query shape varies.
recency_bias: leave at 0 for static reference material. Set 0.2–0.4 for mixed content, 0.6–0.8 for changelogs, news, or status updates.
max_results: start at 10. Drop to 5 for tight context windows; raise to 20 if you rerank downstream.

Decision matrix

Type selection

Value	Queries	Best for
`"knowledge"` (default)	Knowledge documents, files, and app sources	Document Q&A, RAG context.
`"query_apps=true"`	Full selected knowledge scope plus app-aware retrieval	App-specific Q&A that should still query non-app knowledge documents.
`"memory"`	User memories	Personalization and user preferences.
`"all"`	Both, merged in one ranked result set	Personalized answers grounded in both shared and user-specific context.

Query methods

Method	Pipeline	Best for
`"hybrid"` (default)	Dense vectors + BM25 keyword	General-purpose retrieval and RAG.
`"text"`	BM25 only	Exact terms, compliance lookups, phrase query. Pair with `operator`.

Modes

For query_by: "hybrid":

Mode	Behavior	When to use
`"fast"`	Single query pass	Real-time chat, autocomplete, simple lookups.
`"thinking"`	Multi-query expansion + reranking + forceful-relation context	Complex queries, customer-facing answers, anything where quality matters.
`"auto"` (default if `mode` is omitted)	Scores the query before retrieval and routes to `"fast"` or `"thinking"`; defaults to `"thinking"` when the signal is inconclusive. Also overrides `graph_context` to match whichever mode it picks.	Mixed or unpredictable query traffic where you don’t want to hand-pick per request.

"auto"’s resolved pipeline isn’t reported back in the response, so budget latency as thinking-level in the worst case. Omitting mode behaves exactly like mode: "auto" - set it explicitly to "fast" or "thinking" if you want a deterministic pipeline instead.

Filters

metadata_filters are hard exact-match constraints applied before ranking and re-checked after hydration. The shape combines two filter scopes:

{
  "metadata_filters": {
    "department": "engineering",
    "region": "us-east",
    "additional_metadata": {
      "source": "account_plan",
      "author": "alex"
    }
  }
}

Where	What it matches
Top-level keys (`department`, `region`)	The source’s schema-backed `metadata`. Keys must be declared in the database’s `database_metadata_schema` with `enable_match: true`, otherwise they are silently ignored.
Nested under `additional_metadata`	The source’s free-form per-document fields. No schema declaration required. `document_metadata` is accepted as a legacy alias.

Multiple filters are ANDed. Range, contains, fuzzy, and OR operators are not supported in user-provided metadata_filters; run multiple queries or post-process client-side for those cases.

{
  "success": true,
  "data": {
    "chunks": [
      {
        "chunk_uuid": "policy_main_chunk_3",
        "id": "policy_main",
        "chunk_content": "Refunds are issued within 30 days...",
        "source_type": "pdf",
        "source_title": "Compliance Policy",
        "source_upload_time": "2026-05-12T08:14:00Z",
        "source_last_updated_time": "2026-05-12T08:14:00Z",
        "layout": "{\"offsets\":{\"document_level_start_index\":1024},\"page\":3}",
        "relevancy_score": 0.91,
        "extra_context_ids": ["pref-tone"],
        "metadata": { "department": "legal" },
        "additional_metadata": { "author": "Legal Team" }
      }
    ],
    "sources": [
      {
        "id": "policy_main",
        "title": "Compliance Policy",
        "type": "pdf",
        "description": "",
        "url": "",
        "timestamp": "2026-05-12T08:14:00Z",
        "metadata": { "department": "legal" },
        "additional_metadata": { "author": "Legal Team" },
        "app_kind": null,
        "app_provider": null,
        "app_external_id": null
      }
    ],
    "graph_context": {
      "query_paths": [
        {
          "triplets": [
            {
              "source": {
                "name": "Compliance Policy",
                "type": "DOCUMENT",
                "namespace": "default",
                "entity_id": "entity_compliance_policy",
                "identifier": "https://api.hydradb.com/docs/compliance_policy"
              },
              "relation": {
                "canonical_predicate": "GOVERNS",
                "raw_predicate": "governs and regulates",
                "context": "The compliance policy governs the refund processing timeline of 30 days.",
                "confidence": 0.95,
                "temporal_details": null,
                "timestamp": 1778573640.0,
                "relationship_id": "rel_governs_refunds",
                "chunk_id": "policy_main_chunk_3",
                "source_entity_id": "entity_compliance_policy",
                "target_entity_id": "entity_refund_processing"
              },
              "target": {
                "name": "Refund Processing",
                "type": "PROCESS",
                "namespace": "default",
                "entity_id": "entity_refund_processing",
                "identifier": null
              }
            }
          ],
          "relevancy_score": 0.89,
          "combined_context": "The Compliance Policy governs the Refund Processing, which regulates refunds.",
          "group_id": null,
          "source_chunk_ids": ["policy_main_chunk_3"]
        }
      ],
      "chunk_relations": [
        {
          "triplets": [
            {
              "source": {
                "name": "Refund Processing",
                "type": "PROCESS",
                "namespace": "default",
                "entity_id": "entity_refund_processing",
                "identifier": null
              },
              "relation": {
                "canonical_predicate": "MANAGED_BY",
                "raw_predicate": "is managed by",
                "context": "Refund processing is managed by the Finance Department.",
                "confidence": 0.9,
                "temporal_details": "Q2 2026 onwards",
                "timestamp": 1778573640.0,
                "relationship_id": "rel_managed_by_finance",
                "chunk_id": "policy_main_chunk_3",
                "source_entity_id": "entity_refund_processing",
                "target_entity_id": "entity_finance_dept"
              },
              "target": {
                "name": "Finance Department",
                "type": "ORGANIZATION",
                "namespace": "default",
                "entity_id": "entity_finance_dept",
                "identifier": "[email protected]"
              }
            }
          ],
          "relevancy_score": 0.82,
          "combined_context": "Refund Processing is managed by the Finance Department.",
          "group_id": "p_0",
          "source_chunk_ids": ["policy_main_chunk_3"]
        }
      ],
      "chunk_id_to_group_ids": {
        "policy_main_chunk_3": ["p_0"]
      }
    },
    "additional_context": {
      "pref-tone": {
        "chunk_uuid": "pref-tone",
        "id": "mem_user_alex_tone",
        "chunk_content": "Prefers concise answers.",
        "source_type": "memory",
        "source_title": "User preferences",
        "source_upload_time": "2026-05-12T08:14:00Z",
        "source_last_updated_time": "2026-05-12T08:14:00Z"
      }
    }
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": true,
  "data": {
    "chunks": [],
    "sources": [],
    "graph_context": {
      "query_paths": [],
      "chunk_relations": [],
      "chunk_id_to_group_ids": {}
    },
    "additional_context": {}
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "query must not be empty"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

A zero-result query returns empty arrays/maps rather than an error, as shown in the Zero results tab.

Behavior notes

Default Behaviors

mode defaults to "auto". Omitting mode entirely behaves exactly like mode: "auto" - set it explicitly to "fast" or "thinking" if you want a deterministic pipeline.
graph_context is on by default. Set it to false if you only need ranked chunks and want to drop the graph slice from the response.
recency_bias is off by default. Defaults to 0.0 - no recency boost is applied unless you set it.

Important Considerations & Common Mistakes

query_forceful_relations requires mode to resolve to "thinking". In fast mode the flag is silently ignored. The server does not error or warn - your additional_context will simply be empty. Under mode: "auto" this depends on that request’s routing decision, not on what you asked for.
mode: "auto" overrides graph_context. Whatever you send for graph_context is replaced to match the resolved mode - true if auto escalates to thinking, false if it resolves to fast. This also applies when mode is omitted, since it defaults to "auto". Set graph_context explicitly only when calling "fast" or "thinking" directly.
Want a deterministic pipeline instead of automatic routing? Set mode explicitly to "fast" or "thinking" - an omitted mode field now defaults to "auto", not "fast".
Relation timestamp is a Unix epoch float here. In the graph_context slice returned by /query - and in the passthrough relations returned by List Documents with include_fields: ["relations"] - each relation’s timestamp is a Unix epoch value in seconds (a float, e.g. 1778573640.0). The dedicated Context Relations endpoint returns the same field as an ISO-8601 string instead. Normalize before comparing relation timestamps across endpoints.
Use the right metadata namespace. Top-level metadata_filters keys match metadata; free-form per-document fields must be nested under additional_metadata (document_metadata is only a legacy alias). Declare hot top-level filter fields in database_metadata_schema with enable_match: true.
Common mistakes. Check Ingestion Status for recently ingested documents before querying. If you omit collection, HydraDB queries the default collection; use List Collections to discover available IDs.

Errors

Common codes: 400 INVALID_PARAMETERS (empty query), 404 DATABASE_NOT_FOUND, 422 VALIDATION_ERROR, 500 INTERNAL_ERROR. See Error Responses for the full list.

Related Resources

Setup first: Ingest Context - content must be indexed
Confirm indexing: Ingestion Status - wait for completed (or graph_creation)
Graph follow-up: Context Relations - inspect relationships in detail
Concepts: Usage → Query
Concepts: Concepts → Semantic Search
Concepts: Concepts → Context Graphs
Response handling: Usage → How to Use API Results
Read more: Query - Overview

Authorizations

Authorization

string

header

required

API key sent as a Bearer token: "Bearer prefix.secret"

Body

application/json

Unified query request

additional_context

string

Optional context string prepended to the query to improve retrieval relevance.

Example:

"The user is a senior engineer onboarding to the platform."

alpha

any

Weighting balance between dense and sparse retrieval in hybrid mode. "auto" lets HydraDB choose; a number from 0 (full BM25) to 1 (full dense) sets it explicitly.

collection

string

Collection scope. Defaults to the default collection when omitted. Formerly sub_tenant_id; the sub_tenant_id alias is still accepted (deprecated).

Example:

"team_docs"

collections

Preferred /query scope selector. Send either a list of collection IDs for equal normalized weighting, or an object mapping collection ID to a positive relative ranking weight with at most one decimal place. Do not send together with the deprecated sub_tenant_ids or sub_tenant_id.

Required array length: 1 - 100 elements

Example:

["team_docs", "engineering"]

database

string

Database is the canonical v2 name for the tenant scope. TenantID is its deprecated alias and remains fully accepted. The TenantAliases middleware reconciles the two before binding, so TenantID is always populated and the handler reads it; Database/Collection are carried only for docs/OpenAPI.

Example:

"acme_corp"

graph_context

boolean

Whether to include graph context in the response. Defaults to true for /query when omitted.

Example:

true

graph_vector_prune

boolean

GraphVectorPrune switches the graph-connected-chunks lane from "fetch graph-selected chunks and let the fusion reranker sort them out" to "fetch a wider graph-selected candidate pool, then rank that pool by Milvus vector similarity, fully replacing the final chunk list." Works in either fast or thinking mode. Default false preserves existing behavior. Also gated server-side by a repo-level config flag (SearchService's graphVectorPruneEnabled) — if that flag is off, this is forced to false regardless of what the request sets, so a deployment can disable the mechanism without any client-side change.

Example:

true

graph_vector_prune_spacy_entities

boolean

GraphVectorPruneSpacyEntities: when GraphVectorPrune is also set, swaps the graph lane's entity-extraction source from the default LLM-based extractor to a local spaCy subprocess (faster, no network round trip, but a narrower/mismatched entity vocabulary versus the graph's own LLM-extracted node names). No-op if GraphVectorPrune is false (including when forced false by the server-level flag) or no spaCy extractor was configured at startup.

Example:

true

ids

string[]

IDs optionally scopes retrieval to specific source ids. The v2 wire field is ids (matching /context/list); empty means search the whole corpus. Applied as a Milvus source_id in [...] pre-filter that is preserved across the metadata zero-result retry, so a source-scoped search that matches nothing returns nothing rather than silently widening to the whole corpus.

Example:

["HydraDoc1234", "HydraDoc4567"]

max_results

integer

Maximum number of chunks to return.

Example:

10

metadata_filters

object

Filters results by source metadata. Top-level keys target tenant metadata (for example department, priority, active, or tags). Nested additional_metadata keys target document metadata. Values are exact-match scalars or arrays for set-equality/list-style filters.

Show child attributes

Example:

{
  "active": true,
  "additional_metadata": { "author": "ada" },
  "department": "finance",
  "priority": 7,
  "tags": ["alpha", "beta"]
}

mode

enum<string>

Available options:

fast,

thinking,

auto

Example:

"thinking"

Number of adjacent chunks to pull alongside each matched chunk for additional context.

Example:

3

operator

enum<string>

Available options:

or,

and,

phrase

Example:

"and"

query

string

Natural-language search query.

Example:

"Which mode does the user prefer?"

query_apps

boolean

Whether to include app-aware knowledge retrieval. Applies to knowledge hybrid queries.

Example:

true

query_by

enum<string>

Retrieval method to use for the query.

Available options:

hybrid,

text

Example:

"hybrid"

query_forceful_relations

boolean

Whether to force relation expansion for graph-aware query retrieval. Defaults to true when omitted.

Example:

true

recency_bias

number

Recency boost applied to ranking. 0 disables it; higher values favour more recent sources.

Example:

0.2

sub_tenant_id

string

deprecated

Deprecated for /query (since 2.0.1). Use collection for a single scope or collections for multiple. Backwards-compatible and will be removed in a future version. Do not send together with a multi-scope selector.

Example:

"sub_tenant_4567"

sub_tenant_ids

deprecated

Deprecated for /query (since 2.0.1). Use collections instead; it accepts the same list or weighted-object shape. Backwards-compatible and will be removed in a future version. Do not send together with collections.

Required array length: 1 - 100 elements

Example:

["sub_tenant_4567", "sub_tenant_8901"]

tenant_id

string

deprecated

deprecated: use database

Example:

"tenant_1234"

type

enum<string>

Corpus to query: knowledge, memory, or all.

Available options:

knowledge,

memory,

all

Response

data

object

Show child attributes

Example:

{
  "additional_context": "The user is a senior engineer onboarding to the platform.",
  "chunks": [
    {
      "additional_metadata": { "author": "ada", "doc_version": 3 },
      "chunk_content": "HydraDB supports hybrid retrieval across knowledge and memories.",
      "chunk_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "extra_context_ids": [
        "HydraEmbeddings123_2",
        "HydraEmbeddings123_3"
      ],
      "id": "HydraDoc1234",
      "layout": "text",
      "metadata": { "department": "finance", "priority": 7 },
      "relevancy_score": 0.87,
      "source_last_updated_time": "2026-07-02T12:30:00Z",
      "source_title": "Project Phoenix Overview",
      "source_type": "file",
      "source_upload_time": "2026-07-02T10:00:00Z",
      "sub_tenant_id": "sub_tenant_4567"
    }
  ],
  "graph_context": {
    "chunk_id_to_group_ids": { "HydraEmbeddings123_0": ["grp_1234"] },
    "chunk_relations": [
      {
        "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
        "group_id": "grp_1234",
        "relevancy_score": 0.87,
        "source_chunk_ids": [
          "HydraEmbeddings123_0",
          "HydraEmbeddings123_1"
        ],
        "triplets": [
          {
            "relation": {
              "confidence": 0.92,
              "predicate": "works_at"
            },
            "source": {
              "entity_id": "entity_1a2b",
              "name": "Ada",
              "type": "person"
            },
            "target": {
              "entity_id": "entity_3c4d",
              "name": "Acme Corp",
              "type": "organization"
            }
          }
        ]
      }
    ],
    "query_paths": [
      {
        "combined_context": "Acme Corp deploys HydraDB in production for context retrieval.",
        "group_id": "grp_1234",
        "relevancy_score": 0.87,
        "source_chunk_ids": [
          "HydraEmbeddings123_0",
          "HydraEmbeddings123_1"
        ],
        "triplets": [
          {
            "relation": {
              "confidence": 0.92,
              "predicate": "works_at"
            },
            "source": {
              "entity_id": "entity_1a2b",
              "name": "Ada",
              "type": "person"
            },
            "target": {
              "entity_id": "entity_3c4d",
              "name": "Acme Corp",
              "type": "organization"
            }
          }
        ]
      }
    ],
    "synthesis_context": "Related entities: Acme Corp, HydraDB, production deployment."
  },
  "sources": [
    {
      "additional_metadata": { "author": "ada", "doc_version": 3 },
      "app_external_id": "C0123456789",
      "app_kind": "slack",
      "app_provider": "slack",
      "description": "Internal overview of the Project Phoenix rollout.",
      "id": "HydraDoc1234",
      "metadata": { "department": "finance", "priority": 7 },
      "sub_tenant_id": "sub_tenant_4567",
      "timestamp": "2026-07-02T10:00:00Z",
      "title": "Project Phoenix Overview",
      "type": "knowledge",
      "url": "https://docs.hydradb.com/phoenix"
    }
  ]
}

error

object

Error message, empty string on success.

Show child attributes

Example:

{
  "code": "DATABASE_NOT_FOUND",
  "message": "Database not found"
}

API Documentation

Databases

Context

Connectors

Miscellaneous

Query

Querying multiple collections

Transforming the response into LLM context

Common use-cases and their configurations

Request body

Decision matrix

Behavior notes

Errors

Authorizations

Body

Response

​Querying multiple collections

​Transforming the response into LLM context

​Common use-cases and their configurations

​Request body

​Decision matrix

​Behavior notes

​Errors

Authorizations

Body

Response

Querying multiple collections

Transforming the response into LLM context

Common use-cases and their configurations

Request body

Decision matrix

Behavior notes

Errors