Support filter expressions in Neo4j vector store.

 - Move Neo4j filter converters from core to neoj4 vector store project.
 - Update neo4j adoc.

 Resolves #318

Author: meistermeier

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

@@ -146,7 +146,7 @@ public class Embedding implements ModelResult<List<Double>> {
 }
 ----
 
-== Available Implementations
+== Available Implementations [[available-implementations]]
 
 Internally the various `EmbeddingClient` implementations use different low-level libraries and APIs to perform the embedding tasks. The following are some of the available implementations of the `EmbeddingClient` implementations:
 

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

@@ -2,77 +2,53 @@
 
 This section walks you through setting up `Neo4jVectorStore` to store document embeddings and perform similarity searches.
 
-== What is Neo4j?
+link:https://neo4j.com[Neo4j] is an open-source NoSQL graph database.
+It is a fully transactional database (ACID) that stores data structured as graphs consisting of nodes, connected by relationships.
+Inspired by the structure of the real world, it allows for high query performance on complex data while remaining intuitive and simple for the developer.
 
-link:https://neo4j.com[Neo4j] is an open-source NoSQL graph database. It is a fully transactional database (ACID) that stores data structured as graphs consisting of nodes, connected by relationships. Inspired by the structure of the real world, it allows for high query performance on complex data while remaining intuitive and simple for the developer.
+The link:https://neo4j.com/docs/cypher-manual/current/indexes-for-vector-search/[Neo4j's Vector Search] allows users to query vector embeddings from large datasets. An embedding is a numerical representation of a data object, such as text, image, audio, or document.
+Embeddings can be stored on _Node_ properties and can be queried with the `db.index.vector.queryNodes()` function.
+Those indexes are powered by Lucene using a Hierarchical Navigable Small World Graph (HNSW) to perform a k approximate nearest neighbors (k-ANN) query over the vector fields.
 
-== What is Neo4j Vector Search?
+== Prerequisites
 
-link:https://neo4j.com/docs/cypher-manual/current/indexes-for-vector-search/[Neo4j's Vector Search] got introduced in Neo4j 5.11 and was considered GA with the release of version 5.13. Embeddings can be stored on _Node_ properties and can be queried with the `db.index.vector.queryNodes()` function. Those indexes are powered by Lucene using a Hierarchical Navigable Small World Graph (HNSW) to perform a k approximate nearest neighbors (k-ANN) query over the vector fields.
-
-=== Prerequisites
-
-1. OpenAI Account: Create an account at link:https://platform.openai.com/signup[OpenAI Signup] and generate the token at link:https://platform.openai.com/account/api-keys[API Keys].
-
-2. A running Neo4j (5.13+) instance
-a. link:https://hub.docker.com/_/neo4j[Docker] image _neo4j:5.15_
-b. link:https://neo4j.com/download/[Neo4j Desktop]
-c. link:https://neo4j.com/cloud/aura-free/[Neo4j Aura]
-d. link:https://neo4j.com/deployment-center/[Neo4j Server] instance
+* You would need an xref:api/embeddings.adoc#available-implementations[EmbeddingClient] to generate the embeddings stored in the `Neo4jVectorStore`.
+* A running Neo4j (5.13+) instance. Following options are available:
+** link:https://hub.docker.com/_/neo4j[Docker] image `neo4j:5.16.0`
+** link:https://neo4j.com/download/[Neo4j Desktop]
+** link:https://neo4j.com/cloud/aura-free/[Neo4j Aura]
+** link:https://neo4j.com/deployment-center/[Neo4j Server] instance
 
 == Configuration
 
 To connect to Neo4j and use the `Neo4jVectorStore`, you need to provide (e.g. via environment variables) access details for your instance.
 
-Additionally, you will need to provide your OpenAI API Key. Set it as an environment variable like so:
-
-[source,bash]
-----
-export SPRING_AI_OPENAI_API_KEY='Your_OpenAI_API_Key'
-----
-
-== Repository
-
-To acquire Spring AI artifacts, declare the Spring Snapshot repository:
-
-[source,xml]
-----
-<repository>
-	<id>spring-snapshots</id>
-	<name>Spring Snapshots</name>
-	<url>https://repo.spring.io/snapshot</url>
-	<releases>
-		<enabled>false</enabled>
-	</releases>
-</repository>
-----
+TIP: Additionally, you will need a configured xref:api/embeddings.adoc#available-implementations[EmbeddingClient].
 
 == Dependencies
 
