Semantic search API | Elasticsearch Guide [master]

You are looking at preliminary documentation for a future release. Not what you want? See the current release documentation.

› › ›

« kNN search API Scroll API »

Semantic search APIedit

This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Semantic search uses a text embedding NLP model to generate a dense vector from the input query string. The resulting dense vector is then used in a k-nearest neighbor (knn) search against an index containing dense vectors created with the same text embedding model. The search results are semantically similar as learned by the model.

GET my-index/_semantic_search
{
  "model_text": "A picture of a snow capped mountain",
  "model_id": "my-text-embedding-model",
  "knn": {
    "field": "text_embedding",
    "k": 10,
    "num_candidates": 100
  }
}

Requestedit

GET <target>/_semantic_search

POST <target>/_semantic_search

Prerequisitesedit

If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias.

Descriptionedit

The semantic search API uses a text embedding model to create a dense vector representation of the query string.

Path parametersedit

<target>: (Optional, string) Comma-separated list of data streams, indices, and aliases to search. Supports wildcards (*). To search all data streams and indices, use * or _all.

Query parametersedit

routing: (Optional, string) Custom value used to route operations to a specific shard.

Request bodyedit

model_id

(Required, string) The unique identifier of the trained model.

model_text

(Required, string) The input to the text embedding model.

knn

(Required, object) Defines the kNN query to run.

Properties of knn object

field: (Required, string) The name of the vector field to search against. Must be a dense_vector field with indexing enabled.
filter: (Optional, Query DSL 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 is not provided, all documents are allowed to match.
k: (Required, integer) Number of nearest neighbors to return as top hits. This value must be less than num_candidates.
num_candidates: (Required, integer) The number of nearest neighbor candidates to consider per shard. Cannot exceed 10,000. Elasticsearch collects num_candidates results from each shard, then merges them to find the top k results. Increasing num_candidates tends to improve the accuracy of the final k results.

query

(Optional, query object) Defines the search definition using the Query DSL.

text_embedding_config

(Object, optional) Override certain setting of the text embedding model’s configuration.

Properties of text_embedding inference

results_field

(Optional, string) The field that is added to incoming documents to contain the inference prediction. Defaults to predicted_value.

tokenization

(Optional, object) Indicates the tokenization to perform and the desired settings. The default tokenization configuration is bert. Valid tokenization values are

bert: Use for BERT-style models
mpnet: Use for MPNet-style models
roberta: Use for RoBERTa-style and BART-style models

Properties of tokenization

bert

(Optional, object) BERT-style tokenization is to be performed with the enclosed settings.

Properties of bert

truncate

(Optional, string) Indicates how tokens are truncated when they exceed max_sequence_length. The default value is first.

none: No truncation occurs; the inference request receives an error.
first: Only the first sequence is truncated.
second: Only the second sequence is truncated. If there is just one sequence, that sequence is truncated.

For zero_shot_classification, the hypothesis sequence is always the second sequence. Therefore, do not use second in this case.

roberta

(Optional, object) RoBERTa-style tokenization is to be performed with the enclosed settings.

Properties of roberta

truncate

(Optional, string) Indicates how tokens are truncated when they exceed max_sequence_length. The default value is first.

none: No truncation occurs; the inference request receives an error.
first: Only the first sequence is truncated.
second: Only the second sequence is truncated. If there is just one sequence, that sequence is truncated.

For zero_shot_classification, the hypothesis sequence is always the second sequence. Therefore, do not use second in this case.

mpnet

(Optional, object) MPNet-style tokenization is to be performed with the enclosed settings.

Properties of mpnet

truncate

(Optional, string) Indicates how tokens are truncated when they exceed max_sequence_length. The default value is first.

none: No truncation occurs; the inference request receives an error.
first: Only the first sequence is truncated.
second: Only the second sequence is truncated. If there is just one sequence, that sequence is truncated.

For zero_shot_classification, the hypothesis sequence is always the second sequence. Therefore, do not use second in this case.

docvalue_fields

(Optional, array of strings and objects) Array of field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.

You can specify items in the array as a string or object. See Doc value fields.

Properties of docvalue_fields objects

field

(Required, string) Wildcard pattern. The request returns doc values for field names matching this pattern.

format

(Optional, string) Format in which the doc values are returned.

For date fields, you can specify a date date format. For numeric fields fields, you can specify a DecimalFormat pattern.

For other field data types, this parameter is not supported.

fields

(Optional, array of strings and objects) Array of field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.

You can specify items in the array as a string or object. See the fields option.

Properties of fields objects

field

(Required, string) Field to return. Supports wildcards (*).

format

(Optional, string) Format for date and geospatial fields. Other field data types do not support this parameter.

date and date_nanos fields accept a date format. geo_point and geo_shape fields accept:

geojson (default)

GeoJSON

wkt

Well Known Text

mvt(<spec>)

Binary Mapbox vector tile. The API returns the tile as a base64-encoded string. The <spec> has the format <zoom>/<x>/<y> with two optional suffixes: @<extent> and/or :<buffer>. For example, 2/0/1 or 2/0/1@4096:5.

mvt parameters

<zoom>: (Required, integer) Zoom level for the tile. Accepts 0-29.
<x>: (Required, integer) X coordinate for the tile.
<y>: (Required, integer) Y coordinate for the tile.
<extent>: (Optional, integer) Size, in pixels, of a side of the tile. Vector tiles are square with equal sides. Defaults to 4096.
<buffer>: (Optional, integer) Size, in pixels, of a clipping buffer outside the tile. This allows renderers to avoid outline artifacts from geometries that extend past the extent of the tile. Defaults to 5.

_source

(Optional) Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response. Defaults to true. See source filtering.

Valid values for _source

true

(Boolean) The entire document source is returned.

false

(Boolean) The document source is not returned.

<wildcard_pattern>

(string or array of strings) Wildcard (*) pattern or array of patterns containing source fields to return.

<object>

(object) Object containing a list of source fields to include or exclude.

Properties for <object>

excludes

(string or array of strings) Wildcard (*) pattern or array of patterns containing source fields to exclude from the response.

You can also use this property to exclude fields from the subset specified in includes property.

includes

(string or array of strings) Wildcard (*) pattern or array of patterns containing source fields to return.

If this property is specified, only these source fields are returned. You can exclude fields from this subset using the excludes property.

stored_fields

(Optional, string) A comma-separated list of stored fields to return as part of a hit. If no fields are specified, no stored fields are included in the response. See Stored fields.

If this option 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.

Response bodyedit

The semantic search response has the same structure as a kNN search response.

« kNN search API Scroll API »