Run a knn search Deprecated Technical preview; Added in 8.0.0

POST /{index}/_knn_search
Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /{index}/_knn_search

POST /{index}/_knn_search

NOTE: The kNN search API has been replaced by the knn option in the search API.

Perform a k-nearest neighbor (kNN) search on a dense_vector field and return the matching documents. Given a query vector, the API finds the k closest vectors and returns those documents as search hits.

Elasticsearch uses the HNSW algorithm to support efficient kNN search. Like most kNN algorithms, HNSW is an approximate method that sacrifices result accuracy for improved search speed. This means the results returned are not always the true k closest neighbors.

The kNN search API supports restricting the search using a filter. The search will return the top k documents that also match the filter query.

A kNN search response has the exact same structure as a search API response. However, certain sections have a meaning specific to kNN search:

  • The document _score is determined by the similarity between the query and document vector.
  • The hits.total object contains the total number of nearest neighbor candidates considered, which is num_candidates * num_shards. The hits.total.relation will always be eq, indicating an exact value.

Path parameters

  • index string | array[string] Required

    A comma-separated list of index names to search; use _all or to perform the operation on all indices.

Query parameters

  • routing string

    A comma-separated list of specific routing values.

application/json

Body Required

  • _source boolean | object

    Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response.

    One of:
    boolean-1 boolean SourceFilter object

    Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response.

  • docvalue_fields array[object]

    The request returns doc values for field names matching these patterns in the hits.fields property of the response. It accepts wildcard (*) patterns.

    A reference to a field with formatting instructions on how to return the value

    Hide docvalue_fields attributes Show docvalue_fields attributes object
    • field string Required

      A wildcard pattern. The request returns values for field names matching this pattern.

    • format string

      The format in which the values are returned.

    • include_unmapped boolean
  • stored_fields string | array[string]

    A list of stored fields to return as part of a hit. If no fields are specified, no stored fields are included in the response. If this field is specified, the _source parameter defaults to false. You can pass _source: true to return both source fields and stored fields in the search response.

  • fields string | array[string]

    The request returns values for field names matching these patterns in the hits.fields property of the response. It accepts wildcard (*) patterns.

  • filter object | array[object]

    A query to filter the documents that can match. The kNN search will return the top k documents that also match this filter. The value can be a single query or a list of queries. If filter isn't provided, all documents are allowed to match.

    One of:
    QueryContainer object array-2 array[object]

    An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

    External documentation

    An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

    An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

    External documentation
  • knn object Required

    The kNN query to run.

    External documentation
    Hide knn attributes Show knn attributes object
    • field string Required

      The name of the vector field to search against

    • query_vector array[number] Required

      The query vector

    • k number Required

      The final number of nearest neighbors to return as top hits

    • num_candidates number Required

      The number of nearest neighbor candidates to consider per shard

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • took number Required

      The milliseconds it took Elasticsearch to run the request.

    • timed_out boolean Required

      If true, the request timed out before completion; returned results may be partial or empty.

    • _shards object Required

      A count of shards used for the request.

      Hide _shards attributes Show _shards attributes object
      • failed number Required

        The number of shards the operation or search attempted to run on but failed.

      • successful number Required

        The number of shards the operation or search succeeded on.

      • total number Required

        The number of shards the operation or search will run on overall.

      • failures array[object]
        Hide failures attributes Show failures attributes object
        • index string
        • node string
        • reason object Required

          Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        • shard number
        • status string
        • primary boolean
      • skipped number
    • hits object Required

      The returned documents and metadata.

      Hide hits attributes Show hits attributes object

      • total object | number

        Total hit count information, present only if track_total_hits wasn't false in the search request.

        One of:
        TotalHits object number-2 number
      • hits array[object] Required
        Hide hits attributes Show hits attributes object
        • _index string Required
        • _id string

        • _score number | string | null

          One of:
          number-1 number string-2 string | null
        • _explanation object
        • fields object
          Hide fields attribute Show fields attribute object
          • * object Additional properties
        • highlight object
          Hide highlight attribute Show highlight attribute object
          • * array[string] Additional properties
        • inner_hits object
          Hide inner_hits attribute Show inner_hits attribute object
          • * object Additional properties

        • matched_queries array[string] | object

          One of:
          array-1 array[string] object-2 object
        • _nested object
        • _ignored array[string]
        • ignored_field_values object
          Hide ignored_field_values attribute Show ignored_field_values attribute object
          • * array[number | string | boolean | null | object] Additional properties
        • _shard string
        • _node string
        • _routing string
        • _source object
        • _rank number
        • _seq_no number
        • _primary_term number
        • _version number
        • sort array[number | string | boolean | null | object]

      • max_score number | string | null

        One of:
        number-1 number string-2 string | null
    • fields object

      The field values for the documents. These fields must be specified in the request using the fields parameter.

      Hide fields attribute Show fields attribute object
      • * object Additional properties
    • max_score number

      The highest returned document score. This value is null for requests that do not sort by score.
POST /{index}/_knn_search 
curl \
 --request POST 'http://api.example.com/{index}/_knn_search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"_source":true,"docvalue_fields":[{"field":"string","format":"string","include_unmapped":true}],"stored_fields":"string","fields":"string","filter":{},"knn":{"field":"string","query_vector":[42.0],"k":42.0,"num_candidates":42.0}}'