-Add these dependencies to your project:
-
-* OpenAI: Required for calculating embeddings.
+Add the Neo4j Vector Store dependency to your project:
 
 [source,xml]
 ----
 <dependency>
 	<groupId>org.springframework.ai</groupId>
-	<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
+	<artifactId>spring-ai-neo4j-store</artifactId>
 	<version>0.8.0-SNAPSHOT</version>
 </dependency>
 ----
 
-* Neo4j Vector Store
+or to your Gradle `build.gradle` build file.
 
-[source,xml]
+[source,groovy]
 ----
-<dependency>
-	<groupId>org.springframework.ai</groupId>
-	<artifactId>spring-ai-neo4j-store</artifactId>
-	<version>0.8.0-SNAPSHOT</version>
-</dependency>
+dependencies {
+    implementation 'org.springframework.ai:spring-ai-neo4j-store:0.8.0-SNAPSHOT'
+}
 ----
 
+TIP: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file.
+
 == Sample Code
 
 To configure `Neo4jVectorStore` in your application, you can use the following setup:
@@ -92,18 +68,19 @@ You'll need a `VectorStore` to store the embeddings. You can use the `Neo4jVecto
 
 [source,java]
 ----
+@Bean
+public EmbeddingClient embeddingClient() {
+	// Can be any other EmbeddingClient implementation.
+    return new OpenAiEmbeddingClient(new OpenAiApi(System.getenv("SPRING_AI_OPENAI_API_KEY")));
+}
+
 @Bean
 public Driver driver() {
     return GraphDatabase.driver(System.getenv("SPRING_NEO4J_URI"),
             AuthTokens.basic(System.getenv("SPRING_NEO4J_AUTHENTICATION_USERNAME"),
                     System.getenv("SPRING_NEO4J_AUTHENTICATION_PASSWORD")));
 }
 
