---
title: "Unified query"
method: POST
path: "/query"
tags: ["query"]
---

# Unified query

`POST /query`

Unified query endpoint that dispatches across type (knowledge/memory/all) and query_by (hybrid/text). 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.

## Request body

- SearchQueryRequest
  - `additional_context` string — Optional context string prepended to the query to improve retrieval relevance.
  - `alpha` unknown
  - `collection` string — Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).
  - `collections` union — 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.
    - string[]
    - object
  - `database` string — 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.
  - `graph_context` boolean — Whether to include graph context in the response. Defaults to true for /query when omitted.
  - `graph_vector_prune` boolean — 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.
  - `graph_vector_prune_spacy_entities` boolean — 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.
  - `ids` string[] — 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.
  - `max_results` integer — Maximum number of chunks to return.
  - `metadata_filters` SearchMetadataFilters — Filters results by source metadata. Top-level keys target tenant metadata (for example department, priority, active, or tags). Nested additional_metadata keys target document metadata. Values are exact-match scalars or arrays for set-equality/list-style filters.
  - `mode` 'fast' | 'thinking' | 'auto'
  - `num_related_chunks` integer — Number of adjacent chunks to pull alongside each matched chunk for additional context.
  - `operator` 'or' | 'and' | 'phrase'
  - `query` string — Natural-language search query.
  - `query_apps` boolean — Whether to include app-aware knowledge retrieval. Applies to knowledge hybrid queries.
  - `query_by` 'hybrid' | 'text'
  - `query_forceful_relations` boolean — Whether to force relation expansion for graph-aware query retrieval. Defaults to true when omitted.
  - `recency_bias` number — Recency boost applied to ranking. 0 disables it; higher values favour more recent sources.
  - `sub_tenant_id` string — 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.
  - `sub_tenant_ids` union — 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.
    - string[]
    - object
  - `tenant_id` string — deprecated: use database
  - `type` 'knowledge' | 'memory' | 'all' — 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.

## Response `200`

OK

- HandlerEnvelopeSearchV2RetrievalResult
  - `data` SearchV2RetrievalResult
    - `additional_context` object — Map of chunk ID to chunk content for sources declared as related by the author (query_forceful_relations).
    - `chunks` SearchV2Chunk[] — Retrieved and ranked chunks from the knowledge store or memories.
      - `additional_metadata` object — Pydantic aliases (see VectorStoreChunk): document_metadata→additional_metadata, tenant_metadata→metadata. FastAPI serializes by_alias, so the wire uses the aliases.
      - `chunk_content` string — Text content of this chunk.
      - `chunk_uuid` string — Unique identifier for this individual chunk.
      - `extra_context_ids` string[] — IDs of adjacent chunks pulled in as surrounding context.
      - `id` string — Unique identifier for this resource.
      - `layout` string — Layout classification for this chunk (e.g. `text`, `table`, `image`).
      - `metadata` object — Schema-backed tenant metadata attached to the source.
      - `relevancy_score` number — Relevance score for this item against the query.
      - `source_last_updated_time` string — RFC3339 timestamp when the source was last modified.
      - `source_title` string — Title of the parent source document.
      - `source_type` string — Type of the parent source (e.g. `file`, `slack`, `notion`).
      - `source_upload_time` string — RFC3339 timestamp when the source was ingested.
      - `sub_tenant_id` string — Collection this chunk belongs to.
    - `graph_context` SearchGraphContext — 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.
      - `chunk_id_to_group_ids` object — Mapping from chunk ID to the relation group IDs it participates in.
      - `chunk_relations` SearchScoredPathResponse[] — Scored relation paths relevant to the query, grouped by chunk.
        - `combined_context` string — Merged text from all chunk passages in this relation path.
        - `group_id` string — Unique identifier for this relation group.
        - `relevancy_score` number — Relevance score for this item against the query.
        - `source_chunk_ids` string[] — IDs of the chunks that contribute to this relation path.
        - `triplets` SearchPathTriplet[] — Knowledge-graph triplets that make up this relation path.
          - `relation` object — Relation properties including predicate and confidence score.
          - `source` object — Source entity of the relationship.
          - `target` object — Target entity of the relationship.
      - `query_paths` SearchScoredPathResponse[] — Scored relation paths ranked by relevance to the query.
        - `combined_context` string — Merged text from all chunk passages in this relation path.
        - `group_id` string — Unique identifier for this relation group.
        - `relevancy_score` number — Relevance score for this item against the query.
        - `source_chunk_ids` string[] — IDs of the chunks that contribute to this relation path.
        - `triplets` SearchPathTriplet[] — Knowledge-graph triplets that make up this relation path.
          - `relation` object — Relation properties including predicate and confidence score.
          - `source` object — Source entity of the relationship.
          - `target` object — Target entity of the relationship.
    - `sources` SearchSourceInfo[] — Deduplicated source-level metadata for all returned chunks.
      - `additional_metadata` object — Per-document free-form metadata.
      - `app_external_id` string — Provider-assigned identifier for this source (e.g. Slack channel ID).
      - `app_kind` string — App-source fields (populated when the source comes from an app integration). Default null on the wire when absent.
      - `app_provider` string — Provider name for app-sourced items (e.g. `slack`, `github`).
      - `description` string — Human-readable description of the source.
      - `id` string — Unique identifier for this resource.
      - `metadata` object — Pydantic aliases (see VectorStoreChunk). Source metadata defaults to {} on the wire (Python default_factory=dict), unlike chunk metadata which is null.
      - `sub_tenant_id` string — Collection this source belongs to.
      - `timestamp` string — RFC3339 timestamp associated with this item.
      - `title` string — Title or name of the source.
      - `type` string — Source content category (e.g. `knowledge`, `memory`).
      - `url` string — URL to the original source, if available.
  - `error` HandlerApiError
    - `code` string — Machine-readable error code (e.g. `DATABASE_NOT_FOUND`).
    - `message` string — Human-readable description of the error.
  - `meta` HandlerResponseMeta
    - `api_version` string — 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).
    - `collection` string — Collection scope. Defaults to the default collection when omitted. Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still accepted (deprecated).
    - `database` string — Owning database. Formerly `tenant_id`; the `tenant_id` alias is still accepted (deprecated).
    - `deprecation` HandlerDeprecationNotice[] — 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.
      - `deprecated` boolean — Whether this response concerns a deprecated field or route.
      - `deprecated_field` string — The deprecated field name.
      - `deprecated_since` string — API version when the field was deprecated.
      - `message` string — Migration guidance message.
      - `preferred_field` string — The canonical replacement for the deprecated field.
    - `latency_ms` number — Server-side processing time in milliseconds.
    - `request_id` string — Unique identifier for this request, useful for support and tracing.
    - `source_type` string — Type of the parent source (e.g. `file`, `slack`, `notion`).
    - `sub_tenant_id` string
    - `tenant_id` string
  - `success` boolean — Whether the request succeeded.

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.dev/hydradb/apis/hydradb-application-api.md) · [All operations](https://skmtc.dev/hydradb/apis/hydradb-application-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hydradb/hydradb-application-api/revisions/c773cb4e113a/schema)