Collapse buildKnnQueryJson to accept optional filter clause

Signed-off-by: Eric Wei <mengwei.eric@gmail.com>

Author: mengweieric

opensearch/src/main/java/org/opensearch/sql/opensearch/storage/VectorSearchIndex.java

@@ -90,6 +90,15 @@ private QueryBuilder buildKnnQuery() {
 
   // Package-private for testing
   String buildKnnQueryJson() {
+    return buildKnnQueryJson(null);
+  }
+
+  /**
+   * Builds knn query JSON, optionally embedding a filter clause for efficient filtering.
+   *
+   * @param filterJson serialized filter JSON to embed in knn.field.filter, or null for no filter
+   */
+  String buildKnnQueryJson(String filterJson) {
     StringBuilder vectorJson = new StringBuilder("[");
     for (int i = 0; i < vector.length; i++) {
       if (i > 0) vectorJson.append(",");
@@ -110,9 +119,14 @@ String buildKnnQueryJson() {
       }
     }
 
+    String filterClause = "";
+    if (filterJson != null) {
+      filterClause = String.format(",\"filter\":%s", filterJson);
+    }
+
     return String.format(
-        "{\"knn\":{\"%s\":{\"vector\":%s%s}}}",
-        field, vectorJson.toString(), optionsJson.toString());
+        "{\"knn\":{\"%s\":{\"vector\":%s%s%s}}}",
+        field, vectorJson.toString(), optionsJson.toString(), filterClause);
   }
 
   private static boolean isNumeric(String str) {

opensearch/src/test/java/org/opensearch/sql/opensearch/storage/VectorSearchIndexTest.java

@@ -140,6 +140,50 @@ void buildKnnQueryJsonNonNumericOptionRenderedQuoted() {
     assertTrue(json.contains("\"k\":5"), "Numeric option should be unquoted");
   }
 
+  @Test
+  void buildKnnQueryJsonWithFilterEmbeds() {
+    VectorSearchIndex index =
+        new VectorSearchIndex(
+            client, settings, "test-index", "embedding",
+            new float[] {1.0f, 2.0f}, Map.of("k", "5"), FilterType.EFFICIENT);
+
+    String filterJson = "{\"term\":{\"city\":{\"value\":\"Miami\"}}}";
+    String json = index.buildKnnQueryJson(filterJson);
+
+    assertTrue(json.contains("\"filter\""), "Should contain filter field");
+    assertTrue(json.contains("\"term\""), "Should contain the filter content");
+    assertTrue(json.contains("\"k\":5"), "Should still contain k");
+    assertTrue(json.contains("\"vector\":[1.0,2.0]"), "Should contain vector");
+  }
+
+  @Test
+  void buildKnnQueryJsonWithFilterRadial() {
+    VectorSearchIndex index =
+        new VectorSearchIndex(
+            client, settings, "test-index", "embedding",
+            new float[] {1.0f}, Map.of("max_distance", "10.5"), FilterType.EFFICIENT);
+
+    String filterJson = "{\"range\":{\"rating\":{\"gte\":4.0}}}";
+    String json = index.buildKnnQueryJson(filterJson);
+
+    assertTrue(json.contains("\"max_distance\":10.5"), "Should contain max_distance");
+    assertTrue(json.contains("\"filter\""), "Should contain filter");
+  }
+
+  @Test
+  void buildKnnQueryJsonNullFilterProducesBaseJson() {
+    VectorSearchIndex index =
+        new VectorSearchIndex(
+            client, settings, "test-index", "embedding",
+            new float[] {1.0f}, Map.of("k", "5"), null);
+
+    String json = index.buildKnnQueryJson(null);
+    String baseJson = index.buildKnnQueryJson();
+
+    assertEquals(baseJson, json, "null filter should produce same JSON as no-arg version");
+    assertFalse(json.contains("\"filter\""), "Should not contain filter field");
+  }
+
   @Test
   void buildKnnQueryJsonExcludesFilterType() {
     LinkedHashMap<String, String> options = new LinkedHashMap<>();