---
title: Set up and configure semantic_text fields
description: This page provides instructions for setting up and configuring semantic_text fields. Learn how to configure inference endpoints, including default endpoints,...
url: https://www.elastic.co/elastic/docs-builder/docs/3754/reference/elasticsearch/mapping-reference/semantic-text-setup-configuration
products:
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.0
---

# Set up and configure semantic_text fields
This page provides instructions for setting up and configuring `semantic_text` fields. Learn how to configure inference endpoints, including [default](#default-endpoints) endpoints, [Jina on EIS](#using-jina-on-eis), [ELSER on EIS](#using-elser-on-eis), [third-party models on EIS](#using-eis-models), [external inference](#using-external-inference), and dedicated endpoints for ingestion and search operations.
`semantic_text` accepts text only. For images, audio, video, or PDF files, use [`semantic`](https://www.elastic.co/elastic/docs-builder/docs/3754/reference/elasticsearch/mapping-reference/semantic-field) with a compatible multimodal embedding endpoint.

## Configure inference endpoints

You can configure inference endpoints for `semantic_text` fields in the following ways:
- [Default endpoints](#default-endpoints)
- [Use Jina on EIS](#using-jina-on-eis)
- [Use ELSER on EIS](#using-elser-on-eis)
- [Use third-party models on EIS](#using-eis-models)
- [Use external inference](#using-external-inference)

<note>
  If you use an inference endpoint through your ML node and not through Elastic Inference Service (EIS), the recommended method is to [use dedicated endpoints for ingestion and search](#dedicated-endpoints-for-ingestion-and-search).<applies-to>Elastic Stack: Generally available since 9.1</applies-to> If you use EIS, you don't have to set up dedicated endpoints.
</note>


### Use default endpoints

A default endpoint is the inference endpoint that is used when you create a `semantic_text` field without specifying an `inference_id`.
The following example shows a `semantic_text` field configured to use the default inference endpoint:
```json

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

The default inference endpoint varies by deployment type and version:
- <applies-to>Elastic Stack: Generally available since 9.4</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> On Elastic Cloud Hosted deployments running Elastic Stack 9.4+ and on Serverless, the `inference_id` parameter defaults to `.jina-embeddings-v5-text-small` and runs on [EIS](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/explore-analyze/elastic-inference/eis).
- <applies-to>Elastic Stack: Generally available since 9.3</applies-to> On Elastic Cloud Hosted deployments running Elastic Stack 9.3, the `inference_id` parameter defaults to `.elser-2-elastic` and runs on [EIS](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/explore-analyze/elastic-inference/eis#elser-on-eis).
- <applies-to>Elastic Stack: Generally available from 9.0 to 9.2</applies-to> On Elastic Cloud Hosted deployments running Elastic Stack 9.0-9.2, the `inference_id` parameter defaults to `.elser-2-elasticsearch` and runs on the `elasticsearch` service.

If you use the default inference endpoint, it might be updated to a newer version and use a different embedding model than the previous default endpoints. Queries that target these indices together can produce unexpected ranking results.
For details, refer to [potential issues when mixing embedding models across indices](#default-endpoint-considerations).
<dropdown title="Potential issues when mixing embedding models across indices">
  If a `semantic_text` field relies on the default inference endpoint, the model used to generate embeddings might change across versions or deployments. This can result in indices using different embedding models.For example, if the `semantic_text` field is created without specifying `inference_id`, indices created on Elastic Cloud 9.3 use the `.elser-2-elastic` endpoint by default, while indices created on Elastic Cloud 9.4+ use `.jina-embeddings-v5-text-small`. As a result, older indices contain ELSER embeddings while newer indices contain Jina embeddings.Mixed embedding models across indices can occur in several common scenarios, including:
  - [Data streams](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/manage-data/data-store/data-streams) with [ILM rollover](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/manage-data/lifecycle/index-lifecycle-management): When a data stream rolls over, older backing indices may contain ELSER embeddings while newer indices created after an upgrade use Jina embeddings.
  - [Aliases](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/manage-data/data-store/aliases) referencing multiple indices: An alias can point to several indices created at different times. If some indices use ELSER and others use Jina, searches against the alias will query both.
  - Explicit [multi-index searches](https://www.elastic.co/elastic/docs-builder/docs/3754/reference/elasticsearch/rest-apis/search-multiple-data-streams-indices): Queries that target multiple indices (for example `GET index1,index2/_search`) might combine results from indices using different embedding models.
  - [Cross-cluster search](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/explore-analyze/cross-cluster-search): Searches across multiple clusters may query indices created on different stack versions, which may use different default inference endpoints.
  Queries that target indices using different embedding models can lead to issues or unexpected results. The following sections describe these issues and how to mitigate them.

  #### Incorrect ranking due to different scoring scalesELSER and Jina use different scoring ranges. ELSER scores typically range between `0` and above `10`, while Jina scores are normalized between `0` and `1`.
  When results from both models are ranked together, ELSER documents might appear ahead of Jina documents even if the Jina results are more relevant. This can lead to misleading rankings without any errors being returned.To mitigate this issue, ensure that indices queried together use the same embedding model by explicitly specifying the `inference_id` when defining `semantic_text` fields:
  ```json

  {
    "mappings": {
      "properties": {
        "inference_field": {
          "type": "semantic_text",
          "inference_id": ".jina-embeddings-v5-text-small"
        }
      }
    }
  }
  ```
  If indices using different embedding models must be queried together, normalize the scores using a [linear retriever](https://www.elastic.co/elastic/docs-builder/docs/3754/reference/elasticsearch/rest-apis/retrievers/linear-retriever):
  ```json

  {
    "retriever": {
      "linear": {
        "query": "how do neural networks learn",
        "fields": ["inference_field"],
        "normalizer": "minmax"
      }
    }
  }
  ```


  #### Increased inference cost during searchWhen a query targets indices that use different inference endpoints, Elasticsearch must generate query embeddings for each model. This increases inference workload and cost during search.
  To mitigate this issue, ensure that indices queried together use the same inference endpoint. You can do this by:
  - explicitly setting the `inference_id` when defining the `semantic_text` field for new indices, or
  - by [reindexing](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-reindex) older indices with the desired endpoint.


  #### Alerts based on raw relevance scores might stop triggeringSome [alerts](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/explore-analyze/alerting/alerts) or [rules](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/explore-analyze/alerting/alerts/rule-types) rely on raw `_score` values. Because ELSER and Jina use different score ranges, score thresholds designed for ELSER might no longer work when results are generated with Jina.
  For example, a condition such as `_score > 10` might never be satisfied by Jina results, because Jina scores are normalized between `0` and `1`.To mitigate this issue, adjust alert thresholds to match the scoring range of the embedding model being used, or avoid relying on raw `_score` values in alert conditions.
</dropdown>


### Use Jina on EIS

<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.4
</applies-to>

If you use the `.jina-embeddings-v5-text-small` endpoint through the Elastic Inference Service ([Jina on EIS](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/explore-analyze/elastic-inference/eis#jina-embeddings-v5-on-eis)), you can
set up `semantic_text` with the following API request:
```json

{
  "mappings": {
    "properties": {
      "inference_field": {
        "type": "semantic_text",
        "inference_id": ".jina-embeddings-v5-text-small"
      }
    }
  }
}
```


### Use ELSER on EIS

<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.2
  - Elastic Stack: Preview in 9.1
  - Self-managed Elastic deployments: Unavailable
</applies-to>

If you use the `.elser-2-elastic` endpoint that uses the ELSER model as a service through the Elastic Inference Service ([ELSER on EIS](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/explore-analyze/elastic-inference/eis#elser-on-eis)), you can
set up `semantic_text` with the following API request:
```json

{
  "mappings": {
    "properties": {
      "inference_field": {
        "type": "semantic_text",
        "inference_id": ".elser-2-elastic"
      }
    }
  }
}
```


### Use third-party models on EIS

<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.3
</applies-to>

[Elastic Inference Service (EIS)](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/explore-analyze/elastic-inference/eis) also provides third-party embedding models. To use one with `semantic_text`, create an inference endpoint that references the model, then set the `inference_id` parameter to that endpoint's identifier.
The following examples show `semantic_text` fields configured with EIS endpoints for third-party models available on EIS. These are examples only; for the full list, refer to [Supported models](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/explore-analyze/elastic-inference/eis-supported-models).
```json

{
  "mappings": {
    "properties": {
      "inference_field": {
        "type": "semantic_text",
        "inference_id": "eis-google-gemini-embedding-001"
      }
    }
  }
}
```

```json

{
  "mappings": {
    "properties": {
      "inference_field": {
        "type": "semantic_text",
        "inference_id": "eis-microsoft-multilingual-e5-large"
      }
    }
  }
}
```


### Use external inference

You can use your own API keys to connect to external model providers. Create an inference endpoint with the [Create inference API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put), then set that endpoint's ID as the `inference_id` on your `semantic_text` field.
You can also manage external endpoints in Kibana. For details, refer to [External inference](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3754/explore-analyze/elastic-inference/external).

### Use dedicated endpoints for ingestion and search

If you use an inference endpoint through your ML node and not through Elastic Inference Service, the recommended way to use `semantic_text` is by having dedicated inference endpoints for ingestion and search.
This ensures that search speed remains unaffected by ingestion workloads, and vice versa. After creating dedicated inference endpoints for both, you can reference them using the `inference_id`
and `search_inference_id` parameters when setting up the index mapping for an index that uses the `semantic_text` field.
```json

{
  "mappings": {
    "properties": {
      "inference_field": {
        "type": "semantic_text",
        "inference_id": "my-elser-endpoint-for-ingest",
        "search_inference_id": "my-elser-endpoint-for-search"
      }
    }
  }
}
```


## Set `index_options` for `sparse_vectors`

<applies-to>
  - Elastic Stack: Generally available since 9.2
</applies-to>

Configuring `index_options` for [sparse vector fields](https://www.elastic.co/elastic/docs-builder/docs/3754/reference/elasticsearch/mapping-reference/sparse-vector) lets you configure [token pruning](/elastic/docs-builder/docs/3754/reference/elasticsearch/mapping-reference/sparse-vector#token-pruning), which controls whether non-significant or overly frequent tokens are omitted to improve query performance.
The following example enables token pruning and sets pruning thresholds for a `sparse_vector` field:
```json

{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "index_options": {
          "sparse_vector": {
            "prune": true, <1>
            "pruning_config": {
              "tokens_freq_ratio_threshold": 10, <2>
              "tokens_weight_threshold": 0.5 <3>
            }
          }
        }
      }
    }
  }
}
```

Learn more about [sparse_vector index options](/elastic/docs-builder/docs/3754/reference/elasticsearch/mapping-reference/sparse-vector#sparse-vector-index-options) settings and [token pruning](/elastic/docs-builder/docs/3754/reference/elasticsearch/mapping-reference/sparse-vector#token-pruning).

## Set `index_options` for `dense_vectors`

Configuring `index_options` for [dense vector fields](https://www.elastic.co/elastic/docs-builder/docs/3754/reference/elasticsearch/mapping-reference/dense-vector) lets you control how dense vectors are indexed for kNN search. You can select the indexing algorithm, such as `int8_hnsw`, `int4_hnsw`, or `disk_bbq`, among [other available index options](/elastic/docs-builder/docs/3754/reference/elasticsearch/mapping-reference/dense-vector#dense-vector-index-options).
The following example shows how to configure `index_options` for a dense vector field using the `int8_hnsw` indexing algorithm:
```json

{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "index_options": {
          "dense_vector": {
            "type": "int8_hnsw", <1>
            "m": 15, <2>
            "ef_construction": 90 <3>
          }
        }
      }
    }
  }
}
```


### Default `bfloat16` element type

<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.4
</applies-to>

For inference endpoints that produce `float` embeddings, `semantic_text` fields automatically use the [`bfloat16`](/elastic/docs-builder/docs/3754/reference/elasticsearch/mapping-reference/dense-vector#dense-vector-element-type) element type.
This reduces the storage required per vector dimension from 4 to 2 bytes with a negligible impact on search relevance for the vast majority of use cases.
The `bfloat16` format uses a 2-byte floating-point encoding that maintains the same value range as 4-byte floats, but with reduced precision.
You can check if your `semantic_text` field is using `bfloat16` by default by inspecting the default `index_options` for the field using the [get field mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-get-field-mapping):
```json
```

```json
{
  "semantic-embeddings": {
    "mappings": {
      "content": {
        "full_name": "content",
        "mapping": {
          "content": {
            "type": "semantic_text",
            "inference_id": "my-float-embedding-endpoint",
            "index_options": {
              "dense_vector": {
                "element_type": "bfloat16" 
              }
            }
          }
        }
      }
    }
  }
}
```


#### Override the default element type

If your use case requires full `float` precision, you can override the default `bfloat16` element type by specifying `element_type` in `index_options.dense_vector`:
```json

{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": "my-float-embedding-endpoint",
        "index_options": {
          "dense_vector": {
            "element_type": "float" <1>
          }
        }
      }
    }
  }
}
```

You can also combine `element_type` with other index options:
```json

{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": "my-float-embedding-endpoint",
        "index_options": {
          "dense_vector": {
            "element_type": "float",
            "type": "int8_hnsw"
          }
        }
      }
    }
  }
}
```

<note>
  The `element_type` override is only valid for inference endpoints that produce `float` embeddings.
  For `float` models, valid values are `float` and `bfloat16`.
  For other model element types (such as `byte` or `bit`), the `element_type` must match the model's native element type if specified.
</note>