Semantic field type

Introduced 3.1

The semantic field type is a high-level abstraction that simplifies neural search setup in OpenSearch. It can wrap a variety of field types, including all string and binary fields. The semantic field type automatically enables semantic indexing and querying based on the configured machine learning (ML) model.

PREREQUISITE
Before using the semantic field type, you must configure either a local ML model hosted on your OpenSearch cluster or an externally hosted model connected to your OpenSearch cluster. For more information about local models, see Using ML models within OpenSearch. For more information about externally hosted models, see Connecting to externally hosted models.

Example: Dense embedding model

Once you configure a model, you can use it to create an index with a semantic field. This example assumes that you have configured a dense embedding model with the ID n17yX5cBsaYnPfyOzmQU in your cluster:

PUT /my-nlp-index
{
  "settings": {
    "index": {
      "knn": true
    }
  },
  "mappings": {
    "properties": {
      "passage": {
        "type": "semantic",
        "model_id": "n17yX5cBsaYnPfyOzmQU"
      }
    }
  }
}

After creating the index, you can retrieve its mapping to verify that a passage_semantic_info field was automatically created. The passage_semantic_info field contains a knn_vector subfield for storing the dense embedding and additional metadata fields for capturing information such as the model ID, model name, and model type:

GET /my-nlp-index/_mapping
{
  "my-nlp-index": {
    "mappings": {
      "properties": {
        "passage": {
          "type": "semantic",
          "model_id": "n17yX5cBsaYnPfyOzmQU",
          "raw_field_type": "text"
        },
        "passage_semantic_info": {
          "properties": {
            "embedding": {
              "type": "knn_vector",
              "dimension": 384,
              "method": {
                "engine": "faiss",
                "space_type": "l2",
                "name": "hnsw",
                "parameters": {}
              }
            },
            "model": {
              "properties": {
                "id": {
                  "type": "text",
                  "index": false
                },
                "name": {
                  "type": "text",
                  "index": false
                },
                "type": {
                  "type": "text",
                  "index": false
                }
              }
            }
          }
        }
      }
    }
  }
}

The dimension and space_type of the knn_vector field are determined by the ML model configuration. For pretrained dense models, this information is included in the default model configuration. For externally hosted dense embedding models, you must explicitly define the dimension and space_type in the model configuration before using the model with a semantic field.

The autogenerated knn_vector subfield supports additional settings that are not currently configurable in the semantic field. For more information, see Limitations.

Example: Sparse encoding model

Once you configure a model, you can use it to create an index with a semantic field. This example assumes that you have configured a sparse encoding model with the ID n17yX5cBsaYnPfyOzmQU in your cluster:

PUT /my-nlp-index
{
  "mappings": {
    "properties": {
      "passage": {
        "type": "semantic",
        "model_id": "nF7yX5cBsaYnPfyOq2SG"
      }
    }
  }
}

After creating the index, you can retrieve its mapping to verify that a rank_features field was automatically created:

GET /my-nlp-index/_mapping
{
  "my-nlp-index": {
    "mappings": {
      "properties": {
        "passage": {
          "type": "semantic",
          "model_id": "nF7yX5cBsaYnPfyOq2SG",
          "raw_field_type": "text"
        },
        "passage_semantic_info": {
          "properties": {
            "embedding": {
              "type": "rank_features"
            },
            "model": {
              "properties": {
                "id": {
                  "type": "text",
                  "index": false
                },
                "name": {
                  "type": "text",
                  "index": false
                },
                "type": {
                  "type": "text",
                  "index": false
                }
              }
            }
          }
        }
      }
    }
  }
}

Parameters

The semantic field type supports the following parameters.

Text chunking

By default, text chunking is disabled for semantic fields. This is because enabling chunking requires storing each chunk’s embedding in a nested object, which can increase search latency. Searching nested objects requires joining child documents to their parent, along with additional scoring and aggregation logic. The more matching child documents there are, the higher the potential latency.

If you’re working with long-form text and want to improve search relevance, you can enable chunking through the chunking parameter for the semantic field.

Basic chunking configuration

To enable default chunking behavior (fixed token length using all defaults), set chunking to true:

PUT /my-nlp-index
{
  "mappings": {
    "properties": {
      "passage": {
        "type": "semantic",
        "model_id": "nF7yX5cBsaYnPfyOq2SG",
        "chunking": true
      }
    }
  }
}

This is equivalent to setting the algorithm to fixed_token_length:

PUT /my-nlp-index
{
  "mappings": {
    "properties": {
      "passage": {
        "type": "semantic",
        "model_id": "nF7yX5cBsaYnPfyOq2SG",
        "chunking": [
          {
            "algorithm": "fixed_token_length"
          }
        ]
      }
    }
  }
}

Chunking is performed using the fixed token length algorithm.

Advanced chunking configuration

To set up an advanced chunking configuration, you can specify chunking as a list of chunking strategies, where each strategy is applied in sequence to the semantic field. Each item in the list must specify an algorithm and its parameters.

