run_vector_search
Run vector similarity searches on a named Couchbase Search index, optionally combining scalar queries for hybrid ranking or prefilters to narrow candidates.
Instructions
Run the Search service's vector search, including hybrid and prefiltered search.
Embedding: vector_query_text is embedded using the model configured via CB_MCP_EMBEDDING_MODEL_PROVIDER/CB_MCP_EMBEDDING_MODEL/CB_MCP_EMBEDDING_MODEL_API_KEY/CB_MCP_EMBEDDING_MODEL_ENDPOINT (plus CB_MCP_EMBEDDING_MODEL_AWS_* for provider=bedrock). If no provider is configured, this tool returns {"success": False, "error": ...} explaining what to set
Unlike run_vector_query's GSI-backed search, this tool always targets a named Search (FTS) index -- index_name is required. Pass both bucket_name and scope_name together to query a scope-level (scoped) index, or omit both to query a cluster-level ("legacy") index. Confirm the index's exact name/location first with list_search_indexes if unsure -- this tool does not pre-validate index_name; a wrong or non-vector index name fails naturally at the Search service with its own error.
scalar_query and prefilter are both optional and both take the same raw FTS query JSON body run_search accepts (e.g. {"match": "jacket", "field": "description"}), but they do different things -- do not confuse them:
scalar_query makes this a genuinely hybrid search: both the vector query and this scalar query are sent to the Search service together, and it ranks/combines their hits server-side (a document can match via either signal). is_hybrid in the response reflects whether this was set.
prefilter narrows which documents the vector search is even allowed to consider as nearest-neighbor candidates, evaluated before the k-nearest-neighbor search runs -- the Search-service equivalent of run_vector_query's
whereprefilter on a GSI Composite Vector Index. A document that doesn't match prefilter is never returned, regardless of vector similarity.
Both can be set together (prefilter narrows the candidate pool, then scalar_query's relevance signal still contributes to ranking within it). Omit both for a plain vector-only search through this tool (equivalent in intent to run_vector_query, but against a named Search index instead of a GSI vector index).
num_candidates bounds how many nearest-neighbor candidates the vector query considers; limit bounds how many hits the search as a whole returns, and both default to 10. For a vector-only search (no scalar_query), limit above num_candidates is a no-op -- there are never more than num_candidates vector hits to return. With scalar_query set, limit can meaningfully exceed num_candidates, since scalar_query's own matches aren't bounded by it. fields requests specific stored index fields per hit.
This tool does not fetch full document bodies -- a Search hit carries whatever fields the index stores (row.fields), the same as run_search, not a KV-fetched document (a hit has no reliable per-row collection name to fetch against). Follow up with get_document_by_id for any hit you need the full document for.
Returns {"success": True, "index_name", "vector_field", "num_candidates", "limit", "total_hits", "hits": [{"id", "score", "fields"}], "is_hybrid", "is_prefiltered"} or {"success": False, "error": ...}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| fields | No | ||
| prefilter | No | ||
| index_name | Yes | ||
| scope_name | No | ||
| bucket_name | No | ||
| scalar_query | No | ||
| vector_field | Yes | ||
| num_candidates | No | ||
| vector_query_text | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||