Add getNativeClient API to VectorStore interface

Adds getNativeClient API to VectorStore interface allowing access to the underlying native client implementation.

This change:
- Adds getNativeClient() default method to VectorStore interface returning Optional<T>
- Implements getNativeClient() in all vector store implementations exposing their respective native clients
- Adds integration tests verifying native client access for all implementations

Fixes: #2137

Signed-off-by: Soby Chacko <[email protected]>

Author: sobychacko

spring-ai-core/src/main/java/org/springframework/ai/vectorstore/VectorStore.java

@@ -108,6 +108,24 @@ default List<Document> similaritySearch(String query) {
 		return this.similaritySearch(SearchRequest.builder().query(query).build());
 	}
 
+	/**
+	 * Returns the native client if available in this vector store implementation.
+	 *
+	 * Note on usage: 1. Returns empty Optional when no native client is available 2. Due
+	 * to Java type erasure, runtime type checking is not possible
+	 *
+	 * Example usage: When working with implementation with known native client:
+	 * Optional<NativeClientType> client = vectorStore.getNativeClient();
+	 *
+	 * Note: Using Optional<?> will return the native client if one exists, rather than an
+	 * empty Optional. For type safety, prefer using the specific client type.
+	 * @return Optional containing native client if available, empty Optional otherwise
+	 * @param <T> The type of the native client
+	 */
+	default <T> Optional<T> getNativeClient() {
+		return Optional.empty();
+	}
+
 	/**
 	 * Builder interface for creating VectorStore instances. Implements a fluent builder
 	 * pattern for configuring observation-related settings.

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs.adoc

@@ -44,6 +44,10 @@ public interface VectorStore extends DocumentWriter {
     List<Document> similaritySearch(String query);
 
     List<Document> similaritySearch(SearchRequest request);
+
+    default <T> Optional<T> getNativeClient() {
+		return Optional.empty();
+	}
 }
 ```
 

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/apache-cassandra.adoc

@@ -319,3 +319,20 @@ nodetool import wikidata articles ${CASSANDRA_DATA}/data/wikidata/articles-*/
 * An alternative to `nodetool import` is to just restart Cassandra.
 * If there are any failures in the indexes they will be rebuilt automatically.
 ====
+
+== Accessing the Native Client
+
+The Cassandra Vector Store implementation provides access to the underlying native Cassandra client (`CqlSession`) through the `getNativeClient()` method:
+
+[source,java]
+----
+CassandraVectorStore vectorStore = context.getBean(CassandraVectorStore.class);
+Optional<CqlSession> nativeClient = vectorStore.getNativeClient();
+
+if (nativeClient.isPresent()) {
+    CqlSession session = nativeClient.get();
+    // Use the native client for Cassandra-specific operations
+}
+----
+
+The native client gives you access to Cassandra-specific features and operations that might not be exposed through the `VectorStore` interface.

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/azure-cosmos-db.adoc

@@ -205,3 +205,20 @@ Add the following dependency in your Maven project:
     <artifactId>spring-ai-azure-cosmos-db-store</artifactId>
 </dependency>
 ----
+
+== Accessing the Native Client
+
+The Azure Cosmos DB Vector Store implementation provides access to the underlying native Azure Cosmos DB client (`CosmosClient`) through the `getNativeClient()` method:
+
+[source,java]
+----
+CosmosDBVectorStore vectorStore = context.getBean(CosmosDBVectorStore.class);
+Optional<CosmosClient> nativeClient = vectorStore.getNativeClient();
+
+if (nativeClient.isPresent()) {
+    CosmosClient client = nativeClient.get();
+    // Use the native client for Azure Cosmos DB-specific operations
+}
+----
+
+The native client gives you access to Azure Cosmos DB-specific features and operations that might not be exposed through the `VectorStore` interface.

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/azure.adoc

@@ -226,3 +226,20 @@ is converted into the following Azure OData link:https://learn.microsoft.com/en-
 ----
 $filter search.in(meta_country, 'UK,NL', ',') and meta_year ge 2020
 ----
+
+== Accessing the Native Client
+
+The Azure Vector Store implementation provides access to the underlying native Azure Search client (`SearchClient`) through the `getNativeClient()` method:
+
+[source,java]
+----
+AzureVectorStore vectorStore = context.getBean(AzureVectorStore.class);
+Optional<SearchClient> nativeClient = vectorStore.getNativeClient();
+
+if (nativeClient.isPresent()) {
+    SearchClient client = nativeClient.get();
+    // Use the native client for Azure Search-specific operations
+}
+----
+
+The native client gives you access to Azure Search-specific features and operations that might not be exposed through the `VectorStore` interface.

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/coherence.adoc

