Automatic semantic enrichment for Amazon OpenSearch Service

Introduction

Amazon OpenSearch Service uses word-to-word matching (lexical search) to find results, similar to other traditional search engines. This approach works well for specific queries like product codes or model numbers, but struggles with abstract searches where understanding user intent becomes crucial. For example, when you search for "shoes for the beach," lexical search matches individual words "shoes," "beach," "for," and "the" in catalog items, potentially missing relevant products like "water-resistant sandals" or "surf footwear" that don't contain the exact search terms.

Automatic Semantic Enrichment solves this limitation by considering both keyword matches and the contextual meaning behind searches. This feature understands search intent and improves search relevance by up to 20%. Enable this feature for text fields in your index to enhance search results.

Model details and performance benchmark

While this feature handles the technical complexities behind the scenes without exposing the underlying model, we provide transparency through a brief model description and benchmark results to help you make informed decisions about feature adoption in your critical workloads.

Automatic semantic enrichment uses a service-managed, pre-trained sparse model that works effectively without requiring custom fine-tuning. The model analyzes the fields you specify, expanding them into sparse vectors based on learned associations from diverse training data. The expanded terms and their significance weights are stored in native Lucene index format for efficient retrieval. We’ve optimized this process using document-only mode, where encoding happens only during data ingestion. Search queries are merely tokenized rather than processed through the sparse model, making the solution both cost-effective and performant.

Our performance validation during feature development used the MS MARCO passage retrieval dataset, featuring passages averaging 334 characters. For relevance scoring, we measured average Normalized Discounted Cumulative Gain (NDCG) for the first 10 search results (ndcg@10) on the BEIR benchmark for English content and average ndcg@10 on MIRACL for multilingual content. We assessed latency through client-side, 90th-percentile (p90) measurements and search response p90 took values. These benchmarks provide baseline performance indicators for both search relevance and response times. Here are the key benchmark numbers -

Given the unique nature of each workload, we encourage you to evaluate this feature in your development environment using your own benchmarking criteria before making implementation decisions.

Languages Supported

The feature supports English. In addition, the model also supports Arabic, Bengali, Chinese, Finnish, French, Hindi, Indonesian, Japanese, Korean, Persian, Russian, Spanish, Swahili, and Telugu.

Set up an automatic semantic enrichment index for domains

Setting up an index with automatic semantic enrichment enabled for your text fields is easy, and you can manage it through the console, APIs, and CloudFormation templates during new index creation. To enable it for an existing index, you need to recreate the index with automatic semantic enrichment enabled for text fields.

Console experience - The AWS console allows you to easily create an index with automatic semantic enrichment fields. Once you select a domain, you will find the create index button at the top of the console. Once you click the create index button, you will find options to define automatic semantic enrichment fields. In one index, you can have combinations of automatic semantic enrichment for English and multilingual, as well as lexical fields.

API experience - To create an automatic semantic enrichment index using the AWS Command Line Interface (AWS CLI), use the create-index command:

aws opensearch create-index \
--domain-name [domain_name] \
--index-name [index_name] \
--index-schema [index_body] \
            

In the following example index-schema, the title_semantic field has a field type set to text and has parameter semantic_enrichment set to status ENABLED. Setting the semantic_enrichment parameter enables automatic semantic enrichment on the title_semantic field. You can use the language_options field to specify either english or MULTI-LINGUAL.

    aws opensearch create-index \
    --id XXXXXXXXX \
    --index-name 'product-catalog' \
    --index-schema '{
    "mappings": {
        "properties": {
            "product_id": {
                "type": "keyword"
            },
            "title_semantic": {
                "type": "text",
                "semantic_enrichment": {
                    "status": "ENABLED",
                    "language_options": "english"
                }
            },
            "title_non_semantic": {
                "type": "text"
            }
        }
    }
}'
            

To describe the created index, use the following command:

aws opensearch get-index \
--domain-name [domain_name] \
--index-name [index_name] \
           

Update an existing index

You can update an existing index to add new semantic enrichment fields, enable or disable semantic enrichment on existing fields, or add non-semantic text fields. Use the update-index command and provide only the fields you want to change in the index-schema. Fields not included in the request are left unchanged.

To update an index using the AWS CLI, use the update-index command:

