---
navigation_title: "Search and retrieve"
mapped_pages:
  - https://www.elastic.co/guide/en/elasticsearch/reference/current/semantic-text.html
applies_to:
  stack: ga 9.0
  serverless: ga
---

# Search and retrieve `semantic_text` fields [set-up-configuration-semantic-text]

This page provides instructions for searching and retrieving data from `semantic_text` fields. Learn how to query `semantic_text` fields, retrieve indexed chunks, retrieve field embeddings, and highlight the most relevant fragments from search results.

## Query `semantic_text` fields [querying-semantic-text-fields]

You can query `semantic_text` fields using the following query types:

- Match query: The recommended method for querying `semantic_text` fields. You can use [Query DSL](/reference/query-languages/query-dsl/query-dsl-match-query.md) or [ES|QL](/reference/query-languages/esql/functions-operators/search-functions.md#esql-match) syntax. To learn how to run match queries on `semantic_text` fields, refer to this [example](docs-content://solutions/search/semantic-search/semantic-search-semantic-text.md#semantic-text-semantic-search).

- kNN query: Finds the nearest vectors to a query vector using a similarity metric, mainly for advanced or combined search use cases. You can use [Query DSL](/reference/query-languages/query-dsl/query-dsl-knn-query.md#knn-query-with-semantic-text) or {applies_to}`stack: ga 9.2` [ES|QL](/reference/query-languages/esql/functions-operators/dense-vector-functions.md#esql-knn) syntax. To learn how to run knn queries on `semantic_text` fields, refer to this [example](/reference/query-languages/query-dsl/query-dsl-knn-query.md#knn-query-with-semantic-text).

- Sparse vector query: Executes searches using sparse vectors generated by a sparse retrieval model such as [ELSER](docs-content://explore-analyze/machine-learning/nlp/ml-nlp-elser.md). You can use it with [Query DSL](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md) syntax. To learn how to run sparse vector queries on `semantic_text` fields, refer to this [example](/reference/query-languages/query-dsl/query-dsl-sparse-vector-query.md#example-query-on-a-semantic_text-field).

- [Semantic query](/reference/query-languages/query-dsl/query-dsl-semantic-query.md): We don't recommend this legacy query type for _new_ projects, because the alternatives in this list enable more flexibility and customization. The `semantic` query remains available to support existing implementations.

### Retrieve indexed chunks [retrieving-indexed-chunks]
```{applies_to}
stack: ga 9.2
serverless: ga
```

You can retrieve the individual chunks generated by your semantic field's chunking
strategy using the [fields parameter](/reference/elasticsearch/rest-apis/retrieve-selected-fields.md#search-fields-param):

```console
POST test-index/_search
{
  "query": {
    "ids" : {
      "values" : ["1"]
    }
  },
  "fields": [
    {
      "field": "semantic_text_field",
      "format": "chunks"      <1>
    }
  ]
}
```
% TEST[skip:Requires {{infer}} endpoint]

1. Use `"format": "chunks"` to return the field's text as the original text chunks that were indexed.

## Retrieve `semantic_text` field embeddings [returning-semantic-field-embeddings]

By default, embeddings generated for `semantic_text` fields are stored internally and not included in the response when retrieving documents. Retrieving embeddings is useful when you want to:

- Reindex documents into another index with the same `inference_id` without re-running {{infer}}
- Export or migrate documents while preserving their embeddings
- Inspect or debug the raw embeddings generated for your content

The method for retrieving embeddings depends on your {{es}} version:

- If you use {{es}} 9.2 and later, or {{serverless-short}}, use the [`_source.exclude_vectors`](#returning-semantic-field-embeddings-in-_source) parameter to include embeddings in `_source`.
- If you use {{es}} versions earlier than 9.2, use the [`fields` parameter](#returning-semantic-field-embeddings-using-fields) with `_inference_fields` to retrieve embeddings.

### Include embeddings in `_source` [returning-semantic-field-embeddings-in-_source]

```{applies_to}
stack: ga 9.2
serverless: ga
```
To include the full {{infer}} fields, including their embeddings, in `_source`, set the `_source.exclude_vectors` option to `false`:

```console
POST my-index/_search
{
  "_source": {
    "exclude_vectors": false
  },
  "query": {
    "match_all": {}
  }
}
```
% TEST[skip:Requires {{infer}} endpoint]

The embeddings will appear under `_inference_fields` in `_source`.

This works with the
[Get](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-get),
[Search](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search),
and
[Reindex](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-reindex)
APIs.

#### Example: Reindex while preserving embeddings [reindex-while-preserving-embeddings]
```{applies_to}
stack: ga 9.2
serverless: ga
```

When reindexing documents with `semantic_text` fields, you can preserve existing embeddings by including them in the source documents. This allows documents to be re-indexed without triggering {{infer}} again.

::::{warning}
The target index's `semantic_text` field must use the same `inference_id` as the source index to reuse existing embeddings. If the `inference_id` values do not match, the documents will fail the reindex task.
::::

```console
POST _reindex
{
  "source": {
    "index": "my-index-src",
    "_source": {
      "exclude_vectors": false            <1>
    }
  },
  "dest": {
    "index": "my-index-dest"
  }
}
```
% TEST[skip:Requires {{infer}} endpoint]

1. Sends the source documents with their stored embeddings to the destination index.

#### Example: Troubleshoot `semantic_text` fields [troubleshooting-semantic-text-fields]
```{applies_to}
stack: ga 9.2
serverless: ga
```

To verify that your embeddings look correct or debug embedding generation, retrieve the stored embeddings:

```console
POST test-index/_search
{
  "_source": {
    "exclude_vectors": false
  },
  "query": {
    "match": {
      "my_semantic_field": "Which country is Paris in?"
    }
  }
}
```
% TEST[skip:Requires {{infer}} endpoint]

This will return verbose chunked embeddings content that is used to perform
semantic search for `semantic_text` fields:

```console-response
{
  "took": 18,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": { "value": 1, "relation": "eq" },
    "max_score": 16.532316,
    "hits": [
      {
        "_index": "test-index",
        "_id": "1",
        "_score": 16.532316,
        "_source": {
          "my_semantic_field": "Paris is the capital of France.",
          "_inference_fields": {
            "my_semantic_field": {
              "inference": {
                "inference_id": ".elser-2-elasticsearch", <1>
                "model_settings": { <2>
                  "service": "elasticsearch",
                  "task_type": "sparse_embedding"
                },
                "chunks": {
                  "my_semantic_field": [
                    {
                      "start_offset": 0,
                      "end_offset": 31,
                      "embeddings": { <3>
                        "airport": 0.12011719,
                        "brussels": 0.032836914,
                        "capital": 2.1328125,
                        "capitals": 0.6386719,
                        "capitol": 1.2890625,
                        "cities": 0.78125,
                        "city": 1.265625,
                        "continent": 0.26953125,
                        "country": 0.59765625,
                        ...
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    ]
  }
}
```
% TEST[skip:Requires {{infer}} endpoint]
1. The {{infer}} endpoint used to generate embeddings.
2. Lists details about the model used to generate embeddings, such as the service name and task type.
3. The embeddings generated for this chunk.

### Retrieve embeddings using `fields` [returning-semantic-field-embeddings-using-fields]

:::{important}
This method for returning semantic field embeddings is recommended only for {{es}} versions earlier than 9.2.
For version 9.2 and later, use the [`exclude_vectors`](#returning-semantic-field-embeddings-in-_source) parameter instead.
:::

To retrieve stored embeddings, use the `fields` parameter with `_inference_fields`. This lets you include the vector data that is not shown by default in the response.

```console
POST my-index/_search
{
  "query": {
    "match": {
      "my_semantic_field": "Which country is Paris in?"
    }
  },
  "fields": [
    "_inference_fields"
  ]
}
```
% TEST[skip:Requires {{infer}} endpoint]

The `fields` parameter works with the [Search](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search) API.

## Highlight the most relevant fragments [highlighting-fragments]

Extract the most relevant fragments from a `semantic_text` field using the [highlight parameter](/reference/elasticsearch/rest-apis/highlighting.md) in the [Search API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search).

:::::{stepper}

::::{step} Highlight semantic_text fields

Use the highlight parameter with `number_of_fragments` and `order` to control fragment selection and sorting:

```console
POST test-index/_search
{
    "query": {
        "match": {
            "my_semantic_field": "Which country is Paris in?"
        }
    },
    "highlight": {
        "fields": {
            "my_semantic_field": {
                "number_of_fragments": 2,  <1>
                "order": "score"           <2>
            }
        }
    }
}
```
% TEST[skip:Requires {{infer}} endpoint]

1. Specifies the maximum number of fragments to return.
2. Sorts the most relevant highlighted fragments by score when set to `score`. By default, fragments are output in the order they appear in the field (order: none).

::::

::::{step} Enforce semantic highlighter

To restrict highlighting to the semantic highlighter and return no fragments when the field is not of type `semantic_text`, explicitly set the highlighter type to `semantic`:

```console
POST test-index/_search
{
    "query": {
        "match": {
            "my_field": "Which country is Paris in?"
        }
    },
    "highlight": {
        "fields": {
            "my_field": {
                "type": "semantic",         <1>
                "number_of_fragments": 2,
                "order": "score"
            }
        }
    }
}
```
% TEST[skip:Requires {{infer}} endpoint]

1. Ensures that highlighting is applied exclusively to `semantic_text` fields.

::::

::::{step} Retrieve fragments in original order

To retrieve all fragments from the semantic highlighter in their original indexing order without scoring, use a `match_all` query as the `highlight_query`:

```console
POST test-index/_search
{
  "query": {
    "ids": {
      "values": ["1"]
    }
  },
  "highlight": {
    "fields": {
      "my_semantic_field": {
        "number_of_fragments": 5,        <1>
        "highlight_query": { "match_all": {} }
      }
    }
  }
}
```
% TEST[skip:Requires {{infer}} endpoint]

1. Returns the first 5 fragments. Increase this value to retrieve additional fragments.

::::

:::::

## Performing {{ccs}} (CCS) with `semantic_text` [cross-cluster-search]

```{applies_to}
stack: ga 9.2
serverless: unavailable
```

::::{applies-switch}

:::{applies-item} stack: ga 9.3+
`semantic_text` supports [{{ccs}} (CCS)](docs-content://explore-analyze/cross-cluster-search.md) through:

- The [`_search` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search) when [`ccs_minimize_roundtrips`](docs-content://explore-analyze/cross-cluster-search.md#ccs-network-delays) is `true` or `false`.
- [Retrievers](/reference/elasticsearch/rest-apis/retrievers.md)
- [ES|QL](/reference/query-languages/esql.md)

Query `semantic_text` fields across clusters using the standard `_search` endpoint with cluster notation:

```console
POST local-index,remote-cluster:remote-index/_search <1>
{
  "query": {
    "match": {
      "my_semantic_field": "Which country is Paris in?"
    }
  }
}
```
1. `remote-cluster:remote-index` refers to an index on the remote cluster with alias `remote-cluster`.

The same notation can be used to query `semantic_text` fields across clusters with ES|QL:

```console
POST _query
{
    "query": """FROM local-index,remote-cluster:remote-index METADATA _score | <1>
     WHERE MATCH(my_semantic_field, "Which country is Paris in?") |
     SORT _score DESC |
     KEEP my_semantic_field | LIMIT 10
    """
}
```
1. `remote-cluster:remote-index` refers to an index on the remote cluster with alias `remote-cluster`.
:::

:::{applies-item} stack: ga =9.2
`semantic_text` supports [{{ccs}} (CCS)](docs-content://explore-analyze/cross-cluster-search.md) through the [`_search` endpoint](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search) when [`ccs_minimize_roundtrips`](docs-content://explore-analyze/cross-cluster-search.md#ccs-network-delays) is set to `true`.
This is the default value, so most CCS queries work automatically.

CCS is **not** supported in [retrievers](/reference/elasticsearch/rest-apis/retrievers.md) or [ES|QL](/reference/query-languages/esql.md).

Query `semantic_text` fields across clusters using the standard `_search` endpoint with cluster notation:

```console
POST local-index,remote-cluster:remote-index/_search <1>
{
  "query": {
    "match": {
      "my_semantic_field": "Which country is Paris in?"
    }
  }
}
```
1. `remote-cluster:remote-index` refers to an index on the remote cluster with alias `remote-cluster`.
:::

::::