fix(query): escape special characters in tag filter values

Add escapeTagValue() method that escapes RediSearch special characters
including spaces in tag values. This prevents syntax errors when tag
values contain hyphens, colons, periods, or other special characters.

- Add escapeTagValue() that calls escapeSpecialCharacters() + space escaping
- Update tag() method to escape each value before building the query
- Add comprehensive test covering hyphens, colons, @, spaces, and multiple values

Test cases verified:
- "test-user-001" → "test\-user\-001"
- "2025-12-10T15:02:37Z" → "2025\-12\-10T15\:02\:37Z"
- "user@example.com" → "user\@example\.com"
- "New York" → "New\ York"

Author: bsbodden

core/src/main/java/com/redis/vl/query/Filter.java

@@ -61,7 +61,11 @@ public static Filter tag(String field, String... values) {
       return new Filter(FilterType.CUSTOM, field, "*", null);
     }
 
-    String valueStr = values.length == 1 ? values[0] : String.join("|", values);
+    // Escape special characters in each tag value (including spaces)
+    String[] escapedValues =
+        Arrays.stream(values).map(Filter::escapeTagValue).toArray(String[]::new);
+    String valueStr =
+        escapedValues.length == 1 ? escapedValues[0] : String.join("|", escapedValues);
 
     String expr = String.format("@%s:{%s}", escapeFieldName(field), valueStr);
     return new Filter(FilterType.TAG, field, expr, null);
@@ -278,7 +282,7 @@ private static void validateValue(String value) {
     }
   }
 
-  /** Escape special characters in search queries */
+  /** Escape special characters in search queries (for text filters - does NOT escape spaces) */
   private static String escapeSpecialCharacters(String value) {
     // Escape Redis search special characters
     return value
@@ -313,6 +317,12 @@ private static String escapeSpecialCharacters(String value) {
         .replace(";", "\\;");
   }
 
+  /** Escape special characters in tag values (includes space escaping) */
+  private static String escapeTagValue(String value) {
+    // For tag values, escape all special characters including spaces
+    return escapeSpecialCharacters(value).replace(" ", "\\ ");
+  }
+
   /**
    * Build the filter query string
    *

core/src/test/java/com/redis/vl/query/FilterQueryTest.java

@@ -52,6 +52,35 @@ void shouldCreateTagFilterWithMultipleValues() {
     assertThat(filter.build()).isEqualTo("@tags:{redis|database|nosql}");
   }
 
+  @Test
+  @DisplayName("Should escape special characters in tag values")
+  void shouldEscapeSpecialCharactersInTagValues() {
+    // When - test value with hyphens
+    Filter filterWithHyphen = Filter.tag("user_id", "test-user-001");
+    // Then
+    assertThat(filterWithHyphen.build()).isEqualTo("@user_id:{test\\-user\\-001}");
+
+    // When - test value with colons (timestamp)
+    Filter filterWithColon = Filter.tag("timestamp", "2025-12-10T15:02:37Z");
+    // Then
+    assertThat(filterWithColon.build()).isEqualTo("@timestamp:{2025\\-12\\-10T15\\:02\\:37Z}");
+
+    // When - test value with @ symbol (email)
+    Filter filterWithAt = Filter.tag("email", "user@example.com");
+    // Then
+    assertThat(filterWithAt.build()).isEqualTo("@email:{user\\@example\\.com}");
+
+    // When - test value with spaces
+    Filter filterWithSpace = Filter.tag("category", "New York");
+    // Then
+    assertThat(filterWithSpace.build()).isEqualTo("@category:{New\\ York}");
+
+    // When - test multiple values with special characters
+    Filter filterMultiple = Filter.tag("tags", "dev-ops", "ci-cd", "k8s");
+    // Then
+    assertThat(filterMultiple.build()).isEqualTo("@tags:{dev\\-ops|ci\\-cd|k8s}");
+  }
+
   @Test
   @DisplayName("Should create numeric range filter")
   void shouldCreateNumericRangeFilter() {