docs: unified ingest and query contract (PRO-1618), stacked on #296

api-reference/v2/endpoint/query-overview.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Query - Overview"
-description: "Quick reference for query modes, type selection, and when to call each."
+description: "Quick reference for scoping, matching and retrieval modes, and what comes back."
 ---
 
 import { Field } from "/snippets/field.jsx";
 
-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`).
+Use this page to choose the right query shape before opening the full [Query](/api-reference/v2/endpoint/query) endpoint reference. A query has three decisions: where to look (`collection` or `collections`), how to match (`query_by`), and how much retrieval work to spend (`mode`). There is no corpus selector on a unified database: one database is one corpus.
 
 ```mermaid
 flowchart LR
@@ -14,15 +14,14 @@ 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?])
+S([Where should I look?])
 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
+S -- "One collection" --> M
+S -- "Several collections, weighted" --> M
 M -- "Best overall relevance" --> H
 M -- "Exact term or phrase" --> T
 
@@ -35,44 +34,44 @@ linkStyle default stroke:#64748b,stroke-width:2px;
 
 | Parameter | Values | Use it for |
 |---|---|---|
-| <Field name="type" /> | `"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. |
+| <Field name="collections" /> | `string[]` or weighted object | Where to look. A list uses equal normalized weights; an object like `{ "user_alex": 2, "company": 1 }` ranks one scope above another without excluding either. Max 100 collections. `collection` selects a single one. |
 | <Field name="query_by" /> | `"hybrid"`, `"text"` | Choose the matching method. Use `"hybrid"` by default and `"text"` for exact terms or phrases. |
-| <Field name="mode" /> | `"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**). |
+| <Field name="mode" /> | `"fast"`, `"thinking"`, `"auto"` | Choose latency vs quality, or let HydraDB decide. `"fast"` for low-latency paths, `"thinking"` for multi-query retrieval, reranking and declared relations, `"auto"` to score the query and route to one of the two (defaults to `"thinking"` when the signal is inconclusive; also overrides `graph_context` to match; **the default if `mode` is omitted**). |
 | <Field name="max_results" /> | integer | Control prompt size. Start with `10`, reduce for tight context windows, increase only when you rerank or summarize downstream. |
-| <Field name="alpha" /> | `0.0`-`1.0` or `"auto"` | Tune hybrid query. Lower values favor BM25 keywords; higher values favor semantic similarity. |
-| <Field name="metadata_filters" /> | object | Narrow candidates before ranking. Top-level keys match `metadata`; nested `additional_metadata` filters free-form per-source fields. |
-| <Field name="collections" /> | `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. |
-| <Field name="graph_context" /> | boolean | Include entity/relation context with the chunks. On by default; set `false` for chunk-only responses. |
-| <Field name="query_apps" /> | 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. |
+| <Field name="alpha" /> | `0.0` to `1.0` or `"auto"` | Tune hybrid query. Lower values favor BM25 keywords; higher values favor semantic similarity. |
+| <Field name="attributes" /> | object | Narrow candidates with operators (`$eq`, `$in`, `$gte`, `$and`, ...) on the fields declared in `database_metadata_schema`. |
+| <Field name="graph_context" /> | boolean | Include graph paths in `graph[]`. On by default; set `false` for chunk-only responses. |
+| <Field name="follow_forceful_relations" /> | boolean | Pull items linked with `forceful_relations` at ingest into `forceful_relations[]`. On by default. |
+| <Field name="query_apps" /> | boolean | Adds app-aware retrieval for connector content while still querying the full selected scope. |
 
 <Tip>
-For filter design, read [Usage - Metadata](/essentials/v2/attributes) before creating database schemas. For exact request fields, defaults, and response shape, use [Query](/api-reference/v2/endpoint/query).
+For filter design, read [Attributes](/essentials/v2/attributes) before creating database schemas. For exact request fields, defaults, and response shape, use [Query](/api-reference/v2/endpoint/query).
 </Tip>
 
 ## 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` |
+| Fast RAG over shared context | `collection` (the shared one), `query_by="hybrid"`, `mode="fast"`, `max_results=5-10`, `graph_context=false` |
+| Highest-quality RAG | `query_by="hybrid"`, `mode="thinking"`, `graph_context=true`, `alpha="auto"` |
+| Personalized answer | `collections={ "<user>": 2, "<shared>": 1 }`, `query_by="hybrid"`, `mode="thinking"` |
+| A person's preferences only | `collection="<user>"`, `query_by="hybrid"` |
+| Exact keyword or phrase | `query_by="text"`, `operator="phrase"` |
+| Recent operational updates | `query_by="hybrid"`, `recency_bias=0.2-0.4`, `attributes` on the right kind of item |
+| Mixed or unpredictable query complexity | `query_by="hybrid"`, `mode="auto"`; let HydraDB route each query to `fast` or `thinking` |
 
 ## Typical patterns
 
 <AccordionGroup>
