Defer k-NN plugin probe to scan open() so _explain keeps working

The original placement ran knnCapability.requireInstalled() at the
very top of applyArguments(). That hook runs during analysis for
both _query AND _explain, which regressed two existing contracts on
clusters without the k-NN plugin:

- VectorSearchExplainIT explicitly states "_explain only parses and
  plans the query and does NOT require the k-NN plugin". The check
  would have made every explain test fail with "k-NN plugin missing".
- VectorSearchIT is the local-validation/error-path suite. Malformed
  queries on a pluginless cluster would have collapsed to the k-NN
  error instead of the existing SQL validation errors.

Move the probe to VectorSearchIndexScan.open() — a new thin subclass
of OpenSearchIndexScan whose only override calls requireInstalled()
before super.open(). Scan open() runs only on the execute path;
_explain walks the built plan without opening it, so explain stays
functional.

Also reorder applyArguments() — nothing to relocate now that the
capability check has moved, but the comment documents the intent:
local validation runs first so malformed-query errors are stable
regardless of cluster state or probe outcome.

Add two ITs on the default (pluginless) integ-test cluster:
- testExecutionWithoutKnnPluginReturnsCapabilityError — verifies the
  clear "k-NN plugin not installed" error surfaces on execute.
- testExplainWithoutKnnPluginStillWorks — guards the _explain
  contract so future probe relocations can't silently break it.

Also drops the "SQL preview" framing from VectorSearchIndexScanBuilder's
aggregation-rejection error per prior user instruction.

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

Author: mengweieric

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

@@ -262,4 +262,42 @@ public void testBareAggregateRejects() throws IOException {
         ex.getMessage(),
         containsString("Aggregations are not supported on vectorSearch() relations"));
   }
+
+  // ── k-NN plugin capability check ──────────────────────────────────────
+  // The default integ-test cluster does not have the k-NN plugin installed. Execution-path
+  // queries against vectorSearch() should therefore fail with the clear "k-NN plugin missing"
+  // error from KnnPluginCapability, while _explain continues to work because the capability
+  // probe is deferred to scan open() and does not run during analysis/planning.
+
+  @Test
+  public void testExecutionWithoutKnnPluginReturnsCapabilityError() throws IOException {
+    ResponseException ex =
+        expectThrows(
+            ResponseException.class,
+            () ->
+                executeQuery(
+                    "SELECT v._id FROM vectorSearch(table='"
+                        + TEST_INDEX
+                        + "', field='embedding', vector='[1.0, 2.0]', option='k=5') AS v "
+                        + "LIMIT 5"));
+
+    assertThat(ex.getMessage(), containsString("k-NN plugin"));
+    assertThat(ex.getMessage(), containsString("not installed"));
+  }
+
+  @Test
+  public void testExplainWithoutKnnPluginStillWorks() throws IOException {
+    // _explain only parses and plans the query. It must NOT require the k-NN plugin — the
+    // capability probe is intentionally deferred to scan open() so pluginless clusters can
+    // still inspect query plans. If this test starts failing with "k-NN plugin not installed",
+    // the probe has leaked back into an analysis-time path.
+    String explain =
+        explainQuery(
+            "SELECT v._id FROM vectorSearch(table='"
+                + TEST_INDEX
+                + "', field='embedding', vector='[1.0, 2.0]', option='k=5') AS v "
+                + "LIMIT 5");
+
+    assertThat(explain, containsString("wrapper"));
+  }
 }

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

@@ -13,7 +13,9 @@
 import org.opensearch.sql.common.setting.Settings;
 import org.opensearch.sql.opensearch.client.OpenSearchClient;
 import org.opensearch.sql.opensearch.request.OpenSearchRequestBuilder;
+import org.opensearch.sql.opensearch.storage.capability.KnnPluginCapability;
 import org.opensearch.sql.opensearch.storage.scan.OpenSearchIndexScan;
+import org.opensearch.sql.opensearch.storage.scan.VectorSearchIndexScan;
 import org.opensearch.sql.opensearch.storage.scan.VectorSearchIndexScanBuilder;
 import org.opensearch.sql.opensearch.storage.scan.VectorSearchQueryBuilder;
 import org.opensearch.sql.storage.read.TableScanBuilder;
