Skip to main content

Vector Search API

Vector search provides semantic similarity retrieval using embeddings.

For zvec-style feature parity tracking, see ZVEC Compatibility (Vector).

Overview​

The current implementation uses linear scan (no ANN index yet), but supports rich request shapes:

  • Single vector query or multiple vector queries in one request
  • Dense vectors and sparse object-form vectors are accepted
  • Per-query metric selection: cosine, dot, l2, l1
  • Per-query weight, threshold, and normalize
  • Fusion methods for multi-vector queries: weighted_sum, max, average, rrf
  • Filtering via filter_by (and filter alias)
  • Field projection via output_fields and vector inclusion control (include_vector)

Endpoint​

  • POST /collections/{name}/vector_search
  • GET /collections/{name}/vector_search (query-string mode)
  • POST /collections/{name}/search (alias)
  • GET /collections/{name}/search (alias)

The /collections/{name}/search alias is routed to vector search. Use /collections/{name}/documents/search for lexical document search.

Request Body Shapes​

1) Raw vector array (legacy/simple)​

[0.1, 0.2, 0.3, 0.4]

2) Single vector object​

{
  "field_name": "embedding",
  "vector": [0.1, 0.2, 0.3, 0.4],
  "topk": 10,
  "metric_type": "cosine",
  "threshold": 0.2,
  "normalize": true,
  "filter_by": "category:=laptops",
  "output_fields": ["id", "title", "category"],
  "include_vector": false
}

3) Multi-vector query + fusion​

{
  "vector_queries": [
    {
      "field_name": "title_embedding",
      "vector": [0.1, 0.2, 0.3],
      "weight": 0.7,
      "metric_type": "cosine",
      "threshold": 0.1
    },
    {
      "field_name": "body_embedding",
      "vector": [0.3, 0.4, 0.5],
      "weight": 0.3,
      "metric_type": "dot"
    }
  ],
  "fusion": {
    "method": "rrf",
    "rrf_k": 60
  },
  "top_k": 20,
  "query_params": {
    "ef": 128,
    "nprobe": 8,
    "is_linear": true,
    "is_using_refiner": false
  }
}

Optional Keys​

  • topk / top_k / k / limit / per_page: result count
  • query_params / params: execution hints
    • ef / ef_search / hnsw_ef_search
    • nprobe / ivf_nprobe
    • is_linear (scan all docs for exact search)
    • is_using_refiner
  • filter_by or filter: filter expression
  • output_fields: fields to include in document
  • include_vector: when false, queried vector fields are excluded from document
  • radius / max_distance: max vector distance constraint
  • range_filter / min_distance: min vector distance constraint
  • include_distance: include _vector_distance in each hit document
  • hybrid_alpha + q + query_by: enables hybrid behavior through shared search pipeline

Example Response​

{
  "hits": [
    {
      "document": {
        "id": "product1",
        "title": "Gaming Laptop"
      },
      "text_match": 0,
      "_text_match": 0,
      "vector_score": 0.872
    }
  ],
  "found": 1,
  "out_of": 1,
  "page": 1,
  "per_page": 10,
  "total_pages": 1,
  "has_next_page": false,
  "has_prev_page": false,
  "search_time_ms": 2.4
}

Current Limits​

  • Linear scan over candidate documents (no ANN index yet)
  • Best for small/medium datasets or development workflows

Research Directions​

  • Performance-focused vector execution: We are actively prototyping quantized/compact vector representations and candidate re-ranking so the vector stage can scale beyond single-digit millions with predictable latency.
  • Hybrid planners and telemetry: Selectivity-aware filtering, tiered persistence, and GPU batching will be exposed through new query_params hints such as batch size, backend hint, and filter selectivity estimates.
  • Vector quality monitoring: /status and /stats will eventually expose vector-specific metrics (candidate recall, GPU vs. CPU share) so operators can track the impact of the research changes in production.

For experimental details and benchmarking plans, follow the research note in etc/research/2026-02-26.md.