Vector store FilterExpressionConverter fix and enhancements

  Changes doSingleValue() from concrete to abstract method, forcing explicit handling in all implementations.

  BREAKING CHANGE: Custom FilterExpressionConverter implementations must
  now implement doSingleValue() and use appropriate helpers.

Signed-off-by: Ilayaperumal Gopinathan <ilayaperumal.gopinathan@broadcom.com>

Author: ilayaperumalg

.gitignore

@@ -25,7 +25,6 @@ build
 .gradle
 out
 *~
-
 /.gradletasknamecache
 **/*.flattened-pom.xml
 

spring-ai-docs/src/main/antora/modules/ROOT/pages/upgrade-notes.adoc

@@ -441,6 +441,25 @@ If you're using the OpenSearch vector store through Spring AI's `VectorStore` in
 
 Spring AI's internal implementation has been updated to handle these changes automatically.
 
+=== AbstractFilterExpressionConverter: doSingleValue is now abstract
+
+In `AbstractFilterExpressionConverter` (used by vector store filter expression converters), the method `doSingleValue(Object value, StringBuilder context)` has been changed from a concrete method to an abstract method. Custom vector store implementations that extend `AbstractFilterExpressionConverter` must now implement this method explicitly.
+
+==== Impact
+
+* Any custom `FilterExpressionConverter` that extends `AbstractFilterExpressionConverter` and did not override `doSingleValue()` will fail to compile.
+* Implementations must convert a single filter value (String, Number, Boolean, Date, etc.) into the target format and append it to the provided `StringBuilder` context.
+
+==== Migration
+
+Implement `doSingleValue(Object value, StringBuilder context)` in your custom converter. You can use the provided static helper methods:
+
+* **JSON-based filters** (e.g. PostgreSQL JSONPath, Neo4j Cypher, Weaviate): use `emitJsonValue(Object value, StringBuilder context)` to serialize values with proper quoting and escaping.
+* **Lucene-based filters** (e.g. Elasticsearch, OpenSearch, GemFire): use `emitLuceneString(String value, StringBuilder context)` for string values, and handle other types (numbers, booleans, dates) according to your store's query syntax.
+* **Other formats**: implement your own logic and append the result to `context`.
+
+NOTE: The framework normalizes values (e.g. ISO date strings converted to `Date`) before invoking `doSingleValue`, so your implementation receives already-normalized values. The static helper `normalizeDateString(Object)` is available if you need the same normalization when building expressions outside of the standard flow.
+
 
 [[run-all-m3-migrations]]
 === Running All M3 Migrations at Once

spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/filter/converter/AbstractFilterExpressionConverter.java

@@ -16,7 +16,16 @@
 
 package org.springframework.ai.vectorstore.filter.converter;
 
+import java.time.Instant;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.Date;
 import java.util.List;
+import java.util.regex.Pattern;
+
+import tools.jackson.core.JacksonException;
+import tools.jackson.databind.ObjectMapper;
 
 import org.springframework.ai.vectorstore.filter.Filter;
 import org.springframework.ai.vectorstore.filter.Filter.Expression;
@@ -37,6 +46,25 @@
  */
 public abstract class AbstractFilterExpressionConverter implements FilterExpressionConverter {
 
+	/**
+	 * ObjectMapper used for JSON string escaping.
+	 */
+	private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
+	/**
+	 * Pattern for ISO-8601 date strings in UTC (yyyy-MM-dd'T'HH:mm:ss'Z') used to
+	 * recognize and normalize date strings before passing to converters.
+	 */
+	protected static final Pattern ISO_DATE_PATTERN = Pattern
+		.compile("\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z");
+
+	/**
+	 * Formatter for parsing and normalizing ISO date strings.
+	 */
+	protected static final DateTimeFormatter ISO_DATE_FORMATTER = DateTimeFormatter
+		.ofPattern("yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'")
+		.withZone(ZoneOffset.UTC);
+
 	/**
 	 * Create a new AbstractFilterExpressionConverter.
 	 */
@@ -127,29 +155,124 @@ protected void doValue(Filter.Value filterValue, StringBuilder context) {
 			doStartValueRange(filterValue, context);
 			int c = 0;
 			for (Object v : list) {
-				this.doSingleValue(v, context);
+				this.doSingleValue(normalizeDateString(v), context);
 				if (c++ < list.size() - 1) {
 					this.doAddValueRangeSpitter(filterValue, context);
 				}
 			}
 			this.doEndValueRange(filterValue, context);
 		}
 		else {
-			this.doSingleValue(filterValue.value(), context);
+			this.doSingleValue(normalizeDateString(filterValue.value()), context);
 		}
 	}
 
 	/**
-	 * Convert the given value into a string representation.
+	 * If the value is a string matching the ISO date pattern, parse and return as
+	 * {@link Date} so that all converters that handle {@code Date} automatically support
+	 * date strings. Otherwise return the value unchanged.
+	 * @param value the value (possibly a date string)
+	 * @return the value, or a {@code Date} if the value was a parseable date string
+	 */
+	protected static Object normalizeDateString(Object value) {
+		if (!(value instanceof String text) || !ISO_DATE_PATTERN.matcher(text).matches()) {
+			return value;
+		}
+		try {
+			return Date.from(Instant.from(ISO_DATE_FORMATTER.parse(text)));
+		}
+		catch (DateTimeParseException e) {
+			throw new IllegalArgumentException("Invalid date type: " + text, e);
+		}
+	}
+
+	/**
+	 * Convert the given single value into a string representation and append it to the
+	 * context. This method handles all value types including String, Number, Boolean,
+	 * Date, etc.
+	 * <p>
+	 * For convenience, implementations can use the provided static helper methods such as
+	 * {@link #emitJsonValue(Object, StringBuilder)} for JSON-based filters,
+	 * {@link #emitLuceneString(String, StringBuilder)} for Lucene-based filters, or
+	 * implement their own format-specific escaping logic as needed.
 	 * @param value the value to convert
 	 * @param context the context to append the string representation to
 	 */