-@Bean
-public EmbeddingClient embeddingClient() {
-    return new OpenAiEmbeddingClient(new OpenAiApi(System.getenv("SPRING_AI_OPENAI_API_KEY")));
-}
-
 @Bean
 public VectorStore vectorStore(Driver driver, EmbeddingClient embeddingClient) {
     return new Neo4jVectorStore(driver, embeddingClient,
@@ -112,3 +89,77 @@ public VectorStore vectorStore(Driver driver, EmbeddingClient embeddingClient) {
 ----
 
 The `Neo4jVectorStore` is now ready to be used in your application. You can use it to store embeddings and perform similarity searches.
+
+== Metadata filtering
+
+You can leverage the generic, portable xref:api/vectordbs.adoc#metadata-filters[metadata filters] with Neo4j store as well.
+
+For example, you can use either the text expression language:
+
+[source,java]
+----
+vectorStore.similaritySearch(
+                    SearchRequest.defaults()
+                            .withQuery("The World")
+                            .withTopK(TOP_K)
+                            .withSimilarityThreshold(SIMILARITY_THRESHOLD)
+                            .withFilterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));
+----
+
+or programmatically using the `Filter.Expression` DSL:
+
+[source,java]
+----
+FilterExpressionBuilder b = new FilterExpressionBuilder();
+
+vectorStore.similaritySearch(SearchRequest.defaults()
+                    .withQuery("The World")
+                    .withTopK(TOP_K)
+                    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
+                    .withFilterExpression(b.and(
+                            b.in("john", "jill"),
+                            b.eq("article_type", "blog")).build()));
+----
+
+NOTE: Those (portable) filter expressions get automatically converted into the proprietary Neo4j `WHERE` link:https://neo4j.com/developer/cypher/filtering-query-results/[filter expressions].
+
+For example, this portable filter expression:
+
+```sql
+author in ['john', 'jill'] && 'article_type' == 'blog'
+```
+
+is converted into the proprietary Neo4j filter format:
+
+```
+node.`metadata.author` IN ["john","jill"] AND node.`metadata.'article_type'` = "blog"
+```
+
+== Auto-configuration
+
+Spring AI provides Spring Boot auto-configuration for the Neo4j Vector Sore.
+To enable it add the following dependency to your project's Maven `pom.xml` file:
+
+[source, xml]
+----
+<dependency>
+    <groupId>org.springframework.ai</groupId>
+    <artifactId>spring-ai-neo4j-store-spring-boot-starter</artifactId>
+    <version>0.8.0-SNAPSHOT</version>
+</dependency>
+----
+
+or to your Gradle `build.gradle` build file.
+
+[source,groovy]
+----
+dependencies {
+    implementation 'org.springframework.ai:spring-ai-neo4j-store-spring-boot-starter:0.8.0-SNAPSHOT'
+}
+----
+
+TIP: Additionally, you will need a configured `EmbeddingClient` bean. Refer to the xref:api/embeddings.adoc#available-implementations[EmbeddingClient] section for more information.
+
+TIP: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file.
+
+Now you can auto-wire the `Neo4jVectorStore` as a vector store in your application.

spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/neo4j/Neo4jVectorStoreProperties.java

@@ -40,39 +40,39 @@ public class Neo4jVectorStoreProperties {
 	private String indexName = Neo4jVectorStore.DEFAULT_INDEX_NAME;
 
 	public String getDatabaseName() {
-		return databaseName;
+		return this.databaseName;
 	}
 
 	public void setDatabaseName(String databaseName) {
 		this.databaseName = databaseName;
 	}
 
 	public int getEmbeddingDimension() {
-		return embeddingDimension;
+		return this.embeddingDimension;
 	}
 
 	public void setEmbeddingDimension(int embeddingDimension) {
 		this.embeddingDimension = embeddingDimension;
 	}
 
 	public Neo4jVectorStore.Neo4jDistanceType getDistanceType() {
-		return distanceType;
+		return this.distanceType;
 	}
 
 	public void setDistanceType(Neo4jVectorStore.Neo4jDistanceType distanceType) {
 		this.distanceType = distanceType;
 	}
 
 	public String getLabel() {
-		return label;
+		return this.label;
 	}
 
 	public void setLabel(String label) {
 		this.label = label;
 	}
 
 	public String getEmbeddingProperty() {
-		return embeddingProperty;
+		return this.embeddingProperty;
 	}
 
 	public void setEmbeddingProperty(String embeddingProperty) {

vector-stores/spring-ai-neo4j-store/src/main/java/org/springframework/ai/vectorstore/Neo4jVectorStore.java

@@ -22,6 +22,7 @@
 import org.neo4j.driver.Values;
 import org.springframework.ai.document.Document;
 import org.springframework.ai.embedding.EmbeddingClient;
+import org.springframework.ai.vectorstore.filter.Neo4jVectorFilterExpressionConverter;
 import org.springframework.beans.factory.InitializingBean;
 import org.springframework.util.Assert;
 
@@ -222,6 +223,8 @@ public Neo4jVectorStoreConfig build() {
 
 	public static final String DEFAULT_EMBEDDING_PROPERTY = "embedding";
 
+	private final Neo4jVectorFilterExpressionConverter filterExpressionConverter = new Neo4jVectorFilterExpressionConverter();
+
 	private final Driver driver;
 
 	private final EmbeddingClient embeddingClient;
@@ -277,24 +280,25 @@ public Optional<Boolean> delete(List<String> idList) {
 
 	@Override
 	public List<Document> similaritySearch(SearchRequest request) {
-		if (request.getFilterExpression() != null) {
-			throw new UnsupportedOperationException(
-					"The [" + this.getClass() + "] doesn't support metadata filtering!");
-		}
-
 		Assert.isTrue(request.getTopK() > 0, "The number of documents to returned must be greater than zero");
 		Assert.isTrue(request.getSimilarityThreshold() >= 0 && request.getSimilarityThreshold() <= 1,
 				"The similarity score is bounded between 0 and 1; least to most similar respectively.");
 
 		var embedding = Values.value(toFloatArray(this.embeddingClient.embed(request.getQuery())));
 		try (var session = this.driver.session(this.config.sessionConfig)) {
+			StringBuilder condition = new StringBuilder("score >= $threshold");
+			if (request.hasFilterExpression()) {
+				condition.append(" AND ")
+					.append(this.filterExpressionConverter.convertExpression(request.getFilterExpression()));
+			}
+			String query = """
+					CALL db.index.vector.queryNodes($indexName, $numberOfNearestNeighbours, $embeddingValue)
+					YIELD node, score
+					WHERE %s
+					RETURN node, score""".formatted(condition);
+
 			return session
-				.run("""
-						CALL db.index.vector.queryNodes($indexName, $numberOfNearestNeighbours, $embeddingValue)
-						YIELD node, score
-						WHERE score >= $threshold
-						RETURN node, score
-						""",
+				.run(query,
 						Map.of("indexName", this.config.indexName, "numberOfNearestNeighbours", request.getTopK(),
 								"embeddingValue", embedding, "threshold", request.getSimilarityThreshold()))
 				.list(Neo4jVectorStore::recordToDocument);