This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0!

OpenSearch

This section walks you through setting up OpenSearchVectorStore to store document embeddings and perform similarity searches.

OpenSearch is an open-source search and analytics engine originally forked from Elasticsearch, distributed under the Apache License 2.0. It enhances AI application development by simplifying the integration and management of AI-generated assets. OpenSearch supports vector, lexical, and hybrid search capabilities, leveraging advanced vector database functionalities to facilitate low-latency queries and similarity searches as detailed on the vector database page.

The OpenSearch k-NN functionality allows users to query vector embeddings from large datasets. An embedding is a numerical representation of a data object, such as text, image, audio, or document. Embeddings can be stored in the index and queried using various similarity functions.

Prerequisites

Auto-configuration

Spring AI provides Spring Boot auto-configuration for the OpenSearch Vector Store. To enable it, add the following dependency to your project’s Maven pom.xml file:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-opensearch</artifactId>
</dependency>

or to your Gradle build.gradle build file:

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-opensearch'
}
Refer to the Dependency Management section to add the Spring AI BOM to your build file.

The starter brings the AWS SDK modules apache-client, auth and regions, so the Amazon OpenSearch Service configuration is active by default. To connect to a self-managed OpenSearch cluster, turn it off and set the cluster URIs:

spring.ai.vectorstore.opensearch.aws.enabled=false
spring.ai.vectorstore.opensearch.uris=http://localhost:9200

Without aws.enabled=false, the auto-configuration builds an AWS client from the aws. properties and ignores uris, username and password. If the aws. properties are not set, the application fails to start.

The spring-ai-starter-vector-store-aws-opensearch starter adds only the AWS SDK apache-client module, without auth and regions. On its own, it therefore does not activate the Amazon OpenSearch Service configuration, and the store connects through uris. For Amazon OpenSearch Service, use spring-ai-starter-vector-store-opensearch, or add the software.amazon.awssdk:auth module (which brings regions) next to the AWS starter.

Please have a look at the list of configuration parameters for the vector store to learn about the default values and configuration options.

Additionally, you will need a configured EmbeddingModel bean. Refer to the EmbeddingModel section for more information.

Now you can auto-wire the OpenSearchVectorStore as a vector store in your application:

@Autowired VectorStore vectorStore;

// ...

List<Document> documents = List.of(
    new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
    new Document("The World is Big and Salvation Lurks Around the Corner"),
    new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));

// Add the documents to OpenSearch
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());

Configuration Properties

To connect to OpenSearch and use the OpenSearchVectorStore, you need to provide access details for your instance. A simple configuration can be provided via Spring Boot’s application.yml:

spring:
  ai:
    vectorstore:
      opensearch:
        uris: <opensearch instance URIs>
        username: <opensearch username>
        password: <opensearch password>
        index-name: spring-ai-document-index
        initialize-schema: true
        similarity: cosinesimil
        read-timeout: <time to wait for response>
        connection-timeout: <time to wait until connection established>
        path-prefix: <custom path prefix>
        ssl-bundle: <name of SSL bundle>
        aws:  # Only for Amazon OpenSearch Service; set enabled: false for a self-managed cluster
          enabled: true
          domain-name: <optional domain name, prepended to the host>
          host: <aws opensearch host>
          service-name: <aws service name>
          access-key: <aws access key>
          secret-key: <aws secret key>
          region: <aws region>

Properties starting with spring.ai.vectorstore.opensearch.* are used to configure the OpenSearchVectorStore:

Property Description Default Value

spring.ai.vectorstore.opensearch.uris

URIs of the OpenSearch cluster endpoints

-

spring.ai.vectorstore.opensearch.username

Username for accessing the OpenSearch cluster

-

spring.ai.vectorstore.opensearch.password

Password for the specified username

-

spring.ai.vectorstore.opensearch.index-name

Name of the index to store vectors

spring-ai-document-index

spring.ai.vectorstore.opensearch.initialize-schema

Whether to initialize the required schema