-  <Accordion title="Document Q&A from shared knowledge" defaultOpen>
+  <Accordion title="Q&A over shared context" defaultOpen>
 
-Use this for standard RAG over docs, PDFs, tickets, pages, or app sources.
+Use this for standard RAG over docs, policies, tickets, pages, or connector content in a shared collection.
 
 ```json
 {
   "database": "acme",
+  "collection": "company",
   "query": "What is our refund policy?",
-  "type": "knowledge",
   "query_by": "hybrid",
   "mode": "thinking",
   "max_results": 10,
@@ -82,16 +81,15 @@ Use this for standard RAG over docs, PDFs, tickets, pages, or app sources.
 
   </Accordion>
 
-  <Accordion title="Personalized answer with memories">
+  <Accordion title="Personalized answer">
 
-Use this when the answer should combine shared knowledge with user-specific context. Always pass the same `collection` used at memory ingestion.
+Use this when the answer should combine shared context with a person's own. Weight the person's collection above the shared one; the weights rank, they do not exclude.
 
 ```json
 {
   "database": "acme",
-  "collection": "user_alex",
+  "collections": { "user_alex": 2, "company": 1 },
   "query": "What is our refund policy, and how should I explain it to this user?",
-  "type": "all",
   "query_by": "hybrid",
   "mode": "thinking"
 }
@@ -111,7 +109,6 @@ Use this when the same question should search several collection scopes and retu
     "user_alex": 1
   },
   "query": "What renewal risks should we discuss?",
-  "type": "all",
   "query_by": "hybrid",
   "mode": "thinking"
 }
@@ -121,19 +118,18 @@ Use this when the same question should search several collection scopes and retu
 
   <Accordion title="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.
+Use `attributes` when you already know the slice you want. Keys are the fields declared in `database_metadata_schema` and sent as `attributes` at ingest; clauses combine with `$and` and `$or`.
 
 ```json
 {
   "database": "acme",
   "query": "What launch constraints apply to enterprise customers?",
-  "type": "knowledge",
   "query_by": "hybrid",
-  "metadata_filters": {
-    "department": "product",
-    "additional_metadata": {
-      "source": "launch_plan"
-    }
+  "attributes": {
+    "$and": [
+      { "department": { "$eq": "product" } },
+      { "region": { "$in": ["us", "eu"] } }
+    ]
   }
 }
 ```
@@ -148,7 +144,6 @@ Use text query when literal wording matters: legal clauses, SKUs, error codes, I
 {
   "database": "acme",
   "query": "GDPR Article 17",
-  "type": "knowledge",
   "query_by": "text",
   "operator": "phrase"
 }
@@ -159,11 +154,24 @@ Use text query when literal wording matters: legal clauses, SKUs, error codes, I
 
 ## 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).
+`POST /query` returns exactly four keys under `data`:
+
+| Key | Contents |
+| --- | --- |
+| `chunks[]` | Ranked matches: `chunk_id`, `context_id`, `score`, `content`, optional `enrichment` (a string), `enrichment_kind` and `temporal`. No source details; call `GET /context/inspect` with the `context_id` for those. |
+| `graph[]` | Paths through the context graph: `origin` (`query_path` or `chunk_relation`), `triplets[]` and a `path_summary`, which is never empty. Each hop's `relation.chunk_id` names the chunk it came from; a `chunk_relation` path is only returned when one of its hops came from a returned chunk or a `forceful_relations` chunk. |
+| `forceful_relations[]` | Chunks linked with `forceful_relations` at ingest, each with the `via` that brought it in. |
+| `llm_prompt` | A server-built markdown string, ready to inject into a model call: results cited `[1]`, forceful relations `[R1]`, related facts labelled `[P1]` in `graph[]` order with each path's relevance when it has one, then temporal facts and sources. |
+
+Inject `llm_prompt` for the model; preserve `chunks[]` order when you render results yourself. See [How to Use API Results](/essentials/v2/api-results).
+
+## Split databases
+
+A database created with `type: "split"` adds one decision: `type` (`"knowledge"`, `"memory"` or `"all"`) picks the corpus, and the response is the older shape (`chunk_content`, `sources[]`, `graph_context`, `additional_context`). See the [Split databases](/api-reference/v2/endpoint/query#split-databases) section of the endpoint reference.
 
 ## 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/attributes) - filtering with database and document metadata
-- [Concepts - Context Graphs](/essentials/v2/context-graphs) - graph context and relation paths
+- [Query](/api-reference/v2/endpoint/query): full endpoint reference
+- [Usage: Query](/essentials/v2/query): conceptual overview, retrieval modes, and ranking behavior
+- [Usage: Attributes](/essentials/v2/attributes): filtering with declared attributes
+- [Concepts: Context Graphs](/essentials/v2/context-graphs): graph paths and relations