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/