--- title: "Performs a search on a table" method: POST path: "/search" tags: ["Search"] --- # Performs a search on a table `POST /search` The method expects an object with the following mandatory properties: * the name of the table to search * the match query object For details, see the documentation on [**SearchRequest**](SearchRequest.md) The method returns an object with the following properties: - took: the time taken to execute the search query. - timed_out: a boolean indicating whether the query timed out. - hits: an object with the following properties: - total: the total number of hits found. - hits: an array of hit objects, where each hit object represents a matched document. Each hit object has the following properties: - _id: the ID of the matched document. - _score: the score of the matched document. - _source: the source data of the matched document. In addition, if profiling is enabled, the response will include an additional array with profiling information attached. Also, if pagination is enabled, the response will include an additional 'scroll' property with a scroll token to use for pagination Here is an example search response: ``` { 'took':10, 'timed_out':false, 'hits': { 'total':2, 'hits': [ {'_id':'1','_score':1,'_source':{'gid':11}}, {'_id':'2','_score':1,'_source':{'gid':12}} ] } } ``` For conversational search, include a `chat` object instead of `table` and `query`. The response then includes the optional conversational fields on `searchResponse` (`conversation_uuid`, `user_query`, `search_query`, `response`, `sources`). For more information about the match query syntax and additional parameters that can be added to request and response, please see the documentation [here](https://manual.manticoresearch.com/Searching/Full_text_matching/Basic_usage#HTTP-JSON). ## Request body - SearchRequest — Request object for search operation. Either `table` (regular search) or `chat` (conversational search) must be provided. - `table` string — The table to perform the search on - `chat` Chat — Conversational search request handled by Manticore Buddy via `CALL CHAT`. When this object is set, the `/search` endpoint answers through an LLM using KNN-retrieved rows as context instead of returning regular search hits. Required fields are `query`, `table`, and `model_name`. Chat model management (`CREATE CHAT MODEL`, etc.) remains SQL-only. For more information see [Conversational search](https://manual.manticoresearch.com/Searching/Conversational_search#HTTP-JSON-syntax) - `query` string, required — User question to send to the chat model - `table` string, required — Vectorized table to retrieve context from - `model_name` string, required — Name of the chat model - `conversation_uuid` string — Existing conversation id to continue the dialog, or an empty string to start a new conversation. If omitted, a new id is generated. - `vector_field` string — A specific vector field to search by. If omitted, Buddy uses the first `FLOAT_VECTOR` field from `SHOW CREATE TABLE`. - `fields` string — Legacy alias for `vector_field`. A request must not include both `vector_field` and `fields`. - `query` SearchQuery — Defines a query structure for performing search operations - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter - `must` QueryFilter[] — Query clauses that must match for the document to be included - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter — recursive - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - `lat` number — Latitude of the anchor point - `lon` number — Longitude of the anchor point - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `must_not` QueryFilterAlias1[] — Query clauses that must not match for the document to be included - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter — recursive - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - `lat` number — Latitude of the anchor point - `lon` number — Longitude of the anchor point - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `should` QueryFilterAlias2[] — Query clauses that should be matched, but are not required - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter — recursive - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - `lat` number — Latitude of the anchor point - `lon` number — Longitude of the anchor point - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - `lat` number — Latitude of the anchor point - `lon` number — Longitude of the anchor point - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `highlight` Highlight — Options for controlling the behavior of highlighting on a per-field basis - `after_match` string — Text inserted after the matched term, typically used for HTML formatting - `allow_empty` boolean — Permits an empty string to be returned as the highlighting result. Otherwise, the beginning of the original text would be returned - `around` integer — Number of words around the match to include in the highlight - `before_match` string — Text inserted before the match, typically used for HTML formatting - `emit_zones` boolean — Emits an HTML tag with the enclosing zone name before each highlighted snippet - `encoder` 'default' | 'html' — If set to 'html', retains HTML markup when highlighting - `fields` union — List of fields available for highlighting - string[] - object - `force_all_words` boolean — Ignores the length limit until the result includes all keywords - `force_snippets` boolean — Forces snippet generation even if limits allow highlighting the entire text - `highlight_query` QueryFilter — Object used to apply various conditions, such as full-text matching or attribute filtering, to a search query - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter - `must` QueryFilter[] — Query clauses that must match for the document to be included - `must_not` QueryFilterAlias1[] — Query clauses that must not match for the document to be included - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter — recursive - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - … - `should` QueryFilterAlias2[] — Query clauses that should be matched, but are not required - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter — recursive - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - … - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - `lat` number — Latitude of the anchor point - `lon` number — Longitude of the anchor point - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `html_strip_mode` 'none' | 'strip' | 'index' | 'retain' — Defines the mode for handling HTML markup in the highlight - `limits_per_field` boolean — Determines whether the 'limit', 'limit_words', and 'limit_snippets' options operate as individual limits in each field of the document - `no_match_size` 0 | 1 — If set to 1, allows an empty string to be returned as a highlighting result - `order` 'asc' | 'desc' | 'score' — Sets the sorting order of highlighted snippets - `pre_tags` string — Text inserted before each highlighted snippet - `post_tags` string — Text inserted after each highlighted snippet - `start_snippet_id` integer — Sets the starting value of the %SNIPPET_ID% macro - `use_boundaries` boolean — Defines whether to additionally break snippets by phrase boundary characters - `fragment_size` integer — Maximum size of the text fragments in highlighted snippets per field - `limit` integer — Maximum size of snippets per field - `limit_snippets` integer — Maximum number of snippets per field - `limit_words` integer — Maximum number of words per field - `number_of_fragments` integer — Total number of highlighted fragments per field - `join` Join[] — Join clause to combine search data from multiple tables - `type` 'inner' | 'left', required — Type of the join operation - `on` JoinOn[], required — List of objects defining joined tables - `right` JoinCond — Object representing the conditions used to perform the join operation - `field` string, required — Field to join on - `table` string, required — Joined table - `query` FulltextFilter — Defines a type of filter for full-text search queries - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `type` object - `left` JoinCond — Object representing the conditions used to perform the join operation - `field` string, required — Field to join on - `table` string, required — Joined table - `query` FulltextFilter — Defines a type of filter for full-text search queries - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `type` object - `operator` 'eq' - `query` FulltextFilter — Defines a type of filter for full-text search queries - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `table` string, required — Basic table of the join operation - `highlight` Highlight — Options for controlling the behavior of highlighting on a per-field basis - `after_match` string — Text inserted after the matched term, typically used for HTML formatting - `allow_empty` boolean — Permits an empty string to be returned as the highlighting result. Otherwise, the beginning of the original text would be returned - `around` integer — Number of words around the match to include in the highlight - `before_match` string — Text inserted before the match, typically used for HTML formatting - `emit_zones` boolean — Emits an HTML tag with the enclosing zone name before each highlighted snippet - `encoder` 'default' | 'html' — If set to 'html', retains HTML markup when highlighting - `fields` union — List of fields available for highlighting - string[] - object - `force_all_words` boolean — Ignores the length limit until the result includes all keywords - `force_snippets` boolean — Forces snippet generation even if limits allow highlighting the entire text - `highlight_query` QueryFilter — Object used to apply various conditions, such as full-text matching or attribute filtering, to a search query - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter - `must` QueryFilter[] — Query clauses that must match for the document to be included - `must_not` QueryFilterAlias1[] — Query clauses that must not match for the document to be included - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter — recursive - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - … - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `should` QueryFilterAlias2[] — Query clauses that should be matched, but are not required - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter — recursive - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - … - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - `lat` number — Latitude of the anchor point - `lon` number — Longitude of the anchor point - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `html_strip_mode` 'none' | 'strip' | 'index' | 'retain' — Defines the mode for handling HTML markup in the highlight - `limits_per_field` boolean — Determines whether the 'limit', 'limit_words', and 'limit_snippets' options operate as individual limits in each field of the document - `no_match_size` 0 | 1 — If set to 1, allows an empty string to be returned as a highlighting result - `order` 'asc' | 'desc' | 'score' — Sets the sorting order of highlighted snippets - `pre_tags` string — Text inserted before each highlighted snippet - `post_tags` string — Text inserted after each highlighted snippet - `start_snippet_id` integer — Sets the starting value of the %SNIPPET_ID% macro - `use_boundaries` boolean — Defines whether to additionally break snippets by phrase boundary characters - `fragment_size` integer — Maximum size of the text fragments in highlighted snippets per field - `limit` integer — Maximum size of snippets per field - `limit_snippets` integer — Maximum number of snippets per field - `limit_words` integer — Maximum number of words per field - `number_of_fragments` integer — Total number of highlighted fragments per field - `limit` integer — Maximum number of results to return - `knn` Knn — Object representing a k-nearest neighbor search query - `field` string, required — Field to perform the k-nearest neighbor search on - `k` integer — Deprecated. Use the top-level `limit` parameter instead. - `query` union - string - number[] - `query_vector` number[] — The vector used as input for the KNN search - `doc_id` integer - `ef` integer — Optional parameter controlling the accuracy of the search - `rescore` boolean — Optional parameter enabling KNN rescoring (disabled by default) - `oversampling` number — Optional parameter setting a factor by which k is multiplied when executing the KNN search - `filter` QueryFilter — Object used to apply various conditions, such as full-text matching or attribute filtering, to a search query - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter - `must` QueryFilter[] — Query clauses that must match for the document to be included - `must_not` QueryFilterAlias1[] — Query clauses that must not match for the document to be included - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter — recursive - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - … - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `should` QueryFilterAlias2[] — Query clauses that should be matched, but are not required - `query_string` string — Filter object defining a query string - `match` object — Filter object defining a match keyword passed as a string or in a Match object - `match_phrase` object — Filter object defining a match phrase - `match_all` object — Filter object to select all documents - `bool` BoolFilter — recursive - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - … - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `equals` QueryFilterAllOfEquals — Filter to match exact attribute values. - `in` QueryFilterAllOfIn — Filter to match a given set of attribute values. - `range` QueryFilterAllOfRange — Filter to match a given range of attribute values passed in Range objects - `geo_distance` GeoDistance — Object to perform geo-distance based filtering on queries - `location_anchor` GeoDistanceLocationAnchor — Specifies the location of the pin point used for search - `lat` number — Latitude of the anchor point - `lon` number — Longitude of the anchor point - `location_source` string — Field name in the document that contains location data - `distance_type` 'adaptive' | 'haversine' — Algorithm used to calculate the distance - `distance` string — The distance from the anchor point to filter results by - `hybrid` Hybrid — Perform hybrid search on tables with auto-embeddings. Runs full-text and vector search and fuses results with RRF. For more information see [Hybrid search](https://manual.manticoresearch.com/Searching/Hybrid_search#Simplified-JSON-syntax:-hybrid) - `query` string, required — Search query string - `field` string — Vector field name. - `facet_filter_mode` 'strict' | 'auto' | 'max' — Controls how facets inherit attribute filters from the main query. [Faceted search](https://manual.manticoresearch.com/Searching/Faceted_search#HTTP-JSON) - `aggs` unknown - `expressions` unknown - `script_fields` unknown - `max_matches` integer — Maximum number of matches allowed in the result - `offset` integer — Starting point for pagination of the result - `options` object — Additional search options - `profile` boolean — Enable or disable profiling of the search request - `sort` object — Sorting criteria for the search results - `_source` object — Specify which fields to include or exclude in the response - `track_scores` boolean — Enable or disable result weight calculation used for sorting ## Response `200` Ok. Returns `searchResponse`. For conversational search requests that include a `chat` object, the optional conversational fields are also set. - SearchResponse — Response object containing search results. For conversational search requests that include a `chat` object, the optional chat fields below are also populated. For conversational search response fields see [Conversational search](https://manual.manticoresearch.com/Searching/Conversational_search#Response) - `took` integer — Time taken to execute the search - `timed_out` boolean — Indicates whether the search operation timed out - `aggregations` unknown - `hits` SearchResponseHits — Object containing the search hits, which represent the documents that matched the query. - `max_score` integer — Maximum score among the matched documents - `total` integer — Total number of matched documents - `total_relation` string — Indicates whether the total number of hits is accurate or an estimate - `hits` HitsHits[] — Array of hit objects, each representing a matched document - `_id` integer - `_score` integer — The score of the matched document - `_source` object — The source data of the matched document - `_knn_dist` number — The knn distance of the matched document returned for knn queries - `highlight` object — The highlighting-related data of the matched document - `table` string — The table name of the matched document returned for percolate queries - `_type:` string — The type of the matched document returned for percolate queries - `fields` object — The percolate-related fields of the matched document returned for percolate queries - `profile` object — Profile information about the search execution, if profiling is enabled - `scroll` string — Scroll token to be used fo pagination - `warning` object — Warnings encountered during the search operation - `conversation_uuid` string — Existing or generated conversation id (conversational search) - `user_query` string — Original user query (conversational search) - `search_query` string — Standalone search query used for KNN retrieval (conversational search) - `response` string — LLM answer as generated (conversational search) - `sources` string — JSON string containing retrieved source rows used as LLM context (conversational search). ## Other responses - `default` — error ## Changes - **2026-08-04** `eb39c8083035` — 3 breaking, 3 info - added `#/components/schemas/documentId` to the `knn/doc_id` request property `allOf` list - the `knn/doc_id` request property type/format changed from `integer`/`uint64` to ``/`` - the `hits/hits/items/_id` response's property type/format changed from `integer`/`uint64` to ``/`` for status `200` - the request property `knn/k` became optional - …2 more - **2026-07-15** `2fd450aa5f07` — 7 breaking, 1 warning, 20 info - added `subschema #1, subschema #2` to the `join/items/allOf[subschema #1]/on/items/` request property `allOf` list - added `subschema #2` to the `highlight/allOf[subschema #1]/highlight_query` request property `allOf` list - added `subschema #2` to the `knn/filter` request property `allOf` list - added `subschema #2` to the `query/allOf[#/components/schemas/queryFilter]/` request property `allOf` list - …24 more - **2026-02-14** `671933d40ac4` — 2 info - added the new optional request property `knn/oversampling` - added the new optional request property `knn/rescore` - …earlier changes not shown [Full history](https://skmtc.dev/manticoresoftware/apis/manticore-search-client/changes/search/post.md) --- [API](https://skmtc.dev/manticoresoftware/apis/manticore-search-client.md) · [All operations](https://skmtc.dev/manticoresoftware/apis/manticore-search-client/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/manticoresoftware/manticore-search-client/revisions/eb39c8083035/schema)