---
title: Semantic text field type
description: The semantic_text field type accepts text only. To index or search images, audio, video, or PDF files, use semantic with a compatible multimodal embedding...
url: https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text
products:
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.0
---

# Semantic text field type
<warning>
  The `semantic_text` field mapping can be added regardless of license state. However, it typically calls the [Inference API](https://www.elastic.co/docs/api/doc/elasticsearch/group/endpoint-inference), which requires an [appropriate license](https://www.elastic.co/subscriptions). In these cases, using `semantic_text` in a cluster without the appropriate license causes operations such as indexing and reindexing to fail.
</warning>

The `semantic_text` field type accepts text only. To index or search images, audio, video, or PDF files, use [`semantic`](https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-field) with a compatible multimodal embedding endpoint.
For text-based [semantic search](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3739/solutions/search/semantic-search), `semantic_text` provides sensible defaults that automate most of the manual work typically required for vector search. You don't have to manually configure mappings, set up ingestion pipelines, or handle chunking. The field type automatically:
- Configures index mappings: Chooses the correct field type (`sparse_vector` or `dense_vector`), dimensions, similarity functions, and storage optimizations based on the inference endpoint.
- Generates embeddings during indexing: Automatically generates embeddings when you index documents, without requiring ingestion pipelines or inference processors.
- Handles chunking: Automatically chunks long text documents during indexing.

Elasticsearch refers to `semantic` and `semantic_text` as *inference fields*: mapped fields that use inference endpoints and store generated embeddings in internal subfields.

## Should I use [`semantic_text`](https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text) or [`semantic`](https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-field)?

Elasticsearch provides two field types that generate and store embeddings automatically. Choose the field type based on the content and embedding model you want to use.
`semantic_text` accepts text only. To index or search images, audio, video, or PDF files, use `semantic` with a compatible multimodal embedding endpoint.

| Aspect                         | [`semantic`](https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-field) | [`semantic_text`](https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text)             |
|--------------------------------|------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
| Input                          | Text, images, audio, video, and PDF files                                                                                    | **Text only**                                                                                                                                |
| Supported inference task types | `embedding`                                                                                                                  | `embedding`, `text_embedding`, and `sparse_embedding`                                                                                        |
| Vector storage                 | Dense vectors only                                                                                                           | Dense or sparse vectors                                                                                                                      |
| `inference_id`                 | Required. No default endpoint is provided.                                                                                   | Optional. A default endpoint is used when you don't specify one.                                                                             |
| `search_inference_id`          | Optional. If omitted, `inference_id` is used for search.                                                                     | Optional. If omitted, `inference_id` is used for search.                                                                                     |
| `chunking_settings`            | Supported for text input. Chunking does not apply to non-text input.                                                         | Supported for text input.                                                                                                                    |
| `index_options`                | Supports `dense_vector` options.                                                                                             | Supports `dense_vector` and `sparse_vector` options.                                                                                         |
| `meta`                         | Supported.                                                                                                                   | Supported.                                                                                                                                   |
| Availability                   | <applies-to>Elastic Stack: Planned</applies-to> <applies-to>Elastic Cloud Serverless: Preview</applies-to>                   | <applies-to>Elastic Stack: Generally available since 9.0</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> |


## Basic `semantic_text` mapping example

The following example creates an index mapping with a `semantic_text` field, using default values:
```json

{
  "mappings": { 
    "properties": {
      "content": { 
        "type": "semantic_text"
      }
    }
  }
}
```

<important>
  If you don't specify an `inference_id`, like in the example above, and upgrade to a later version, newly created indices might use a different embedding model than existing ones. Queries that target these indices together can produce unexpected ranking results.
  For details, refer to [potential issues when mixing embedding models across indices](/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-setup-configuration#default-endpoint-considerations).
</important>


## Extended `semantic_text` mapping example

The following example creates an index mapping with a `semantic_text` field that uses dense vectors:
```json

{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": "my-inference-endpoint", <1>
        "search_inference_id": "my-search-inference-endpoint", <2>
        "index_options": { <3>
          "dense_vector": {
            "type": "bbq_disk"
          }
        },
        "chunking_settings": { <4>
          "strategy": "word",
          "max_chunk_size": 120,
          "overlap": 40
        }
      }
    }
  }
}
```

<tip>
  For a complete example, refer to the [Semantic search with `semantic_text`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3739/solutions/search/semantic-search/semantic-search-semantic-text) tutorial.
</tip>


## Overview

The `semantic_text` field type documentation is organized into reference content and how-to guides.

### Reference

The [Reference](https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-reference) section provides technical reference content:
- [Parameters](/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-reference#semantic-text-params): Parameter descriptions for `semantic_text` fields.
- [Inference endpoints](/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-reference#configuring-inference-endpoints): Overview of inference endpoints used with `semantic_text` fields.
- [Chunking](/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-reference#chunking-behavior): How `semantic_text` automatically processes long text passages by generating smaller chunks.
- [Pre-filtering for dense vector queries](/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-reference#pre-filtering-for-dense-vector-queries): Automatic pre-filtering behavior for dense vector queries on `semantic_text` fields.
- [Limitations](/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-reference#limitations): Current limitations of `semantic_text` fields.
- [Document count discrepancy](/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-reference#document-count-discrepancy): Understanding document counts in `_cat/indices` for indices with `semantic_text` fields.
- [Querying `semantic_text` fields](/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-search-retrieval#querying-semantic-text-fields): Supported query types for `semantic_text` fields.


### How-to guides

The [How-to guides](https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-how-tos) section organizes procedure descriptions and examples into the following guides:
- [Set up and configure `semantic_text` fields](https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-setup-configuration): Learn how to configure inference endpoints, including default and preconfigured options, ELSER on EIS, custom endpoints, and dedicated endpoints for ingestion and search operations.
- [Ingest data with `semantic_text` fields](https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-ingestions): Learn how to index pre-chunked content, use `copy_to` and multi-fields to collect values from multiple fields, and perform updates and partial updates to optimize ingestion costs.
- [Search and retrieve `semantic_text` fields](https://www.elastic.co/elastic/docs-builder/docs/3739/reference/elasticsearch/mapping-reference/semantic-text-search-retrieval): Learn how to query `semantic_text` fields, retrieve indexed chunks, return field embeddings, and highlight the most relevant fragments from search results.