Query

POST /query searches your knowledge, your memories, or both, and returns ranked passages, called chunks, with their source details and the context graph around them. Your application puts them in the model’s prompt; the model writes the answer. The defaults work without tuning. In this guide:

Run a query and read what comes back.
Pick a recipe: starting parameters for the common cases.
Tune the ranking: mode, alpha, recency_bias, and max_results.
Choose what to search: several collections, knowledge and memories together, and metadata filters.
Add relationships: the context graph, linked sources, and app-aware search.
Query on behalf of a user: the acl field.
Common mistakes.

1. Run a query

This request searches the acme_corp database for knowledge about rotating API keys. Every query starts from this request; later sections add fields. The body is JSON; ingestion is multipart.

Run a query: Python, TypeScript, or cURL

Set up your SDK client before running the Python or TypeScript example.

result = client.query(
    database="acme_corp",
    collection="company_docs",
    query="How do I rotate API keys?",
    type="knowledge",
    max_results=5,
)

for chunk in result.data.chunks:
    print(chunk.source_title, chunk.chunk_content)

const result = await client.query({
  database: "acme_corp",
  collection: "company_docs",
  query: "How do I rotate API keys?",
  type: "knowledge",
  maxResults: 5,
});

if (!result.data || typeof result.data === "string") throw new Error("Expected structured query results");
for (const chunk of result.data.chunks) {
  console.log(chunk.sourceTitle, chunk.chunkContent);
}

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",
    "collection": "company_docs",
    "query": "How do I rotate API keys?",
    "type": "knowledge",
    "max_results": 5
  }'

The response is wrapped in the standard envelope, so read the result from data. Trimmed to the fields you use most, it looks like this:

{
  "success": true,
  "data": {
    "chunks": [
      {
        "chunk_uuid": "runbook_keys_chunk_2",
        "id": "runbook_keys",
        "chunk_content": "Rotate API keys from Settings, then Security. The old key stays valid for 24 hours.",
        "source_title": "API key runbook",
        "relevancy_score": 0.91,
        "metadata": { "document_type": "runbook" }
      }
    ],
    "sources": [
      { "id": "runbook_keys", "title": "API key runbook", "type": "pdf", "url": "" }
    ],
    "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": 412.0
  }
}

The full response schema is on the Query API reference.

What each property means

Property	What it is
`database`	The database to search. Required on every call. A query never reads another database.
`collection`	The collection to search, the same one you ingested into. Leave it out to search the database’s default collection. Section 4 covers searching several at once.
`query`	The question or search terms, in natural language. Cannot be empty.
`type`	What to search: `"knowledge"` (the default) for documents and app sources, `"memory"` for saved preferences and conversations, or `"all"` for both.
`max_results`	How many chunks to return. Default `10`, maximum `250`.

What comes back

data.chunks: the matching passages, ranked by relevance, each with its chunk_content, source_title, relevancy_score, and metadata. Keep the order.
data.sources: one entry per source, with its id, title, and url for citations.
data.graph_context and data.additional_context: relationships and linked passages, covered in section 5.

Pass the whole result to build_string (Python) or buildString (TypeScript) for a prompt-ready string. See How to Use API Results for more. New context is searchable once its indexing status reaches graph_creation.

2. Pick a recipe

Start from the row that matches your goal. Leave everything else at its default.

I want to	`type`	`query_by`	`mode`	Notes
Answer questions from documents	`"knowledge"`	`"hybrid"`	`"thinking"`	Keep `graph_context` on (the default) to include relationships between the people, topics, or services the documents mention
Match an exact keyword or phrase	`"knowledge"`	`"text"`	Not used	Set `operator` to `"and"` or `"phrase"` to control how the keywords must match. Semantic Search has the example
Personalize a response	`"memory"`	`"hybrid"`	`"thinking"`	Search the collection the memories were saved in
Personalize and ground in documents	`"all"`	`"hybrid"`	`"thinking"`	One call reads both stores from the same scope. If the documents live in another collection, list both in `collections`
Search Slack, Jira, Gmail, and other app data	`"knowledge"`	`"hybrid"`	`"thinking"`	Leave `query_apps` on (the default) so threads, replies, and linked records expand along with the matching item
Serve mixed traffic with one setting	`"knowledge"`	`"hybrid"`	`"auto"`	HydraDB scores each query and routes it to `"fast"` or `"thinking"`. This is also what you get when `mode` is omitted

query_by picks how the text is matched: "hybrid" (the default) matches by meaning and by keyword together, and "text" matches keywords only. mode picks how much work the query does. Section 3 explains mode; Semantic Search covers query_by.

3. Tune the ranking

Most of the time the defaults are right. When they are not, start here:

mode: "fast" is one retrieval pass, for chat and autocomplete. "thinking" expands the query, reranks, and pulls in linked sources, for answers where quality matters more than latency. "auto", the default, scores each query and routes it to one of the two, choosing thinking when unsure; the response does not say which it chose. Applies to query_by: "hybrid" only.
alpha: the balance between meaning (1.0) and keywords (0.0) in a hybrid query. Default 0.8, which "auto" also resolves to. Lower it toward 0.3 to 0.5 for error codes, SKUs, and product names; raise it toward 0.9 for conceptual questions. Semantic Search has the full table.
recency_bias: how much newer context is favored, from 0.0 to 1.0. Default 0.4, a mild tilt that only reorders close results. Send 0 for policies and other context that rarely changes, and 0.6 to 0.8 for changelogs and status updates.
max_results: drop to 5 for tight context windows; raise to 20 when you rerank downstream.
additional_context: a short factual hint, such as "user is on the billing page", that sharpens retrieval. It is not a filter.

