run_search
Executes full-text search queries against Couchbase Search indexes, returning relevance-scored hits, facets, and highlighting, or fetches execution plans for debugging.
Instructions
Run an FTS (Search) query against a Search index, or fetch its execution plan.
Use this instead of run_sql_plus_plus_query's SEARCH() function when you need relevance-scored, fuzzy, or linguistic full-text matching (scoring, highlighting, faceting, fuzzy/phrase/wildcard matching) — SQL++ can invoke FTS predicates too, but this tool gives clearer tracing of what data was searched and keeps FTS-specific result shape (score, fragments, facets) out of general query results.
query is the raw FTS query JSON body, passed through unvalidated to the Search service — this supports every non-vector FTS query type, e.g.:
{"match": "ale", "field": "type"}
{"conjuncts": [{"match": "ale"}, {"term": "beer", "field": "type"}]}
{"query": "type:beer +name:ale"} (query_string) Vector search is NOT supported by this tool (separate feature).
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. Passing only one is invalid. Confirm the index's exact name/location first with list_search_indexes. Don't guess which fields a query body can target — if you don't already know what the index maps and how those fields are analyzed, call get_search_index_definition first; a field-scoped query against an unmapped field matches nothing rather than erroring. Note this only works for indexes with explicit static field mappings — a dynamically mapped index (dynamic: true) has no fixed field list to inspect, since it indexes whatever fields appear in each document; for those, look at actual document contents instead to know what's queryable.
explain: if True, fetches the execution plan instead of normal results. The Search service exposes the query plan per matched document, not as a separate plan-only/ dry-run call — so explain=True still executes the query (with explain enabled) and returns the explanation for each returned hit. limit defaults to 1 in this mode to keep it cheap (pass a larger limit to see the plan for more matched documents), and skip/fields/sort/facets/highlight_fields/disable_scoring/raw are ignored — they only apply when explain=False.
limit/skip/fields/sort/facets/highlight_fields/disable_scoring map to the equivalent Search options. limit defaults to 10 when explain=False (matching the other query tools in this server) and to 1 when explain=True. raw is a passthrough dict for any other SearchOptions field not exposed directly (e.g. highlight_style, consistent_with).
Returns {"success": True, "index_name", "explain", "limit" (the limit actually applied, since it defaults differently depending on explain), "total_hits", "hits", "facets", "metadata": {"errors","metrics"}} on success, or {"success": False, "error": ...} if the input is invalid or the query fails (e.g. bad query syntax, index not found). total_hits counts the hits actually returned, so it is capped by limit — for how many documents matched overall, read metadata.metrics.total_rows instead, and don't report total_hits as the size of the match set. hits entries are {"id","score","fields","fragments"} when explain=False, or {"id","score","explanation"} when explain=True (facets is empty in that case).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| raw | No | ||
| skip | No | ||
| sort | No | ||
| limit | No | ||
| query | Yes | ||
| facets | No | ||
| fields | No | ||
| explain | No | ||
| index_name | Yes | ||
| scope_name | No | ||
| bucket_name | No | ||
| disable_scoring | No | ||
| highlight_fields | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||