v1

latestOpenAPI 3.1.0MIT2026-07-17116965.4 KB
Search

Performs a search on a table

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 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.

post/search

Request body

tablestring

The table to perform the search on

limitinteger

Maximum number of results to return

facet_filter_mode'strict' | 'auto' | 'max'

Controls how facets inherit attribute filters from the main query. Faceted search

{"stackTrail":"components:schemas:searchRequest:properties:aggs","oasType":"schema","type":"unknown","description":"Defines aggregation settings for grouping results","example":{"agg1":{"terms":{"field":"field1","size":1000,"sort":[{"field1":null,"order":"asc"}]}}}}
{"stackTrail":"components:schemas:searchRequest:properties:expressions","oasType":"schema","type":"unknown","description":"Expressions to calculate additional values for the result. Simpler alternative to `script_fields`; expression names must be lowercase.\n","example":{"title_len":"crc32(title)"}}
{"stackTrail":"components:schemas:searchRequest:properties:script_fields","oasType":"schema","type":"unknown","description":"Named expressions computed at search time. Each value defines an inline script whose result is stored under the field name. For more information see [Expressions](https://manual.manticoresearch.com/Searching/Expressions#script_fields)\n","example":{"add_all":{"script":{"inline":"( gid * 10 ) | crc32(title)"}},"title_len":{"script":{"inline":"crc32(title)"}}}}
max_matchesinteger

Maximum number of matches allowed in the result

offsetinteger

Starting point for pagination of the result

optionsobject

Additional search options

profileboolean

Enable or disable profiling of the search request

sortobject

Sorting criteria for the search results

_sourceobject

Specify which fields to include or exclude in the response

track_scoresboolean

Enable or disable result weight calculation used for sorting

Example request

{
  "table": "your_table",
  "query": {
    "query_string": "your_query"
  }
}

Response

Ok. Returns searchResponse. For conversational search requests that include a chat object, the optional conversational fields are also set.

tookinteger

Time taken to execute the search

timed_outboolean

Indicates whether the search operation timed out

{"stackTrail":"components:schemas:searchResponse:properties:aggregations","oasType":"schema","type":"unknown","description":"Aggregated search results grouped by the specified criteria. Each named aggregation typically contains a `buckets` array (or keyed map) of bucket objects with `key`, `doc_count`, and optional `status`.\n","example":{"sizes":{"buckets":[{"key":"small","doc_count":1,"status":"selected"},{"key":"large","doc_count":1,"status":"available"}]},"colors":{"buckets":[{"key":10,"doc_count":1019},{"key":9,"doc_count":954,"status":"unavailable"}]}}}
profileobject

Profile information about the search execution, if profiling is enabled

scrollstring

Scroll token to be used fo pagination

warningobject

Warnings encountered during the search operation

conversation_uuidstring

Existing or generated conversation id (conversational search)

user_querystring

Original user query (conversational search)

search_querystring

Standalone search query used for KNN retrieval (conversational search)

responsestring

LLM answer as generated (conversational search)

sourcesstring

JSON string containing retrieved source rows used as LLM context (conversational search).

Example response

{
  "hits": {
    "total": 2,
    "hits": [
      {
        "_id": 1,
        "_score": 1,
        "_source": {
          "gid": 11
        }
      },
      {
        "_id": 2,
        "_score": 1,
        "_source": {
          "gid": 20
        }
      }
    ]
  },
  "took": 0,
  "user_query": "What is vector search?",
  "sources": "[{\"id\":1,\"title\":\"Vector Search\",\"content\":\"...\",\"knn_dist\":0.12}]",
  "response": "Vector search finds similar items by comparing embeddings...",
  "profile": "{}",
  "scroll": "scroll",
  "warning": "{}",
  "timed_out": true,
  "search_query": "vector search, embeddings, similarity search",
  "aggregations": {
    "sizes": {
      "buckets": [
        {
          "key": "small",
          "doc_count": 1,
          "status": "selected"
        },
        {
          "key": "large",
          "doc_count": 1,
          "status": "available"
        }
      ]
    },
    "colors": {
      "buckets": [
        {
          "key": 10,
          "doc_count": 1019
        },
        {
          "key": 9,
          "doc_count": 954,
          "status": "unavailable"
        }
      ]
    }
  },
  "conversation_uuid": "docs-chat-001"
}
All 11 operations