> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Query - Overview
> Quick reference for query modes, type selection, and when to call each.
export const Field = ({name, type, required, recommended}) => {
const label = required ? 'required' : recommended ? 'recommended' : null;
const typeLabel = typeof type === 'string' ? type : null;
const ariaParts = [name, typeLabel && `${typeLabel}`, label].filter(Boolean);
return
{name}
{required && *}
{recommended && ●}
{type && {type}}
{label &&
{label}
}
;
};
Use this page to choose the right query shape before opening the full [Query](/api-reference/v2/endpoint/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`).
```mermaid theme={"dark"}
flowchart LR
classDef standard fill:#0f172a,stroke:#334155,stroke-width:2px,color:#f8fafc;
classDef innovation fill:#CC4515,stroke:#FF571A,stroke-width:3px,color:#ffffff,font-weight:bold;
Q([I want to retrieve context])
S([What should I query?])
M([What kind of match?])
H([query_by: hybrid])
T([query_by: text])
Q --> S
S -- "Documents / files / app sources" --> M
S -- "User memories" --> M
S -- "Both" --> M
M -- "Best overall relevance" --> H
M -- "Exact term or phrase" --> T
class Q,S,M,T standard;
class H innovation;
linkStyle default stroke:#64748b,stroke-width:2px;
```
## 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](/essentials/v2/metadata) before creating database schemas. For exact request fields, defaults, and response shape, use [Query](/api-reference/v2/endpoint/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
Use this for standard RAG over docs, PDFs, tickets, pages, or app sources.
```json theme={"dark"}
{
"database": "acme",
"query": "What is our refund policy?",
"type": "knowledge",
"query_by": "hybrid",
"mode": "thinking",
"max_results": 10,
"graph_context": true
}
```
Use this when the answer should combine shared knowledge with user-specific context. Always pass the same `collection` used at memory ingestion.
```json theme={"dark"}
{
"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"
}
```
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.
```json theme={"dark"}
{
"database": "acme",
"collections": {
"workspace_42": 2,
"user_alex": 1
},
"query": "What renewal risks should we discuss?",
"type": "all",
"query_by": "hybrid",
"mode": "thinking"
}
```
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.
```json theme={"dark"}
{
"database": "acme",
"query": "What launch constraints apply to enterprise customers?",
"type": "knowledge",
"query_by": "hybrid",
"metadata_filters": {
"department": "product",
"additional_metadata": {
"source": "launch_plan"
}
}
}
```
Use text query when literal wording matters: legal clauses, SKUs, error codes, IDs, or compliance references.
```json theme={"dark"}
{
"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](/essentials/v2/api-results).
## Related sections
* [Query](/api-reference/v2/endpoint/query) - full endpoint reference
* [Usage - Query](/essentials/v2/query) - conceptual overview, retrieval modes, and ranking behavior
* [Usage - Metadata](/essentials/v2/metadata) - filtering with database and document metadata
* [Concepts - Context Graphs](/essentials/v2/context-graphs) - graph context and relation paths