|
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
-
A running OpenSearch instance. The following options are available:
-
If required, an API key for the EmbeddingModel to generate the embeddings stored by the
OpenSearchVectorStore.
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 |
|---|---|---|
|
URIs of the OpenSearch cluster endpoints |
- |
|
Username for accessing the OpenSearch cluster |
- |
|
Password for the specified username |
- |
|
Name of the index to store vectors |
|
|
Whether to initialize the required schema |
|
|
The similarity function (k-NN space type) to use (cosinesimil, l1, l2, linf, innerproduct) |
|
|
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 |
|
|
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. |
- |
|
Custom JSON mapping for the index. Overrides default mapping generation. |
- |
|
Time to wait for response from the opposite endpoint. 0 - infinity. |
- |
|
Time to wait until connection established. 0 - infinity. |
- |
|
Path prefix for OpenSearch API endpoints. Useful when OpenSearch is behind a reverse proxy with a non-root path. |
- |
|
Name of the SSL Bundle to use in case of SSL connection |
- |
|
Whether to use the Amazon OpenSearch Service client when the AWS SDK is on the classpath.
Set it to |
|
|
Optional domain name.
When set, the client connects to |
- |
|
Hostname of the Amazon OpenSearch Service endpoint |
- |
|
AWS service name used to sign requests, for example |
- |
|
AWS access key |
- |
|
AWS secret key |
- |
|
AWS region |
- |
|
The auto-configuration creates one
In both cases, |
|
The |
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.