false

spring.ai.vectorstore.opensearch.similarity

The similarity function (k-NN space type) to use (cosinesimil, l1, l2, linf, innerproduct)

cosinesimil

spring.ai.vectorstore.opensearch.use-approximate-knn

Whether to use approximate k-NN for faster searches. If true, uses HNSW-based approximate search. If false, uses exact brute-force k-NN. See Approximate k-NN and Exact k-NN

false

spring.ai.vectorstore.opensearch.dimensions

Vector size used for validation, built-in index mappings, and dimension placeholders in custom mappings. When unset, new built-in approximate mappings use 1536; exact mappings and custom-mapping placeholders use the embedding model’s size. A hard-coded dimension in a custom mapping is preserved. For an existing index, an unset size is read from its mapping.

-

spring.ai.vectorstore.opensearch.mapping-json

Custom JSON mapping for the index. Overrides default mapping generation.

-

spring.ai.vectorstore.opensearch.read-timeout

Time to wait for response from the opposite endpoint. 0 - infinity.

-

spring.ai.vectorstore.opensearch.connection-timeout

Time to wait until connection established. 0 - infinity.

-

spring.ai.vectorstore.opensearch.path-prefix

Path prefix for OpenSearch API endpoints. Useful when OpenSearch is behind a reverse proxy with a non-root path.

-

spring.ai.vectorstore.opensearch.ssl-bundle

Name of the SSL Bundle to use in case of SSL connection

-

spring.ai.vectorstore.opensearch.aws.enabled

Whether to use the Amazon OpenSearch Service client when the AWS SDK is on the classpath. Set it to false for a self-managed cluster.

true

spring.ai.vectorstore.opensearch.aws.domain-name

Optional domain name. When set, the client connects to <domain-name>.<host>.

-

spring.ai.vectorstore.opensearch.aws.host

Hostname of the Amazon OpenSearch Service endpoint

-

spring.ai.vectorstore.opensearch.aws.service-name

AWS service name used to sign requests, for example es for a managed domain or aoss for OpenSearch Serverless

-

spring.ai.vectorstore.opensearch.aws.access-key

AWS access key

-

spring.ai.vectorstore.opensearch.aws.secret-key

AWS secret key

-

spring.ai.vectorstore.opensearch.aws.region

AWS region

-

The auto-configuration creates one OpenSearchClient, and spring.ai.vectorstore.opensearch.aws.enabled decides which one. The property is read only by the auto-configuration conditions, so it has no configuration metadata and your IDE does not complete it.

  • If the AWS SDK auth, regions and apache-client modules are on the classpath and aws.enabled is not false, the client signs requests for Amazon OpenSearch Service and uses the aws.* properties. The spring-ai-starter-vector-store-opensearch starter puts these modules on the classpath.

  • If aws.enabled is false, or one of these modules is missing, the client connects to uris with username, password and path-prefix.

In both cases, connection-timeout, read-timeout and ssl-bundle apply. A self-managed cluster therefore needs aws.enabled=false when you use the spring-ai-starter-vector-store-opensearch starter, or when the AWS SDK is on the classpath for other services.

The path-prefix property allows you to specify a custom path prefix when OpenSearch is running behind a reverse proxy that uses a non-root path. For example, if your OpenSearch instance is accessible at example.com/opensearch/ instead of example.com/, you would set path-prefix: /opensearch.

The following similarity functions are available:

  • cosinesimil - Default, suitable for most use cases. Measures cosine similarity between vectors.

  • l1 - Manhattan distance between vectors.

  • l2 - Euclidean distance between vectors.

  • linf - Chebyshev distance between vectors.

Upsert support

OpenSearchVectorStore implements upsert(List<EmbeddedDocument>), so you can write documents together with embeddings you computed elsewhere instead of having the store embed them. Writing the same id again replaces the existing document, so a re-run with stable ids does not create duplicates. Upsert needs manageDocumentIds to be true, the default, because with it off OpenSearch generates its own ids and cannot replace a document by id. See Writing User-Supplied Embeddings for details.

