Add filter-based deletion to VectorStore implementations

Add the ability to delete documents from vector stores using filter expressions.
This allows for more flexible document deletion based on metadata criteria
rather than just document IDs.

Key changes:
- Add delete(Filter.Expression) method to VectorStore interface
- Implement filter-based deletion in ChromaVectorStore using where clauses
- Implement filter-based deletion in ElasticsearchVectorStore using deleteByQuery
- Implement filter-based deletion in PgVectorStore using jsonpath filters
- Add integration tests for filter-based deletion across all implementations
- Add default implementation in AbstractObservationVectorStore

This extends the VectorStore API to support more sophisticated document
management capabilities while maintaining consistent behavior across
different backend implementations.

Author: sobychacko

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

@@ -24,6 +24,7 @@
 import org.springframework.ai.document.Document;
 import org.springframework.ai.document.DocumentWriter;
 import org.springframework.ai.embedding.BatchingStrategy;
+import org.springframework.ai.vectorstore.filter.Filter;
 import org.springframework.ai.vectorstore.observation.DefaultVectorStoreObservationConvention;
 import org.springframework.ai.vectorstore.observation.VectorStoreObservationConvention;
 import org.springframework.lang.Nullable;
@@ -62,6 +63,14 @@ default void accept(List<Document> documents) {
 	@Nullable
 	Optional<Boolean> delete(List<String> idList);
 
+	/**
+	 * Deletes documents from the vector store based on filter criteria.
+	 * @param filterExpression Filter expression to identify documents to delete
+	 * @return Returns true if the documents were successfully deleted
+	 */
+	@Nullable
+	Optional<Boolean> delete(Filter.Expression filterExpression);
+
 	/**
 	 * Retrieves documents by query embedding similarity and metadata filters to retrieve
 	 * exactly the number of nearest-neighbor results that match the request criteria.

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

@@ -18,6 +18,7 @@
 
 import java.util.List;
 import java.util.Optional;
+import java.util.stream.Collectors;
 
 import io.micrometer.observation.ObservationRegistry;
 
@@ -27,6 +28,7 @@
 import org.springframework.ai.vectorstore.AbstractVectorStoreBuilder;
 import org.springframework.ai.vectorstore.SearchRequest;
 import org.springframework.ai.vectorstore.VectorStore;
+import org.springframework.ai.vectorstore.filter.Filter;
 import org.springframework.lang.Nullable;
 
 /**
@@ -99,6 +101,19 @@ public Optional<Boolean> delete(List<String> deleteDocIds) {
 			.observe(() -> this.doDelete(deleteDocIds));
 	}
 
+	@Override
+	@Nullable
+	public Optional<Boolean> delete(Filter.Expression filterExpression) {
+		VectorStoreObservationContext observationContext = this
+				.createObservationContextBuilder(VectorStoreObservationContext.Operation.DELETE.value())
+				.build();
+
+		return VectorStoreObservationDocumentation.AI_VECTOR_STORE
+				.observation(this.customObservationConvention, DEFAULT_OBSERVATION_CONVENTION, () -> observationContext,
+						this.observationRegistry)
+				.observe(() -> this.doDelete(filterExpression));
+	}
+
 	@Override
 	@Nullable
 	public List<Document> similaritySearch(SearchRequest request) {
@@ -131,6 +146,18 @@ public List<Document> similaritySearch(SearchRequest request) {
 	 */
 	public abstract Optional<Boolean> doDelete(List<String> idList);
 
+	/**
+	 * Template method for concrete implementations to provide filter-based deletion logic.
+	 * @param filterExpression Filter expression to identify documents to delete
+	 * @return Returns true if the documents were successfully deleted
+	 */
+	@Nullable
+	protected Optional<Boolean> doDelete(Filter.Expression filterExpression) {
+		// this is temporary until we implement this method in all concrete vector stores, at which point
+		// this method will become an abstract method.
+		throw new UnsupportedOperationException();
+	}
+
 	/**
 	 * Perform the actual similarity search operation.
 	 * @param request the search request

vector-stores/spring-ai-chroma-store/src/main/java/org/springframework/ai/chroma/vectorstore/ChromaVectorStore.java

@@ -25,6 +25,8 @@
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.json.JsonMapper;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import org.springframework.ai.chroma.vectorstore.ChromaApi.AddEmbeddingsRequest;
 import org.springframework.ai.chroma.vectorstore.ChromaApi.DeleteEmbeddingsRequest;
@@ -40,6 +42,7 @@
 import org.springframework.ai.vectorstore.AbstractVectorStoreBuilder;
 import org.springframework.ai.vectorstore.SearchRequest;
 import org.springframework.ai.vectorstore.VectorStore;
+import org.springframework.ai.vectorstore.filter.Filter;
 import org.springframework.ai.vectorstore.filter.FilterExpressionConverter;
 import org.springframework.ai.vectorstore.observation.AbstractObservationVectorStore;
 import org.springframework.ai.vectorstore.observation.VectorStoreObservationContext;
@@ -81,6 +84,8 @@ public class ChromaVectorStore extends AbstractObservationVectorStore implements
 
 	private boolean initialized = false;
 
+	private static final Logger logger = LoggerFactory.getLogger(ChromaVectorStore.class);
+
 	/**
 	 * @param builder {@link VectorStore.Builder} for chroma vector store
 	 */
@@ -162,7 +167,31 @@ public Optional<Boolean> doDelete(@NonNull List<String> idList) {
 	}
 
 	@Override
-	public @NonNull List<Document> doSimilaritySearch(@NonNull SearchRequest request) {
+	protected Optional<Boolean> doDelete(Filter.Expression expression) {
+		Assert.notNull(expression, "Filter expression must not be null");
+
+		try {
+			ChromaFilterExpressionConverter converter = new ChromaFilterExpressionConverter();
+			String whereClauseStr = converter.convertExpression(expression);
+
+			Map<String, Object> whereClause = this.chromaApi.where(whereClauseStr);
+
+			logger.debug("Deleting with where clause: {}", whereClause);
+
+			DeleteEmbeddingsRequest deleteRequest = new DeleteEmbeddingsRequest(null, whereClause);
+			int status = this.chromaApi.deleteEmbeddings(this.collectionId, deleteRequest);
+
+			return Optional.of(status == 200);
+		}
+		catch (Exception e) {
+			logger.error("Failed to delete documents by filter: {}", e.getMessage(), e);
+			return Optional.of(false);
+		}
+	}
+
+	@Override
+	@NonNull
+	public List<Document> doSimilaritySearch(@NonNull SearchRequest request) {
 
 		String query = request.getQuery();
 		Assert.notNull(query, "Query string must not be null");

vector-stores/spring-ai-chroma-store/src/test/java/org/springframework/ai/chroma/vectorstore/ChromaVectorStoreIT.java

@@ -36,6 +36,7 @@
 import org.springframework.ai.openai.api.OpenAiApi;
 import org.springframework.ai.vectorstore.SearchRequest;
 import org.springframework.ai.vectorstore.VectorStore;
+import org.springframework.ai.vectorstore.filter.Filter;
 import org.springframework.boot.SpringBootConfiguration;
 import org.springframework.boot.test.context.runner.ApplicationContextRunner;
 import org.springframework.context.annotation.Bean;
@@ -169,6 +170,69 @@ public void addAndSearchWithFilters() {
 		});
 	}
 
+	@Test
+	public void deleteWithFilterExpression() {
+		this.contextRunner.run(context -> {
+			VectorStore vectorStore = context.getBean(VectorStore.class);
+
+			// Create test documents with different metadata
+			var bgDocument = new Document("The World is Big and Salvation Lurks Around the Corner",
+					Map.of("country", "Bulgaria"));
+			var nlDocument = new Document("The World is Big and Salvation Lurks Around the Corner",
+					Map.of("country", "Netherlands"));
+
+			// Add documents to the store
+			vectorStore.add(List.of(bgDocument, nlDocument));
+
+			// Wait for indexing
+			try {
+				Thread.sleep(1000);
+			}
+			catch (InterruptedException e) {
+				Thread.currentThread().interrupt();
+			}
+
+			// Verify initial state
+			var request = SearchRequest.builder().query("The World").topK(5).build();
+			List<Document> results = vectorStore.similaritySearch(request);
+			assertThat(results).hasSize(2);
+
+			// Delete document with country = Bulgaria
+			Filter.Expression filterExpression = new Filter.Expression(
+					Filter.ExpressionType.EQ,
+					new Filter.Key("country"),
+					new Filter.Value("Bulgaria")
+			);
+
+			Optional<Boolean> deleteResult = vectorStore.delete(filterExpression);
+			assertThat(deleteResult).isPresent().contains(true);
+
+			// Wait for deletion to be processed
+			try {
+				Thread.sleep(1000);
+			}
+			catch (InterruptedException e) {
+				Thread.currentThread().interrupt();
+			}
+
+			// Verify Bulgaria document was deleted
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+					.filterExpression("country == 'Bulgaria'")
+					.build());
+			assertThat(results).isEmpty();
+
+			// Verify Netherlands document still exists
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+					.filterExpression("country == 'Netherlands'")
+					.build());
+			assertThat(results).hasSize(1);
+			assertThat(results.get(0).getMetadata().get("country")).isEqualTo("Netherlands");
+
+			// Clean up
+			vectorStore.delete(List.of(nlDocument.getId()));
+		});
+	}
+
 	@Test
 	public void documentUpdateTest() {
 

vector-stores/spring-ai-elasticsearch-store/src/main/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStore.java

@@ -26,6 +26,7 @@
 import co.elastic.clients.elasticsearch.ElasticsearchClient;
 import co.elastic.clients.elasticsearch.core.BulkRequest;
 import co.elastic.clients.elasticsearch.core.BulkResponse;
+import co.elastic.clients.elasticsearch.core.DeleteByQueryResponse;
 import co.elastic.clients.elasticsearch.core.SearchResponse;
 import co.elastic.clients.elasticsearch.core.bulk.BulkResponseItem;
 import co.elastic.clients.elasticsearch.core.search.Hit;
@@ -221,6 +222,32 @@ public Optional<Boolean> doDelete(List<String> idList) {
 		return Optional.of(bulkRequest(bulkRequestBuilder.build()).errors());
 	}
 
+	@Override
+	public Optional<Boolean> doDelete(Filter.Expression filterExpression) {
+		// For the index to be present, either it must be pre-created or set the
+		// initializeSchema to true.
+		if (!indexExists()) {
+			throw new IllegalArgumentException("Index not found");
+		}
+
+		try {
+			DeleteByQueryResponse response = this.elasticsearchClient.deleteByQuery(d -> d
+					.index(this.options.getIndexName())
+					.query(q -> q
+							.queryString(qs -> qs
+									.query(getElasticsearchQueryString(filterExpression))
+							)
+					)
+			);
+
+			// Return true if any documents were deleted
+			return Optional.of(!response.deleted().equals(0L));
+		}
+		catch (IOException e) {
+			throw new RuntimeException(e);
+		}
+	}
+
 	private BulkResponse bulkRequest(BulkRequest bulkRequest) {
 		try {
 			return this.elasticsearchClient.bulk(bulkRequest);

vector-stores/spring-ai-elasticsearch-store/src/test/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStoreIT.java

@@ -24,6 +24,7 @@
 import java.util.Date;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.UUID;
 import java.util.concurrent.TimeUnit;
 
@@ -53,6 +54,11 @@
 import org.springframework.ai.openai.OpenAiEmbeddingModel;
 import org.springframework.ai.openai.api.OpenAiApi;
 import org.springframework.ai.vectorstore.SearchRequest;
+import org.springframework.ai.vectorstore.filter.Filter;
+import org.springframework.ai.vectorstore.filter.Filter.Expression;
+import org.springframework.ai.vectorstore.filter.Filter.ExpressionType;
+import org.springframework.ai.vectorstore.filter.Filter.Key;
+import org.springframework.ai.vectorstore.filter.Filter.Value;
 import org.springframework.boot.SpringBootConfiguration;
 import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
 import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
@@ -143,6 +149,66 @@ public void addAndDeleteDocumentsTest() {
 		});
 	}
 
+	@Test
+	public void deleteDocumentsByFilterExpressionTest() {
+		getContextRunner().run(context -> {
+			ElasticsearchVectorStore vectorStore = context.getBean("vectorStore_cosine",
+					ElasticsearchVectorStore.class);
+			ElasticsearchClient elasticsearchClient = context.getBean(ElasticsearchClient.class);
+
+			IndicesStats stats = elasticsearchClient.indices()
+					.stats(s -> s.index("spring-ai-document-index"))
+					.indices()
+					.get("spring-ai-document-index");
+
+			assertThat(stats.total().docs().count()).isEqualTo(0L);
+
+			// Add documents with metadata
+			List<Document> documents = List.of(
+					new Document("1", getText("classpath:/test/data/spring.ai.txt"), Map.of("meta1", "meta1")),
+					new Document("2", getText("classpath:/test/data/time.shelter.txt"), Map.of()),
+					new Document("3", getText("classpath:/test/data/great.depression.txt"), Map.of("meta2", "meta2"))
+			);
+
+			vectorStore.add(documents);
+			elasticsearchClient.indices().refresh();
+
+			stats = elasticsearchClient.indices()
+					.stats(s -> s.index("spring-ai-document-index"))
+					.indices()
+					.get("spring-ai-document-index");
+			assertThat(stats.total().docs().count()).isEqualTo(3L);
+
+			// Delete documents with meta1 using filter expression
+			Expression filterExpression = new Expression(
+					ExpressionType.EQ,
+					new Key("meta1"),
+					new Value("meta1")
+			);
+
+			Optional<Boolean> deleteResult = vectorStore.delete(filterExpression);
+			elasticsearchClient.indices().refresh();
+
+			assertThat(deleteResult).isPresent().contains(true);
+
+			stats = elasticsearchClient.indices()
+					.stats(s -> s.index("spring-ai-document-index"))
+					.indices()
+					.get("spring-ai-document-index");
+			assertThat(stats.total().docs().count()).isEqualTo(2L);
+
+			// Clean up remaining documents
+			vectorStore.delete(List.of("2", "3"));
+			elasticsearchClient.indices().refresh();
+
+			stats = elasticsearchClient.indices()
+					.stats(s -> s.index("spring-ai-document-index"))
+					.indices()
+					.get("spring-ai-document-index");
+			assertThat(stats.total().docs().count()).isEqualTo(0L);
+		});
+	}
+
 	@ParameterizedTest(name = "{0} : {displayName} ")
 	@ValueSource(strings = { "cosine", "l2_norm", "dot_product" })
 	public void addAndSearchTest(String similarityFunction) {

vector-stores/spring-ai-pgvector-store/src/main/java/org/springframework/ai/vectorstore/pgvector/PgVectorStore.java

@@ -45,6 +45,7 @@
 import org.springframework.ai.vectorstore.AbstractVectorStoreBuilder;
 import org.springframework.ai.vectorstore.SearchRequest;
 import org.springframework.ai.vectorstore.VectorStore;
+import org.springframework.ai.vectorstore.filter.Filter;
 import org.springframework.ai.vectorstore.filter.FilterExpressionConverter;
 import org.springframework.ai.vectorstore.observation.AbstractObservationVectorStore;
 import org.springframework.ai.vectorstore.observation.VectorStoreObservationContext;
@@ -315,6 +316,23 @@ public Optional<Boolean> doDelete(List<String> idList) {
 		return Optional.of(updateCount == idList.size());
 	}
 
+	@Override
+	protected Optional<Boolean> doDelete(Filter.Expression filterExpression) {
+		String nativeFilterExpression = this.filterExpressionConverter.convertExpression(filterExpression);
+
+		String sql = "DELETE FROM " +
+				getFullyQualifiedTableName() +
+				" WHERE metadata::jsonb @@ '" +
+				nativeFilterExpression +
+				"'::jsonpath";
+
+		// Execute the delete
+		int updateCount = this.jdbcTemplate.update(sql);
+
+		// Return true if any records were deleted
+		return Optional.of(updateCount > 0);
+	}
+
 	@Override
 	public List<Document> doSimilaritySearch(SearchRequest request) {