-	protected void doSingleValue(Object value, StringBuilder context) {
-		if (value instanceof String) {
-			context.append(String.format("\"%s\"", value));
+	protected abstract void doSingleValue(Object value, StringBuilder context);
+
+	/**
+	 * Emit a string value formatted for Lucene query syntax by appending escaped
+	 * characters to the provided context. Used by Elasticsearch, OpenSearch, and GemFire
+	 * VectorDB query string filters.
+	 * <p>
+	 * Lucene/Elasticsearch query strings require backslash-escaping of special
+	 * characters: {@code + - = ! ( ) { } [ ] ^ " ~ * ? : \ / & | < >}
+	 * @param value the string value to format
+	 * @param context the context to append the escaped string to
+	 * @see <a href=
+	 * "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#_reserved_characters">Elasticsearch
+	 * Reserved Characters</a>
+	 */
+	protected static void emitLuceneString(String value, StringBuilder context) {
+		for (int i = 0; i < value.length(); i++) {
+			char c = value.charAt(i);
+
+			// Escape Lucene query string special characters
+			switch (c) {
+				case '+':
+				case '-':
+				case '=':
+				case '!':
+				case '(':
+				case ')':
+				case '{':
+				case '}':
+				case '[':
+				case ']':
+				case '^':
+				case '"':
+				case '~':
+				case '*':
+				case '?':
+				case ':':
+				case '\\':
+				case '/':
+				case '&':
+				case '|':
+				case '<':
+				case '>':
+					context.append('\\').append(c);
+					break;
+				default:
+					context.append(c);
+					break;
+			}
+		}
+	}
+
+	/**
+	 * Emit a value formatted as JSON by appending its JSON representation to the provided
+	 * context. Used for PostgreSQL JSONPath, Neo4j Cypher, Weaviate GraphQL, and other
+	 * JSON-based filter expressions.
+	 * <p>
+	 * This method uses Jackson's ObjectMapper to properly serialize all value types:
+	 * <ul>
+	 * <li>Strings: properly quoted and escaped with double quotes, backslashes, and
+	 * control characters handled</li>
+	 * <li>Numbers: formatted without quotes (e.g., 42, 3.14)</li>
+	 * <li>Booleans: formatted as JSON literals {@code true} or {@code false}</li>
+	 * <li>null: formatted as JSON literal {@code null}</li>
+	 * <li>Other types: handled according to Jackson's default serialization</li>
+	 * </ul>
+	 * @param value the value to format (can be any type)
+	 * @param context the context to append the JSON representation to
+	 */
+	protected static void emitJsonValue(Object value, StringBuilder context) {
+		try {
+			context.append(OBJECT_MAPPER.writeValueAsString(value));
 		}
-		else {
-			context.append(value);
+		catch (JacksonException e) {
+			throw new RuntimeException("Error serializing value to JSON.", e);
 		}
 	}
 

spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/filter/converter/PineconeFilterExpressionConverter.java

@@ -62,4 +62,9 @@ protected void doKey(Key key, StringBuilder context) {
 		context.append("\"").append(identifier).append("\": ");
 	}
 
+	@Override
+	protected void doSingleValue(Object value, StringBuilder context) {
+		emitJsonValue(value, context);
+	}
+
 }

spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/filter/converter/PrintFilterExpressionConverter.java

@@ -53,4 +53,9 @@ public void doEndGroup(Group group, StringBuilder context) {
 		context.append(")");
 	}
 
+	@Override
+	protected void doSingleValue(Object value, StringBuilder context) {
+		emitJsonValue(value, context);
+	}
+
 }

spring-ai-vector-store/src/main/java/org/springframework/ai/vectorstore/filter/converter/SimpleVectorStoreFilterExpressionConverter.java

@@ -16,13 +16,10 @@
 
 package org.springframework.ai.vectorstore.filter.converter;
 
-import java.time.Instant;
 import java.time.ZoneOffset;
 import java.time.format.DateTimeFormatter;
-import java.time.format.DateTimeParseException;
 import java.util.Date;
 import java.util.List;
-import java.util.regex.Pattern;
 
 import org.springframework.ai.vectorstore.filter.Filter;
 import org.springframework.ai.vectorstore.filter.Filter.Expression;
@@ -35,8 +32,6 @@
  */
 public class SimpleVectorStoreFilterExpressionConverter extends AbstractFilterExpressionConverter {
 
-	private static final Pattern DATE_FORMAT_PATTERN = Pattern.compile("\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z");
-
 	private final DateTimeFormatter dateFormat;
 
 	public SimpleVectorStoreFilterExpressionConverter() {
@@ -83,7 +78,7 @@ protected void doValue(Filter.Value filterValue, StringBuilder context) {
 			var formattedList = new StringBuilder("{");
 			int c = 0;
 			for (Object v : list) {
-				this.doSingleValue(v, formattedList);
+				this.doSingleValue(normalizeDateString(v), formattedList);
 				if (c++ < list.size() - 1) {
 					this.doAddValueRangeSpitter(filterValue, formattedList);
 				}
@@ -98,7 +93,7 @@ protected void doValue(Filter.Value filterValue, StringBuilder context) {
 			}
 		}
 		else {
-			this.doSingleValue(filterValue.value(), context);
+			this.doSingleValue(normalizeDateString(filterValue.value()), context);
 		}
 	}
 
@@ -114,6 +109,43 @@ private void appendSpELContains(StringBuilder formattedList, StringBuilder conte
 		context.append(formattedList).append(".contains(").append(metadata).append(")");
 	}
 
+	/**
+	 * Emit a SpEL-formatted string value with single quote wrapping and escaping by
+	 * appending to the provided context.
+	 * <p>
+	 * Escapes single quotes (using backslash) and backslashes (double backslash)
+	 * according to SpEL string literal rules.
+	 * <p>
+	 * This method prevents SpEL injection attacks by properly escaping special
+	 * characters.
+	 * @param text the string value to format
+	 * @param context the context to append the SpEL string literal to
+	 * @since 2.0.0
+	 */
+	protected static void emitSpelString(String text, StringBuilder context) {
+		context.append("'"); // Opening quote
+
+		for (int i = 0; i < text.length(); i++) {
+			char c = text.charAt(i);
+
+			switch (c) {
+				case '\'':
+					// SpEL: single quote → backslash escaped
+					context.append("\\'");
+					break;
+				case '\\':
+					// SpEL: backslash → double backslash
+					context.append("\\\\");
+					break;
+				default:
+					context.append(c);
+					break;
+			}
+		}
+
+		context.append("'"); // Closing quote
+	}
+
 	@Override
 	protected void doSingleValue(Object value, StringBuilder context) {
 		if (value instanceof Date date) {
@@ -122,20 +154,7 @@ protected void doSingleValue(Object value, StringBuilder context) {
 			context.append("'");
 		}
 		else if (value instanceof String text) {
-			context.append("'");
-			if (DATE_FORMAT_PATTERN.matcher(text).matches()) {
-				try {
-					Instant date = Instant.from(this.dateFormat.parse(text));
-					context.append(this.dateFormat.format(date));
-				}
-				catch (DateTimeParseException e) {
-					throw new IllegalArgumentException("Invalid date type:" + text, e);
-				}
-			}
-			else {
-				context.append(text);
-			}
-			context.append("'");
+			emitSpelString(text, context);
 		}
 		else {
 			context.append(value);

vector-stores/spring-ai-azure-cosmos-db-store/src/main/java/org/springframework/ai/vectorstore/cosmosdb/CosmosDBFilterExpressionConverter.java

@@ -130,4 +130,9 @@ private String getOperationSymbol(Filter.Expression exp) {
 		};
 	}
 
+	@Override
+	protected void doSingleValue(Object value, StringBuilder context) {
+		emitJsonValue(value, context);
+	}
+
 }