In production:

Timeouts: 3 to 5 s for thinking, 500 ms or less for fast. Budget "auto" like thinking.
Literal token plus intent: run query_by: "hybrid" and query_by: "text" in parallel, dedupe by chunk_uuid, and keep the text hits.
Recall, then rerank: ask for max_results: 20 and apply your own rules before picking the final set.
Caching: key on the database, the collections, the caller’s acl, and every query parameter, and expire entries when context or permissions change.

4. Choose what to search

To search beyond one collection:

Several collections: send collections instead, as a list, or as an object of weights to rank one collection over another. Up to 100; every listed collection must exist, or the call returns 400. max_results caps the merged list.
Knowledge and memories together: type: "all" reads both from the same collections and ranks them together. When shared documents and memories live in different collections, list both.
A slice you already know: metadata_filters narrows results before ranking, such as only runbooks or only one team’s documents. Metadata covers the operators.

Search shared documents and a user's memories together: Python, TypeScript, or cURL

result = client.query(
    database="acme_corp",
    collections=["company_docs", "user_john_123"],
    query="How do I reset my password?",
    type="all",
    mode="thinking",
    max_results=8,
)

const result = await client.query({
  database: "acme_corp",
  collections: ["company_docs", "user_john_123"],
  query: "How do I reset my password?",
  type: "all",
  mode: "thinking",
  maxResults: 8,
});

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",
    "collections": ["company_docs", "user_john_123"],
    "query": "How do I reset my password?",
    "type": "all",
    "mode": "thinking",
    "max_results": 8
  }'

Knowledge and memories come back together in data.chunks, ranked as one list. To let the user’s memories outrank the shared documents, send weights instead of a list:

{
  "collections": {
    "user_john_123": 2,
    "company_docs": 1
  }
}

5. Add relationships

Three fields bring in context beyond the passages that matched. All three are on by default.

graph_context: the relationships HydraDB extracted from your context, such as “Payments team owns billing service”, in data.graph_context. false drops it, but only in fast mode; thinking always includes it. Context Graphs explains how to read it.
query_forceful_relations: sources linked at ingest with relations.ids, such as a contract and its addendum, returned in data.additional_context. Thinking mode only; fast mode skips it without an error. Knowledge shows how to declare the links.
query_apps: for app sources, an extra lane that rebuilds Slack threads, follows ticket and parent links, and matches exact ids and people. It still searches everything else, and has no effect on memories.

6. Query on behalf of a user

Send the caller’s email in acl, such as "acl": ["[email protected]"], and results are limited to documents that person may retrieve, plus public and unrestricted ones. Without acl the query is not filtered, so derive it from your signed-in session, never from the client. Access Control covers setting ACLs on documents and the principal forms.

Common mistakes

Symptom	Cause	Fix
Empty `query_paths` or `chunk_relations`	`graph_context` set to `false`, or no relationships exist for the result set	Leave `graph_context` on (the default). Empty arrays are normal when there is nothing to return. See Context Graphs.
Recent uploads do not appear in results	Indexing not finished	Poll `GET /context/status` with the source ids. Chunks are invisible until processing reaches at least `graph_creation`.
`metadata_filters` does not narrow results	Filter key is in the wrong namespace, the value does not match exactly, or the top-level field was not declared in the database schema	Top-level keys match `metadata`; free-form per-document fields must be nested under `additional_metadata`. Declare hot filter keys in `database_metadata_schema` before production ingest.
Memories missing from a `type: "knowledge"` query	Wrong store selected	Use `type: "memory"` or `type: "all"`.
Knowledge missing from a `type: "all"` query	The documents live in a different collection from the one you sent	List both collections in `collections`.
Recency does not seem to matter	`recency_bias` was sent as `0`, or the default `0.4` tilt is too mild	Raise it toward `1.0`.
`operator: "phrase"` returns `400`	`query_by` not set to `"text"`	`"and"` and `"phrase"` only apply to BM25 text queries: switch `query_by` to `"text"`.
`query_forceful_relations` ignored	Request runs in `mode: "fast"` (or `auto` routed to fast)	Linked sources are fetched only in thinking mode. Set `mode: "thinking"`.
`graph_context: false` ignored	Request runs in thinking mode (`mode: "thinking"`, or `auto` routed to thinking)	Thinking always includes the graph slice; `false` takes effect only in fast mode. Set `mode: "fast"` to drop it.
Expected a deterministic `fast` or `thinking` pipeline, got auto-routed instead	`mode` was omitted	Omitting `mode` means `"auto"`. Set `mode` explicitly to `"fast"` or `"thinking"`.

Knowledge: the documents and app records a query searches
Memories: preferences, decisions, and past conversations
How to Use API Results: turning the response into a model prompt
Semantic Search: how meaning and keyword matching combine, and the alpha table
Context Graphs: reading and using graph_context
Metadata: designing filterable fields
Access Control: giving documents ACLs and querying as a caller
Query: API Reference: the full parameter and response schema

Get Started

Usage

Organize

Understand

Plugins

For Agents

1. Run a query

What each property means

What comes back

2. Pick a recipe

3. Tune the ranking

4. Choose what to search

5. Add relationships

6. Query on behalf of a user

Common mistakes

​1. Run a query

​What each property means

​What comes back

​2. Pick a recipe

​3. Tune the ranking

​4. Choose what to search

​5. Add relationships

​6. Query on behalf of a user

​Common mistakes

​Related

1. Run a query

What each property means

What comes back

2. Pick a recipe

3. Tune the ranking

4. Choose what to search

5. Add relationships

6. Query on behalf of a user

Common mistakes

Related