The MongoDBAtlasVectorStore implementation has been enhanced with a builder
pattern to provide a more flexible and type-safe way to configure the vector
store. This change improves the developer experience by making the API more
intuitive and less error-prone.
The old constructors and configuration classes have been deprecated in favor
of the builder pattern. This aligns with Spring's best practices for
configuration APIs.
Additionally, the package has been refactored to
org.springframework.ai.vectorstore.mongodb.atlas to avoid having
multiple vector store modules share the same package name.
Documentation has been updated to reflect these changes and provide
examples of using the new builder pattern.review
The changes introduce a fluent builder pattern for ElasticsearchVectorStore
configuration, making it easier to create and customize instances with
optional parameters. All Elasticsearch-related classes are moved to a
dedicated elasticsearch package for better organization.
Key changes:
* Add ElasticsearchVectorStore.builder() with comprehensive options
* Move classes to org.springframework.ai.vectorstore.elasticsearch package
* Deprecate old constructors in favor of builder pattern
* Add support for configurable batching strategies
* Enhance documentation with usage examples and best practices
- Move PgVectorStore and related classes to org.springframework.ai.pg.vectorstore package
- Update builder pattern to use more idiomatic method names (e.g. withSchemaName -> schemaName)
- Deprecate existing constructors and old Builder class in favor of new static builder() method
- Update tests to reflect the new builder style usage
- Update docs
Introduces a fluent builder API to improve configuration readability and
type safety when creating MilvusVectorStore instances. This replaces the
existing configuration object approach which was less intuitive and harder
to maintain.
The builder pattern provides better encapsulation of configuration logic
and validation, while maintaining backward compatibility through a
deprecated config class. This change makes the codebase more maintainable
and the API more discoverable for users.
Key changes:
- Replace configuration object with fluent builder pattern
- Move Milvus-related classes to dedicated milvus package
- Deprecate MilvusVectorStoreConfig in favor of builder
- Update constructor to use builder internally
- Maintain backward compatibility with deprecated config
- Add comprehensive builder methods with validation
The commit restructures the ChromaVectorStore builder pattern to use a no-args constructor
with fluent API for setting the ChromaApi.
This change:
- Makes builder creation consistent with other vector stores
- Moves ChromaApi validation to the doValidate method
- Improves builder API ergonomics
The change requires updating all builder usages to use the new .chromaApi() method instead
of passing it in the constructor.
The Document class previously allowed multiple media entries while also having a
text field, leading to ambiguity in content handling. This change enforces a
clear separation between text and media documents to prevent content type
confusion and simplify document processing.
A Document now must contain either text content or a single media entry, but
never both. This aligns with the class's primary use in ETL pipelines where
clear content type boundaries are essential for proper embedding generation and
vector database storage.
Additional architectural changes:
- Document now implements a cleaner API by removing deprecated methods
- Removed MediaContent interface implementation from Document class
- Document.getMedia() now returns a single Media object instead of Collection
- Removed EMPTY_TEXT constant in favor of proper null handling
- Constructor signatures simplified and streamlined
- Builder pattern improved to enforce single content type constraint
The breaking changes include:
- Media is now a single entry instead of a collection
- Content field renamed to text for clarity
- Removed support for mixed content types
- Simplified builder API to prevent ambiguous construction
Prefer using text-related methods over deprecated content methods to
better reflect the actual content type being handled and improve API clarity.
- Since Document's reference to its embedding is deprecated, store the embedding into OpenSearch vector store by creating an explicit OpenSearch Document type which has embedding associated with it
- Create an explicit MariaDBDocument to store the embeddings of its content
- This is because the Spring AI Document no longer holds reference to its embeddings
- Address the test case which checks just the MariaDB documents storing without their embeddings
- Re-enable the MariDB ITs
This refactoring introduces a consistent builder pattern across vector store
implementations to standardize configuration and initialization, while also
moving ChromaVectorStore to a dedicated chroma package.
Key changes:
- Add VectorStore.Builder interface and AbstractVectorStoreBuilder to establish
a common builder hierarchy
- Move ChromaVectorStore and related classes from vectorstore to
org.springframework.ai.chroma.vectorstore package
- Migrate ChromaVectorStore to builder pattern as the first implementation
- Add null-safety annotations and parameter validation
- Deprecate direct constructors in favor of builder API
- Update all tests and documentation to reflect new structure
The builder pattern provides several benefits:
- Consistent configuration across all vector store implementations
- Better validation of required parameters
- More flexible initialization order
- Clearer separation of concerns between configuration and usage
- Improved discoverability of options through method chaining
- Since the Document object's reference to the `embedding` is deprecated and will be removed, the VectorStore implementations require a way to store the embedding of the corresponding Document objects
- One way to fix this is, to have the EmbeddingModel#embed to return the embeddings in the same order as that of the Documents passed to it.
- Since both the Document and embedding collections use the List object, their iteration operation will make sure to keep them in line with the same order.
- A fix is required to preserve the order when batching strategy is applied.
- Updated the Javadoc for BatchingStrategy
- Fixed the Document List order in TokenCountBatchingStrategy
- Refactored the vector store implementations to update this change
Resolves #GH-1826
- PaymentStatusFunctionCallingIT in org.springframework.ai.mistralai.api.tool
is failing. Needs investigation.
See https://github.com/spring-projects/spring-ai/issues/1853
- OpenSearchVectorStoreWithOllamaIT updated to pull model if not available.
Document
* Introduced “score” attribute in Document API. It stores the similarity score.
* Consolidate “distance” metadata for Documents. It stores the distance measurement.
* Adopted prefix-less naming convention in Document.Builder and deprecated old methods.
* Deprecated the many overloaded Document constructors in favour of Document.Builder.
Vector Stores
* Every vector store implementation now configures a “score” attribute with the similarity score of the Document embedding. It also includes the “distance” metadata with the distance measurement.
* Fixed error in Elasticsearch where distance and similarity were mixed up.
* Added missing integration tests for SimpleVectorStore.
* The Azure Vector Store and HanaDB Vector Store do not include those measurements because the product documentation do not include information about how the similarity score is returned, and without access to the cloud products I could not verify that via debugging.
* Improved tests to actually assert the result of the similarity search based on the returned score.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Updated `org.springframework.boot.autoconfigure.AutoConfiguration.imports` to include MariaDB vector store auto-configuration
- Created MariaDB Vector Store autoconfiguration integration tests (`MariaDbStoreAutoConfigurationIT`)
- Added MariaDB store properties configuration and tests (`MariaDbStorePropertiesTests`)
- Introduced new Maven modules:
- `spring-ai-mariadb-store`: Core MariaDB vector store implementation
- `spring-ai-starter-mariadb-store`: Spring Boot starter for MariaDB vector store
- Added `MariaDBFilterExpressionConverter` to support JSON-based metadata filtering in MariaDB
- Implemented filter expression conversion for MariaDB vector store queries
- Added README.md with documentation link for MariaDB Vector Store
- Updated project dependencies to include MariaDB JDBC driver and test containers
- Configured integration testing with TestContainers for MariaDB
- Added observability support for MariaDB vector store operations
- Add new Maven profile 'ci-fast-integration-tests' for running selective ITs
- Remove redundant vector store skip flags from properties section
- Update maven-failsafe-plugin to version 3.5.2
- Configure test exclusions for various components:
- Most model integration tests (Anthropic and OpenAI)
- Most vector store tests (except PgVector and Chroma)
- Most auto-configuration tests
- All test containers and docker compose tests
- AI evaluation tests
- Convert the docker-compose tests into ITs
- Convert the testcontainers tests into ITs
- Updated README.md
- Explain the new profile and also the new integration tests repo
- Describe ways to run integration tests for specific modules
- Add badge for https://github.com/spring-projects/spring-ai-integration-tests
- Upgrade Spring Boot to 3.3.6
- Update swagger-codegen-maven-plugin to 3.0.64
- Add custom template for HttpBasicAuth
- Fix mockwebserver version to 4.12.0
- Fix parent version reference in opensearch-store
- Added Jackson annotations for JSON property handling in Chroma API request/response records.
Use @JsonInclude(JsonInclude.Include.NON_NULL) to ignore empty fields such as null where.
Use @JsonProperty(XYZ) to provide a strong contract with the Cohere API.
- Updated the Docker image for running Chroma locally and in tests to version 0.5.20.
- Enhanced methods with non-null assertions for improved code safety.
- Added a simple search test to verify document similarity search functionality.
Fixes#1749
Implemented a new configuration property 'useKeylessAuth' to toggle
between API key and Azure default credential authentication.
Added necessary dependencies and updated tests to reflect the new changes.
co-authored-by: mattgotteiner <mattgotteiner@users.noreply.github.com>
- Fix the embedding dimension configuration for opensearch client indices mapping
The dimension config is obtained by the underlying embedding model's dimension
- Updated OpenSearch mapping JSON to include dynamic embedding dimension.
- Changed default mapping for OpenSearch vector store to use generic dimension placeholder.
- Fixed OpenSearchVectorStoreAutoConfiguration to fallback to new default mapping if no custom mapping is provided.
- Added test for verifying mapping configuration with OpenSearch vector store.
- Added test dependencies for Ollama integration.
- Refactored OpenSearch integration tests to use new mapping and dimension logic.
Add tests
- Verify the mappingJson field is correctly set - verify the override works fine
- Add integration tests with Ollama embedding model
Resolves#1589
- Remove deprecated types,methods and references
- Remove usage of "Generation(String text)" and replace with
"Generation(AssistantMessage)"
- Remove MiniMaxApi,MootShotApi,OpenAiApi,ZhiPuAiApi
ChatCompletionFinishReason's FUNCTION_CALL
- Remove OllamaApi's deprecated types
- Remove deprecated constructors from PostgresMlEmbeddingModel
- Remove deprecated constructor from Media
- Remove tokenNames usage from antlr4 FiltersLexer and FiltersParser
- Remove deprecated methods from CassandraVectorStoreProperties
- Remove deprecated constructor and static config class from QdrantVectorStore
- Minor cleanups on removing deprecated models and versions
- Remove old name for mixtral models
Resolves#1599
Resolves#1628
In Azure Vector Store, the embedding field needs to be retrievable
for proper functionality. While SearchField class doesn't have a
'retrievable' property, the 'hidden' field serves the same purpose.
The fix sets hidden=false on the embedding field to make it retrievable.
Link: https://github.com/spring-projects/spring-ai/issues/1628
Due to changes in Chroma v0.5.13 (chroma-core/chroma#2880), the delete
operation no longer returns values. This impacts our ChromaVectorStore's delete
functionality.
Now we need to check the HTTP status code instead to properly verify if the
delete operation succeeded.
Test suite has been updated.
Resolves#1529
The change addresses initialization issues when ChromaVectorStore is used outside
Spring context, particularly in scenarios where collections are created manually
before store instantiation. Previously, collection ID wasn't properly populated
when afterPropertiesSet() wasn't called by Spring container.
- Add builder pattern to ChromaVectorStore for better initialization control
- Add initialization flag to prevent multiple collection creation calls
- Add integration tests for builder pattern usage scenarios
- Add spring-ai-transformers dependency for testing
- Remove unused constants (SIMILARITY_THRESHOLD_ALL, DEFAULT_TOP_K)
Collection ID is now properly set regardless of whether the store is managed by
Spring or created manually, solving the 404 Not Found errors during document
insertion.
Fixes: #1240
- Add maven properties for all vector stores such as
skip.vectorstore.azure-cosmos-db to control IT test execution
- Chroma and PGVector IT tests are enabled by default
- Docker Compose and Testcontainers module ITs are skipped by default
- Add parallel job to run docker-compose and testcontainers ITs
- Fix parameter access syntax in setNodeVectorProperty DDL statement
- Define DEFAULT_TRANSACTION_SIZE for the hardcoded batch size in
the delete query
Fixes#1623
Signed-off-by: jitokim <pigberger70@gmail.com>
Integrates Oracle Coherence 24.09+ as a vector store backend for Spring AI. The
implementation provides:
- Support for vector similarity search with configurable distance metrics (Cosine,
Inner Product, L2)
- Multiple indexing options including HNSW and Binary Quantization indexes
- Filter expression evaluation for metadata-based filtering
- Vector normalization capabilities
- Comprehensive test coverage including integration tests
The implementation includes:
- CoherenceVectorStore main implementation
- CoherenceFilterExpressionConverter for Spring AI to Coherence filter conversion
- Auto-configuration support via spring-boot-starter
- Documentation and usage examples
Requires Oracle Coherence 24.09 or later.
Replace traditional switch statements with Java 14 switch expressions across
vector store filter converters and related components. This change improves
code quality in our filter expression handling for Azure, Milvus, Redis,
Typesense and Weaviate implementations.
The switch expressions eliminate fall-through behavior, enforce exhaustive
pattern matching at compile time, and provide a more direct way to return
values. This makes the filter conversion logic more robust and maintainable.
- Milvus requires "not in" operator syntax instead of "nin" for filtering.
- See https://milvus.io/docs/boolean.md
- Updated test and added additional test coverage
- Disable project-wide Checkstyle checks to unblock development
- Add documentation for enabling Checkstyle locally
- Fix remaining checkstyle violations in current codebase
Fixes#1669
- The doSimilaritySearch method did not pass the databaseName parameter in milvus 2.3.4 and before, resulting in the use of the default database; The current milvus upgrade to 2.3.5 supports passing the databaseName parameter
- Update doSimilaritySearch to set the database name from the Milvus configuration
This change uses `session.executeWrite` and `session.executeRead` to interact with the database.
Those methods use build-in retries for several Neo4j specific error states.
Doing will improve the overall user experience in this case as the no other external retry mechanism should be used.
Doing so is fine, as the Neo4j vector store is not subject to Springs general transaction management.
