Run a knn search Deprecated Technical preview

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

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

  • _source boolean | object

    Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

    One of:
    _types:SourceConfig boolean _types:SourceFilter object
  • 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.

    Hide docvalue_fields attributes Show docvalue_fields attributes object
    • field string Required

      Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

    • format string

      The format in which the values are returned.

    • include_unmapped boolean
  • stored_fields string | array[string]
  • fields string | array[string]

  • 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:
    query_dsl:QueryContainer object array-2 array[object]

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

    Additional properties are allowed.

    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.

    Additional properties are allowed.

    External documentation
  • knn object Required

    Additional properties are allowed.

    Hide knn attributes Show knn attributes object
    • field string Required

      Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

    • query_vector array[number] Required
    • 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

      Additional properties are allowed.

      Hide _shards attributes Show _shards attributes object
      • failed number Required
      • successful number Required
      • total number Required
      • failures array[object]
        Hide failures attributes Show failures attributes object
        • index string
        • node string
        • reason object Required

          Additional properties are allowed.

          Hide reason attributes Show reason attributes object
          • type string Required

            The type of error

          • reason string

            A human-readable explanation of the error, in English.

          • stack_trace string

            The server stack trace. Present only if the error_trace=true parameter was sent with the request.

          • caused_by object

            Additional properties are allowed.

          • root_cause array[object]

            Additional properties are allowed.

          • suppressed array[object]

            Additional properties are allowed.

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

      Additional properties are allowed.

      Hide hits attributes Show hits attributes object
    • 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

        Additional properties are allowed.

    • 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 '{"":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}}'
Request examples 
{
  "": 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
  }
}
Response examples (200) 
{
  "took": 42.0,
  "timed_out": true,
  "_shards": {
    "failed": 42.0,
    "successful": 42.0,
    "total": 42.0,
    "failures": [
      {
        "index": "string",
        "node": "string",
        "reason": {
          "type": "string",
          "reason": "string",
          "stack_trace": "string",
          "caused_by": {},
          "root_cause": [
            {}
          ],
          "suppressed": [
            {}
          ]
        },
        "shard": 42.0,
        "status": "string"
      }
    ],
    "skipped": 42.0
  },
  "hits": {
    "total": {
      "relation": "eq",
      "value": 42.0
    },
    "hits": [
      {
        "_index": "string",
        "_id": "string",
        "_score": 42.0,
        "_explanation": {
          "description": "string",
          "details": [
            {}
          ],
          "value": 42.0
        },
        "fields": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "highlight": {
          "additionalProperty1": [
            "string"
          ],
          "additionalProperty2": [
            "string"
          ]
        },
        "inner_hits": {
          "additionalProperty1": {
            "hits": {}
          },
          "additionalProperty2": {
            "hits": {}
          }
        },
        "matched_queries": [
          "string"
        ],
        "_nested": {
          "field": "string",
          "offset": 42.0,
          "_nested": {}
        },
        "_ignored": [
          "string"
        ],
        "ignored_field_values": {
          "additionalProperty1": [
            {}
          ],
          "additionalProperty2": [
            {}
          ]
        },
        "_shard": "string",
        "_node": "string",
        "_routing": "string",
        "_source": {},
        "_rank": 42.0,
        "_seq_no": 42.0,
        "_primary_term": 42.0,
        "_version": 42.0,
        "sort": [
          42.0
        ]
      }
    ],
    "max_score": 42.0
  },
  "fields": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "max_score": 42.0
}