---
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 and...
url: https://www.elastic.co/elastic/docs-builder/docs/3028/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) and [preconfigured](#preconfigured-endpoints) options, ELSER on EIS, custom endpoints, and dedicated endpoints for ingestion and search operations.

## Configure inference endpoints

You can configure inference endpoints for `semantic_text` fields in the following ways:
- [Use ELSER on EIS](#using-elser-on-eis)
- [Default](#default-endpoints) and [preconfigured](#preconfigured-endpoints) endpoints
- [Use a custom inference endpoint](#using-custom-endpoint)

<note>
  If you use a [custom inference endpoint](#using-custom-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"
      }
    }
  }
}
```

<important>
  The default inference endpoint varies by deployment type and version:
  - <applies-to>Elastic Stack: Planned</applies-to> On Elastic Cloud 9.4+, 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/3028/explore-analyze/elastic-inference/eis). `.jina-embeddings-v5-text-small` is expected to become the default model for Serverless soon.
  - <applies-to>Elastic Stack: Generally available since 9.3</applies-to> <applies-to>Elastic Cloud Serverless: Generally available</applies-to> In version 9.3 and on Serverless, the `inference_id` parameter defaults to `.elser-2-elastic` and runs on [EIS](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/explore-analyze/elastic-inference/eis#elser-on-eis).
  - <applies-to>Elastic Stack: Generally available from 9.0 to 9.2</applies-to> In versions 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).
</important>

<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/3028/manage-data/data-store/data-streams) with [ILM rollover](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/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/3028/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/3028/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/3028/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/3028/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 indeces, 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/3028/explore-analyze/alerting/alerts) or [rules](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/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 preconfigured endpoints

Preconfigured endpoints are inference endpoints that are automatically available in the deployment or project and do not require manual creation. The available preconfigured endpoints vary across deployment types and versions.
To view the list of available preconfigured endpoints for your deployment, go to **Inference endpoints** in Kibana.
To use a preconfigured endpoint, set the `inference_id` parameter to the identifier of the endpoint you want to use:
```json

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


### 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 preconfigured `.elser-2-elastic` endpoint that utilizes the ELSER model as a service through the Elastic Inference Service ([ELSER on EIS](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/explore-analyze/elastic-inference/eis#elser-on-eis)), you can
set up `semantic_text` with the following API request:
<tab-set>
  <tab-item title="Using ELSER on EIS on Serverless">
    <applies-to>
      - Elastic Cloud Serverless: Generally available
    </applies-to>

    ```json

    {
      "mappings": {
        "properties": {
          "inference_field": {
            "type": "semantic_text"
          }
        }
      }
    }
    ```
  </tab-item>

  <tab-item title="Using ELSER on EIS in Cloud">
    <applies-to>
      - Elastic Stack: Generally available since 9.2
      - Self-managed Elastic deployments: Unavailable
    </applies-to>

    ```json

    {
      "mappings": {
        "properties": {
          "inference_field": {
            "type": "semantic_text",
            "inference_id": ".elser-2-elastic"
          }
        }
      }
    }
    ```
  </tab-item>
</tab-set>


### Use a custom inference endpoint

To use a custom inference endpoint instead of the [default](#default-endpoints) or [preconfigured](#preconfigured-endpoints) endpoints, you
must [Create inference API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put)
and specify its `inference_id` when setting up the `semantic_text` field type.
```json

{
  "mappings": {
    "properties": {
      "inference_field": {
        "type": "semantic_text",
        "inference_id": "my-openai-endpoint" <1>
      }
    }
  }
}
```


### Use dedicated endpoints for ingestion and search

If you use a [custom inference endpoint](#using-custom-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/3028/reference/elasticsearch/mapping-reference/sparse-vector) lets you configure [token pruning](/elastic/docs-builder/docs/3028/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/3028/reference/elasticsearch/mapping-reference/sparse-vector#sparse-vector-index-options) settings and [token pruning](/elastic/docs-builder/docs/3028/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/3028/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/3028/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>
          }
        }
      }
    }
  }
}
```