For example, to apply the delimiter algorithm followed by fixed token chunking, use the following request. The text is first split at paragraph breaks (\n\n), and each resulting segment is then divided into fixed-size token chunks:

PUT /my-nlp-index
{
  "mappings": {
    "properties": {
      "passage": {
        "type": "semantic",
        "model_id": "nF7yX5cBsaYnPfyOq2SG",
        "chunking": [
          {
            "algorithm": "delimiter",
            "parameters": {
              "delimiter": "\n\n"
            }
          },
          {
            "algorithm": "fixed_token_length",
            "parameters": {
              "token_limit": 128,
              "overlap_rate": 0.2
            }
          }
        ]
      }
    }
  }
}

This gives you more control over how input text is segmented and ensures that embeddings better reflect natural language boundaries.

Supported algorithms

The chunking parameter supports all algorithms supported by the text chunking ingest processor.

Dense embedding configuration

When a semantic field uses a dense model, OpenSearch automatically generates a companion knn_vector field to store the embeddings. You can use the dense_embedding_config parameter to customize how this vector field is configured during index creation.

The structure of dense_embedding_config closely mirrors the configuration for a standard knn_vector field. You can use this parameter to configure settings like the k-NN engine and indexing behavior.

For all supported parameters for the dense_embedding_config, see k-NN vector parameters. While dense_embedding_config supports most of the same options as knn_vector, the following parameters are not supported:

• dimension: The embedding dimension must match the output dimension of the ML model and is automatically inferred from the model_id. You should set the correct dimension in the model configuration, not in the field mapping.

• space_type: The similarity space (for example, cosinesimil, l2, or innerproduct) must align with the model and is resolved from the model configuration.

The following example contains a dense_embedding_config:

PUT /my-nlp-index
{
  "mappings": {
    "properties": {
      "passage": {
        "type": "semantic",
        "model_id": "nF7yX5cBsaYnPfyOq2SG",
        "dense_embedding_config": {
          "method": {
            "name": "hnsw",
            "engine": "lucene",
            "parameters": {
              "ef_construction": 128,
              "m": 32
            }
          }
        }
      }
    }
  }
}

Sparse encoding configuration

When a semantic field uses a sparse model, OpenSearch automatically generates a companion field to store the sparse vector representation. By default, this vector is pruned in order to reduce dimensionality and improve efficiency.

The sparse_encoding_config parameter allows you to control how pruning is applied during encoding by specifying a strategy and its parameters. This provides fine-grained control over how sparse vectors are indexed, balancing accuracy and storage/performance.

The sparse_encoding_config object supports all pruning strategies available in the sparse encoding ingest processor.

The following example contains a sparse_encoding_config. It keeps only the 64 highest-scoring terms in the sparse vector:

PUT /my-nlp-index
{
  "mappings": {
    "properties": {
      "passage": {
        "type": "semantic",
        "model_id": "nF7yX5cBsaYnPfyOq2SG",
        "sparse_encoding_config": {
          "prune_type": "top_k",
          "prune_ratio": 64
        }
      }
    }
  }
}

Ingest batch size for semantic fields

When documents are ingested into an index containing semantic fields, OpenSearch uses a system-generated ingest pipeline to call the underlying ML model and generate embeddings. To optimize performance, these operations are batched.

You can control the number of documents processed together during this step using the index-level dynamic index.neural_search.semantic_ingest_batch_size setting. This setting specifies the number of documents batched together when generating embeddings for semantic fields during ingestion (default is 10).

Batching improves throughput by reducing the overhead of model inference. However, increasing the batch size may also increase memory usage. You should tune this setting based on your model’s performance characteristics and expected ingest volume.

This setting controls how many documents are processed together in a batch, but it does not directly determine the size of the input sent to the model.

If a single document contains multiple semantic fields, embeddings are generated for each one.

If text chunking is enabled for a semantic field, the content may be split into multiple chunks, and embeddings will be generated for each chunk. As a result, the actual number of model inference calls and total embedding inputs per batch may be significantly higher than the batch size value.

The following example updates the ingest batch size to 32 for the my-index index. The change takes effect immediately and applies to all subsequently ingested documents containing semantic fields.

PUT /my-index/_settings
{
  "index": {
    "neural_search.semantic_ingest_batch_size": 32
  }
}

For more information about updating dynamic settings, see Dynamic settings.

Limitations

Note the following limitations of the semantic field:

• Remote cluster support: neural queries on semantic fields are not supported in cross-cluster search. While you can retrieve documents from remote indexes, semantic queries require access to the local model configuration and index mappings. Thus, you must run the query directly against the embedding field using traditional query methods.

• Repeated inference: When a document is updated, OpenSearch reruns inference on the semantic field even if the field’s content has not changed. There is currently no way to reuse previously generated embeddings, which may lead to unnecessary inference operations.

• Mapping restrictions: The semantic field does not support dynamic mappings and must be explicitly defined in the index mapping. Additionally, you cannot use a semantic field in the fields section of another field, so multi-field configurations are not supported.

Next steps

• Using a semantic field with text embedding models for semantic search
• Using a semantic field with sparse encoding models for neural sparse search