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.

Vector Field Search

vector_field_search lets you bring your own embeddings instead of relying on Flux-generated ones. This is useful when you already have an embedding pipeline (e.g., OpenAI, Cohere, or a custom model) and want to store and query vectors directly.

Prerequisites

1. Create a vector field – Add a field with type: "vector" and meta.dimensions set to one of the supported sizes (256, 384, 768, 1024, 1536) via the Fields API.
2. Store embeddings – Include the embedding array when creating or updating resources. The array length must match the field's configured dimensions.
3. Republish – Resources must be published after adding vector data.

vector_field_search Parameters

Supported Modes

vector_field_search works with search_mode set to "vector" or "vector_boosted":

hybrid mode is not supported with vector_field_search. Use vector_search (auto-generated embeddings) for hybrid queries.

Constraints

• vector_field_search and vector_search are mutually exclusive — you cannot use both in the same request.
• The query_vector dimension must exactly match the field's configured dimensions. A mismatch returns 422 validation_error.
• If the specified field does not exist or is not a vector type, the request returns 422 invalid_request.

Examples

Pure Vector Field Search

curl -X POST \
  "https://7c9h4pwu.fxns.io/ml/speakers/_search" \
  -H "Authorization: Secure <access_key>:<signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "search_mode": "vector",
    "vector_field_search": {
      "field": "speaker_embedding",
      "query_vector": [0.012, -0.034, 0.056, ...],
      "top_k": 20,
      "similarity_threshold": 0.6
    }
  }'

Vector-Boosted with Custom Embeddings

{
  "search_mode": "vector_boosted",
  "find_text": {
    "query": "keynote speaker AI",
    "fields": ["bio", "topics"]
  },
  "vector_field_search": {
    "field": "speaker_embedding",
    "query_vector": [0.012, -0.034, 0.056, ...],
    "top_k": 30,
    "similarity_threshold": 0.5
  },
  "vector_boost_config": {
    "boost_factor": 1.3,
    "similarity_threshold": 0.7,
    "max_boost_results": 15
  }
}

Text results are ranked first, then boosted by cosine similarity to your embedding vector.

Vector Field Search with Filters

{
  "search_mode": "vector",
  "vector_field_search": {
    "field": "product_embedding",
    "query_vector": [0.012, -0.034, 0.056, ...],
    "top_k": 50,
    "similarity_threshold": 0.5
  },
  "where": {
    "$": {
      "all_of": [
        {"category__eq": "electronics"},
        {"in_stock__eq": true}
      ]
    }
  }
}

Filters are applied after vector retrieval, narrowing results to matching documents.

Scoring

Each result includes a relevance score in _sys.relevance. The formula depends on the search mode:

Scenarios

vector_field_search composes naturally with filters, sorting, pagination, and boost tuning. Below are common combinations.

Filtered Vector Search

Find similar speakers who match specific criteria:

{
  "search_mode": "vector",
  "vector_field_search": {
    "field": "speaker_embedding",
    "query_vector": [0.012, -0.034, 0.056, "...768 floats..."],
    "top_k": 50,
    "similarity_threshold": 0.5
  },
  "where": {
    "$": {
      "all_of": [
        {"gender__eq": "female"},
        {"years_experience__gte": 5}
      ]
    }
  }
}

Filters are applied after vector retrieval. If too few results come back, increase top_k or loosen similarity_threshold.

Boosted Search with Phrase Match

Find articles containing an exact phrase, boosted by topic embedding similarity:

{
  "search_mode": "vector_boosted",
  "find_phrase": {
    "query": "machine learning",
    "fields": ["title", "abstract"]
  },
  "vector_field_search": {
    "field": "topic_embedding",
    "query_vector": [0.023, -0.011, 0.089, "...384 floats..."],
    "top_k": 25
  }
}

find_phrase works identically to find_text in boosted mode. Phrase matches are ranked first, then boosted by vector similarity.

Tuning Boost Behavior

Control how aggressively vector scores influence ranking:

{
  "search_mode": "vector_boosted",
  "find_text": {
    "query": "sustainable packaging",
    "fields": ["description"]
  },
  "vector_field_search": {
    "field": "product_embedding",
    "query_vector": [0.045, -0.022, 0.067, "...384 floats..."],
    "top_k": 40,
    "similarity_threshold": 0.3
  },
  "vector_boost_config": {
    "boost_factor": 2.0,
    "similarity_threshold": 0.6,
    "max_boost_results": 10
  }
}

