v1

latestOpenAPI 3.1.0Proprietary2026-07-262570100.1 KB

query

Unified 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.

post/query

Request body

additional_contextstring

Optional context string prepended to the query to improve retrieval relevance.

{"stackTrail":"components:schemas:search.QueryRequest:properties:alpha","oasType":"schema","type":"unknown","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."}

collectionstring

Collection scope. Defaults to the default collection when omitted. Formerly sub_tenant_id; the sub_tenant_id alias is still accepted (deprecated).

databasestring

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_contextboolean

Whether to include graph context in the response. Defaults to true for /query when omitted.

graph_vector_pruneboolean

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_entitiesboolean

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.

idsstring[]

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_resultsinteger

Maximum number of chunks to return.

metadata_filtersSearchMetadataFilters

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_chunksinteger

Number of adjacent chunks to pull alongside each matched chunk for additional context.

operator'or' | 'and' | 'phrase'

querystring

Natural-language search query.

query_appsboolean

Whether to include app-aware knowledge retrieval. Applies to knowledge hybrid queries.

query_by'hybrid' | 'text'

query_forceful_relationsboolean

Whether to force relation expansion for graph-aware query retrieval. Defaults to true when omitted.

recency_biasnumber

Recency boost applied to ranking. 0 disables it; higher values favour more recent sources.

sub_tenant_idstring

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.

tenant_idstring

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.

Example request

{
  "additional_context": "The user is a senior engineer onboarding to the platform.",
  "collection": "team_docs",
  "collections": [
    "finance",
    "legal"
  ],
  "database": "acme_corp",
  "graph_context": true,
  "graph_vector_prune": true,
  "graph_vector_prune_spacy_entities": true,
  "ids": [
    "HydraDoc1234",
    "HydraDoc4567"
  ],
  "max_results": 10,
  "metadata_filters": {
    "active": true,
    "additional_metadata": {
      "author": "ada"
    },
    "department": "finance",
    "priority": 7,
    "tags": [
      "alpha",
      "beta"
    ]
  },
  "num_related_chunks": 3,
  "query": "Which mode does the user prefer?",
  "query_apps": true,
  "query_forceful_relations": true,
  "recency_bias": 0.2,
  "sub_tenant_id": "sub_tenant_4567",
  "sub_tenant_ids": [
    "finance",
    "legal"
  ],
  "tenant_id": "tenant_1234"
}

Response

successboolean

Whether the request succeeded.

Example response

{
  "data": {
    "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",
        "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_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"
              }
            }
          ]
        }
      ]
    },
    "sources": [
      {
        "additional_metadata": {
          "author": "ada",
          "doc_version": 3
        },
        "app_external_id": "C0123456789",
        "app_kind": "slack",
        "app_provider": "slack",
        "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"
      }
    ]
  },
  "error": {
    "code": "DATABASE_NOT_FOUND",
    "message": "Database not found"
  },
  "meta": {
    "collection": "team_docs",
    "database": "acme_corp",
    "deprecation": [
      {
        "deprecated": true,
        "deprecated_field": "tenant_id",
        "deprecated_since": "2.0.1",
        "message": "tenant_id is deprecated; use database instead.",
        "preferred_field": "database"
      }
    ],
    "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": true
}