Hybrid Search — MDDB API

Combined sparse (FTS) + dense (vector) search with fusion strategies

Hybrid sparse+dense search #

POST /v1/hybrid-search

Combine FTS (keyword) and vector (semantic) search into a single query. Returns results ranked by a fused score.

Fusion strategies:

• alpha (default): Weighted alpha blending — combined = (1-alpha) * normalizedFTS + alpha * vectorScore. Alpha=0 is pure keyword, alpha=1 is pure semantic.
• rrf: Reciprocal Rank Fusion — score = 1/(k + rank_fts) + 1/(k + rank_vector). Rank-based, no alpha needed.

FTS algorithms: bm25 (default), bm25f (field-weighted).

Vector algorithms: flat (default), hnsw, ivf, pq, opq, sq, sq4, bq.

Use filterMeta to pre-filter by metadata before both FTS and vector scoring.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: HybridSearchRequest

{
  "algorithm": "bm25",
  "alpha": 0.5,
  "bm25B": 0.75,
  "bm25K1": 0,
  "boost": {
    "status:archived": -3,
    "tag:featured": 2
  },
  "collection": "blog",
  "disableStem": false,
  "disableSynonyms": false,
  "distanceMetric": "cosine",
  "explain": false,
  "facetBy": [
    "string"
  ],
  "facetMaxValues": 0,
  "feedbackMode": "query",
  "feedbackWeight": 0.5,
  "fieldWeights": {
    "content": 1,
    "meta": 2,
    "title": 3
  },
  "filter": {
    "kind": {
      "not": [
        "test"
      ]
    },
    "modified": {
      "gte": "2026-09-01"
    },
    "path": {
      "prefix": "internal/"
    },
    "size": {
      "lt": 10000
    },
    "summary": {
      "exists": true
    },
    "title": {
      "contains": "hnsw"
    }
  },
  "filterMeta": {
    "category": [
      "tutorial"
    ]
  },
  "format": "results",
  "fuzzy": 0,
  "geo": {
    "lat": 51.5074,
    "lng": -0.1278,
    "radiusMeters": 5000
  },
  "groupBy": {
    "key": "path",
    "perGroup": 1
  },
  "includeContent": false,
  "includeImages": false,
  "lang": "en",
  "latencyTargetMs": 0,
  "negative": [
    "string"
  ],
  "oversample": 0,
  "passageLines": 0,
  "positive": [
    "string"
  ],
  "query": "how to deploy with Docker",
  "queryDecomposition": "off",
  "readLevel": "indexed",
  "rocchio": {
    "alpha": 1,
    "beta": 0.75,
    "gamma": 0.25
  },
  "rrfK": 60,
  "signals": {
    "diversity": 0.8,
    "diversityThreshold": 0.5,
    "freshness": 0.1,
    "freshnessHalfLifeDays": 180,
    "proximity": 0.1
  },
  "sort": "distance",
  "strategy": "alpha",
  "threshold": 0,
  "topK": 10,
  "vectorAlgorithm": "flat",
  "waitForIndex": 0,
  "waitForKeys": [
    "string"
  ]
}

Responses #

Status	Description	Body
200	Hybrid search results	oneOf HybridSearchResponse | PassagesResponse (application/json)
400	Invalid request	ErrorResponse (application/json)