Custom Sort Order

Find similar products, break ties by price:

{
  "search_mode": "vector",
  "vector_field_search": {
    "field": "product_embedding",
    "query_vector": [0.012, -0.034, 0.056, "...384 floats..."],
    "top_k": 50
  },
  "sort": ["price"]
}

Results are ordered by vector similarity first. The sort parameter acts as a tiebreaker when two documents have equal similarity scores.

Paginated Vector Search

Browse similar items page by page:

{
  "search_mode": "vector",
  "vector_field_search": {
    "field": "image_embedding",
    "query_vector": [0.012, -0.034, 0.056, "...768 floats..."],
    "top_k": 100,
    "similarity_threshold": 0.4
  },
  "limit": 20
}

The response includes pagination URLs:

{
  "limit": 20,
  "next": "https://example.fxns.io/ml/images/_search?next=abc123&limit=20",
  "previous": null,
  "results": ["..."]
}

Pass the next URL to retrieve the following page. Pagination works identically to all other search modes — see Pagination for details.

Full Combination

Find similar electronics in stock under $500, sorted by price, paginated:

{
  "search_mode": "vector",
  "vector_field_search": {
    "field": "product_embedding",
    "query_vector": [0.012, -0.034, 0.056, "...384 floats..."],
    "top_k": 100,
    "similarity_threshold": 0.4
  },
  "where": {
    "$": {
      "all_of": [
        {"category__eq": "electronics"},
        {"in_stock__eq": true},
        {"price__lte": 500}
      ]
    }
  },
  "sort": ["price"],
  "limit": 10
}

All features compose naturally: vector retrieval selects candidates, filters narrow them down, sort acts as a tiebreaker, and pagination slices the result set. Request the next page with ?next=<cursor>&limit=10.

When to Use vector_field_search vs vector_search

Reading the Response

Every search response includes a metadata object with the effective parameters that were used, including any server-side defaults.

The shape varies by mode:

"metadata": {
  "search_mode": "vector",
  "limit": 100,
  "vector_search_enabled": true,
  "top_k": 10,
  "similarity_threshold": 0.4
}

"metadata": {
  "search_mode": "hybrid",
  "limit": 100,
  "vector_search_enabled": true,
  "top_k": 10,
  "similarity_threshold": 0.4,
  "text_threshold": 0.85,
  "vector_weight": 0.6,
  "text_weight": 0.4
}

"metadata": {
  "search_mode": "vector_boosted",
  "limit": 100,
  "vector_search_enabled": true,
  "top_k": 5,
  "similarity_threshold": 0.6,
  "text_threshold": 0.8,
  "boost_factor": 1.5,
  "boost_similarity_threshold": 0.6,
  "max_boost_results": 5
}

"metadata": {
  "search_mode": "text",
  "limit": 100,
  "text_threshold": 0.85
}

When using vector_field_search, the metadata also includes a vector_field_search sub-object:

"metadata": {
  "search_mode": "vector",
  "limit": 100,
  "vector_search_enabled": true,
  "top_k": 10,
  "similarity_threshold": 0.4,
  "vector_field_search": {
    "field": "speaker_embedding",
    "dimension": 768,
    "top_k": 30,
    "similarity_threshold": 0.5,
    "distance_metric": "cosine"
  }
}

Best Practices

1. Start with a smaller top_k (10–25) to keep responses fast. Increase only when needed.
2. Tune similarity_threshold – the default is 0.4; raise it for stricter matches or lower for broader recall.
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 payload (vector_search or vector_field_search) when required, combining find_text with search_mode="vector", or using vector_field_search with search_mode="text" all return 422 validation_error. 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.
7. Increase top_k when using VFS with filters – where conditions are applied after vector retrieval. Set top_k to 3–5× your expected result count so enough candidates survive post-filtering.
8. Set boost thresholds in vector_boost_config – In vector_boosted mode, vector_boost_config.similarity_threshold and max_boost_results override the corresponding VFS parameters. Define your intended thresholds there to avoid confusion.

Troubleshooting

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