[[semantic-search-api]]
=== Semantic search API
++++
<titleabbrev>Semantic search</titleabbrev>
++++

experimental::[]
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 <<knn-search,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.

[source,console]
----
GET my-index/_semantic_search
{
  "query_string": "A picture of a snow capped mountain",
  "model_id": "my-text-embedding-model",
  "knn": {
    "field": "text_embedding",
    "k": 10,
    "num_candidates": 100
  }
}
----
// TEST[skip:TBD]


[[semantic-search-api-request]]
==== {api-request-title}

`GET <target>/_semantic_search`

`POST <target>/_semantic_search`

[[semantic-search-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `read`
<<privileges-list-indices,index privilege>> for the target data stream, index,
or alias.

[[semantic-search-api-desc]]
==== {api-description-title}

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


[[semantic-search-api-path-params]]
==== {api-path-parms-title}

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

[role="child_attributes"]
[[semantic-search-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=routing]

[role="child_attributes"]
[[semantic-search-api-request-body]]
==== {api-request-body-title}

`model_id`::
(Required, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id]

`query_string`::
(Required, string) The input text to embed.

`knn`::
(Required, object)
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=knn]

`query`::
(Optional, <<query-dsl,query object>>) Defines the search definition using the
<<query-dsl,Query DSL>>.

`text_embedding_config`::
(Object, optional) Override certain setting of the text embedding model's configuration
.Properties of text_embedding inference
[%collapsible%open]
=====
`results_field`::::
(Optional, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-results-field]

`tokenization`::::
(Optional, object)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization]
+
.Properties of tokenization
[%collapsible%open]
======
`bert`::::
(Optional, object)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-bert]
+
.Properties of bert
[%collapsible%open]
=======
`truncate`::::
(Optional, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-truncate]
=======
`roberta`::::
(Optional, object)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-roberta]
+
.Properties of roberta
[%collapsible%open]
=======
`truncate`::::
(Optional, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-truncate]
=======
`mpnet`::::
(Optional, object)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-mpnet]
+
.Properties of mpnet
[%collapsible%open]
=======
`truncate`::::
(Optional, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-config-nlp-tokenization-truncate]
=======
======
=====

include::{es-repo-dir}/search/search.asciidoc[tag=docvalue-fields-def]
include::{es-repo-dir}/search/search.asciidoc[tag=fields-param-def]
include::{es-repo-dir}/search/search.asciidoc[tag=source-filtering-def]
include::{es-repo-dir}/search/search.asciidoc[tag=stored-fields-def]

[role="child_attributes"]
[[semantic-search-api-response-body]]
==== {api-response-body-title}

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