Updated the manual configuration examples in the following docs to show
the correct usage of the inner builder class:
- azure.adoc: Show builder(searchIndexClient, embeddingModel) with all available options
- chroma.adoc: Show builder(chromaApi, embeddingModel) with collection config
- oracle.adoc: Show builder(jdbcTemplate, embeddingModel) with database options
The examples now reflect the current implementation where the builder takes
both the client and embedding model as constructor arguments.
- Rename all specific builder inner classes (PineconeBuilder, MongoDBBuilder, etc.)
to simply Builder for consistency across vector store implementations
- Update code references to use the new standardized Builder class names
The change establishes a consistent naming convention for builder classes
across the vector store implementations, improving code uniformity.
- Replace Document.getContent() with getText() across all vector store implementations
- Fix incorrect package declarations in package-info.java files
- Make builder constructors private and implement proper builder patterns
- Add @Nullable annotations for better null safety
- Simplify PineconeVectorStore builder API by requiring essential parameters in factory method
- Make static Map fields final
- Clean up code and improve JavaDoc documentation
The changes focus on making the vector store APIs more consistent,
type-safe, and maintainable while following best practices for
builder patterns and null safety.
This commit refactors the builder pattern implementation across all VectorStore
implementations to make the EmbeddingModel a required constructor parameter
rather than an optional builder method. Key changes include:
- Move embeddingModel from being a builder method to a required constructor parameter
- Make embeddingModel final in AbstractVectorStoreBuilder
- Remove redundant validate() methods since EmbeddingModel validation now happens
in constructor
- Update all VectorStore builder instantiations to pass EmbeddingModel in builder
creation
- Add @Nullable annotations to appropriate methods in VectorStore interface
This change improves the API design by:
1. Enforcing that EmbeddingModel is provided at builder creation time
2. Removing the possibility of forgotten EmbeddingModel configuration
3. Simplifying the builder implementation by moving validation to construction
4. Making the dependency on EmbeddingModel more explicit in the API
Breaking Changes:
- VectorStore builders must now be created with an EmbeddingModel parameter
- The embeddingModel() builder method has been removed from all implementations
The Ollama options builder API has been refactored to follow standard Java
builder pattern conventions. This change deprecates all builder methods
prefixed with 'with' in favor of more concise method names, improving API
consistency and usability.
The deprecated methods are marked for removal in version 1.0.0-M5, giving
users time to migrate to the new builder pattern. This change aligns with
our goal of providing a more intuitive and maintainable API surface.
Breaking Changes:
* builder() method now returns Builder instead of OllamaOptions
* Clients using the old fluent API will need to migrate to the new builder pattern
Refactor Ollama options builder methods
This commit deprecates builder methods with the "with" prefix in the VectorStoreObservationContext class
and introduces new methods without the prefix for a cleaner API. For example:
withCollectionName() → collectionName()
withDimensions() → dimensions()
withNamespace() → namespace()
The old methods are marked as deprecated for maintaining backward compatibility.
All vector store implementations have been updated to use the new method names.
Introduces a builder pattern for configuring QdrantVectorStore instances to
provide a more flexible and type-safe way to create and configure vector stores.
This change:
- Makes configuration more intuitive through fluent builder methods
- Improves validation by enforcing required parameters at compile time
- Deprecates old constructors in favor of the builder pattern
- Adds comprehensive builder tests to ensure reliability
- Updates reference documentation with builder usage examples
- Maintains backward compatibility while providing a clear migration path
The builder pattern simplifies QdrantVectorStore configuration by providing
clear method names, proper validation, and better IDE support through method
chaining. This makes the API more user-friendly and helps prevent configuration
errors at compile time rather than runtime.
Introduces a builder pattern for configuring MariaDBVectorStore instances and
improves the overall implementation. This change:
- Makes configuration more flexible and type-safe through builder methods
- Deprecates old constructors and builder in favor of the new builder pattern
- Adds comprehensive validation of configuration options
- Improves documentation with clear examples and better structure
- Updates all test classes to use the new builder pattern
- Adds comprehensive builder tests
- Updated reference documentation
The builder pattern provides a more maintainable and user-friendly way to
configure vector stores while ensuring configuration validity at compile time.
This aligns with the project's move towards using builder patterns across all
vector store implementations.
Introduces a builder pattern for configuring TypesenseVectorStore instances and
moves the implementation to the org.springframework.ai.vectorstore.typesense
package. This change:
- Makes configuration more flexible and type-safe through builder methods
- Improves code organization by moving to a dedicated vector store package
- Deprecates old constructors in favor of the builder pattern
- Adds comprehensive validation of configuration options
- Enhances documentation with clear usage examples
- Adds dedicated builder test class for better test coverage
- Add builder tests
- update reference docs
The builder pattern simplifies TypesenseVectorStore configuration while ensuring
proper validation of all settings. The package move aligns with Spring AI's
architectural patterns and improves maintainability by grouping related classes
together.
review
Introduces a builder pattern for configuring WeaviateVectorStore instances and
moves the implementation to the org.springframework.ai.vectorstore.weaviate
package. This change:
- Makes configuration more flexible and type-safe through builder methods
- Improves code organization by moving to a dedicated vector store package
- Deprecates old constructors in favor of the builder pattern
- Adds builder tests
- Enables better IDE support through method chaining
Introduces a builder pattern for configuring CassandraVectorStore instances and
moves the implementation to the org.springframework.ai.vectorstore.cassandra
package. This change:
- Makes configuration more flexible and type-safe through builder methods
- Improves code organization by moving to a dedicated vector store package
- Deprecates old constructors in favor of the builder pattern
- Adds comprehensive validation of configuration options
- Enables better IDE support through method chaining
- The builder pattern provides a more maintainable and user-friendly way to
configure vector stores while ensuring configuration validity at compile time.
Add builder pattern to OpenSearchVectorStore
Introduces a builder pattern for OpenSearchVectorStore configuration and
refactors the package structure to org.springframework.ai.vectorstore.opensearch
for better organization and consistency with other vector stores.
The builder pattern improves usability by:
* Providing a fluent API for configuring store instances
* Making configuration options more discoverable through method names
* Enabling better validation of configuration parameters
* Supporting optional parameters with sensible defaults
* The package refactoring aligns with the project's standard package naming
conventions and improves code organization. All constructors are deprecated
in favor of the new builder pattern to guide users toward the preferred
configuration approach.
Refactors RedisVectorStore to use the builder pattern for improved
configuration and usability. The changes include:
* Move classes to org.springframework.ai.vectorstore.redis package
* Add RedisBuilder with comprehensive configuration options
* Deprecate RedisVectorStoreConfig in favor of builder pattern
* Enhance documentation with detailed usage examples
* Improve error handling and parameter validation
This change makes RedisVectorStore configuration more intuitive and
consistent with other vector stores in the project.
The Neo4j vector store implementation has been enhanced with a builder
pattern to be more intuitive than using ctors and follows spring ai builder
conventions. Current constructors have been deprecated to maintain
backward compatibility for one releaes cycle.
The change includes:
* Move classes to dedicated neo4j package for better organization
* Add comprehensive builder pattern implementation with validation
* Improve documentation with detailed usage examples
* Deprecate but maintain old configuration approach for compatibility
* Update integration tests to demonstrate new builder pattern
* Enhance code readability and maintainability
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
