Docs

Signed-off-by: Gerrit Meier <[email protected]>

Author: meistermeier

src/main/antora/modules/ROOT/nav.adoc

@@ -26,6 +26,7 @@
 ** xref:repositories/sdn-extension.adoc[]
 ** xref:repositories/query-keywords-reference.adoc[]
 ** xref:repositories/query-return-types-reference.adoc[]
+** xref:repositories/vector-search.adoc[]
 
 * xref:repositories/projections.adoc[]
 ** xref:projections/sdn-projections.adoc[]

src/main/antora/modules/ROOT/pages/repositories/vector-search.adoc

@@ -0,0 +1,30 @@
+[[sdn-vector-search]]
+= Neo4j Vector Search
+
+== The `@VectorSearch` annotation
+Spring Data Neo4j supports Neo4j's vector search on the repository level by using the `@VectorSearch` annotation.
+For this to work, Neo4j needs to have a vector index in place.
+How to create a vector index is explained in the https://neo4j.com/docs/cypher-manual/current/indexes/search-performance-indexes/managing-indexes/[Neo4j documentation].
+
+NOTE: It's not required to have any (Spring Data) Vector typed property be defined in the domain entities for this to work
+because the search operates exclusively on the index.
+
+The `@VectorSearch` annotation requires two arguments:
+The name of the vector index to be used and the number of nearest neighbours.
+
+For a general vector search over the whole domain, it's possible to use a derived finder method without any property.
+[source,java,indent=0,tabsize=4]
+----
+include::example$integration/imperative/VectorSearchIT.java[tags=sdn-vector-search.usage;sdn-vector-search.usage.findall]
+----
+
+The vector index can be combined with any property-based finder method to filter down the results.
+
+NOTE: For technical reasons, the vector search will always be executed before the property search gets invoked.
+E.g. if the property filter looks for a person named "Helge",
+but the vector search only yields "Hannes", there won't be a result.
+
+[source,java,indent=0,tabsize=4]
+----
+include::example$integration/imperative/VectorSearchIT.java[tags=sdn-vector-search.usage;sdn-vector-search.usage.findbyproperty]
+----

src/main/java/org/springframework/data/neo4j/repository/query/VectorSearch.java

@@ -29,7 +29,6 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
 @Documented
-// @Query
 public @interface VectorSearch {
 
 	String indexName();

src/test/java/org/springframework/data/neo4j/integration/imperative/VectorSearchIT.java

@@ -60,7 +60,7 @@ void setupData(@Autowired BookmarkCapture bookmarkCapture, @Autowired Driver dri
 		try (Session session = driver.session(bookmarkCapture.createSessionConfig())) {
 			session.run("MATCH (n) detach delete n");
 			session.run("""
-					CREATE VECTOR INDEX dingsIndex IF NOT EXISTS
+					CREATE VECTOR INDEX entityIndex IF NOT EXISTS
 					FOR (m:EntityWithVector)
 					ON m.myVector
 					OPTIONS { indexConfig: {
@@ -81,7 +81,7 @@ void setupData(@Autowired BookmarkCapture bookmarkCapture, @Autowired Driver dri
 	@AfterEach
 	void removeIndex(@Autowired BookmarkCapture bookmarkCapture, @Autowired Driver driver) {
 		try (Session session = driver.session(bookmarkCapture.createSessionConfig())) {
-			session.run("DROP INDEX `dingsIndex` IF EXISTS");
+			session.run("DROP INDEX `entityIndex` IF EXISTS");
 		}
 	}
 
@@ -128,24 +128,33 @@ void dontFindByNameWithVectorIndexAndScore(@Autowired VectorSearchRepository rep
 		assertThat(result).hasSize(0);
 	}
 
+	// tag::sdn-vector-search.usage[]
 	interface VectorSearchRepository extends Neo4jRepository<EntityWithVector, String> {
 
-		@VectorSearch(indexName = "dingsIndex", numberOfNodes = 2)
+		// end::sdn-vector-search.usage[]
+		// tag::sdn-vector-search.usage.findall[]
+		@VectorSearch(indexName = "entityIndex", numberOfNodes = 2)
 		List<EntityWithVector> findBy(String name, Vector searchVector);
+		// end::sdn-vector-search.usage.findall[]
 
-		@VectorSearch(indexName = "dingsIndex", numberOfNodes = 1)
+		// tag::sdn-vector-search.usage.findbyproperty[]
+		@VectorSearch(indexName = "entityIndex", numberOfNodes = 1)
 		List<EntityWithVector> findByName(String name, Vector searchVector);
+		// end::sdn-vector-search.usage.findbyproperty[]
 
-		@VectorSearch(indexName = "dingsIndex", numberOfNodes = 2)
+		@VectorSearch(indexName = "entityIndex", numberOfNodes = 2)
 		List<EntityWithVector> findByName(String name, Vector searchVector, Score score);
 
-		@VectorSearch(indexName = "dingsIndex", numberOfNodes = 2)
+		@VectorSearch(indexName = "entityIndex", numberOfNodes = 2)
 		SearchResults<EntityWithVector> findAllBy(Vector searchVector);
 
-		@VectorSearch(indexName = "dingsIndex", numberOfNodes = 2)
+		@VectorSearch(indexName = "entityIndex", numberOfNodes = 2)
 		SearchResult<EntityWithVector> findBy(Vector searchVector, Score score);
 
+		// tag::sdn-vector-search.usage[]
+
 	}
+	// end::sdn-vector-search.usage[]
 
 	@Configuration
 	@EnableTransactionManagement