Manual Configuration

Instead of using the Spring Boot auto-configuration, you can manually configure the OpenSearch vector store. For this you need to add the spring-ai-opensearch-store to your project:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-opensearch-store</artifactId>
</dependency>

or to your Gradle build.gradle build file:

dependencies {
    implementation 'org.springframework.ai:spring-ai-opensearch-store'
}
Refer to the Dependency Management section to add the Spring AI BOM to your build file.

Create an OpenSearch client bean:

// org.apache.hc.core5.http.HttpHost
// org.opensearch.client.transport.httpclient5.ApacheHttpClient5TransportBuilder
@Bean
public OpenSearchClient openSearchClient() throws URISyntaxException {
    HttpHost host = HttpHost.create("http://localhost:9200");
    OpenSearchTransport transport = ApacheHttpClient5TransportBuilder.builder(host).build();
    return new OpenSearchClient(transport);
}

Then create the OpenSearchVectorStore bean using the builder pattern:

@Bean
public VectorStore vectorStore(OpenSearchClient openSearchClient, EmbeddingModel embeddingModel) {
    return OpenSearchVectorStore.builder(openSearchClient, embeddingModel)
        .index("custom-index")                // Optional: defaults to "spring-ai-document-index"
        .similarityFunction("l2")             // Optional: defaults to "cosinesimil"
        .useApproximateKnn(true)              // Optional: defaults to false (exact k-NN)
        .dimensions(1536)                     // Optional: explicit vector size, see the defaults above
        .initializeSchema(true)               // Optional: defaults to false
        .batchingStrategy(new TokenCountBatchingStrategy()) // Optional: defaults to TokenCountBatchingStrategy
        .build();
}

// This can be any EmbeddingModel implementation
@Bean
public EmbeddingModel embeddingModel() {
    return new OpenAiEmbeddingModel(OpenAiEmbeddingOptions.builder().apiKey(System.getenv("OPENAI_API_KEY")).build());
}

Custom Mappings

A custom mapping, set with mappingJson or spring.ai.vectorstore.opensearch.mapping-json, is used only when the store creates the index; it does not change an existing index. A fixed size in the mapping, such as "dimension": 4, creates a field that accepts four-dimensional vectors. If you also configure dimensions, set it to the same value: it controls validation but does not rewrite a fixed size in the mapping. To have the store fill in the size, write "dimension": %s, which becomes the configured dimensions, or the embedding model’s size when none is configured. To create the index without calling the embedding model, configure dimensions explicitly.

Metadata Filtering

You can leverage the generic, portable metadata filters with OpenSearch as well.

For example, you can use either the text expression language:

vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("The World")
        .topK(TOP_K)
        .similarityThreshold(SIMILARITY_THRESHOLD)
        .filterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'").build());

or programmatically using the Filter.Expression DSL:

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.builder()
    .query("The World")
    .topK(TOP_K)
    .similarityThreshold(SIMILARITY_THRESHOLD)
    .filterExpression(b.and(
        b.in("author", "john", "jill"),
        b.eq("article_type", "blog")).build()).build());
Those (portable) filter expressions get automatically converted into the proprietary OpenSearch Query string query.

For example, this portable filter expression:

author in ['john', 'jill'] && 'article_type' == 'blog'

is converted into the proprietary OpenSearch filter format:

metadata.author:(john OR jill) AND metadata.article_type:blog

Accessing the Native Client

The OpenSearch Vector Store implementation provides access to the underlying native OpenSearch client (OpenSearchClient) through the getNativeClient() method:

OpenSearchVectorStore vectorStore = context.getBean(OpenSearchVectorStore.class);
Optional<OpenSearchClient> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    OpenSearchClient client = nativeClient.get();
    // Use the native client for OpenSearch-specific operations
}

The native client gives you access to OpenSearch-specific features and operations that might not be exposed through the VectorStore interface.