Run a knn search | Elasticsearch API documentation (v8)

Path parameters

indexstring | array[string] Required
A comma-separated list of index names to search; use _all or to perform the operation on all indices.

Query parameters

routingstring
A comma-separated list of specific routing values.

application/json

Body

_sourceboolean | object
Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
SourceConfigboolean SourceFilterobject
Hide attributes Show attributes
excludesstring | array[string]
includesstring | array[string]
docvalue_fieldsarray[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
- fieldstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- formatstring
  The format in which the values are returned.
- include_unmappedboolean
stored_fieldsstring | array[string]
fieldsstring | array[string]
filterobject | 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:
QueryContainerobject array-2array[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
knnobject Required
Hide knn attributes Show knn attributes object
- fieldstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- query_vectorarray[number] Required
- knumber Required
  The final number of nearest neigrs to return as top hits
- num_candidatesnumber Required
  The number of nearest neigr candidates to consider per shard

Responses

200 application/json
Hide response attributes Show response attributes object
- tooknumber Required
  The milliseconds it took Elasticsearch to run the request.
- timed_outboolean Required
  If true, the request timed out before completion; returned results may be partial or empty.
- _shardsobject Required
  Hide _shards attributes Show _shards attributes object
  failednumber Required
  successfulnumber Required
  totalnumber Required
  failuresarray[object]
  Hide failures attributes Show failures attributes object
  indexstring
  nodestring
  reasonobject Required
  Hide reason attributes Show reason attributes object
  typestring Required
  The type of error
  reasonstring
  A human-readable explanation of the error, in English.
  stack_tracestring
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  caused_byobject
  root_causearray[object]
  suppressedarray[object]
  shardnumber Required
  statusstring
  skippednumber
- hitsobject Required
  Hide hits attributes Show hits attributes object
  totalobject | number
  Total hit count information, present only if track_total_hits wasn't false in the search request.
  One of:
  TotalHitsobject number-2number
  hitsarray[object] Required
  Hide hits attributes Show hits attributes object
  _indexstring Required
  _idstring
  _scorenumber | string | null
  One of:
  number-1number string-2string | null
  _explanationobject
  Hide _explanation attributes Show _explanation attributes object
  descriptionstring Required
  detailsarray[object] Required
  valuenumber Required
  fieldsobject
  Hide fields attribute Show fields attribute object
  *object Additional properties
  highlightobject
  Hide highlight attribute Show highlight attribute object
  *array[string] Additional properties
  inner_hitsobject
  Hide inner_hits attribute Show inner_hits attribute object
  *object Additional properties
  Hide * attribute Show * attribute object
  hitsobject Required
  matched_queriesarray[string] | object
  One of:
  array-1array[string]object-2object
  _nestedobject
  Hide _nested attributes Show _nested attributes object
  fieldstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  offsetnumber Required
  _nestedobject
  _ignoredarray[string]
  ignored_field_valuesobject
  Hide ignored_field_values attribute Show ignored_field_values attribute object
  *array[number | string | boolean | null | object] Additional properties
  A field value.
  _shardstring
  _nodestring
  _routingstring
  _sourceobject
  _ranknumber
  _seq_nonumber
  _primary_termnumber
  _versionnumber
  sortarray[number | string | boolean | null | object]
  A field value.
  A field value.
  One of:
  FieldValuenumber FieldValuenumber FieldValuestring FieldValueboolean FieldValuestring | null FieldValueobject
  max_scorenumber | string | null
  One of:
  number-1number string-2string | null
- fieldsobject
  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_scorenumber
  The highest returned document score. This value is null for requests that do not sort by score.

GET /{index}/_knn_search

curl \
 --request GET '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}}'

Path parameters

Query parameters

Body

_sourceboolean | object

filterobject | array[object]

Responses

totalobject | number

_scorenumber | string | null

matched_queriesarray[string] | object

max_scorenumber | string | null