aws opensearch update-index \
--domain-name [domain_name] \
--index-name [index_name] \
--index-schema [index_body]

Add a new semantic enrichment field

You can add a new text field with semantic enrichment enabled to an existing index. The service automatically sets up the required ML model, ingest pipeline, and search pipeline. New documents indexed after the update are enriched automatically.

aws opensearch update-index \
--domain-name my-domain \
--index-name product-catalog \
--index-schema '{
    "mappings": {
        "properties": {
            "description": {
                "type": "text",
                "semantic_enrichment": {
                    "status": "ENABLED",
                    "language_options": "english"
                }
            }
        }
    }
}'

Disable semantic enrichment on a field

To disable semantic enrichment on a field that currently has it enabled, set status to DISABLED. The field is removed from the ingest and search pipelines. The underlying text field and its embedding field remain in the index but are no longer enriched.

aws opensearch update-index \
--domain-name my-domain \
--index-name product-catalog \
--index-schema '{
    "mappings": {
        "properties": {
            "title_semantic": {
                "type": "text",
                "semantic_enrichment": {
                    "status": "DISABLED"
                }
            }
        }
    }
}'

Update limitations

The following operations are not supported by update-index and require you to delete and recreate the index:

Data ingestion and search

Once you've created an index with automatic semantic enrichment enabled, the feature works automatically during data ingestion process, no additional configuration required.

Data ingestion: When you add documents to your index, the system automatically:

This process uses OpenSearch's built-in ML connectors and ingest pipelines, which are created and managed automatically behind the scenes.

Search: The semantic enrichment data is already indexed, so queries run efficiently without invoking the ML model again. This means you get improved search relevance with no additional search latency overhead.

Using automatic semantic enrichment with VPC domains

Automatic semantic enrichment is supported on both public access and VPC access domains running OpenSearch version 2.19 or later with the latest service software update.

For VPC access domains, Amazon OpenSearch Service uses a managed service to provision the ML model, ingest pipeline, and search pipeline that power semantic enrichment. Because a VPC domain is not publicly reachable, you must authorize this managed service to access your domain before you create or manage a semantic enrichment index.

Authorize the OpenSearch Service features principal

Grant access with the AuthorizeVpcEndpointAccess API, specifying features.opensearchservice.amazonaws.com as the service principal:

aws opensearch authorize-vpc-endpoint-access \
  --domain-name domain-name \
  --service "features.opensearchservice.amazonaws.com" \
  --region region

A successful call returns:

{
    "AuthorizedPrincipal": {
        "PrincipalType": "AWS Service",
        "Principal": "features.opensearchservice.amazonaws.com"
    }
}

You only need to authorize the principal once per domain. This step is not required for public access domains.

If you attempt a semantic enrichment index operation (create-index, update-index, get-index, or delete-index) on a VPC domain before authorizing the principal, the operation fails with an error similar to the following:

An error occurred (AccessDeniedException) when calling the GetIndex operation: This operation is not authorized for VPC domain. Please authorize 'features.opensearchservice.amazonaws.com' through the AuthorizeVpcEndpointAccess API.

After authorizing the principal, retry the operation.

Console experience

You can complete the authorization and create a semantic enrichment index for a VPC domain directly from the console. In the Amazon OpenSearch Service console, select your VPC domain to display the automatic semantic enrichment banner, and then choose Go to Indexes to open the Indexes tab.

If the OpenSearch Service features principal has not yet been authorized to access the domain, the Indexes tab shows an access denied message instead of the Create index button. Choose Authorize Principal to open the VPC endpoints tab.

On the VPC endpoints tab, choose Authorize principal, select Authorize Principals from other AWS Services, and choose OpenSearch Service Features. This performs the same authorization as the AuthorizeVpcEndpointAccess API described in the preceding section.

Return to the Indexes tab. The Create index button is now available. Choose Create index to open the create index page, where you can define your automatic semantic enrichment fields and create the index for your VPC domain.

Configuring permissions for automatic semantic enrichment

Before creating an index with automatic semantic enrichment, you need to configure the required permissions. This section explains the permissions needed for different index operations and how to set them up for both AWS Identity and Access Management (IAM) and fine-grained access control scenarios.

IAM permissions