@@ -0,0 +1,17 @@
+
+== Accessing the Native Client
+
+The Coherence Vector Store implementation provides access to the underlying native Coherence client (`Session`) through the `getNativeClient()` method:
+
+[source,java]
+----
+CoherenceVectorStore vectorStore = context.getBean(CoherenceVectorStore.class);
+Optional<Session> nativeClient = vectorStore.getNativeClient();
+
+if (nativeClient.isPresent()) {
+    Session session = nativeClient.get();
+    // Use the native client for Coherence-specific operations
+}
+----
+
+The native client gives you access to Coherence-specific features and operations that might not be exposed through the `VectorStore` interface.

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/elasticsearch.adoc

@@ -269,3 +269,20 @@ public EmbeddingModel embeddingModel() {
     return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("OPENAI_API_KEY")));
 }
 ----
+
+== Accessing the Native Client
+
+The Elasticsearch Vector Store implementation provides access to the underlying native Elasticsearch client (`ElasticsearchClient`) through the `getNativeClient()` method:
+
+[source,java]
+----
+ElasticsearchVectorStore vectorStore = context.getBean(ElasticsearchVectorStore.class);
+Optional<ElasticsearchClient> nativeClient = vectorStore.getNativeClient();
+
+if (nativeClient.isPresent()) {
+    ElasticsearchClient client = nativeClient.get();
+    // Use the native client for Elasticsearch-specific operations
+}
+----
+
+The native client gives you access to Elasticsearch-specific features and operations that might not be exposed through the `VectorStore` interface.

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/mariadb.adoc

@@ -204,3 +204,20 @@ vectorStore.similaritySearch(SearchRequest.builder()
 ----
 
 NOTE: These filter expressions are automatically converted into the equivalent MariaDB JSON path expressions.
+
+== Accessing the Native Client
+
+The MariaDB Vector Store implementation provides access to the underlying native JDBC client (`JdbcTemplate`) through the `getNativeClient()` method:
+
+[source,java]
+----
+MariaDBVectorStore vectorStore = context.getBean(MariaDBVectorStore.class);
+Optional<JdbcTemplate> nativeClient = vectorStore.getNativeClient();
+
+if (nativeClient.isPresent()) {
+    JdbcTemplate jdbc = nativeClient.get();
+    // Use the native client for MariaDB-specific operations
+}
+----
+
+The native client gives you access to MariaDB-specific features and operations that might not be exposed through the `VectorStore` interface.

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/milvus.adoc

@@ -229,3 +229,20 @@ If Docker complains about resources, then execute:
 ----
 docker system prune --all --force --volumes
 ----
+
+== Accessing the Native Client
+
+The Milvus Vector Store implementation provides access to the underlying native Milvus client (`MilvusServiceClient`) through the `getNativeClient()` method:
+
+[source,java]
+----
+MilvusVectorStore vectorStore = context.getBean(MilvusVectorStore.class);
+Optional<MilvusServiceClient> nativeClient = vectorStore.getNativeClient();
+
+if (nativeClient.isPresent()) {
+    MilvusServiceClient client = nativeClient.get();
+    // Use the native client for Milvus-specific operations
+}
+----
+
+The native client gives you access to Milvus-specific features and operations that might not be exposed through the `VectorStore` interface.

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/mongodb.adoc

@@ -228,3 +228,20 @@ To get started with Spring AI and MongoDB:
 
 * See the https://www.mongodb.com/docs/atlas/atlas-vector-search/ai-integrations/spring-ai/#std-label-spring-ai[Getting Started guide for Spring AI Integration].
 * For a comprehensive code example demonstrating Retrieval Augmented Generation (RAG) with Spring AI and MongoDB, refer to this https://www.mongodb.com/developer/languages/java/retrieval-augmented-generation-spring-ai/[detailed tutorial].
+
+== Accessing the Native Client
+
+The MongoDB Atlas Vector Store implementation provides access to the underlying native MongoDB client (`MongoClient`) through the `getNativeClient()` method:
+
+[source,java]
+----
+MongoDBAtlasVectorStore vectorStore = context.getBean(MongoDBAtlasVectorStore.class);
+Optional<MongoClient> nativeClient = vectorStore.getNativeClient();
+
+if (nativeClient.isPresent()) {
+    MongoClient client = nativeClient.get();
+    // Use the native client for MongoDB-specific operations
+}
+----
+
+The native client gives you access to MongoDB-specific features and operations that might not be exposed through the `VectorStore` interface.