Vector Search

Flux can compare semantic meaning—not just keywords—by generating embeddings for your content and your search queries. This guide explains when to enable vector search, how each mode works, and how to configure _search requests even if you have never worked with vectors before.

Prerequisites

1. Vectorizable fields – Mark relevant string or text fields with vectorizable=true in the Fields API. Flux only stores embeddings for those fields.
2. Re-save content – Existing resources must be republished after you enable vectorization so embeddings can be generated. _search returns no vector matches until the content has embeddings.
3. Vector storage – Embeddings consume vector storage units (see Resources API). Running out of units causes writes to fail with insufficient_units.
4. Flux search endpoint – Vector queries run through the same _search endpoint as traditional filters.

Choosing a Mode

Use vector when you want purely semantic results (e.g., “inspiration photos that feel cozy”). Use vector_boosted or hybrid when you still care about keyword relevance but want semantic refinement.

vector_search Parameters

These values go inside the _search body:

"search_mode": "vector",
"vector_search": {
  "query": "cozy modern living room inspiration",
  "fields": ["body"],
  "top_k": 25,
  "similarity_threshold": 0.65
}

Flux automatically generates an embedding for query, compares it to your stored embeddings, and returns the closest matches.

Boost & Hybrid Controls

When you mix text and vector search, you can fine-tune how vector results influence ranking.

vector_boost_config

"vector_boost_config": {
  "boost_factor": 1.2,
  "similarity_threshold": 0.8,
  "max_boost_results": 20
}

• boost_factor amplifies vector hits relative to text-only results (defaults to 1.5).
• similarity_threshold ensures only strong matches boost the score.
• max_boost_results caps how many results get boosted.

hybrid_config

"hybrid_config": {
  "vector_weight": 0.6,
  "text_weight": 0.4,
  "rerank_results": true
}

• Set weights to control how vector vs text scores are combined (defaults: 0.6 / 0.4).
• rerank_results=true sorts by the combined score; set to false to keep text order and annotate with hybrid scores.

Examples

1. Pure Vector Search

curl -X POST \
  "https://7c9h4pwu.fxns.io/gallery/projects/_search" \
  -H "Authorization: Secure <access_key>:<signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "search_mode": "vector",
    "vector_search": {
      "query": "warm minimalist living room",
      "fields": ["description"],
      "top_k": 30,
      "similarity_threshold": 0.7
    }
  }'

2. Vector-Boosted Keyword Search

{
  "search_mode": "vector_boosted",
  "find_text": {
    "query": "sofa",
    "fields": ["title", "summary"]
  },
  "vector_search": {
    "query": "comfortable modern sofa",
    "fields": ["body"]
  },
  "vector_boost_config": {
    "boost_factor": 1.3,
    "similarity_threshold": 0.75,
    "max_boost_results": 15
  }
}

Flux runs the text search first, then boosts matches whose embeddings are semantically similar to the vector query.

3. Hybrid Search

{
  "search_mode": "hybrid",
  "find_phrase": {
    "query": "content strategy",
    "fields": ["title"]
  },
  "vector_search": {
    "query": "content marketing playbook",
    "fields": ["body"]
  },
  "hybrid_config": {
    "vector_weight": 0.5,
    "text_weight": 0.5,
    "rerank_results": true
  }
}

Hybrid combines both scores into a new field (metadata.score in the response) and sorts by the weighted score when rerank_results is true.

Reading the Response

In addition to the usual _sys/data payload, vector-enabled responses include metadata:

"metadata": {
  "search_mode": "vector_boosted",
  "vector_search_enabled": true,
  "tokens_used": 256
}

• search_mode echoes the mode Flux executed (useful if you let users choose).
• vector_search_enabled confirms embeddings were used.
• tokens_used approximates the number of tokens sent to the embedding model (helpful for monitoring costs).

Best Practices

1. Start with a smaller top_k (10–25) to keep responses fast. Increase only when needed.
2. Tune similarity_threshold – 0.7 is a good baseline; lower it for broader matches.
3. Keep limit ≥ top_k – Flux returns up to limit documents. If top_k is higher than limit, extra vector hits will be dropped.
4. Monitor storage usage – The _sys.vectors_size field in the Resources API helps track vector storage consumption.
5. Handle validation errors – Missing vector_search when required, combining find_text with search_mode="vector", or exceeding the join limit all return 422 invalid_request. Check error_code for exact causes.
6. Expect higher latency for narrow filters – Combining vectors with restrictive where__ filters or joins forces Flux to scan more data to find matches. Loosen filters or lower thresholds if queries become slow.

Troubleshooting

Need a refresher on the full _search payload? See the Search documentation for a complete reference.