Manticore Search Search API
Operations about performing searches over tables
OpenAPI Specification
openapi: 3.1.0
info:
title: Manticore Client Index Search API
description: 'Сlient for Manticore Search.
'
version: 5.0.0
contact:
name: Manticore Software Ltd.
email: info@manticoresearch.com
url: https://manticoresearch.com/contact-us/
license:
name: MIT
url: http://opensource.org/licenses/MIT
servers:
- description: Default Manticore Search HTTP
url: http://127.0.0.1:9308/
tags:
- name: Search
description: Operations about performing searches over tables
paths:
/search:
post:
summary: Performs a search on a table
x-is_search: true
description: "\nThe method expects an object with the following mandatory properties:\n* the name of the table to search\n* the match query object\nFor details, see the documentation on [**SearchRequest**](SearchRequest.md)\nThe method returns an object with the following properties:\n- 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:\n - total: the total number of hits found.\n - hits: an array of hit objects, where each hit object represents a matched document. Each hit object has the following properties:\n - _id: the ID of the matched document.\n - _score: the score of the matched document.\n - _source: the source data of the matched document.\n\nIn 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\nHere is an example search response:\n\n ```\n {\n 'took':10,\n 'timed_out':false,\n 'hits':\n {\n 'total':2,\n 'hits':\n [\n {'_id':'1','_score':1,'_source':{'gid':11}},\n {'_id':'2','_score':1,'_source':{'gid':12}}\n ]\n }\n }\n ```\n\nFor 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).\n"
operationId: search
tags:
- Search
externalDocs:
url: https://manual.manticoresearch.com/Searching/Full_text_matching/Basic_usage#HTTP-JSON
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/searchRequest'
example:
- '''request=SearchRequest(table="test",query=Query(query_string="abc"))'''
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/searchResponse'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
/autocomplete:
post:
summary: Performs an autocomplete search on a table
description: "\nThe method expects an object with the following mandatory properties:\n* the name of the table to search\n* the query string to autocomplete\nFor details, see the documentation on [**Autocomplete**](Autocomplete.md)\nAn example: ``` {\n \"table\":\"table_name\",\n \"query\":\"query_beginning\"\n} ```\nAn example of the method's response:\n\n ```\n [\n {\n \"total\": 3,\n \"error\": \"\",\n \"warning\": \"\",\n \"columns\": [\n {\n \"query\": {\n \"type\": \"string\"\n }\n }\n ],\n \"data\": [\n {\n \"query\": \"hello\"\n },\n {\n \"query\": \"helio\"\n },\n {\n \"query\": \"hell\"\n }\n ]\n }\n ] \n ```\n\nFor more detailed information about the autocomplete queries, please refer to the documentation [here](https://manual.manticoresearch.com/Searching/Autocomplete).\n"
operationId: autocomplete
tags:
- Search
externalDocs:
url: https://manual.manticoresearch.com/dev/Searching/Autocomplete?client=JSON
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/autocompleteRequest'
example:
- '''request=AutocompleteRequest(table="test",query="abc")'''
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/sqlRawResponse'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
/pq/{table}/search:
post:
summary: Perform reverse search on a percolate table
operationId: percolate
description: "Performs a percolate search.\nThis method must be used only on percolate tables.\nExpects two parameters: the table name and an object with array of documents to be tested.\nAn example of the documents object: ```\n {\n \"query\" {\n \"percolate\": {\n \"document\": {\n \"content\":\"sample content\"\n }\n }\n }\n }\n```\nResponds with an object with matched stored queries: ```\n {\n 'timed_out':false,\n 'hits': {\n 'total':2,\n 'max_score':1,\n 'hits': [\n {\n 'table':'idx_pq_1',\n '_type':'doc',\n '_id':'2',\n '_score':'1',\n '_source': {\n 'query': {\n 'match':{'title':'some'}\n }\n }\n },\n {\n 'table':'idx_pq_1',\n '_type':'doc',\n '_id':'5',\n '_score':'1',\n '_source': {\n 'query': {\n 'ql':'some | none'\n }\n }\n }\n ]\n }\n }\n```\n"
tags:
- Search
externalDocs:
url: https://manual.manticoresearch.com/Updating_documents/UPDATE
parameters:
- in: path
name: table
schema:
type: string
required: true
description: Name of the percolate table
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/percolateRequest'
example:
query:
percolate:
document:
title: some text to match
responses:
'200':
description: items found
content:
application/json:
schema:
$ref: '#/components/schemas/searchResponse'
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
components:
schemas:
highlightFieldOption:
type: object
properties:
fragment_size:
type: integer
description: Maximum size of the text fragments in highlighted snippets per field
limit:
type: integer
description: Maximum size of snippets per field
limit_snippets:
type: integer
description: Maximum number of snippets per field
limit_words:
type: integer
description: Maximum number of words per field
number_of_fragments:
type: integer
description: Total number of highlighted fragments per field
additionalProperties: false
description: Options for controlling the behavior of highlighting on a per-field basis
boolFilter:
type: object
properties:
must:
type: array
items:
$ref: '#/components/schemas/queryFilter'
description: Query clauses that must match for the document to be included
must_not:
type: array
items:
$ref: '#/components/schemas/queryFilterAlias1'
description: Query clauses that must not match for the document to be included
should:
type: array
items:
$ref: '#/components/schemas/queryFilterAlias2'
description: Query clauses that should be matched, but are not required
additionalProperties: false
queryFilterAlias2:
$ref: '#/components/schemas/queryFilter'
searchResponse:
type: object
description: Response object containing the results of a search request
properties:
took:
type: integer
description: Time taken to execute the search
timed_out:
type: boolean
description: Indicates whether the search operation timed out
aggregations:
type: object
additionalProperties: true
description: Aggregated search results grouped by the specified criteria
hits:
type: object
properties:
max_score:
type: integer
description: Maximum score among the matched documents
total:
type: integer
description: Total number of matched documents
total_relation:
type: string
description: Indicates whether the total number of hits is accurate or an estimate
hits:
type: array
items:
$ref: '#/components/schemas/hitsHits'
description: Array of hit objects, each representing a matched document
description: Object containing the search hits, which represent the documents that matched the query.
example:
total: 2
hits:
- _id: 1
_score: 1
_source:
gid: 11
- _id: 2
_score: 1
_source:
gid: 20
profile:
type: object
description: Profile information about the search execution, if profiling is enabled
scroll:
type: string
description: Scroll token to be used fo pagination
warning:
type: object
additionalProperties: true
description: Warnings encountered during the search operation
sqlRawResponse:
type: array
items:
type: object
highlight:
allOf:
- type: object
description: Defines a query HIGHLIGHT expression to emphasize matched results
properties:
after_match:
type: string
default: </strong>
description: Text inserted after the matched term, typically used for HTML formatting
allow_empty:
type: boolean
description: Permits an empty string to be returned as the highlighting result. Otherwise, the beginning of the original text would be returned
around:
type: integer
description: Number of words around the match to include in the highlight
before_match:
type: string
default: <strong>
description: Text inserted before the match, typically used for HTML formatting
emit_zones:
type: boolean
description: Emits an HTML tag with the enclosing zone name before each highlighted snippet
encoder:
type: string
enum:
- default
- html
description: If set to 'html', retains HTML markup when highlighting
fields:
$ref: '#/components/schemas/highlightFields'
force_all_words:
type: boolean
description: Ignores the length limit until the result includes all keywords
force_snippets:
type: boolean
description: Forces snippet generation even if limits allow highlighting the entire text
highlight_query:
oneOf:
- type: null
- $ref: '#/components/schemas/queryFilter'
description: Optional query object to customize highlighting behavior
html_strip_mode:
type: string
enum:
- none
- strip
- index
- retain
description: Defines the mode for handling HTML markup in the highlight
limits_per_field:
type: boolean
description: Determines whether the 'limit', 'limit_words', and 'limit_snippets' options operate as individual limits in each field of the document
no_match_size:
type: integer
enum:
- 0
- 1
description: If set to 1, allows an empty string to be returned as a highlighting result
order:
type: string
enum:
- asc
- desc
- score
description: Sets the sorting order of highlighted snippets
pre_tags:
type: string
default: <strong>
description: Text inserted before each highlighted snippet
post_tags:
type: string
default: </strong>
description: Text inserted after each highlighted snippet
start_snippet_id:
type: integer
description: Sets the starting value of the %SNIPPET_ID% macro
use_boundaries:
type: boolean
description: Defines whether to additionally break snippets by phrase boundary characters
- $ref: '#/components/schemas/highlightFieldOption'
aggHistogram:
additionalProperties: false
description: Object to use histograms in aggregation, i.e., grouping search results by histogram values
properties:
field:
description: Field to group by
example: field
type: string
interval:
description: Interval of the histogram values
example: 10
type: integer
offset:
description: Offset of the histogram values. Default value is 0.
example: 1
type: integer
keyed:
description: Flag that defines if a search response will be a dictionary with the bucket keys. Default value is false.
example: true
type: boolean
required:
- field
- interval
aggComposite:
type: object
description: Object to perform composite aggregation, i.e., grouping search results by multiple fields
properties:
size:
type: integer
description: Maximum number of composite buckets in the result
example: 1000
sources:
type: array
items:
type: object
description: List of objects that contain terms used for composite aggregation.
additionalProperties:
$ref: '#/components/schemas/aggCompositeSource'
additionalProperties: false
searchQuery:
allOf:
- $ref: '#/components/schemas/queryFilter'
- type: object
properties:
highlight:
$ref: '#/components/schemas/highlight'
description: Defines a query structure for performing search operations
highlightFields:
oneOf:
- type: array
items:
type: string
- type: object
description: List of fields available for highlighting
aggCompositeTerm:
type: object
required:
- field
properties:
field:
type: string
description: Name of field to operate with
example: field1
additionalProperties: false
description: Object representing a term to be used in composite aggregation.
knn:
type: object
required:
- field
properties:
field:
type: string
description: Field to perform the k-nearest neighbor search on
k:
type: integer
deprecated: true
description: Deprecated. Use the top-level `limit` parameter instead.
query:
oneOf:
- type: string
- type: array
items:
type: number
query_vector:
type: array
items:
type: number
description: The vector used as input for the KNN search
doc_id:
type: integer
format: uint64
description: The docuemnt ID used as input for the KNN search
ef:
type: integer
description: Optional parameter controlling the accuracy of the search
filter:
$ref: '#/components/schemas/queryFilter'
description: Object representing a k-nearest neighbor search query
join:
allOf:
- type: object
required:
- type
- 'on'
- table
properties:
type:
type: string
enum:
- inner
- left
description: Type of the join operation
'true':
type: array
items:
$ref: '#/components/schemas/joinOn'
description: List of objects defining joined tables
query:
$ref: '#/components/schemas/fulltextFilter'
table:
type: string
description: Basic table of the join operation
additionalProperties: false
description: Object representing the join operation between two tables
errorResponse:
type: object
description: Error response object containing information about the error and a status code
required:
- error
properties:
error:
$ref: '#/components/schemas/responseError'
status:
type: integer
description: HTTP status code of the error response
default: 500
example:
status: 500
error: an error occured
geoDistance:
type: object
properties:
location_anchor:
type: object
description: Specifies the location of the pin point used for search
properties:
lat:
type: number
description: Latitude of the anchor point
lon:
type: number
description: Longitude of the anchor point
additionalProperties: false
location_source:
type: string
description: Field name in the document that contains location data
distance_type:
type: string
enum:
- adaptive
- haversine
description: Algorithm used to calculate the distance
distance:
type: string
pattern: /^\.+(km|m|cm|mm|mi|yd|ft|in|NM|nmi|kilometers|meters|centimeters|millimeters|miles|yards|foots|inches|nauticalmiles|)$/
description: The distance from the anchor point to filter results by
additionalProperties: false
description: Object to perform geo-distance based filtering on queries
queryFilterAlias1:
$ref: '#/components/schemas/queryFilter'
autocompleteRequest:
type: object
description: Object containing the data for performing an autocomplete search.
required:
- table
- query
properties:
table:
type: string
description: The table to perform the search on
query:
type: string
description: The beginning of the string to autocomplete
options:
type: object
description: "Autocomplete options\n - layouts: A comma-separated string of keyboard layout codes to validate and check for spell correction. Available options - us, ru, ua, se, pt, no, it, gr, uk, fr, es, dk, de, ch, br, bg, be. By default, all are enabled.\n - fuzziness: (0,1 or 2) Maximum Levenshtein distance for finding typos. Set to 0 to disable fuzzy matching. Default is 2\n - prepend: true/false If true, adds an asterisk before the last word for prefix expansion (e.g., *word )\n - append: true/false If true, adds an asterisk after the last word for prefix expansion (e.g., word* )\n - expansion_len: Number of characters to expand in the last word. Default is 10.\n"
additionalProperties: true
example:
table: test
query: Start
options:
layouts: us,uk
fuzziness: 0
joinCond:
type: object
required:
- field
- table
properties:
field:
type: string
description: Field to join on
table:
type: string
description: Joined table
query:
$ref: '#/components/schemas/fulltextFilter'
type:
type: {}
additionalProperties: false
description: Object representing the conditions used to perform the join operation
aggregation:
allOf:
- type: object
description: Object used for grouping search results
properties:
terms:
$ref: '#/components/schemas/aggTerms'
sort:
type: array
items:
type: {}
composite:
$ref: '#/components/schemas/aggComposite'
histogram:
$ref: '#/components/schemas/aggHistogram'
responseErrorText:
type: string
description: Error message text returned in case of an error
fulltextFilter:
type: object
properties:
query_string:
type: string
description: Filter object defining a query string
match:
type: object
description: Filter object defining a match keyword passed as a string or in a Match object
match_phrase:
type: object
description: Filter object defining a match phrase
match_all:
type: object
description: Filter object to select all documents
additionalProperties: false
description: Defines a type of filter for full-text search queries
queryFilter:
allOf:
- $ref: '#/components/schemas/fulltextFilter'
- type: object
properties:
bool:
$ref: '#/components/schemas/boolFilter'
equals:
type: {}
description: Filter to match exact attribute values.
in:
type: object
description: Filter to match a given set of attribute values.
range:
type: object
description: Filter to match a given range of attribute values passed in Range objects
geo_distance:
$ref: '#/components/schemas/geoDistance'
additionalProperties: false
description: Object used to apply various conditions, such as full-text matching or attribute filtering, to a search query
percolateRequest:
type: object
description: Object containing the query for percolating documents against stored queries in a percolate table
required:
- query
properties:
query:
type: object
additionalProperties: true
required:
- percolate
properties:
percolate:
type: object
description: Object representing the document to percolate
example:
percolate:
document:
title: some text to match
hitsHits:
type: object
properties:
_id:
type: integer
format: uint64
description: The ID of the matched document
_score:
type: integer
description: The score of the matched document
_source:
type: object
description: The source data of the matched document
_knn_dist:
type: number
description: The knn distance of the matched document returned for knn queries
highlight:
type: object
description: The highlighting-related data of the matched document
table:
type: string
description: The table name of the matched document returned for percolate queries
'_type:':
type: string
description: The type of the matched document returned for percolate queries
fields:
type: object
description: The percolate-related fields of the matched document returned for percolate queries
additionalProperties: true
description: Search hit representing a matched document
searchRequest:
description: Request object for search operation
type: object
required:
- table
properties:
table:
type: string
description: The table to perform the search on
query:
$ref: '#/components/schemas/searchQuery'
join:
type: array
items:
$ref: '#/components/schemas/join'
description: Join clause to combine search data from multiple tables
highlight:
$ref: '#/components/schemas/highlight'
limit:
type: integer
description: Maximum number of results to return
knn:
$ref: '#/components/schemas/knn'
aggs:
type: object
additionalProperties:
$ref: '#/components/schemas/aggregation'
example:
agg1:
terms:
field: field1
size: 1000
sort:
- field1: null
order: asc
description: Defines aggregation settings for grouping results
expressions:
type: object
additionalProperties:
type: string
example:
title_len: crc32(title)
description: Expressions to calculate additional values for the result
max_matches:
type: integer
description: Maximum number of matches allowed in the result
offset:
type: integer
description: Starting point for pagination of the result
options:
type: object
description: Additional search options
profile:
type: boolean
description: Enable or disable profiling of the search request
sort:
type: {}
description: Sorting criteria for the search results
_source:
type: {}
description: Specify which fields to include or exclude in the response
track_scores:
type: boolean
description: Enable or disable result weight calculation used for sorting
example:
table: your_table
query:
query_string: your_query
joinOn:
allOf:
- type: object
properties:
right:
$ref: '#/components/schemas/joinCond'
additionalProperties: false
- type: object
properties:
left:
$ref: '#/components/schemas/joinCond'
additionalProperties: false
- type: object
properties:
operator:
type: string
enum:
- eq
additionalProperties: false
description: Defines joined tables
aggTerms:
type: object
required:
- field
properties:
field:
type: string
description: Name of attribute to aggregate by
example: field1
size:
type: integer
description: Maximum number of buckets in the result
example: 1000
description: Object containing term fields to aggregate on
additionalProperties: false
responseErrorDetails:
type: object
description: Detailed error information returned in case of an error response
required:
- type
properties:
type:
type: string
description: Type or category of the error
reason:
type:
- string
- 'null'
description: Detailed explanation of why the error occurred
table:
type:
- string
- 'null'
description: The table related to the error, if applicable
responseError:
oneOf:
- $ref: '#/components/schemas/responseErrorDetails'
- $ref: '#/components/schemas/responseErrorText'
aggCompositeSource:
type: object
required:
- terms
properties:
terms:
$ref: '#/components/schemas/aggCompositeTerm'
additionalProperties: false
description: Object containing terms used for composite aggregation.
externalDocs:
description: Find out more about Manticore Search
url: https://manticoresearch.com/