Address review feedback: reword user-facing error, strengthen explain test, rename constructor comment

- Reword filter_type error message to be user-friendly and actionable
  (no longer leaks internal ScriptQueryUnSupportedException text)
- Strengthen efficient-mode explain IT: assert no bool/must (proves not
  post-filter shape), decode base64 knn payload to verify filter and
  predicate field are embedded inside knn query
- Rename "Backward-compatible constructor" to clarify intent

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

Author: mengweieric

integ-test/src/test/java/org/opensearch/sql/sql/VectorSearchExplainIT.java

@@ -202,8 +202,33 @@ public void testExplainFilterTypeEfficientProducesKnnWithFilter() throws IOExcep
                 + "WHERE v.state = 'TX' "
                 + "LIMIT 5");
 
-    // Efficient mode: knn rebuilt with filter inside, wrapped in WrapperQueryBuilder
+    // Efficient mode: knn rebuilt with filter inside, wrapped in WrapperQueryBuilder.
+    // The knn JSON (including the embedded filter) is base64-encoded inside the wrapper,
+    // so we verify structure by: (1) wrapper present, (2) no bool/must in plaintext
+    // (that would be post-filter shape), (3) decode the base64 payload to confirm
+    // the filter and predicate field are embedded inside the knn query.
     assertTrue("Explain should contain wrapper query:\n" + explain, explain.contains("wrapper"));
+    assertFalse(
+        "Efficient mode should not produce bool query (that is post-filter shape):\n" + explain,
+        explain.contains("\"bool\""));
+    assertFalse(
+        "Efficient mode should not contain must clause:\n" + explain, explain.contains("\"must\""));
+
+    // Extract and decode the base64 knn payload to verify filter embedding.
+    // The explain output escapes quotes as \", so match both \" and " forms.
+    java.util.regex.Matcher m =
+        java.util.regex.Pattern.compile("\\\\?\"query\\\\?\":\\\\?\"([A-Za-z0-9+/=]+)\\\\?\"")
+            .matcher(explain);
+    assertTrue("Explain should contain base64-encoded knn query:\n" + explain, m.find());
+    String knnJson =
+        new String(
+            java.util.Base64.getDecoder().decode(m.group(1)),
+            java.nio.charset.StandardCharsets.UTF_8);
+    assertTrue(
+        "Efficient mode knn JSON should contain filter:\n" + knnJson, knnJson.contains("filter"));
+    assertTrue(
+        "Efficient mode knn JSON should contain the WHERE predicate field:\n" + knnJson,
+        knnJson.contains("state"));
   }
 
   @Test

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

@@ -43,7 +43,7 @@ public VectorSearchIndex(
     this.filterType = filterType;
   }
 
-  /** Backward-compatible constructor — defaults to no explicit filter type. */
+  /** Default constructor — preserves existing call sites; uses no explicit filter type. */
   public VectorSearchIndex(
       OpenSearchClient client,
       Settings settings,

opensearch/src/main/java/org/opensearch/sql/opensearch/storage/scan/VectorSearchQueryBuilder.java

@@ -84,9 +84,8 @@ public boolean pushDownFilter(LogicalFilter filter) {
     } catch (ScriptQueryUnSupportedException e) {
       if (filterTypeExplicit) {
         throw new ExpressionEvaluationException(
-            "filter_type requires a pushdownable WHERE clause, but the given condition"
-                + " cannot be pushed down: "
-                + e.getMessage());
+            "filter_type only works when the WHERE clause can be translated to an"
+                + " OpenSearch filter. Rewrite the WHERE clause or omit filter_type.");
       }
       // Default mode: fall back to in-memory filtering (matches base class behavior)
       return false;

opensearch/src/test/java/org/opensearch/sql/opensearch/storage/scan/VectorSearchQueryBuilderTest.java

@@ -571,8 +571,9 @@ void pushDownFilterNonPushdownableWithExplicitFilterTypeThrows() {
 
     ExpressionEvaluationException ex =
         assertThrows(ExpressionEvaluationException.class, () -> builder.pushDownFilter(filter));
-    assertTrue(ex.getMessage().contains("filter_type requires a pushdownable WHERE clause"));
-    assertTrue(ex.getMessage().contains("cannot be pushed down"));
+    assertTrue(
+        ex.getMessage().contains("filter_type only works when the WHERE clause can be translated"));
+    assertTrue(ex.getMessage().contains("Rewrite the WHERE clause or omit filter_type"));
   }
 
   @Test