> ## Documentation Index > Fetch the complete documentation index at: https://cortex-e852fafe-auto-update-openapi-90ba87bf22729efa0749c85.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Query > Unified retrieval over knowledge, memories, or both. 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} } ; }; 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](/api-reference/v2/endpoint/query-overview#recommended-configurations). `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. ```python Python SDK theme={null} 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.", ) ``` ```typescript TypeScript SDK theme={null} 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.", }); ``` ```bash cURL theme={null} curl -X POST 'https://api.hydradb.com/query' \ -H "Authorization: Bearer " \ -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: ```json Equal weighting theme={null} { "database": "acme_corp", "collections": ["workspace_42", "user_alex"], "query": "What renewal risks should I know about?", "type": "all" } ``` ```json Weighted ranking theme={null} { "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. ```python Python SDK theme={null} 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) ``` ```typescript TypeScript SDK theme={null} import { HydraDBClient } from "@hydradb/sdk"; import { buildString } from "@hydradb/sdk/helpers"; 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 ```bash cURL theme={null} curl -X POST 'https://api.hydradb.com/query' \ -H "Authorization: Bearer " \ -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 }' ``` ```typescript TypeScript SDK theme={null} const result = await client.query({ database: "acme_corp", query: "What is our refund policy?", type: "knowledge", queryBy: "hybrid", mode: "thinking", maxResults: 10, graphContext: true, }); ``` ```python Python SDK theme={null} 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, ) ``` ```bash cURL theme={null} curl -X POST 'https://api.hydradb.com/query' \ -H "Authorization: Bearer " \ -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" }' ``` ```typescript TypeScript SDK theme={null} 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", }); ``` ```python Python SDK theme={null} 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", ) ``` ```bash cURL theme={null} curl -X POST 'https://api.hydradb.com/query' \ -H "Authorization: Bearer " \ -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 }' ``` ```typescript TypeScript SDK theme={null} 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, }); ``` ```python Python SDK theme={null} 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, ) ``` ```bash cURL theme={null} curl -X POST 'https://api.hydradb.com/query' \ -H "Authorization: Bearer " \ -H "API-Version: 2" \ -H "Content-Type: application/json" \ -d '{ "database": "acme_corp", "query": "GDPR Article 17", "type": "knowledge", "query_by": "text", "operator": "phrase" }' ``` ```typescript TypeScript SDK theme={null} const result = await client.query({ database: "acme_corp", query: "GDPR Article 17", type: "knowledge", queryBy: "text", operator: "phrase", }); ``` ```python Python SDK theme={null} result = client.query( database="acme_corp", query="GDPR Article 17", type="knowledge", query_by="text", operator="phrase", ) ``` ```bash cURL theme={null} curl -X POST 'https://api.hydradb.com/query' \ -H "Authorization: Bearer " \ -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" }' ``` ```typescript TypeScript SDK theme={null} 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", }); ``` ```python Python SDK theme={null} 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](#decision-matrix). (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](/essentials/v2/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](#decision-matrix). Each list holds at most 500 values, and the whole object is capped at 64 KiB of compact JSON, measured after operator objects are reduced to their values; over either returns `400`. (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 | 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. | | 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`. | 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. `metadata_filters` are hard exact-match constraints applied before ranking and re-checked after hydration. The shape combines two filter scopes: ```json theme={null} { "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. | Separate keys are ANDed. Each `metadata` (top-level) key takes an operator object naming the comparison: | Operator | Value | Matches | | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `equals` | a single value | sources whose field is **exactly** that value | | `contains` | a single value | sources whose field **holds** that value. Multi-value fields are stored comma-joined, so this matches one member of that list | | `contains_any` | an array | sources holding **any one** of the listed values (OR/IN) | ```json theme={null} "metadata_filters": { "department": { "equals": "legal" }, "attendee_emails": { "contains": "b@company.com" }, "tags": { "contains_any": ["alpha", "beta"] } } ``` Adding values to `contains_any` **widens** the result set. There is no ALL/AND operator within a single key, and range and fuzzy operators are not supported; run multiple queries or post-process client-side for those cases. Operators apply to `metadata` (top-level keys) only. Inside `additional_metadata`, use a bare scalar for an exact match or a bare array to match any listed value. An operator used inside `additional_metadata` is **not** rejected. It is read as an exact-match filter against a stored object, so on a normal field it matches nothing and the request returns `200` with an empty result rather than an error. The bare forms still work and are unchanged, but are **deprecated** in favour of the operators, because the comparison they perform is inferred from the JSON shape rather than stated. A bare scalar behaves as `equals`, a bare array as `contains_any`, and a bare single-element array as `contains` - so `{"emails": "a@x"}` and `{"emails": ["a@x"]}` differ by one character and return different results. `contains`, `contains_any` and lists are supported on `VARCHAR` fields only: any of them passed for a declared field of another type is rejected with `400 VALIDATION_ERROR`. `equals` works on every declared type, so `{"priority": {"equals": 7}}` is valid on an `INT64` field. A known operator given the wrong operand type, or several operators in one object, is rejected with `400 VALIDATION_ERROR`. A **misspelled** operator is not: `{"contian": "x"}` is indistinguishable from a filter for a stored object with that key, so it is left alone and matches nothing. `contains`, `contains_any` and `equals` are reserved key names: an object built only from them is read as an operator and can no longer exact-match a stored object, and an object whose keys are ALL operator names is rejected with `400`. Mixing an operator name with any other key (`{"contains": "a", "other": 1}`) is unaffected. A caller needing the reserved shape must rename the nested key or the field. ```json Success theme={null} { "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": "finance@hydradb.com" } } ], "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 } } ``` ```json Zero results theme={null} { "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 } } ``` ```json Failure theme={null} { "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](/api-reference/v2/endpoint/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](/api-reference/v2/endpoint/source-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](/api-reference/v2/endpoint/source-status) for recently ingested documents before querying. If you omit `collection`, HydraDB queries the default collection; use [List Collections](/api-reference/v2/endpoint/list-sub-tenants) 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](/api-reference/v2/error-responses) for the full list. `400` also covers oversized filters: a `metadata_filters` list above 500 values, or a `metadata_filters` object above 64 KiB of compact JSON. The message names the offending key or reports the actual byte count. See [Filter size limits](/essentials/v2/metadata#filter-size-limits).
**Related Resources** * **Setup first:** [Ingest Context](/api-reference/v2/endpoint/ingest-context) - content must be indexed * **Confirm indexing:** [Ingestion Status](/api-reference/v2/endpoint/source-status) - wait for `completed` (or `graph_creation`) * **Graph follow-up:** [Context Relations](/api-reference/v2/endpoint/source-relations) - inspect relationships in detail * **Concepts:** [Usage → Query](/essentials/v2/query) * **Concepts:** [Concepts → Semantic Search](/essentials/v2/semantic-search) * **Concepts:** [Concepts → Context Graphs](/essentials/v2/context-graphs) * **Response handling:** [Usage → How to Use API Results](/essentials/v2/api-results) * **Read more:** [Query - Overview](/api-reference/v2/endpoint/query-overview) ## OpenAPI ````yaml api-reference/v2/openapi.json POST /query openapi: 3.1.0 info: contact: email: support@hydradb.com name: HydraDB Support description: >- HydraDB Application API — knowledge ingestion, search, and memory management. license: name: Proprietary title: HydraDB Application API version: 0.1.0 servers: - description: Production server url: https://api.hydradb.com security: [] externalDocs: description: '' url: '' paths: /query: post: tags: - query summary: Unified query description: >- Unified query endpoint that dispatches across type and query_by (hybrid/text). Optionally filter by one or more exact document titles with `titles`; these are resolved to source IDs before normal retrieval. Filter with `attributes` (an operator language, pushed into the vector search); `metadata_filters` is deprecated in favour of it and still works. `type` is knowledge (the default), memory, or all (both, merged). Prefer sub_tenant_ids for sub-tenant scoping; legacy sub_tenant_id is deprecated for /query and cannot be sent together with sub_tenant_ids. requestBody: content: application/json: schema: $ref: '#/components/schemas/search.QueryRequest' description: Unified query request required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/handler.Envelope-search_V2RetrievalResult' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponse' description: Bad Request '404': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponse' description: Not Found '500': content: application/json: schema: $ref: '#/components/schemas/handler.ErrorResponse' description: Internal Server Error security: - BearerAuth: [] components: schemas: search.QueryRequest: properties: acl: description: >- ACL scopes retrieval to documents the given principals may access (PRO-1684 document ACLs): a document matches when its stored ACL is empty (unrestricted, pre-RBAC content and connectors without permission support), contains __public__, or intersects these principals. Entries are bare emails or prefixed principals (user_email:/group:/domain:). Omitted, empty, or ["*"] disables ACL filtering entirely, today's behavior. Like IDs, the resulting clause survives the metadata zero-result retry. An entry that is not a known principal fails CLOSED: it matches only public and unrestricted documents, never restricted. items: type: string type: array uniqueItems: false additional_context: description: >- Optional context string prepended to the query to improve retrieval relevance. example: The user is a senior engineer onboarding to the platform. type: string alpha: description: >- 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. attributes: additionalProperties: {} description: >- Attributes is the go-forward metadata filter: a MongoDB-like operator query ($eq/$ne/$gt/$gte/$lt/$lte/$in/$nin/$and/$or/$not/$exists) over the database attributes, translated to a safe Milvus scalar pre-filter by BuildAttributesFilterExpr (PRO-1618). It composes (AND) with the deprecated metadata_filters while both exist. Field names are allowlisted and values escaped, so it is injection-safe. It is applied everywhere metadata_filters is, and nowhere else: the chunks a query returns, the additional context and forceful-relation chunks (the fail-closed post-filter net in the service), and the graph paths, which the graph lane prunes by resolving every source a path cites and dropping the paths that touch one failing the predicate (disallowedGraphSources). Product decision 2026-09-04: `attributes` behaves like `metadata_filters` on every part of the response. type: object code_search: description: |- CodeSearch forces the repository code-search branch on (true) or off (false) for this query, overriding the classifier. Nil = let the classifier decide. Only meaningful where the branch is enabled. example: true type: boolean collection: description: >- 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 type: string collections: description: >- 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. example: - team_docs - engineering oneOf: - example: - finance - legal items: type: string maxItems: 100 minItems: 1 type: array - additionalProperties: exclusiveMinimum: 0 multipleOf: 0.1 type: number example: finance: 1.5 legal: 0.8 maxProperties: 100 minProperties: 1 type: object x-preferred: true database: description: >- 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 type: string graph_context: description: >- Whether to include graph context in the response. Defaults to true for /query when omitted. example: true type: boolean graph_vector_prune: description: >- 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 type: boolean graph_vector_prune_spacy_entities: description: >- 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 type: boolean ids: description: >- 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 items: type: string type: array uniqueItems: false max_results: description: Maximum number of chunks to return. example: 10 type: integer metadata_filters: $ref: '#/components/schemas/search.MetadataFilters' deprecated: true x-deprecated: true mode: $ref: '#/components/schemas/search.RecallMode' example: thinking num_related_chunks: description: >- Number of adjacent chunks to pull alongside each matched chunk for additional context. example: 3 type: integer operator: $ref: '#/components/schemas/search.Operator' example: and profile_entity_type: description: >- ProfileEntityType/ProfileNamespace refine the subject's graph identity; defaults ("PERSON"/"users") cover the common case of a person subject. type: string profile_namespace: type: string profile_subject: description: >- ProfileSubject names the entity whose compiled profile should ride the response as profile_context/profile_filter (PRO-1797). Payload-only: chunk ranking is never altered. Omitted = no profile block. Dark until the repo-level ENTITY_PROFILE_CONTEXT_ENABLED flag is on. type: string query: description: Natural-language search query. example: Which mode does the user prefer? type: string query_apps: description: >- Whether to include app-aware knowledge retrieval. Applies to knowledge hybrid queries. Defaults to true when omitted; pass false to search files only. example: true type: boolean query_by: $ref: '#/components/schemas/search.QueryBy' description: Retrieval method to use for the query. example: hybrid query_forceful_relations: description: >- Whether to force relation expansion for graph-aware query retrieval. Defaults to true when omitted. example: true type: boolean recency_bias: description: >- Recency boost applied to ranking (0.0-1.0). Omit it to get the always-on default baseline of 0.40 (a bounded <=40% swing on normalized relevance — it reorders within a relevance gap of up to 0.40 but never buries a more strongly relevant result); send 0 to disable recency entirely; higher values favour more recent sources more strongly. example: 0.2 type: number sub_tenant_id: deprecated: true description: >- 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 type: string x-deprecated-since: 2.0.1 sub_tenant_ids: deprecated: true description: >- 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. example: - sub_tenant_4567 - sub_tenant_8901 oneOf: - example: - finance - legal items: type: string maxItems: 100 minItems: 1 type: array - additionalProperties: exclusiveMinimum: 0 multipleOf: 0.1 type: number example: finance: 1.5 legal: 0.8 maxProperties: 100 minProperties: 1 type: object x-deprecated: 'true' x-deprecated-since: 2.0.1 temporal_intent: $ref: '#/components/schemas/search.TemporalIntentOverride' example: duration_to_now: true mode: thinking temporal_now: description: >- TemporalNow optionally anchors "now" for temporal reasoning (ISO-8601). Callers replaying past conversations (or backfilling) must supply it or to-now durations and recency windows resolve against the server's wall clock (LongMemEval measured 0 exact to-now durations from this alone). type: string temporal_reasoning: description: >- TemporalReasoning activates the temporal read path: the query is classified into a temporal mode (current/as-of/range/upcoming...), matching edge-level temporal facts are resolved from the edge_temporal store and ride back on the response (temporal_facts / temporal_duration / temporal_filter). CONTRACT: chunk ranking is NEVER altered — ON returns the same chunks as OFF; the layer is additive payload + computed answers only (rank shaping measured net-negative on BEAM/LongMemEval/TEMPO; see temporal_filters.go). Optional; ON by default — pass temporal_reasoning:false to disable. Resolved by GetTemporalReasoningOrDefault (ownership rule). example: true type: boolean tenant_id: deprecated: true description: 'deprecated: use database' example: tenant_1234 type: string x-deprecated: 'true' titles: description: >- Optional exact document-title filter. Values are matched case-insensitively and ORed, resolved to source IDs, then the normal query pipeline runs within that source scope. When ids is also supplied, the two filters are intersected. items: type: string type: array uniqueItems: false type: $ref: '#/components/schemas/search.SourceType' description: >- Corpus to query: knowledge (the default), memory, or all (both, merged). type: object handler.Envelope-search_V2RetrievalResult: properties: data: $ref: '#/components/schemas/search.V2RetrievalResult' example: additional_context: The user is a senior engineer onboarding to the platform. app_search_fusion: stats: app_chunks: 1 app_has_exact_ids: true app_lane_empty_text: true consensus: 1 exact_candidates: 1 exact_promoted: 1 limit: 1 normal_chunks: 1 normal_displaced: 1 tail_added: 1 tail_candidates: 1 stats_by_pass: - app_chunks: 1 app_has_exact_ids: true app_lane_empty_text: true consensus: 1 exact_candidates: 1 exact_promoted: 1 limit: 1 normal_chunks: 1 normal_displaced: 1 tail_added: 1 tail_candidates: 1 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 collection: team_docs 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 code_search: duration_ms: 0.5 repos: - duration_ms: 0.5 error: '' status: completed truncated: true unsigned: true status: completed forceful_relations: declared: - chunk: additional_metadata: author: ada doc_version: 3 chunk_content: >- HydraDB supports hybrid retrieval across knowledge and memories. chunk_uuid: a1b2c3d4-e5f6-7890-1234-567890abcdef collection: team_docs 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 inferred: - chunk: additional_metadata: author: ada doc_version: 3 chunk_content: >- HydraDB supports hybrid retrieval across knowledge and memories. chunk_uuid: a1b2c3d4-e5f6-7890-1234-567890abcdef collection: team_docs 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: paths: - chunk_ids: - HydraEmbeddings123_0 - HydraEmbeddings123_1 combined_context: >- Acme Corp deploys HydraDB in production for context retrieval. relevancy_score: 0.87 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 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 profile_context: entity_id: entity_1a2b entries: - confidence: 0.92 name: general version: 1 profile_filter: applied: true degraded: true entity_id: entity_1a2b found: true selected_entries: 1 version: 1 source_facts: - app_kind: slack chunk_id: HydraEmbeddings123_0 provider: slack relationship_id: rel_1234 source_id: HydraDoc1234 synced_at: 1 source_filter: applied: true degraded: true matched_facts: 1 mode: thinking provider: slack thread_scope: true truncated: true sources: - additional_metadata: author: ada doc_version: 3 app_external_id: C0123456789 app_kind: slack app_provider: slack collection: team_docs 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 temporal_duration: approximate: true days: 1 from: chunk_id: HydraEmbeddings123_0 event_end: 1 event_start: 1 relationship_id: rel_1234 source_id: HydraDoc1234 status: completed pairing_confidence: 0.5 to: chunk_id: HydraEmbeddings123_0 event_end: 1 event_start: 1 relationship_id: rel_1234 source_id: HydraDoc1234 status: completed temporal_facts: - chunk_id: HydraEmbeddings123_0 event_end: 1 event_start: 1 relationship_id: rel_1234 source_id: HydraDoc1234 status: completed temporal_filter: applied: true chunk_scope: 1 degraded: true matched_facts: 1 mode: thinking promoted: 1 truncated: true error: $ref: '#/components/schemas/handler.apiError' description: Error message, empty string on success. example: code: DATABASE_NOT_FOUND message: Database not found meta: $ref: '#/components/schemas/handler.responseMeta' example: collection: team_docs database: acme_corp latency_ms: 12.3 request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d source_type: file sub_tenant_id: sub_tenant_4567 tenant_id: tenant_1234 success: description: Whether the request succeeded. example: true type: boolean type: object handler.ErrorResponse: properties: data: {} detail: $ref: '#/components/schemas/handler.ErrorDetail' description: Structured error detail with code, message, and deprecation hints. example: deprecated: true deprecated_field: tenant_id error_code: VALIDATION_ERROR message: Request validation failed preferred_field: database error: $ref: '#/components/schemas/handler.apiError' description: Error message, empty string on success. example: code: DATABASE_NOT_FOUND message: Database not found meta: $ref: '#/components/schemas/handler.ErrorMeta' example: latency_ms: 12.3 request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d success: description: Whether the request succeeded. example: true type: boolean type: object search.MetadataFilters: additionalProperties: {} description: >- DEPRECATED: use `attributes`, which is an operator language pushed into the vector search rather than bare equality applied after it. `metadata_filters` keeps working, and is still the only way to filter on per-context custom_attributes, which `attributes` does not cover yet. Filters results by context metadata. Top-level keys target tenant metadata (for example department, priority, active, or tags). Nested additional_metadata keys target document metadata. Separate keys are ANDed. Each top-level key accepts an operator object naming the comparison: {"contains": value} matches sources whose field holds that value (multi-value fields are stored comma-joined, so this matches one member); {"contains_any": [values]} matches sources holding ANY one of the listed values; {"equals": value} matches sources whose field is exactly that value. The bare forms remain supported and unchanged but are deprecated in favour of the operators, because the comparison they perform is inferred from the JSON shape rather than stated: a bare scalar behaves as equals, a bare array as contains_any, and a bare single-element array as contains. Operators apply to top-level keys only; inside additional_metadata use the bare scalar or array forms. An operator used inside additional_metadata is NOT rejected - it is read as an exact-match filter against a stored object, so on a normal field it matches nothing and the request returns 200 with an empty result rather than an error. A known operator given the wrong operand type, or several operators in one object, is rejected with 400 VALIDATION_ERROR rather than silently matching nothing. A MISSPELLED operator is not: {"contian": "x"} is indistinguishable from a filter for a stored object with that key, so it is left alone and matches nothing. An object whose keys are not operator names is likewise treated as an exact-match filter against a stored object, unchanged. RESERVED NAMES: contains, contains_any and equals are reserved as the keys of a top-level filter object, so an object built only from them is read as an operator and is no longer available for exact object matching -- {"f": {"contains": "x"}} is read as the operator, and an object whose keys are ALL operator names is rejected with 400. A caller matching such an object in a JSON-typed field must rename the nested key or the field. Mixing an operator name with any other key ({"contains": "a", "other": 1}) is unaffected and still exact-matches. There is no ALL/AND operator within a single key. contains, contains_any and arrays are supported on VARCHAR fields only: any of them passed for a declared field of another type is rejected with 400 VALIDATION_ERROR. equals works on every declared type, so {"priority": {"equals": 7}} is valid on an INT64 field. Size limits: each list may hold at most 500 values, and the whole metadata_filters object is capped at 64 KiB measured on its compact JSON encoding in UTF-8 bytes AFTER operator objects are reduced to their values, so {"contains": "x"} is measured as ["x"] and the operator keyword itself costs nothing. The cap bounds the cost of the resulting vector-store expression, which the operator spelling does not change. Field names and punctuation count. Exceeding either returns 400 naming the offending key or the actual byte count. example: active: true additional_metadata: author: ada department: finance priority: 7 tags: - alpha - beta type: object search.RecallMode: enum: - fast - thinking - auto type: string x-enum-varnames: - RecallModeFast - RecallModeThinking - RecallModeAuto search.Operator: enum: - or - and - phrase type: string x-enum-varnames: - OperatorOr - OperatorAnd - OperatorPhrase search.QueryBy: enum: - hybrid - text type: string x-enum-varnames: - QueryByHybrid - QueryByText search.TemporalIntentOverride: description: |- TemporalIntent (EXPERIMENTAL) lets the caller supply the classification (mode/window/phrases) directly, bypassing the regex classifier — for agents whose own LLM already understands the query, and for non-English queries. Invalid overrides fall back to the classifier. properties: cutoff: type: string duration_to_now: example: true type: boolean event_phrases: items: type: string type: array uniqueItems: false mode: example: thinking type: string window_end: type: string window_start: type: string type: object search.SourceType: description: >- Source is the wire field `type` (Python QueryRequest.source has alias="type"). SourceLegacy accepts the pre-rename `source` key (Python populate_by_name=True keeps the field name valid on input); resolveSourceAlias folds it into Source. enum: - knowledge - memory - all type: string x-enum-varnames: - SourceKnowledge - SourceMemory - SourceAll search.V2RetrievalResult: properties: additional_context: additionalProperties: $ref: '#/components/schemas/search.V2Chunk' deprecated: true description: 'deprecated: use forceful_relations' example: The user is a senior engineer onboarding to the platform. type: object x-deprecated: 'true' alias_expansions: description: >- AliasExpansions is the alias layer's honesty stamp (V0): which nickname was expanded to which canonical name for this answer. items: $ref: '#/components/schemas/search.AliasExpansionNote' type: array uniqueItems: false app_search_fusion: $ref: '#/components/schemas/search.AppSearchFusionDiagnostics' description: >- App-search fusion diagnostics for unscoped requests: final returned chunk attribution and pre-postprocessing fusion counts. Omitted for ACL-scoped requests and when no attributed chunks remain. example: stats: app_chunks: 1 app_has_exact_ids: true app_lane_empty_text: true consensus: 1 exact_candidates: 1 exact_promoted: 1 limit: 1 normal_chunks: 1 normal_displaced: 1 tail_added: 1 tail_candidates: 1 stats_by_pass: - app_chunks: 1 app_has_exact_ids: true app_lane_empty_text: true consensus: 1 exact_candidates: 1 exact_promoted: 1 limit: 1 normal_chunks: 1 normal_displaced: 1 tail_added: 1 tail_candidates: 1 chunks: description: Retrieved and ranked chunks from the knowledge store or memories. example: - additional_metadata: author: ada doc_version: 3 chunk_content: HydraDB supports hybrid retrieval across knowledge and memories. chunk_uuid: a1b2c3d4-e5f6-7890-1234-567890abcdef collection: team_docs 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 items: $ref: '#/components/schemas/search.V2Chunk' type: array uniqueItems: false code_search: $ref: '#/components/schemas/search.CodeSearchResult' example: duration_ms: 0.5 repos: - duration_ms: 0.5 error: '' status: completed truncated: true unsigned: true status: completed forceful_relations: $ref: '#/components/schemas/search.ForcefulRelationsBucket' example: declared: - chunk: additional_metadata: author: ada doc_version: 3 chunk_content: >- HydraDB supports hybrid retrieval across knowledge and memories. chunk_uuid: a1b2c3d4-e5f6-7890-1234-567890abcdef collection: team_docs 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 inferred: - chunk: additional_metadata: author: ada doc_version: 3 chunk_content: >- HydraDB supports hybrid retrieval across knowledge and memories. chunk_uuid: a1b2c3d4-e5f6-7890-1234-567890abcdef collection: team_docs 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: $ref: '#/components/schemas/search.GraphPlane' example: paths: - chunk_ids: - HydraEmbeddings123_0 - HydraEmbeddings123_1 combined_context: Acme Corp deploys HydraDB in production for context retrieval. relevancy_score: 0.87 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 graph_context: $ref: '#/components/schemas/search.GraphContext' example: 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 profile_context: $ref: '#/components/schemas/search.ProfileContext' example: entity_id: entity_1a2b entries: - confidence: 0.92 name: general version: 1 profile_filter: $ref: '#/components/schemas/search.ProfileFilterInfo' example: applied: true degraded: true entity_id: entity_1a2b found: true selected_entries: 1 version: 1 source_facts: description: |- SourceFacts surface the matched app-native (edge_source) facts when source_reasoning was active; omitted otherwise (PRO-1602). example: - app_kind: slack chunk_id: HydraEmbeddings123_0 provider: slack relationship_id: rel_1234 source_id: HydraDoc1234 synced_at: 1 items: $ref: '#/components/schemas/search.SourceFact' type: array uniqueItems: false source_filter: $ref: '#/components/schemas/search.SourceFilterInfo' example: applied: true degraded: true matched_facts: 1 mode: thinking provider: slack thread_scope: true truncated: true sources: description: Deduplicated source-level metadata for all returned chunks. example: - additional_metadata: author: ada doc_version: 3 app_external_id: C0123456789 app_kind: slack app_provider: slack collection: team_docs 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 items: $ref: '#/components/schemas/search.SourceInfo' type: array uniqueItems: false temporal_duration: $ref: '#/components/schemas/search.TemporalDuration' example: approximate: true days: 1 from: chunk_id: HydraEmbeddings123_0 event_end: 1 event_start: 1 relationship_id: rel_1234 source_id: HydraDoc1234 status: completed pairing_confidence: 0.5 to: chunk_id: HydraEmbeddings123_0 event_end: 1 event_start: 1 relationship_id: rel_1234 source_id: HydraDoc1234 status: completed temporal_facts: description: |- TemporalFacts surface the matched edge-level temporal facts when temporal_reasoning was requested; omitted otherwise. example: - chunk_id: HydraEmbeddings123_0 event_end: 1 event_start: 1 relationship_id: rel_1234 source_id: HydraDoc1234 status: completed items: $ref: '#/components/schemas/search.TemporalFact' type: array uniqueItems: false temporal_filter: $ref: '#/components/schemas/search.TemporalFilterInfo' example: applied: true chunk_scope: 1 degraded: true matched_facts: 1 mode: thinking promoted: 1 truncated: true type: object handler.apiError: properties: code: description: Machine-readable error code (e.g. `DATABASE_NOT_FOUND`). example: DATABASE_NOT_FOUND type: string message: description: Human-readable description of the error. example: Database not found type: string type: object handler.responseMeta: properties: api_version: description: >- APIVersion echoes the version of the API that served the request (PRO-1209), sourced from reqmeta.APIVersion — the same value carried by OpenAPI info.version and /health — so a client always knows which API version produced a response. Always present (no omitempty). type: string collection: description: >- 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 type: string database: description: >- Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated). example: acme_corp type: string deprecation: description: >- Deprecation lists any migration nudges that apply to this request — the caller used a legacy /tenants route, a legacy tenant_id/sub_tenant_id field, or the deprecated sub_tenant_ids selector. It is a non-breaking signal (the status code is unchanged); omitempty keeps it absent for fully-migrated requests. A list so independent deprecations coexist without clobbering. items: $ref: '#/components/schemas/handler.deprecationNotice' type: array uniqueItems: false latency_ms: description: Server-side processing time in milliseconds. example: 12.3 type: number request_id: description: Unique identifier for this request, useful for support and tracing. example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d type: string source_type: description: Type of the parent source (e.g. `file`, `slack`, `notion`). example: file type: string sub_tenant_id: deprecated: true example: sub_tenant_4567 type: string x-deprecated: 'true' tenant_id: deprecated: true example: tenant_1234 type: string x-deprecated: 'true' type: object handler.ErrorDetail: properties: deprecated: description: Whether this response concerns a deprecated field or route. example: true type: boolean deprecated_field: description: The deprecated field name. example: tenant_id type: string error_code: description: Machine-readable error classification code. example: VALIDATION_ERROR type: string message: description: Human-readable description of the error. example: Request validation failed type: string preferred_field: description: The canonical replacement for the deprecated field. example: database type: string success: deprecated: true description: >- Deprecated for API clients: always false on this path, so it carries no information. To detect a failure read the HTTP status code; for what went wrong read the envelope's error.code and error.message, and meta.request_id when reporting it. The whole `detail` object is deprecated legacy — tagging the field individually so SDK users see it on the property, not just the container (PRO-1208). example: true type: boolean x-deprecated: 'true' type: object handler.ErrorMeta: properties: api_version: type: string latency_ms: example: 12.3 type: number request_id: description: Unique identifier for this request, useful for support and tracing. example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d type: string type: object search.V2Chunk: properties: additional_metadata: additionalProperties: {} description: >- Pydantic aliases (see VectorStoreChunk): document_metadata→additional_metadata, tenant_metadata→metadata. FastAPI serializes by_alias, so the wire uses the aliases. example: author: ada doc_version: 3 type: object chunk_content: description: Text content of this chunk. example: HydraDB supports hybrid retrieval across knowledge and memories. type: string chunk_uuid: description: Unique identifier for this individual chunk. example: a1b2c3d4-e5f6-7890-1234-567890abcdef type: string collection: description: >- Collection this chunk belongs to. Canonical name; mirrors the deprecated `sub_tenant_id` alias. example: team_docs type: string extra_context_ids: description: IDs of adjacent chunks pulled in as surrounding context. example: - HydraEmbeddings123_2 - HydraEmbeddings123_3 items: type: string type: array uniqueItems: false id: description: Unique identifier for this resource. example: HydraDoc1234 type: string layout: description: >- Layout classification for this chunk (e.g. `text`, `table`, `image`). example: text type: string metadata: additionalProperties: {} description: Schema-backed tenant metadata attached to the source. example: department: finance priority: 7 type: object relevancy_score: description: Relevance score for this item against the query. example: 0.87 type: number source_last_updated_time: description: RFC3339 timestamp when the source was last modified. example: '2026-07-02T12:30:00Z' type: string source_title: description: Title of the parent source document. example: Project Phoenix Overview type: string source_type: description: Type of the parent source (e.g. `file`, `slack`, `notion`). example: file type: string source_upload_time: description: RFC3339 timestamp when the source was ingested. example: '2026-07-02T10:00:00Z' type: string sub_tenant_id: deprecated: true description: 'deprecated: use collection' example: sub_tenant_4567 type: string x-deprecated: 'true' type: object search.AliasExpansionNote: properties: alias: type: string canonical: type: string type: object search.AppSearchFusionDiagnostics: description: |- AppSearchFusion is the diagnostic block of the query_apps fusion (PRO-1882): per-chunk lane attribution and counts. Present only when query_apps was on, the request was not ACL-scoped, and attributed chunks survived final filtering. Identifier maps cover only returned chunks. properties: app_recipes: additionalProperties: type: string description: >- AppRecipes maps the chunk_uuid of each final chunk the app lane returned to the recipe that produced it (exact_id, recall, dated, bm25, broad, ...), including chunks the normal lane also had, so a consensus can be attributed to a recipe. type: object chunk_origins: additionalProperties: type: string description: >- ChunkOrigins maps every returned chunk_uuid to where the fusion placed it from: "normal" (normal lane only), "both" (both lanes, normal position kept), "exact_id" (promoted from the app lane's exact-identifier recipe), "app_tail" (appended from the app lane). type: object stats: $ref: '#/components/schemas/search.AppSearchFusionStats' description: >- Counts for the first or only fusion pass before postprocessing, not final response counts or totals across alias alternatives. The entire diagnostic block is omitted for ACL-scoped requests. example: app_chunks: 1 app_has_exact_ids: true app_lane_empty_text: true consensus: 1 exact_candidates: 1 exact_promoted: 1 limit: 1 normal_chunks: 1 normal_displaced: 1 tail_added: 1 tail_candidates: 1 stats_by_pass: description: >- StatsByPass preserves each independent fusion's accounting when results combine multiple passes, in merge order (original before alternate when both have diagnostics). Counts overlap; they are not unique totals. example: - app_chunks: 1 app_has_exact_ids: true app_lane_empty_text: true consensus: 1 exact_candidates: 1 exact_promoted: 1 limit: 1 normal_chunks: 1 normal_displaced: 1 tail_added: 1 tail_candidates: 1 items: $ref: '#/components/schemas/search.AppSearchFusionStats' type: array uniqueItems: false type: object search.CodeSearchResult: description: CodeSearch is the repository code-search branch's answer, when routed. properties: decided_by: description: >- DecidedBy names the signal that routed the query: "request" (caller forced it), "planner" (is_code_query) or "stage2" (embedding router). type: string duration_ms: description: DurationMS is the wall time the branch took. example: 0.5 type: number reason: description: Reason explains a non-ok status in one sentence. type: string repos: description: Repos lists each repository searched with its own status and answer. example: - duration_ms: 0.5 error: '' status: completed truncated: true unsigned: true items: $ref: '#/components/schemas/search.CodeSearchRepoResult' type: array uniqueItems: false status: description: >- Status is "ok" when at least one repository answered, "not_found" when none had an archive, "error"/"timeout" when the branch failed, or "skipped" with a Reason when it was not attempted (no repositories connected, caller opted out). example: completed type: string type: object search.ForcefulRelationsBucket: description: |- ForcefulRelations is the caller-declared relation bucket, carrying the from->to edge that additional_context discards when it flattens these into a chunk-uuid map. Always present, so a caller can read it unconditionally. properties: declared: example: - chunk: additional_metadata: author: ada doc_version: 3 chunk_content: >- HydraDB supports hybrid retrieval across knowledge and memories. chunk_uuid: a1b2c3d4-e5f6-7890-1234-567890abcdef collection: team_docs 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 items: $ref: '#/components/schemas/search.ForcefulRelationEntry' type: array uniqueItems: false inferred: example: - chunk: additional_metadata: author: ada doc_version: 3 chunk_content: >- HydraDB supports hybrid retrieval across knowledge and memories. chunk_uuid: a1b2c3d4-e5f6-7890-1234-567890abcdef collection: team_docs 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 items: $ref: '#/components/schemas/search.ForcefulRelationEntry' type: array uniqueItems: false type: object search.GraphPlane: description: |- Graph is the consolidated graph plane: query_paths and chunk_relations consolidated into one ordered paths[] list, with each path carrying the chunk ids it supports so the caller no longer joins against chunk_id_to_group_ids. Populated whenever graph_context is on; graph_context stays populated beside it. properties: paths: example: - chunk_ids: - HydraEmbeddings123_0 - HydraEmbeddings123_1 combined_context: Acme Corp deploys HydraDB in production for context retrieval. relevancy_score: 0.87 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 items: $ref: '#/components/schemas/search.GraphPath' type: array uniqueItems: false type: object search.GraphContext: deprecated: true description: |- GraphContext is omitted entirely when graph_context is disabled on the request (pointer + omitempty), so the response carries no graph slice instead of an empty-but-present object. properties: chunk_id_to_group_ids: additionalProperties: items: type: string type: array description: Mapping from chunk ID to the relation group IDs it participates in. example: HydraEmbeddings123_0: - grp_1234 type: object chunk_relations: description: Scored relation paths relevant to the query, grouped by chunk. example: - 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 items: $ref: '#/components/schemas/search.ScoredPathResponse' type: array uniqueItems: false query_paths: description: Scored relation paths ranked by relevance to the query. example: - 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 items: $ref: '#/components/schemas/search.ScoredPathResponse' type: array uniqueItems: false type: object x-deprecated: 'true' search.ProfileContext: description: |- ProfileContext/ProfileFilter surface the entity-profile block when the request named a profile_subject (PRO-1797); omitted otherwise. properties: entity_id: description: Unique identifier for this entity in the graph. example: entity_1a2b type: string entries: example: - confidence: 0.92 items: $ref: '#/components/schemas/search.ProfileEntry' type: array uniqueItems: false headline: type: string name: description: Human-readable label for this resource. example: general type: string perspective: type: string subject: type: string summary: type: string version: example: 1 type: integer type: object search.ProfileFilterInfo: properties: applied: example: true type: boolean degraded: example: true type: boolean entity_id: description: Unique identifier for this entity in the graph. example: entity_1a2b type: string found: example: true type: boolean selected_entries: example: 1 type: integer subject: type: string version: example: 1 type: integer type: object search.SourceFact: properties: actor: type: string actor_role: type: string app_kind: description: App integration category, populated for connector-synced sources. example: slack type: string chunk_id: description: Chunk that provides evidence for this relation. example: HydraEmbeddings123_0 type: string connector: type: string container: type: string provider: description: >- External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`). example: slack type: string relation: type: string relationship_id: description: Unique identifier for this relationship instance. example: rel_1234 type: string source_id: example: HydraDoc1234 type: string synced_at: example: 1 type: integer thread_id: type: string type: object search.SourceFilterInfo: description: SourceFilter reports what the source layer did for this request. properties: actor_scope: type: string applied: example: true type: boolean container_scope: type: string degraded: example: true type: boolean matched_facts: example: 1 type: integer mode: example: thinking type: string provider: description: >- External provider being synced (e.g. `slack`, `github`, `linear`, `notion`, `gmail`). example: slack type: string thread_scope: example: true type: boolean truncated: example: true type: boolean type: object search.SourceInfo: properties: additional_metadata: additionalProperties: {} description: Per-document free-form metadata. example: author: ada doc_version: 3 type: object app_external_id: description: >- Provider-assigned identifier for this source (e.g. Slack channel ID). example: C0123456789 type: string app_kind: description: >- App-source fields (populated when the source comes from an app integration). Default null on the wire when absent. example: slack type: string app_provider: description: Provider name for app-sourced items (e.g. `slack`, `github`). example: slack type: string collection: description: >- Collection this source belongs to. Canonical name; mirrors the deprecated `sub_tenant_id` alias. example: team_docs type: string description: description: Human-readable description of the source. example: Internal overview of the Project Phoenix rollout. type: string id: description: Unique identifier for this resource. example: HydraDoc1234 type: string metadata: additionalProperties: {} description: >- Pydantic aliases (see VectorStoreChunk). Source metadata defaults to {} on the wire (Python default_factory=dict), unlike chunk metadata which is null. example: department: finance priority: 7 type: object sub_tenant_id: deprecated: true description: 'deprecated: use collection' example: sub_tenant_4567 type: string x-deprecated: 'true' timestamp: description: RFC3339 timestamp associated with this item. example: '2026-07-02T10:00:00Z' type: string title: description: Title or name of the source. example: Project Phoenix Overview type: string type: description: Source content category (e.g. `knowledge`, `memory`). example: knowledge type: string url: description: URL to the original source, if available. example: https://docs.hydradb.com/phoenix type: string type: object search.TemporalDuration: description: TemporalDuration is the computed event-duration answer, when resolved. properties: approximate: description: >- Approximate is set when either endpoint's granularity is coarser than a day (month/year brackets) — the day count is then a floor-to-floor estimate, not an exact span; consumers should not present it as exact. example: true type: boolean days: example: 1 type: integer from: $ref: '#/components/schemas/search.TemporalFact' example: chunk_id: HydraEmbeddings123_0 event_end: 1 event_start: 1 relationship_id: rel_1234 source_id: HydraDoc1234 status: completed from_date: type: string pairing_confidence: description: >- PairingConfidence is the normalized pair-scorer margin (0..1); low values mean the endpoints were weakly anchored to the question. Durations whose endpoints share no entity token with the question are suppressed entirely (P4: a wrong confident day count misleads answerers). example: 0.5 type: number to: $ref: '#/components/schemas/search.TemporalFact' example: chunk_id: HydraEmbeddings123_0 event_end: 1 event_start: 1 relationship_id: rel_1234 source_id: HydraDoc1234 status: completed to_date: type: string type: object search.TemporalFact: properties: chunk_id: description: Chunk that provides evidence for this relation. example: HydraEmbeddings123_0 type: string date_precision: description: >- DatePrecision is the resolution of the resolved dates: "day", "month", "year" (coarser-than-day dates are floored to bracket starts). type: string event_end: example: 1 type: integer event_start: example: 1 type: integer evidence_phrase: description: |- EvidencePhrase is the verbatim source phrase the dates were resolved from (e.g. "today", "two weeks ago"). type: string fact_type: type: string object: type: string relation: type: string relationship_id: description: Unique identifier for this relationship instance. example: rel_1234 type: string source_id: example: HydraDoc1234 type: string status: description: Current lifecycle or processing state. example: completed type: string subject: type: string type: object search.TemporalFilterInfo: description: TemporalFilter reports what the temporal layer did for this request. properties: applied: description: >- Applied is true when the temporal layer engaged for a classified temporal query — including when it matched zero dated facts; MatchedFacts carries the actual count. It is false only when the fact lookup degraded (Degraded). example: true type: boolean chunk_scope: example: 1 type: integer degraded: description: >- Degraded is true when the fact lookup FAILED (as opposed to matching nothing) — callers must not read an empty payload as "no temporal facts exist" when this is set. example: true type: boolean matched_facts: example: 1 type: integer mode: example: thinking type: string promoted: example: 1 type: integer scope: description: >- Scope reports how the chunk scope was applied: "soft" (bounded ranking promotion) or "" (no scope). Hard scoping was removed after TEMPO. type: string truncated: example: true type: boolean type: object handler.deprecationNotice: properties: deprecated: description: Whether this response concerns a deprecated field or route. example: true type: boolean deprecated_field: description: The deprecated field name. example: tenant_id type: string deprecated_since: description: API version when the field was deprecated. example: 2.0.1 type: string message: description: Migration guidance message. example: tenant_id is deprecated; use database instead. type: string preferred_field: description: The canonical replacement for the deprecated field. example: database type: string type: object search.AppSearchFusionStats: description: |- Stats describes the first (or only) fusion pass before postprocessing, not final counts or a sum across alias alternatives/fan-out branches. properties: app_chunks: description: AppChunks is what the app lane returned. example: 1 type: integer app_has_exact_ids: description: AppHasExactIDs mirrors the app plan's exact-identifier marker. example: true type: boolean app_lane_empty_text: description: >- AppLaneEmptyText is true when the app lane returned no chunks (sources or side context only). example: true type: boolean consensus: description: >- Consensus counts app chunks the normal lane already had; they keep the normal lane's position. example: 1 type: integer exact_candidates: description: |- ExactCandidates counts app chunks the exact-identifier recipe found; ExactPromoted is how many of them were placed above the normal lane. example: 1 type: integer exact_promoted: description: Exact-identifier chunks placed above the normal lane. example: 1 type: integer limit: description: Limit is the final chunk limit the fusion applied. example: 1 type: integer normal_chunks: description: NormalChunks is what the normal lane returned. example: 1 type: integer normal_displaced: description: |- NormalDisplaced counts normal-lane chunks the promoted block and the tail pushed past the limit. example: 1 type: integer tail_added: description: App-only chunks appended within the tail budget. example: 1 type: integer tail_candidates: description: >- TailCandidates counts app-only chunks eligible for the tail; TailAdded is how many were appended within the tail budget. example: 1 type: integer type: object search.CodeSearchRepoResult: properties: answer: type: string duration_ms: example: 0.5 type: number error: description: Error message, empty string on success. example: '' type: string repo: type: string status: description: Current lifecycle or processing state. example: completed type: string truncated: example: true type: boolean unsigned: example: true type: boolean type: object search.ForcefulRelationEntry: properties: chunk: $ref: '#/components/schemas/search.V2Chunk' example: additional_metadata: author: ada doc_version: 3 chunk_content: HydraDB supports hybrid retrieval across knowledge and memories. chunk_uuid: a1b2c3d4-e5f6-7890-1234-567890abcdef collection: team_docs 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 via: $ref: '#/components/schemas/search.RelationVia' type: object search.GraphPath: properties: chunk_ids: example: - HydraEmbeddings123_0 - HydraEmbeddings123_1 items: type: string type: array uniqueItems: false combined_context: description: Merged text from all chunk passages in this relation path. example: Acme Corp deploys HydraDB in production for context retrieval. type: string relevancy_score: description: Relevance score for this item against the query. example: 0.87 type: number triplets: description: Knowledge-graph triplets that make up this relation path. example: - 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 items: $ref: '#/components/schemas/search.PathTriplet' type: array uniqueItems: false type: object search.ScoredPathResponse: properties: combined_context: description: Merged text from all chunk passages in this relation path. example: Acme Corp deploys HydraDB in production for context retrieval. type: string group_id: description: Unique identifier for this relation group. example: grp_1234 type: string relevancy_score: description: Relevance score for this item against the query. example: 0.87 type: number source_chunk_ids: description: IDs of the chunks that contribute to this relation path. example: - HydraEmbeddings123_0 - HydraEmbeddings123_1 items: type: string type: array uniqueItems: false triplets: description: Knowledge-graph triplets that make up this relation path. example: - 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 items: $ref: '#/components/schemas/search.PathTriplet' type: array uniqueItems: false type: object search.ProfileEntry: properties: confidence: description: Confidence score, from 0 to 1. example: 0.92 type: number facet: type: string since: type: string slot: type: string state: description: stated | observed | inferred | record type: string statement_keys: items: type: string type: array uniqueItems: false text: type: string type: object search.RelationVia: properties: from: type: string to: type: string type: object search.PathTriplet: properties: relation: additionalProperties: {} description: Relation properties including predicate and confidence score. example: confidence: 0.92 predicate: works_at type: object source: additionalProperties: {} description: Source entity of the relationship. example: entity_id: entity_1a2b name: Ada type: person type: object target: additionalProperties: {} description: Target entity of the relationship. example: entity_id: entity_3c4d name: Acme Corp type: organization type: object type: object securitySchemes: BearerAuth: bearerFormat: API key description: 'API key sent as a Bearer token: "Bearer prefix.secret"' scheme: bearer type: http ````