Run a knn search Deprecated Technical preview

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.

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

      Format in which the values are returned.

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

  • filter object | array[object]

    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]

    Additional properties are allowed.

    External documentation

    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

POST /{index}/_knn_search 
curl \
 -X POST http://api.example.com/{index}/_knn_search \
 -H "Content-Type: application/json" \
 -d '{"":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
}