Query

Use this page to choose the right query shape before opening the full Query endpoint reference. Query has three main decisions: what to query (type), how to match (query_by), and how much retrieval work to spend (mode).

Parameters that matter

Parameter	Values	Use it for
	`"knowledge"`, `"memory"`, `"all"`	Choose the collection. Use `"knowledge"` for shared docs/app sources, `"memory"` for user context, and `"all"` when an answer should use both.
	`"hybrid"`, `"text"`	Choose the matching method. Use `"hybrid"` by default and `"text"` for exact terms or phrases.
	`"fast"`, `"thinking"`, `"auto"`	Choose latency vs quality, or let HydraDB decide. Use `"fast"` for low-latency paths, `"thinking"` for multi-query retrieval, reranking, and forceful-relation context, and `"auto"` to score the query and route to one of the two automatically (defaults to `"thinking"` when the signal is inconclusive; also overrides `graph_context` to match - the default if `mode` is omitted).
	integer	Control prompt size. Start with `10`, reduce for tight context windows, increase only when you rerank or summarize downstream.
	`0.0`-`1.0` or `"auto"`	Tune hybrid query. Lower values favor BM25 keywords; higher values favor semantic similarity.
	object	Narrow candidates before ranking. Top-level keys match `metadata`; nested `additional_metadata` filters free-form per-source fields.
	`string[]` or weighted object	Query one or more user/workspace/team scopes. A list uses equal normalized weights; an object like `{ "workspace_42": 2, "user_alex": 1 }` applies relative ranking weights with at most one decimal place. Max 100 collections.
	boolean	Include entity/relation context with the chunks. On by default; set `false` for chunk-only responses.
	boolean	Adds app-aware retrieval while still querying the full selected knowledge scope. Use it for better app-source matching; it does not restrict retrieval to app sources only.

For filter design, read Usage - Metadata before creating database schemas. For exact request fields, defaults, and response shape, use Query.

Recommended configurations

User intent	Recommended config
Fast document RAG	`type="knowledge"`, `query_by="hybrid"`, `mode="fast"`, `max_results=5-10`, `graph_context=false`
Highest-quality document RAG	`type="knowledge"`, `query_by="hybrid"`, `mode="thinking"`, `graph_context=true`, `alpha="auto"`
Personalized answer	`type="all"`, include `collection`, `query_by="hybrid"`, `mode="thinking"`
User preferences only	`type="memory"`, include `collection`, `query_by="hybrid"`
Exact keyword or phrase	`type="knowledge"`, `query_by="text"`, `operator="phrase"`
Recent operational updates	`query_by="hybrid"`, `recency_bias=0.2-0.4`, filter to the right document type
Mixed or unpredictable query complexity	`query_by="hybrid"`, `mode="auto"` - let HydraDB route each query to `fast` or `thinking`

Typical patterns

Document Q&A from shared knowledge

Use this for standard RAG over docs, PDFs, tickets, pages, or app sources.

{
  "database": "acme",
  "query": "What is our refund policy?",
  "type": "knowledge",
  "query_by": "hybrid",
  "mode": "thinking",
  "max_results": 10,
  "graph_context": true
}

Personalized answer with memories

Use this when the answer should combine shared knowledge with user-specific context. Always pass the same collection used at memory ingestion.

{
  "database": "acme",
  "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"
}

Fan out across teams, workspaces, or users

Use this when the same question should search several collection scopes and return one globally ranked result set. Use a list for equal weighting, or an object when one scope should influence ranking more strongly.

{
  "database": "acme",
  "collections": {
    "workspace_42": 2,
    "user_alex": 1
  },
  "query": "What renewal risks should we discuss?",
  "type": "all",
  "query_by": "hybrid",
  "mode": "thinking"
}

Filtered query for a specific slice

Use metadata_filters when you already know the slice you want. Top-level keys match schema-backed metadata fields; declare hot filters in database_metadata_schema with enable_match: true. Free-form per-source fields go under additional_metadata (document_metadata is a legacy alias). Multiple filters are ANDed exact-match constraints.

{
  "database": "acme",
  "query": "What launch constraints apply to enterprise customers?",
  "type": "knowledge",
  "query_by": "hybrid",
  "metadata_filters": {
    "department": "product",
    "additional_metadata": {
      "source": "launch_plan"
    }
  }
}

Exact phrase lookup

Use text query when literal wording matters: legal clauses, SKUs, error codes, IDs, or compliance references.

{
  "database": "acme",
  "query": "GDPR Article 17",
  "type": "knowledge",
  "query_by": "text",
  "operator": "phrase"
}

Response summary

POST /query returns ranked data.chunks[], deduplicated data.sources[], optional data.graph_context, and optional data.additional_context from forceful relations. Preserve data.chunks[] order when building prompts; HydraDB has already ranked the results. For prompt formatting and citation patterns, see How to Use API Results.

Query - full endpoint reference
Usage - Query - conceptual overview, retrieval modes, and ranking behavior
Usage - Metadata - filtering with database and document metadata
Concepts - Context Graphs - graph context and relation paths

API Documentation

Databases

Context

Connectors

Miscellaneous

Query - Overview

Parameters that matter

Recommended configurations

Typical patterns

Response summary

​Parameters that matter

​Recommended configurations

​Typical patterns

​Response summary

​Related sections

Parameters that matter

Recommended configurations

Typical patterns

Response summary

Related sections