Spring AI Vector Store
Since Camel 4.17
Only producer is supported
The Spring AI Vector Store component provides support for storing and retrieving documents in vector databases using Spring AI vector store capabilities.
Vector stores enable:
-
Storage of documents with embeddings
-
Similarity search based on vector distance
-
Metadata-based filtering
-
Document management (add, upsert, delete)
URI format
spring-ai-vector-store:storeId[?options]
Where storeId can be any string to uniquely identify the endpoint
Configuring Options
Camel components are configured on two separate levels:
-
component level
-
endpoint level
Configuring Component Options
At the component level, you set general and shared configurations that are, then, inherited by the endpoints. It is the highest configuration level.
For example, a component may have security settings, credentials for authentication, urls for network connection and so forth.
Some components only have a few options, and others may have many. Because components typically have pre-configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.
You can configure components using:
-
the Component DSL.
-
in a configuration file (
application.properties,*.yamlfiles, etc). -
directly in the Java code.
Configuring Endpoint Options
You usually spend more time setting up endpoints because they have many options. These options help you customize what you want the endpoint to do. The options are also categorized into whether the endpoint is used as a consumer (from), as a producer (to), or both.
Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the Endpoint DSL and DataFormat DSL as a type safe way of configuring endpoints and data formats in Java.
A good practice when configuring options is to use Property Placeholders.
Property placeholders provide a few benefits:
-
They help prevent using hardcoded urls, port numbers, sensitive information, and other settings.
-
They allow externalizing the configuration from the code.
-
They help the code to become more flexible and reusable.
The following two sections list all the options, firstly for the component followed by the endpoint.
Component Options
The Spring AI Vector Store component supports the following options which are listed below.
| Name | Description | Default | Type |
|---|---|---|---|
The configuration. | SpringAiVectorStoreConfiguration | ||
Filter expression for metadata-based filtering in searches. | String | ||
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean | |
The operation to perform on the vector store (ADD, DELETE, SIMILARITY_SEARCH, UPSERT). Enum values:
| ADD | SpringAiVectorStoreOperation | |
Whether SIMILARITY_SEARCH of a float[] body, such as the vector of spring-ai-embeddings, searches with this vector. By default it searches for the text of the CamelSpringAiEmbeddingInputText header, which the vector store embeds again. The vector store must support the search with a vector, and the vector must come from the same embedding model as the stored vectors. | false | boolean | |
The minimum similarity score threshold (0-1) for similarity search. | 0 | double | |
The maximum number of similar documents to return for similarity search. | 5 | int | |
Autowired Required The VectorStore to use for vector operations. | VectorStore | ||
Whether autowiring is enabled. This is used for automatic autowiring options (the option must be marked as autowired) by looking up in the registry to find if there is a single instance of matching type, which then gets configured on the component. This can be used for automatic configuring JDBC data sources, JMS connection factories, AWS Clients, etc. | true | boolean |
Endpoint Options
The Spring AI Vector Store endpoint is configured using URI syntax:
spring-ai-vector-store:storeId
With the following path and query parameters:
Query Parameters
| Name | Description | Default | Type |
|---|---|---|---|
Filter expression for metadata-based filtering in searches. | String | ||
The operation to perform on the vector store (ADD, DELETE, SIMILARITY_SEARCH, UPSERT). Enum values:
| ADD | SpringAiVectorStoreOperation | |
Whether SIMILARITY_SEARCH of a float[] body, such as the vector of spring-ai-embeddings, searches with this vector. By default it searches for the text of the CamelSpringAiEmbeddingInputText header, which the vector store embeds again. The vector store must support the search with a vector, and the vector must come from the same embedding model as the stored vectors. | false | boolean | |
The minimum similarity score threshold (0-1) for similarity search. | 0 | double | |
The maximum number of similar documents to return for similarity search. | 5 | int | |
Autowired Required The VectorStore to use for vector operations. | VectorStore | ||
Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean |
Message Headers
The Spring AI Vector Store component supports the following message header(s), which is/are listed below:
| Name | Description | Default | Type |
|---|---|---|---|
CamelSpringAiVectorStoreOperation (producer) Constant: | The operation to perform (ADD, DELETE, SIMILARITY_SEARCH, UPSERT). Enum values:
| SpringAiVectorStoreOperation | |
CamelSpringAiVectorStoreTopK (producer) Constant: | The maximum number of similar documents to return (topK). | Integer | |
CamelSpringAiVectorStoreSimilarityThreshold (producer) Constant: | The similarity threshold (0-1). | Double | |
CamelSpringAiVectorStoreFilterExpression (producer) Constant: | Filter expression for metadata-based filtering. | String | |
CamelSpringAiVectorStoreUpsertDocumentId (producer) Constant: | The id of the document that UPSERT writes from a float[] body: the document with this id is replaced. Without it, the document gets a random UUID. | String | |
CamelSpringAiVectorStoreUpsertDocumentIds (producer) Constant: | The ids of the documents that UPSERT writes from a List of float[] body, one per vector: the documents with these ids are replaced. Without it, each document gets a random UUID. | List | |
CamelSpringAiVectorStoreDocumentIds (producer) Constant: | List of document IDs (output of ADD, UPSERT and SIMILARITY_SEARCH, and input of DELETE when the message has no body). | List | |
CamelSpringAiVectorStoreSimilarDocuments (producer) Constant: | List of similar documents found. | List | |
CamelSpringAiVectorStoreDocumentsAdded (producer) Constant: | Number of documents added by ADD, or written by UPSERT. | Integer | |
CamelSpringAiVectorStoreDocumentsDeleted (producer) Constant: | Number of document IDs that DELETE gave to the vector store, as the vector store does not tell how many of them existed. | Integer |
Message Body
The message body at each side of the Spring AI Vector Store component: Consumer is the body of the messages the consumer creates, Consumer reply the bodies a consumer that answers its caller can reply with, Producer input the bodies the producer can send or write, and Producer output the body after the producer.
| Side | Body | Description |
|---|---|---|
Producer input |
| ADD takes a Document, a List of Document or of texts, or text (another body is added as its text); a List with another element fails. After spring-ai-embeddings it adds the float[] (or List of float[]) body with the text of the CamelSpringAiEmbeddingInputText(s) header, and a vector without its text fails. DELETE takes the id, a Document, or a List of ids or Documents (such as the result of SIMILARITY_SEARCH); the CamelSpringAiVectorStoreDocumentIds header is used only without a body. SIMILARITY_SEARCH takes the query text, or after spring-ai-embeddings the float[] body with the CamelSpringAiEmbeddingInputText header, or the float[] alone with searchByVector. UPSERT writes the float[] (or List of float[]) body of spring-ai-embeddings as it is, with the text of the CamelSpringAiEmbeddingInputText(s) header, or takes an EmbeddedDocument or a List of EmbeddedDocument. Otherwise no body fails. The CamelSpringAiVectorStoreOperation header overrides operation.
|
Producer output |
| SIMILARITY_SEARCH gives the List of Document found. ADD, UPSERT and DELETE keep the body, with the ids and the count in headers.
|
The bodies are the ones with the default options. A side that is not listed is not known, and tooling does not guess it. The carriers, the sides and the tools that use them are described in Message Body Types.
Operations
The component supports four operations:
ADD Operation
Stores documents in the vector store. Can accept:
-
String text (embeddings will be generated automatically)
-
Document objects
-
List of Documents or of String texts (an element of another type fails)
-
Output from the spring-ai-embeddings component (semi-automatic integration, this depends on the underlying Spring AI Vectore Store implementation): a
float[]body with theCamelSpringAiEmbeddingInputTextheader, or a List offloat[]body with theCamelSpringAiEmbeddingInputTextsheader with one text per vector. A vector without its text fails.
The CamelSpringAiEmbeddingInputText(s) headers are only used together with a vector body, so a header left over from an earlier spring-ai-embeddings call does not replace a Document or text body.
ADD of a vector stores its text, and the vector store embeds the text again with its own embedding model. The vector only goes in the embedding metadata of the document. To store the vector itself, use UPSERT.
After documents are added, the component sets the CamelSpringAiVectorStoreDocumentIds header containing a list of the IDs of the added documents. This allows you to reference or track the stored documents in subsequent processing steps.
| Best Practice: Use the ADD operation directly with the vector store component when working with text. The component will automatically handle embedding generation internally if the vector store is configured with an embedding model. This is the recommended approach as it simplifies your routes and reduces the number of steps. |
UPSERT Operation
Writes vectors that are already computed, such as the output of the spring-ai-embeddings component, as they are. The embedding model of the vector store is not called. A document with the same ID is replaced, otherwise a new document is added. UPSERT takes:
-
A
float[]body with theCamelSpringAiEmbeddingInputTextheader, the text of the vector. TheCamelSpringAiVectorStoreUpsertDocumentIdheader is the ID of the document. Without it, the document gets a random UUID. -
A List of
float[]body with theCamelSpringAiEmbeddingInputTextsheader, with one text per vector. TheCamelSpringAiVectorStoreUpsertDocumentIdsheader is the List of IDs, with one ID per vector. Without it, each document gets a random UUID. -
A Spring AI
EmbeddedDocument(a Document with its vector), or a List ofEmbeddedDocument. The ID and the metadata are the ones of the Document, and the ID headers are not used.
A vector without its text fails, and so does a List of texts or of IDs with another size than the List of vectors. UPSERT does not write the embedding and precomputed_embedding metadata of ADD.
Like ADD, UPSERT sets the CamelSpringAiVectorStoreDocumentsAdded header to the number of documents written, and the CamelSpringAiVectorStoreDocumentIds header to their IDs. UPSERT does not read the IDs from CamelSpringAiVectorStoreDocumentIds, as ADD, UPSERT and SIMILARITY_SEARCH set this header to their own output IDs.
The vector store must support UPSERT. In Spring AI 2.1, the Chroma, Couchbase, Elasticsearch, MariaDB, MongoDB Atlas, Neo4j, OpenSearch, PgVector, Qdrant, Redis and Typesense vector stores do. With another vector store, such as SimpleVectorStore, UPSERT fails with an UnsupportedOperationException and nothing is written: use ADD instead. Some vector stores only accept IDs in a given format, for example Qdrant needs UUIDs.
DELETE Operation
Removes documents from the vector store by their IDs. The body has the documents to delete: an ID, a Document, or a List of IDs or of Documents (such as the result of SIMILARITY_SEARCH). Only when there is no body, the IDs are taken from the CamelSpringAiVectorStoreDocumentIds header. The body comes first because ADD and SIMILARITY_SEARCH set this header to their own output IDs.
The CamelSpringAiVectorStoreDocumentsDeleted header is the number of IDs given to the vector store. The Spring AI VectorStore API does not tell how many of them existed, so IDs that are not in the store are counted too.
SIMILARITY_SEARCH Operation
Searches for documents similar to a query text. After the spring-ai-embeddings component, where the body is the float[] vector of the text, the query is the text in the CamelSpringAiEmbeddingInputText header (the vector store embeds the query itself).
With the searchByVector option, the float[] body is the query: the vector store searches with this vector, and does not embed a text. The CamelSpringAiEmbeddingInputText header is then not needed. A text body is still searched as a text. The vector store must support the search with a vector, as for UPSERT, otherwise the search fails with an UnsupportedOperationException. The topK, similarityThreshold and filterExpression options and headers apply as for a text.
The component returns matching documents in the message body and sets the following headers:
-
CamelSpringAiVectorStoreSimilarDocuments- List of Document objects found -
CamelSpringAiVectorStoreDocumentIds- List of IDs of the found documents
ADD or UPSERT
-
With ADD and a text query, the vector store embeds the texts with its own embedding model, when it writes and when it searches. This is the simplest way.
-
With UPSERT and
searchByVector, the route computes the vectors, for example with the spring-ai-embeddings component, and the vector store writes and searches with these vectors as they are. Use it to choose the embedding model in the route, or to embed each text only once.
Use the same embedding model, with the same settings, to write and to search. A vector of another model gives meaningless results, and no error is raised. This also applies when you mix the operations: documents written with UPSERT and searched with a text use the embedding model of the vector store for the query, and documents written with ADD and searched with searchByVector use the model of the route for the query. |
Usage Examples
Add Documents from Text (Recommended)
This is the recommended best practice for adding documents. The vector store component handles embedding generation internally:
-
Java
-
XML
-
YAML
from("direct:store")
.to("spring-ai-vector-store:myStore?operation=ADD&vectorStore=#vectorStore"); <route>
<from uri="direct:store"/>
<to uri="spring-ai-vector-store:myStore?operation=ADD&vectorStore=#vectorStore"/>
</route> - route:
from:
uri: direct:store
steps:
- to:
uri: spring-ai-vector-store:myStore
parameters:
operation: ADD
vectorStore: "#vectorStore" When you send plain text to this route, the component automatically: 1. Generates embeddings using the embedding model configured in the vector store 2. Creates a Document object 3. Stores it in the vector store
This single-step approach is simpler and more efficient than manually chaining the embeddings component.
Add from Embeddings Component (Alternative)
If you need explicit control over the embedding process or want to manipulate embeddings before storing, you can chain the components:
-
Java
-
XML
-
YAML
from("direct:embedAndStore")
.to("spring-ai-embeddings:test?embeddingModel=#embeddingModel")
.to("spring-ai-vector-store:test?vectorStore=#vectorStore"); <route>
<from uri="direct:embedAndStore"/>
<to uri="spring-ai-embeddings:test?embeddingModel=#embeddingModel"/>
<to uri="spring-ai-vector-store:test?vectorStore=#vectorStore"/>
</route> - route:
from:
uri: direct:embedAndStore
steps:
- to:
uri: spring-ai-embeddings:test
parameters:
embeddingModel: "#embeddingModel"
- to:
uri: spring-ai-vector-store:test
parameters:
vectorStore: "#vectorStore" | This approach is only necessary when you need to access or modify the embeddings between generation and storage. For most use cases, the direct ADD operation (shown above) is preferred. With ADD, the vector store embeds the text again: to store the vectors of the embeddings component, use UPSERT (shown below). |
Store and Search with the Vectors of the Embeddings Component
UPSERT stores the vectors that the spring-ai-embeddings component computes, and searchByVector searches with the vector of the query. The vector store does not embed any text, so it must support UPSERT and the search with a vector.
-
Java
-
XML
-
YAML
from("direct:store")
.to("spring-ai-embeddings:embed?embeddingModel=#embeddingModel")
.to("spring-ai-vector-store:myStore?operation=UPSERT&vectorStore=#vectorStore");
from("direct:search")
.to("spring-ai-embeddings:embed?embeddingModel=#embeddingModel")
.to("spring-ai-vector-store:myStore?operation=SIMILARITY_SEARCH&searchByVector=true&topK=5&vectorStore=#vectorStore"); <route>
<from uri="direct:store"/>
<to uri="spring-ai-embeddings:embed?embeddingModel=#embeddingModel"/>
<to uri="spring-ai-vector-store:myStore?operation=UPSERT&vectorStore=#vectorStore"/>
</route>
<route>
<from uri="direct:search"/>
<to uri="spring-ai-embeddings:embed?embeddingModel=#embeddingModel"/>
<to uri="spring-ai-vector-store:myStore?operation=SIMILARITY_SEARCH&searchByVector=true&topK=5&vectorStore=#vectorStore"/>
</route> - route:
from:
uri: direct:store
steps:
- to:
uri: spring-ai-embeddings:embed
parameters:
embeddingModel: "#embeddingModel"
- to:
uri: spring-ai-vector-store:myStore
parameters:
operation: UPSERT
vectorStore: "#vectorStore"
- route:
from:
uri: direct:search
steps:
- to:
uri: spring-ai-embeddings:embed
parameters:
embeddingModel: "#embeddingModel"
- to:
uri: spring-ai-vector-store:myStore
parameters:
operation: SIMILARITY_SEARCH
searchByVector: true
topK: 5
vectorStore: "#vectorStore" To replace a document, for example when its text changes, set its ID in the CamelSpringAiVectorStoreUpsertDocumentId header (or the IDs in CamelSpringAiVectorStoreUpsertDocumentIds for a List of texts) before UPSERT.
Similarity Search
-
Java
-
XML
-
YAML
from("direct:search")
.setBody(constant("What is AI?"))
.to("spring-ai-vector-store:myStore?operation=SIMILARITY_SEARCH&topK=5&similarityThreshold=0.7")
.log("Found ${header.CamelSpringAiVectorStoreSimilarDocuments.size()} similar documents")
.log("Document IDs: ${header.CamelSpringAiVectorStoreDocumentIds}"); <route>
<from uri="direct:search"/>
<setBody><constant>What is AI?</constant></setBody>
<to uri="spring-ai-vector-store:myStore?operation=SIMILARITY_SEARCH&topK=5&similarityThreshold=0.7"/>
<log message="Found ${header.CamelSpringAiVectorStoreSimilarDocuments.size()} similar documents"/>
<log message="Document IDs: ${header.CamelSpringAiVectorStoreDocumentIds}"/>
</route> - route:
from:
uri: direct:search
steps:
- setBody:
constant: "What is AI?"
- to:
uri: spring-ai-vector-store:myStore
parameters:
operation: SIMILARITY_SEARCH
topK: 5
similarityThreshold: 0.7
- log:
message: "Found ${header.CamelSpringAiVectorStoreSimilarDocuments.size()} similar documents"
- log:
message: "Document IDs: ${header.CamelSpringAiVectorStoreDocumentIds}" Delete Documents
Delete documents by specifying their IDs in the body:
from("direct:delete")
.setBody(constant(Arrays.asList("doc1", "doc2")))
.to("spring-ai-vector-store:myStore?operation=DELETE"); You can also chain operations to search for documents and then delete the documents found:
from("direct:searchAndDelete")
.setBody(constant("outdated content"))
.to("spring-ai-vector-store:myStore?operation=SIMILARITY_SEARCH&topK=10")
.log("Found ${header.CamelSpringAiVectorStoreDocumentIds.size()} documents to delete")
// DELETE deletes the List of Document that SIMILARITY_SEARCH gives in the body
.setHeader(SpringAiVectorStoreHeaders.OPERATION, constant(SpringAiVectorStoreOperation.DELETE))
.to("spring-ai-vector-store:myStore"); Configuration
Configuring the Vector Store
To use the ADD operation with automatic embedding generation (recommended), configure your vector store with an embedding model:
// Create a Qdrant Client
QdrantClient qdrantClient
= new QdrantClient(QdrantGrpcClient.newBuilder(QDRANT.getGrpcHost(), QDRANT.getGrpcPort(), false).build());
// Create an embedding model
EmbeddingModel embeddingModel = new OllamaEmbeddingModel(ollamaApi, options);
// Create a vector store with the embedding model
// Example with Qdrant
VectorStore vectorStore = QdrantVectorStore.builder(qdrantClient, embeddingModel)
.collectionName("my_collection")
.initializeSchema(true)
.build();
// Or with Simple Vector Store
VectorStore vectorStore = new SimpleVectorStore(embeddingModel);
// Register in Camel context
context.getRegistry().bind("vectorStore", vectorStore);
// Use in route - the component will use the configured embedding model
from("direct:start")
.to("spring-ai-vector-store:test?vectorStore=#vectorStore&operation=ADD"); | Make sure your vector store is configured with an embedding model to enable automatic embedding generation when using the ADD operation with text input. |
Search Parameters
-
topK- Maximum number of results (default: 5) -
similarityThreshold- Minimum similarity score 0-1 (default: 0.0) -
filterExpression- Metadata-based filter expression -
searchByVector- Search with thefloat[]body instead of the text of theCamelSpringAiEmbeddingInputTextheader (default: false)