Performs a kNN search Deprecated Technical preview

POST /{index}/_knn_search

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
}