The following IAM permissions are required for automatic semantic enrichment operations. These permissions vary depending on the specific index operation you want to perform.

CreateIndex API permissions

To create an index with automatic semantic enrichment, you need the following IAM permissions:

UpdateIndex API permissions

To update an existing index with automatic semantic enrichment, you need the following IAM permissions:

GetIndex API permissions

To retrieve information about an index with automatic semantic enrichment, you need the following IAM permissions:

DeleteIndex API permissions

To delete an index with automatic semantic enrichment, you need the following IAM permissions:

Sample IAM policy

The following sample identity-based access policy provides the permissions necessary for a user to manage indexes with automatic semantic enrichment:

{
    "Version": "2012-10-17", 
    "Statement": [
        {
            "Sid": "AllowSemanticEnrichmentIndexOperations",
            "Effect": "Allow",
            "Action": [
                "es:CreateIndex",
                "es:UpdateIndex",
                "es:GetIndex",
                "es:DeleteIndex",
                "es:ESHttpHead",
                "es:ESHttpGet",
                "es:ESHttpPut",
                "es:ESHttpPost",
                "es:ESHttpDelete"
            ],
            "Resource": "arn:aws:es:aws-region:111122223333:domain/domain-name"
        }
    ]
}

Replace aws-region, 111122223333, and domain-name with your specific values. You can further restrict access by specifying particular index patterns in the resource ARN.

Fine-grained access control permissions

If your Amazon OpenSearch Service domain has fine-grained access control enabled, you need additional permissions beyond the IAM permissions.

Domains created on or after August 12, 2026 include a predefined fine-grained access control role, automatic_semantic_enrichment_full_access, that grants the permissions required to manage semantic enrichment indexes. If your domain uses fine-grained access control, map your user or backend role to automatic_semantic_enrichment_full_access instead of assigning the individual cluster and index permissions manually.

If your domain was created before this date, use the fine-grained access control permissions described in the following sections. The following permissions are required for each index operation.

CreateIndex API permissions

When fine-grained access control is enabled, the following additional permissions are required for creating an index with automatic semantic enrichment:

UpdateIndex API permissions

When fine-grained access control is enabled, the following additional permissions are required for updating an index with automatic semantic enrichment:

GetIndex API permissions

When fine-grained access control is enabled, the following additional permissions are required for retrieving information about an index with automatic semantic enrichment:

DeleteIndex API permissions

When fine-grained access control is enabled, the following additional permission is required for deleting an index with automatic semantic enrichment:

Query Rewrites

Automatic semantic enrichment automatically converts your existing “match” queries to semantic search queries without requiring query modifications. If a match query is part of a compound query, the system traverses your query structure, finds match queries, and replaces them with neural sparse queries. Currently, the feature only supports replacing “match” queries, whether it’s a standalone query or part of a compound query. “multi_match” is not supported. In addition, the feature supports all compound queries to replace their nested match queries. Compound queries include: bool, boosting, constant_score, dis_max, function_score, and hybrid.

Limitations of automatic semantic enrichment

Automatic semantic search is most effective when applied to small-to-medium sized fields containing natural language content, such as movie titles, product descriptions, reviews, and summaries. Although semantic search enhances relevance for most use cases, it might not be optimal for certain scenarios. Consider following limitations when deciding whether to implement automatic semantic enrichment for your specific use case.

Pricing

Amazon OpenSearch Service bills automatic semantic enrichment based on OpenSearch Compute Units (OCUs) consumed during sparse vector generation at indexing time. You're charged only for actual usage during indexing for the text fields where you enabled automatic semantic enrichment. One Semantic Search OCU can process 11.1 million tokens for English content. To process 2.4 billion tokens, you'd need about 216 Semantic Search OCU-hours (2.4 billion / 11.10 million). With a price of $0.24 per Semantic Search OCU-hour, the cost for processing 10 GB of data for automatic semantic search would be $51 (216 OCU-hours x $0.24/OCU-hour). There are no additional Semantic Search OCU charges during search operations or for data storage.

You can monitor this consumption using the Amazon CloudWatch metric SemanticSearchOCU. For specific details about model token limits, volume throughput per OCU, and an example of a sample calculation, visit OpenSearch Service Pricing.

Supported AWS Regions

Automatic semantic enrichment is available in the following AWS Regions: