---
title: Semantic search with semantic_text
description: Learn how to set up semantic search using the semantic_text field type, from creating an index mapping to ingesting data and running queries.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/solutions/search/semantic-search/semantic-search-semantic-text
products:
- Elasticsearch
applies_to:
- Elastic Cloud Serverless: Generally available
- Elastic Stack: Generally available
---
# Semantic search with semantic_text
This tutorial walks you through setting up semantic search using the [`semantic_text`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/mapping-reference/semantic-text) field type. By the end, you will be able to:
- Create an index mapping with a `semantic_text` field
- Ingest documents that are automatically converted to vector embeddings
- Query your data using semantic search with both Query DSL and ES|QL
The `semantic_text` field type simplifies the inference workflow by providing inference at ingestion time with sensible defaults. You don’t need to define model-related settings and parameters, or create inference ingest pipelines.
We recommend using the `semantic_text` workflow for [semantic search](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/solutions/search/semantic-search) in the Elastic Stack. When you need more control over indexing and query settings, you can use the complete inference workflow instead (refer to the [Inference API documentation](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/explore-analyze/elastic-inference/inference-api) for details).
This tutorial uses the [Elastic Inference Service (EIS)](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/explore-analyze/elastic-inference/eis), but you can use any service and model supported by the [Inference API](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/explore-analyze/elastic-inference/inference-api).
## Before you begin
- This tutorial uses the [Elastic Inference Service (EIS)](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/explore-analyze/elastic-inference/eis), which is automatically enabled on Elastic Cloud Hosted deployments and Serverless projects.
You can also use [EIS for self-managed clusters](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/explore-analyze/elastic-inference/connect-self-managed-cluster-to-eis).
- To use the `semantic_text` field type with an inference service other than Elastic Inference Service, you must create an inference endpoint using the [Create inference API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put).
## Create the index mapping
Create a destination index with a [`semantic_text`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/mapping-reference/semantic-text) field. This field stores the vector embeddings that the inference endpoint generates from your input text.
You can run inference either using the [Elastic Inference Service](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/explore-analyze/elastic-inference/eis) or on your own ML-nodes. The following examples show you both scenarios.
```json
{
"mappings": {
"properties": {
"content": { <1>
"type": "semantic_text" <2>
}
}
}
}
```
```json
{
"mappings": {
"properties": {
"content": { <1>
"type": "semantic_text", <2>
"inference_id": ".elser-2-elasticsearch" <3>
}
}
}
}
```
For large-scale deployments using dense vector embeddings, you can significantly reduce memory usage by configuring quantization strategies like BBQ. For advanced configuration, refer to [Optimizing vector storage](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/solutions/search/semantic-search/vector-storage-for-semantic-search).
If you're using web crawlers or connectors to generate indices, you have to [update the index mappings](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-mapping) for these indices to include the `semantic_text` field. Once the mapping is updated, you'll need to run a full web crawl or a full connector sync. This ensures that all existing documents are reprocessed and updated with the new semantic embeddings, enabling semantic search on the updated data.
## Ingest data
With your index mapping in place, add some data. Because you mapped the `content` field as `semantic_text`, Elasticsearch automatically intercepts the text during ingestion, sends it to the inference endpoint, and stores the resulting vector embeddings alongside your document.
Use the [`_bulk` API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk) to ingest a few sample documents:
```
POST _bulk
{ "index": { "_index": "semantic-embeddings", "_id": "1" } }
{ "content": "After running, cool down with light cardio for a few minutes to lower your heart rate and reduce muscle soreness." }
{ "index": { "_index": "semantic-embeddings", "_id": "2" } }
{ "content": "Marathon plans stress weekly mileage; carb loading before a race does not replace recovery between hard sessions." }
{ "index": { "_index": "semantic-embeddings", "_id": "3" } }
{ "content": "Tune cluster performance by monitoring thread pools and refresh interval." }
```
The response returns `"errors": false` and an `items` array with a `"result": "created"` entry for each document. If you see errors, check that your index mapping and inference endpoint are configured correctly.
## Run a semantic search query
With your data ingested and automatically embedded, you can query it using semantic search. Choose between [Query DSL](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/explore-analyze/query-filter/languages/querydsl) or [ES|QL](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) syntax.
The Query DSL approach uses the [`match` query](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/query-dsl/query-dsl-match-query) type with the `semantic_text` field:
```json
{
"query": {
"match": {
"content": { <1>
"query": "What causes muscle soreness after running?" <2>
}
}
}
}
```
The ES|QL approach uses the [match (`:`) operator](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql/functions-operators/operators#esql-match-operator), which automatically detects the `semantic_text` field and performs the search on it. The query uses `METADATA _score` to sort by `_score` in descending order.
```json
{
"query": """
FROM semantic-embeddings METADATA _score <1>
| WHERE content: "How to avoid muscle soreness while running?" <2>
| SORT _score DESC <3>
| LIMIT 1000 <4>
"""
}
```
Both queries return the documents ranked by semantic relevance. The documents about running and muscle soreness score highest because they are semantically closest to the query, while the document about cluster performance scores lower.
## Further examples and reading
- For an overview of all query types supported by `semantic_text` fields and guidance on when to use them, see [Querying `semantic_text` fields](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/mapping-reference/semantic-text-search-retrieval).
- If you want to use `semantic_text` in hybrid search, refer to [this notebook](https://colab.research.google.com/github/elastic/elasticsearch-labs/blob/main/notebooks/search/09-semantic-text.ipynb) for a step-by-step guide.
- For more information on how to optimize your ELSER endpoints, refer to [the ELSER recommendations](/elastic/docs-content/pull/5668/explore-analyze/machine-learning/nlp/ml-nlp-elser#elser-recommendations) section in the model documentation.
- To learn more about model autoscaling, refer to the [trained model autoscaling](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/deploy-manage/autoscaling/trained-model-autoscaling) page.
- To learn how to optimize storage and search performance when using dense vector embeddings, read about [Optimizing vector storage](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/5668/solutions/search/semantic-search/vector-storage-for-semantic-search).