run_vector_query

Embed a query and run a vector similarity search against a GSI vector index.

Embedding: 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 -- it is not hidden from tool discovery when unconfigured.

Index selection: this tool queries a Couchbase 8.0+ GSI vector index (Composite Vector Index or Hyperscale Vector Index) via SQL++'s APPROX_VECTOR_DISTANCE(). Unlike Search-service vector search, GSI selects the index automatically from the vector field referenced in the query -- there is no index_name parameter, and none is needed.

distance_metric is required, deliberately with no default: it must match the similarity the index was created with (CREATE INDEX ... WITH {"similarity": ...}), or Couchbase silently falls back to not using the Composite/Hyperscale Vector Index at all (no error -- the query still returns correct results, just unindexed). There is no one value that's usually right, since it depends entirely on how the specific index was created, and this tool has no index_name to look that up automatically (see above) -- call list_indexes first and read the similarity value out of the matching index's definition field (valid values: cosine, dot, l2/euclidean, l2_squared/euclidean_squared).

num_probes/rerank/top_n_scan are Hyperscale Vector Index tuning parameters. num_probes (integer) is the number of centroids to probe -- raise it to improve poor recall. rerank (true/false) re-checks the top candidates against the full vectors; it needs num_probes. top_n_scan (integer) is how many candidates to rerank; it needs num_probes and rerank. num_probes alone, or num_probes + rerank, are both valid. A Composite Vector Index doesn't use any of them. This tool itself has no index_name to check, but list_indexes now reports each index's vector_type ("hyperscale" or "composite") -- check that first if you need to know which shape will actually serve the query.

where is an optional raw SQL++ boolean expression (e.g. "doc.status = 'active'") appended to prefilter candidates before the vector ordering -- this tool only ever emits a SELECT, so, unlike run_sql_plus_plus_query, there is no write-guard for it to bypass. If the index was created with a partial-index condition (create_query_index's condition), where must match or imply it for the planner to actually use that index -- otherwise it falls back to a full scan silently (confirmed via EXPLAIN), the same footgun documented above for a mismatched distance_metric.

select_fields limits the projected document fields; omit it to return the full document. limit defaults to 10, matching the other query/search tools in this server.

Returns {"success": True, "hits": [{"id", "distance", "document": {... selected fields, or the full document}}], "total_hits", "cluster_major_version", and a "warning" key only when the detected cluster major version is below 8 (informational -- a pre-8.0 cluster fails the query naturally with its own "unknown function" error rather than being blocked here)} or {"success": False, "error": ...}. The document is nested under "document" rather than merged into the hit directly -- a document field literally named "id" or "distance" would otherwise silently collide with (and could overwrite) this tool's own id/distance metadata.