Refine Cassandra Vector Search documentation.

Add metadata prefiltering. Update documentation to reflect Cassandra specifics regarding sorting.

Closes #1608

Author: mp911de

spring-data-cassandra/src/test/java/org/springframework/data/cassandra/core/CassandraVectorSearchIntegrationTests.java

@@ -16,6 +16,7 @@
 package org.springframework.data.cassandra.core;
 
 import static org.assertj.core.api.Assertions.*;
+import static org.springframework.data.cassandra.core.query.Criteria.*;
 
 import java.util.List;
 import java.util.UUID;
@@ -86,16 +87,19 @@ void shouldQueryVector() {
 
 		Comments one = new Comments();
 		one.setId(UUID.randomUUID());
+		one.setLanguage("en");
 		one.setVector(Vector.of(0.45f, 0.09f, 0.01f, 0.2f, 0.11f));
 		one.setComment("Raining too hard should have postponed");
 
 		Comments two = new Comments();
 		two.setId(UUID.randomUUID());
+		two.setLanguage("en");
 		two.setVector(Vector.of(0.99f, 0.5f, 0.99f, 0.1f, 0.34f));
 		two.setComment("Second rest stop was out of water");
 
 		Comments three = new Comments();
 		three.setId(UUID.randomUUID());
+		three.setLanguage("en");
 		three.setVector(Vector.of(0.9f, 0.54f, 0.12f, 0.1f, 0.95f));
 		three.setComment("LATE RIDERS SHOULD NOT DELAY THE START");
 
@@ -107,7 +111,7 @@ void shouldQueryVector() {
 
 		Columns columns = Columns.empty().include("comment").select("vector",
 				it -> it.similarity(vector).cosine().as("similarity"));
-		Query query = Query.select(columns).limit(3).sort(VectorSort.ann("vector", vector));
+		Query query = Query.select(columns).and(where("language").is("en")).limit(3).sort(VectorSort.ann("vector", vector));
 
 		List<CommentSearch> result = template.query(Comments.class).as(CommentSearch.class).matching(query).all();
 
@@ -134,6 +138,7 @@ static class Comments {
 
 		@Id UUID id;
 		String comment;
+		@SaiIndexed String language;
 
 		@VectorType(dimensions = 5)
 		@SaiIndexed Vector vector;
@@ -154,6 +159,14 @@ public void setComment(String comment) {
 			this.comment = comment;
 		}
 
+		public String getLanguage() {
+			return language;
+		}
+
+		public void setLanguage(String language) {
+			this.language = language;
+		}
+
 		public Vector getVector() {
 			return vector;
 		}

spring-data-cassandra/src/test/java/org/springframework/data/cassandra/repository/VectorSearchIntegrationTests.java

@@ -92,28 +92,28 @@ void setUp() {
 		repository.saveAll(List.of(w1, w2, w3, w4));
 	}
 
-	@Test // GH-
+	@Test // GH-1573
 	void searchWithoutScoringFunctionShouldFail() {
 		assertThatExceptionOfType(QueryCreationException.class)
 				.isThrownBy(() -> repository.searchByEmbeddingNear(VECTOR, Limit.of(100)));
 	}
 
-	@Test // GH-
+	@Test // GH-1573
 	void shouldConsiderScoringFunction() {
 
-		SearchResults<WithVectorFields> results = repository.searchByEmbeddingNear(VECTOR,
-				ScoringFunction.dotProduct(), Limit.of(100));
+		SearchResults<WithVectorFields> results = repository.searchByEmbeddingNearAndCountry(VECTOR,
+				ScoringFunction.dotProduct(), "de", Limit.of(100));
 
-		assertThat(results).hasSize(4);
+		assertThat(results).hasSize(3);
 
 		for (SearchResult<WithVectorFields> result : results) {
 			assertThat(result.getScore()).isInstanceOf(Similarity.class);
 			assertThat(result.getScore().getValue()).isNotCloseTo(0d, offset(0.1d));
 		}
 
-		results = repository.searchByEmbeddingNear(VECTOR, VectorScoringFunctions.EUCLIDEAN, Limit.of(100));
+		results = repository.searchByEmbeddingNearAndCountry(VECTOR, VectorScoringFunctions.EUCLIDEAN, "de", Limit.of(100));
 
-		assertThat(results).hasSize(4);
+		assertThat(results).hasSize(3);
 
 		for (SearchResult<WithVectorFields> result : results) {
 
@@ -122,19 +122,19 @@ void shouldConsiderScoringFunction() {
 		}
 	}
 
-	@Test // GH-
+	@Test // GH-1573
 	void shouldRunAnnotatedSearchByVector() {
 
-		SearchResults<WithVectorFields> results = repository.searchAnnotatedByEmbeddingNear(VECTOR, Limit.of(100));
+		SearchResults<WithVectorFields> results = repository.searchAnnotatedByEmbeddingNear(VECTOR, "de", Limit.of(100));
 
-		assertThat(results).hasSize(4);
+		assertThat(results).hasSize(3);
 		for (SearchResult<WithVectorFields> result : results) {
 			assertThat(result.getScore()).isInstanceOf(Similarity.class);
 			assertThat(result.getScore().getValue()).isNotCloseTo(0d, offset(0.1d));
 		}
 	}
 
-	@Test // GH-
+	@Test // GH-1573
 	void shouldFindByVector() {
 
 		List<WithVectorFields> result = repository.findByEmbeddingNear(VECTOR, Limit.of(100));
@@ -144,22 +144,29 @@ void shouldFindByVector() {
 
 	interface VectorSearchRepository extends CrudRepository<WithVectorFields, UUID> {
 
-		SearchResults<WithVectorFields> searchByEmbeddingNear(Vector embedding, ScoringFunction function, Limit limit);
+		SearchResults<WithVectorFields> searchByEmbeddingNearAndCountry(Vector embedding, ScoringFunction function,
+				String country, Limit limit);
 
 		SearchResults<WithVectorFields> searchByEmbeddingNear(Vector embedding, Limit limit);
 
 		List<WithVectorFields> findByEmbeddingNear(Vector embedding, Limit limit);
 
-		@Query("SELECT id,description,country,similarity_cosine(embedding,:embedding) AS score FROM withvectorfields ORDER BY embedding ANN OF :embedding LIMIT :limit")
-		SearchResults<WithVectorFields> searchAnnotatedByEmbeddingNear(Vector embedding, Limit limit);
+		@Query("""
+				SELECT id,description,country,similarity_cosine(embedding,:embedding) AS score
+				FROM withvectorfields
+				WHERE country = :country
+				ORDER BY embedding ANN OF :embedding
+				LIMIT :limit
+				""")
+		SearchResults<WithVectorFields> searchAnnotatedByEmbeddingNear(Vector embedding, String country, Limit limit);
 
 	}
 
 	@Table
 	static class WithVectorFields {
 
 		@Id String id;
-		String country;
+		@SaiIndexed String country;
 		String description;
 
 		@VectorType(dimensions = 5)

src/main/antora/modules/ROOT/partials/vector-search-method-annotated-include.adoc

@@ -7,9 +7,10 @@ interface CommentRepository extends Repository<Comment, String> {
   @Query("""
          SELECT id, description, country, similarity_cosine(embedding,:embedding) AS score
          FROM comments
+         WHERE country = :country
          ORDER BY embedding ANN OF :embedding LIMIT :limit
          """)
-  SearchResults<WithVectorFields> searchAnnotatedByEmbeddingNear(Vector embedding, Limit limit);
+  SearchResults<WithVectorFields> searchByEmbeddingNearAndCountry(Vector embedding, String country, Limit limit);
 }
 ----
 ====

src/main/antora/modules/ROOT/partials/vector-search-method-derived-include.adoc

@@ -6,7 +6,7 @@ interface CommentRepository extends Repository<Comment, String> {
 
   List<Comment> searchByEmbeddingNear(Vector vector);
 
-  SearchResults<Comment> searchByEmbeddingNear(Vector vector, ScoringFunction function);
+  SearchResults<Comment> searchByEmbeddingNearAndCountry(Vector vector, ScoringFunction function, String country);
 
 }
 ----

src/main/antora/modules/ROOT/partials/vector-search-model-include.adoc

@@ -4,6 +4,8 @@
 class Comment {
 
   @Id String id;
+
+  @SaiIndexed
   String country;
   String comment;
 

src/main/antora/modules/ROOT/partials/vector-search-repository-include.adoc

@@ -4,10 +4,10 @@
 ----
 interface CommentRepository extends Repository<Comment, String> {
 
-  SearchResults<Comment> searchByEmbeddingNear(Vector vector, ScoringFunction function, Limit limit);
+  SearchResults<Comment> searchByEmbeddingNearAndCountry(Vector vector, ScoringFunction function, String country, Limit limit);
 
 }
 
-SearchResults<Comment> results = repository.searchByEmbeddingNear(Vector.of(…), ScoringFunction.cosine(), Limit.of(10));
+SearchResults<Comment> results = repository.searchByEmbeddingNearAndCountry(Vector.of(…), ScoringFunction.cosine(), "…", Limit.of(10));
 ----
 ====

src/main/antora/modules/ROOT/partials/vector-search.adoc

@@ -60,7 +60,7 @@ ifdef::vector-search-repository-include[]
 include::{vector-search-repository-include}[]
 endif::[]
 
-In this example, the `searchByCountryAndEmbeddingNear` method returns a `SearchResults<Comment>` object, which contains a list of `SearchResult<Comment>` instances.
+In this example, the `searchByEmbeddingNearAndCountry` method returns a `SearchResults<Comment>` object, which contains a list of `SearchResult<Comment>` instances.
 Each result includes the matched `Comment` entity and its relevance score.
 
 Relevance score is a numerical value that indicates how closely the matched vector aligns with the query vector.
@@ -147,21 +147,5 @@ If an annotated query does not define e.g. the score, then the score value in th
 [[vector-search.method.sorting]]
 === Sorting
 
-By default, search results are ordered according to their score.
-You can override sorting by using the `Sort` parameter:
+Cassandra Vector search results are ordered according to their score through the `ORDER BY embedding ANN OF [vector]` clause.
 
-.Using `Sort` in Repository Search Methods
-====
-[source,java]
-----
-interface CommentRepository extends Repository<Comment, String> {
-
-  SearchResults<Comment> searchByEmbeddingNearOrderByCountry(Vector vector, Score score);
-
-  SearchResults<Comment> searchByEmbeddingWithin(Vector vector, Score score, Sort sort);
-}
-----
-====
-
-Please note that custom sorting does not allow expressing the score as a sorting criteria.
-You can only refer to domain properties.