Polish S3 vector store filter deletion

Add tests for NOT, ISNULL, and ISNOTNULL filter expressions and the
null-metadata vector case in S3VectorStoreTests.

Fix incorrect filter format example in the S3 Vector Store reference
documentation and add a section documenting filter-based deletion.

Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>

Author: sobychacko

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

@@ -122,13 +122,37 @@ For example, this portable filter expression:
 country in ['UK', 'NL'] && year >= 2020
 ----
 
-is converted into the proprietary S3 Vector Store filter format:
+is converted into the S3 Vector Store filter format:
 
-[source,text]
+[source,json]
 ----
-@country:{UK | NL} @year:[2020 inf]
+{"$and": [{"country": {"$in": ["UK", "NL"]}}, {"year": {"$gte": 2020}}]}
 ----
 
+=== Filter-based Deletion
+
+You can also delete documents by filter expression:
+
+[source,java]
+----
+vectorStore.delete("country in ['UK', 'NL'] && year >= 2020");
+----
+
+or programmatically:
+
+[source,java]
+----
+FilterExpressionBuilder b = new FilterExpressionBuilder();
+
+vectorStore.delete(b.and(
+        b.in("country", "UK", "NL"),
+        b.gte("year", 2020)).build());
+----
+
+NOTE: S3 Vectors does not provide a server-side filter-delete API.
+Filter-based deletion lists all vectors in the index (paginated, 500 per page) and evaluates the filter expression locally.
+For large indexes this operation is proportional to the total number of stored vectors.
+
 == Manual Configuration
 
 Instead of using the Spring Boot auto-configuration, you can manually configure the S3 Vector Store. For this you need to add the `spring-ai-s3-vector-store` to your project:

vector-stores/spring-ai-s3-vector-store/src/main/java/org/springframework/ai/vectorstore/s3/S3VectorStoreFilterExpressionEvaluator.java

@@ -116,7 +116,6 @@ private Object filterValue(Filter.Operand operand) {
 		throw new IllegalArgumentException("Expected a Value operand but got: " + operand.getClass().getName());
 	}
 
-	@SuppressWarnings("unchecked")
 	private int compare(@Nullable Object metaVal, @Nullable Object filterVal) {
 		if (metaVal == null && filterVal == null) {
 			return 0;
@@ -135,7 +134,9 @@ private int compare(@Nullable Object metaVal, @Nullable Object filterVal) {
 		}
 		if (metaVal instanceof Comparable comparable && filterVal instanceof Comparable) {
 			try {
-				return comparable.compareTo(filterVal);
+				@SuppressWarnings("unchecked")
+				int result = comparable.compareTo(filterVal);
+				return result;
 			}
 			catch (ClassCastException ex) {
 				throw new IllegalArgumentException("Cannot compare values of incompatible types %s and %s"

vector-stores/spring-ai-s3-vector-store/src/test/java/S3VectorStoreTests.java

@@ -153,6 +153,62 @@ void filterDeleteSkipsDeleteWhenNoVectorsMatch() {
 		verify(s3VectorsClient, never()).queryVectors(any(QueryVectorsRequest.class));
 	}
 
+	@Test
+	void filterDeleteHandlesNotExpression() {
+		S3VectorsClient s3VectorsClient = mock(S3VectorsClient.class);
+		FilterExpressionBuilder b = new FilterExpressionBuilder();
+		when(s3VectorsClient.listVectors(any(ListVectorsRequest.class))).thenReturn(ListVectorsResponse.builder()
+			.vectors(vector("chunk-1", Map.of("fileId", "file-1")), vector("chunk-2", Map.of("fileId", "file-2")),
+					vector("chunk-3", Map.of("fileId", "file-1")))
+			.build());
+
+		S3VectorStore vectorStore = vectorStore(s3VectorsClient);
+
+		vectorStore.delete(b.not(b.eq("fileId", "file-2")).build());
+
+		ArgumentCaptor<DeleteVectorsRequest> deleteRequestCaptor = ArgumentCaptor.forClass(DeleteVectorsRequest.class);
+		verify(s3VectorsClient).deleteVectors(deleteRequestCaptor.capture());
+		assertThat(deleteRequestCaptor.getValue().keys()).containsExactly("chunk-1", "chunk-3");
+	}
+
+	@Test
+	void filterDeleteHandlesIsNullExpression() {
+		S3VectorsClient s3VectorsClient = mock(S3VectorsClient.class);
+		FilterExpressionBuilder b = new FilterExpressionBuilder();
+		when(s3VectorsClient.listVectors(any(ListVectorsRequest.class))).thenReturn(ListVectorsResponse.builder()
+			.vectors(vector("chunk-1", Map.of("fileId", "file-1")), vectorWithNullMetadata("chunk-2"),
+					vector("chunk-3", Map.of("tag", "x")))
+			.build());
+
+		S3VectorStore vectorStore = vectorStore(s3VectorsClient);
+
+		// Expect: chunk-2 (null metadata map) and chunk-3 (fileId key absent) both match
+		vectorStore.delete(b.isNull("fileId").build());
+
+		ArgumentCaptor<DeleteVectorsRequest> deleteRequestCaptor = ArgumentCaptor.forClass(DeleteVectorsRequest.class);
+		verify(s3VectorsClient).deleteVectors(deleteRequestCaptor.capture());
+		assertThat(deleteRequestCaptor.getValue().keys()).containsExactly("chunk-2", "chunk-3");
+	}
+
+	@Test
+	void filterDeleteHandlesIsNotNullExpression() {
+		S3VectorsClient s3VectorsClient = mock(S3VectorsClient.class);
+		FilterExpressionBuilder b = new FilterExpressionBuilder();
+		when(s3VectorsClient.listVectors(any(ListVectorsRequest.class))).thenReturn(ListVectorsResponse.builder()
+			.vectors(vector("chunk-1", Map.of("fileId", "file-1")), vectorWithNullMetadata("chunk-2"),
+					vector("chunk-3", Map.of("tag", "x")))
+			.build());
+
+		S3VectorStore vectorStore = vectorStore(s3VectorsClient);
+
+		// Expect: only chunk-1 has a non-null fileId value
+		vectorStore.delete(b.isNotNull("fileId").build());
+
+		ArgumentCaptor<DeleteVectorsRequest> deleteRequestCaptor = ArgumentCaptor.forClass(DeleteVectorsRequest.class);
+		verify(s3VectorsClient).deleteVectors(deleteRequestCaptor.capture());
+		assertThat(deleteRequestCaptor.getValue().keys()).containsExactly("chunk-1");
+	}
+
 	private static S3VectorStore vectorStore(S3VectorsClient s3VectorsClient) {
 		return new S3VectorStore.Builder(s3VectorsClient, mock(EmbeddingModel.class))
 			.vectorBucketName("test-vector-bucket")
@@ -164,6 +220,10 @@ private static ListOutputVector vector(String key, Map<String, Object> metadata)
 		return ListOutputVector.builder().key(key).metadata(metadata(metadata)).build();
 	}
 
+	private static ListOutputVector vectorWithNullMetadata(String key) {
+		return ListOutputVector.builder().key(key).build();
+	}
+
 	private static Document metadata(Map<String, Object> metadata) {
 		Map<String, Document> values = new LinkedHashMap<>(metadata.size());
 		metadata.forEach((key, value) -> values.put(key, DocumentUtils.toDocument(value)));