@@ -27,6 +29,10 @@ public class VectorSearchIndex extends OpenSearchIndex {
   private final float[] vector;
   private final Map<String, String> options;
   private final FilterType filterType; // null means default (POST)
+  // Nullable for back-compat with existing tests and the non-vector-search constructor. When
+  // present, the scan defers a lazy k-NN plugin probe to open() so execution fails fast with a
+  // clear SQL error if the plugin is missing.
+  private final KnnPluginCapability knnCapability;
 
   public VectorSearchIndex(
       OpenSearchClient client,
@@ -35,12 +41,25 @@ public VectorSearchIndex(
       String field,
       float[] vector,
       Map<String, String> options,
-      FilterType filterType) {
+      FilterType filterType,
+      KnnPluginCapability knnCapability) {
     super(client, settings, indexName);
     this.field = field;
     this.vector = vector;
     this.options = options;
     this.filterType = filterType;
+    this.knnCapability = knnCapability;
+  }
+
+  public VectorSearchIndex(
+      OpenSearchClient client,
+      Settings settings,
+      String indexName,
+      String field,
+      float[] vector,
+      Map<String, String> options,
+      FilterType filterType) {
+    this(client, settings, indexName, field, vector, options, filterType, null);
   }
 
   /** Default constructor — preserves existing call sites; uses no explicit filter type. */
@@ -51,7 +70,7 @@ public VectorSearchIndex(
       String field,
       float[] vector,
       Map<String, String> options) {
-    this(client, settings, indexName, field, vector, options, null);
+    this(client, settings, indexName, field, vector, options, null, null);
   }
 
   @Override
@@ -89,11 +108,15 @@ public TableScanBuilder createScanBuilder() {
     }
 
     Function<OpenSearchRequestBuilder, OpenSearchIndexScan> createScanOperator =
-        rb ->
-            new OpenSearchIndexScan(
-                getClient(),
-                rb.getMaxResponseSize(),
-                rb.build(getIndexName(), cursorKeepAlive, getClient(), getFieldTypes().isEmpty()));
+        rb -> {
+          var request =
+              rb.build(getIndexName(), cursorKeepAlive, getClient(), getFieldTypes().isEmpty());
+          if (knnCapability != null) {
+            return new VectorSearchIndexScan(
+                getClient(), rb.getMaxResponseSize(), request, knnCapability);
+          }
+          return new OpenSearchIndexScan(getClient(), rb.getMaxResponseSize(), request);
+        };
     return new VectorSearchIndexScanBuilder(queryBuilder, createScanOperator);
   }
 

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

@@ -93,7 +93,10 @@ public String toString() {
 
   @Override
   public Table applyArguments() {
-    knnCapability.requireInstalled();
+    // Local validation runs first so that malformed queries return stable SQL validation errors
+    // regardless of cluster state. The k-NN plugin presence is checked later, lazily at scan
+    // open() time, so analysis-time paths (_explain, local validation) stay functional on
+    // clusters without k-NN.
     validateNamedArgs();
     String tableName = getArgumentValue(TABLE);
     String fieldName = getArgumentValue(FIELD);
@@ -112,7 +115,7 @@ public Table applyArguments() {
     }
 
     return new VectorSearchIndex(
-        client, settings, tableName, fieldName, vector, options, filterType);
+        client, settings, tableName, fieldName, vector, options, filterType, knnCapability);
   }
 
   private float[] parseVector(String vectorLiteral) {

opensearch/src/main/java/org/opensearch/sql/opensearch/storage/capability/KnnPluginCapability.java

@@ -24,7 +24,9 @@
  * <p>The probe requires a {@link NodeClient}. In REST-client mode (standalone SQL service) the node
  * client is absent and the check is skipped — execution-time errors remain the signal there.
  *
- * <p>The check runs lazily on the first vectorSearch() invocation so cluster boot is unaffected.
+ * <p>The check runs lazily at scan open() — i.e. only when a vectorSearch() query is actually
+ * executed — so analysis-time paths like _explain and local argument validation keep working on
+ * clusters without k-NN.
  */
 public class KnnPluginCapability {
 

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

@@ -0,0 +1,37 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.opensearch.storage.scan;
+
+import org.opensearch.sql.opensearch.client.OpenSearchClient;
+import org.opensearch.sql.opensearch.request.OpenSearchRequest;
+import org.opensearch.sql.opensearch.storage.capability.KnnPluginCapability;
+
+/**
+ * OpenSearch scan for vector-search relations. Delegates everything to {@link OpenSearchIndexScan}
+ * except for {@link #open()}, where it first verifies the k-NN plugin is installed so we fail fast
+ * with a clear SQL error before the native request would fail deep in execution. The check is
+ * deferred to open() (not applyArguments() or the scan builder) so that analysis-time paths like
+ * _explain continue to work on clusters without k-NN.
+ */
+public class VectorSearchIndexScan extends OpenSearchIndexScan {
+
+  private final KnnPluginCapability knnCapability;
+
+  public VectorSearchIndexScan(
+      OpenSearchClient client,
+      int maxResponseSize,
+      OpenSearchRequest request,
+      KnnPluginCapability knnCapability) {
+    super(client, maxResponseSize, request);
+    this.knnCapability = knnCapability;
+  }
+
+  @Override
+  public void open() {
+    knnCapability.requireInstalled();
+    super.open();
+  }
+}

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

@@ -11,10 +11,9 @@
 import org.opensearch.sql.planner.logical.LogicalAggregation;
 
 /**
- * Scan builder for vector search relations. Rejects aggregation pushdown as a SQL preview
- * constraint: aggregations over vectorSearch() relations are not supported in the current preview.
- * Native OpenSearch k-NN does support aggregations alongside similarity search; this restriction is
- * specific to the SQL surface and may be lifted in a later release.
+ * Scan builder for vector search relations. Rejects aggregation pushdown: aggregations over
+ * vectorSearch() relations are not supported in the SQL surface. Native OpenSearch k-NN does
+ * support aggregations alongside similarity search; this restriction is specific to the SQL layer.
  */
 public class VectorSearchIndexScanBuilder extends OpenSearchIndexScanBuilder {
 
@@ -27,6 +26,6 @@ public VectorSearchIndexScanBuilder(
   @Override
   public boolean pushDownAggregation(LogicalAggregation aggregation) {
     throw new ExpressionEvaluationException(
-        "Aggregations are not supported on vectorSearch() relations in the SQL preview.");
+        "Aggregations are not supported on vectorSearch() relations.");
   }
 }

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

@@ -68,12 +68,11 @@ void testApplyArguments() {
   }
 
   @Test
-  void testApplyArgumentsPropagatesKnnCapabilityFailure() {
-    // If the capability check fires, applyArguments() must not proceed to build the table.
-    KnnPluginCapability throwingCapability = org.mockito.Mockito.mock(KnnPluginCapability.class);
-    org.mockito.Mockito.doThrow(new ExpressionEvaluationException("k-NN plugin not installed"))
-        .when(throwingCapability)
-        .requireInstalled();
+  void testApplyArgumentsDoesNotProbeKnnCapability() {
+    // Contract: applyArguments() runs during analysis (including _explain) and must NOT invoke
+    // the k-NN plugin probe. The probe is deferred to scan open() so pluginless clusters can
+    // still explain and validate vectorSearch() queries locally.
+    KnnPluginCapability observingCapability = org.mockito.Mockito.mock(KnnPluginCapability.class);
     FunctionName functionName = FunctionName.of("vectorsearch");
     List<Expression> args =
         List.of(
@@ -83,10 +82,9 @@ void testApplyArgumentsPropagatesKnnCapabilityFailure() {
             DSL.namedArgument("option", DSL.literal("k=5")));
     VectorSearchTableFunctionImplementation impl =
         new VectorSearchTableFunctionImplementation(
-            functionName, args, client, settings, throwingCapability);
-    ExpressionEvaluationException ex =
-        assertThrows(ExpressionEvaluationException.class, impl::applyArguments);
-    assertTrue(ex.getMessage().contains("k-NN plugin"));
+            functionName, args, client, settings, observingCapability);
+    impl.applyArguments();
+    org.mockito.Mockito.verify(observingCapability, org.mockito.Mockito.never()).requireInstalled();
   }
 
   @Test

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

@@ -0,0 +1,39 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.opensearch.storage.scan;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.doThrow;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+import org.junit.jupiter.api.Test;
+import org.opensearch.sql.exception.ExpressionEvaluationException;
+import org.opensearch.sql.opensearch.client.OpenSearchClient;
+import org.opensearch.sql.opensearch.request.OpenSearchRequest;
+import org.opensearch.sql.opensearch.storage.capability.KnnPluginCapability;
+
+class VectorSearchIndexScanTest {
+
+  @Test
+  void openProbesKnnPluginBeforeFetch() {
+    OpenSearchClient client = mock(OpenSearchClient.class);
+    OpenSearchRequest request = mock(OpenSearchRequest.class);
+    KnnPluginCapability capability = mock(KnnPluginCapability.class);
+    doThrow(new ExpressionEvaluationException("k-NN plugin missing"))
+        .when(capability)
+        .requireInstalled();
+
+    VectorSearchIndexScan scan = new VectorSearchIndexScan(client, 10, request, capability);
+    ExpressionEvaluationException ex =
+        assertThrows(ExpressionEvaluationException.class, scan::open);
+    assertTrue(ex.getMessage().contains("k-NN plugin"));
+    // Capability threw, so the underlying client must not have been touched for this scan.
+    verify(client, never()).search(request);
+  }
+}