Fail fast when k-NN plugin is missing

vectorSearch() currently lets queries proceed even when the k-NN plugin
is not installed; the user sees a cryptic native OpenSearch error deep
in execution. This change adds a lazy capability probe that runs on the
first vectorSearch() invocation per JVM and throws a clear message when
the plugin is absent.

- KnnPluginCapability: probes Nodes Info once via NodeClient, caches the
  result. Successful results (positive or negative) are cached; probe
  failures (IO, timeout) are not, so subsequent calls retry. If no
  NodeClient is available (REST-client / standalone mode), the check is
  skipped and execution-time errors remain the signal.
- The probe uses the canonical k-NN plugin class name rather than the
  artifact name so it survives repackaging variants.
- Wired into VectorSearchTableFunctionImplementation.applyArguments() so
  the failure surfaces before any DSL is built. Resolver instantiates
  one shared capability per registration; the constructor remains
  backward-compatible (two-arg form delegates to the three-arg form).
- Unit tests cover: node-client absent (skip), plugin present (pass),
  plugin absent (throw), positive/negative caching, and probe-failure
  non-caching.

Plugin registration stays unconditional — failing at registration would
break introspection (SHOW FUNCTIONS etc.) on clusters without k-NN.

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

Author: mengweieric

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

@@ -28,6 +28,7 @@
 import org.opensearch.sql.expression.function.FunctionName;
 import org.opensearch.sql.expression.function.TableFunctionImplementation;
 import org.opensearch.sql.opensearch.client.OpenSearchClient;
+import org.opensearch.sql.opensearch.storage.capability.KnnPluginCapability;
 import org.opensearch.sql.storage.Table;
 
 public class VectorSearchTableFunctionImplementation extends FunctionExpression
@@ -47,17 +48,20 @@ public class VectorSearchTableFunctionImplementation extends FunctionExpression
   private final List<Expression> arguments;
   private final OpenSearchClient client;
   private final Settings settings;
+  private final KnnPluginCapability knnCapability;
 
   public VectorSearchTableFunctionImplementation(
       FunctionName functionName,
       List<Expression> arguments,
       OpenSearchClient client,
-      Settings settings) {
+      Settings settings,
+      KnnPluginCapability knnCapability) {
     super(functionName, arguments);
     this.functionName = functionName;
     this.arguments = arguments;
     this.client = client;
     this.settings = settings;
+    this.knnCapability = knnCapability;
   }
 
   @Override
@@ -89,6 +93,7 @@ public String toString() {
 
   @Override
   public Table applyArguments() {
+    knnCapability.requireInstalled();
     validateNamedArgs();
     String tableName = getArgumentValue(TABLE);
     String fieldName = getArgumentValue(FIELD);

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

@@ -8,7 +8,6 @@
 import static org.opensearch.sql.data.type.ExprCoreType.STRING;
 
 import java.util.List;
-import lombok.RequiredArgsConstructor;
 import org.apache.commons.lang3.tuple.Pair;
 import org.opensearch.sql.common.setting.Settings;
 import org.opensearch.sql.expression.Expression;
@@ -17,8 +16,8 @@
 import org.opensearch.sql.expression.function.FunctionResolver;
 import org.opensearch.sql.expression.function.FunctionSignature;
 import org.opensearch.sql.opensearch.client.OpenSearchClient;
+import org.opensearch.sql.opensearch.storage.capability.KnnPluginCapability;
 
-@RequiredArgsConstructor
 public class VectorSearchTableFunctionResolver implements FunctionResolver {
 
   public static final String VECTOR_SEARCH = "vectorsearch";
@@ -30,6 +29,18 @@ public class VectorSearchTableFunctionResolver implements FunctionResolver {
 
   private final OpenSearchClient client;
   private final Settings settings;
+  private final KnnPluginCapability knnCapability;
+
+  public VectorSearchTableFunctionResolver(OpenSearchClient client, Settings settings) {
+    this(client, settings, new KnnPluginCapability(client));
+  }
+
+  VectorSearchTableFunctionResolver(
+      OpenSearchClient client, Settings settings, KnnPluginCapability knnCapability) {
+    this.client = client;
+    this.settings = settings;
+    this.knnCapability = knnCapability;
+  }
 
   @Override
   public Pair<FunctionSignature, FunctionBuilder> resolve(FunctionSignature unresolvedSignature) {
@@ -40,7 +51,7 @@ public Pair<FunctionSignature, FunctionBuilder> resolve(FunctionSignature unreso
         (functionProperties, arguments) -> {
           validateArguments(arguments);
           return new VectorSearchTableFunctionImplementation(
-              functionName, arguments, client, settings);
+              functionName, arguments, client, settings, knnCapability);
         };
     return Pair.of(functionSignature, functionBuilder);
   }

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

@@ -0,0 +1,90 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.sql.opensearch.storage.capability;
+
+import java.util.Objects;
+import java.util.Optional;
+import java.util.concurrent.atomic.AtomicReference;
+import org.opensearch.action.admin.cluster.node.info.NodesInfoRequest;
+import org.opensearch.action.admin.cluster.node.info.NodesInfoResponse;
+import org.opensearch.action.admin.cluster.node.info.PluginsAndModules;
+import org.opensearch.plugins.PluginInfo;
+import org.opensearch.sql.exception.ExpressionEvaluationException;
+import org.opensearch.sql.opensearch.client.OpenSearchClient;
+import org.opensearch.transport.client.node.NodeClient;
+
+/**
+ * Probes the cluster's Nodes Info API once and caches whether the k-NN plugin is installed, so
+ * vectorSearch() fails fast with a clear error when the plugin is absent instead of surfacing a
+ * native OpenSearch error deep in execution.
+ *
+ * <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.
+ */
+public class KnnPluginCapability {
+
+  /**
+   * Canonical k-NN plugin class. Using the class name (not artifact name) so the check is stable
+   * across packaging variants.
+   */
+  private static final String KNN_PLUGIN_CLASSNAME = "org.opensearch.knn.plugin.KNNPlugin";
+
+  private final OpenSearchClient client;
+  private final AtomicReference<Boolean> cached = new AtomicReference<>();
+
+  public KnnPluginCapability(OpenSearchClient client) {
+    this.client = client;
+  }
+
+  /**
+   * Throws {@link ExpressionEvaluationException} with a user-facing message if the k-NN plugin is
+   * not installed on any node in the cluster. The result is cached after the first successful
+   * probe; probe failures are not cached so the next call retries.
+   */
+  public void requireInstalled() {
+    Boolean hit = cached.get();
+    if (hit == null) {
+      Optional<Boolean> probed = probe();
+      if (probed.isEmpty()) {
+        // Probe unavailable (REST-client mode, no NodeClient). Don't block — execution-time
+        // errors will surface if k-NN is genuinely missing.
+        return;
+      }
+      hit = probed.get();
+      cached.set(hit);
+    }
+    if (!hit) {
+      throw new ExpressionEvaluationException(
+          "vectorSearch() requires the k-NN plugin, which is not installed on this cluster."
+              + " Install opensearch-knn or use a cluster that has it.");
+    }
+  }
+
+  private Optional<Boolean> probe() {
+    Optional<NodeClient> maybeNode = client.getNodeClient();
+    if (maybeNode.isEmpty()) {
+      return Optional.empty();
+    }
+    NodeClient node = maybeNode.get();
+    try {
+      NodesInfoRequest request = new NodesInfoRequest().clear().addMetric("plugins");
+      NodesInfoResponse response = node.admin().cluster().nodesInfo(request).actionGet();
+      boolean installed =
+          response.getNodes().stream()
+              .map(info -> info.getInfo(PluginsAndModules.class))
+              .filter(Objects::nonNull)
+              .flatMap(p -> p.getPluginInfos().stream())
+              .map(PluginInfo::getClassname)
+              .anyMatch(KNN_PLUGIN_CLASSNAME::equals);
+      return Optional.of(installed);
+    } catch (Exception e) {
+      // Probe failed (IO error, timeout). Don't cache — let the next call retry.
+      return Optional.empty();
+    }
+  }
+}

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

@@ -22,6 +22,7 @@
 import org.opensearch.sql.expression.Expression;
 import org.opensearch.sql.expression.function.FunctionName;
 import org.opensearch.sql.opensearch.client.OpenSearchClient;
+import org.opensearch.sql.opensearch.storage.capability.KnnPluginCapability;
 import org.opensearch.sql.storage.Table;
 
 @ExtendWith(MockitoExtension.class)
@@ -31,6 +32,11 @@ class VectorSearchTableFunctionImplementationTest {
 
   @Mock private Settings settings;
 
+  // No-op capability — tests in this class don't exercise the k-NN plugin probe.
+  // Dedicated tests for the probe live in KnnPluginCapabilityTest.
+  private final KnnPluginCapability knnCapability =
+      org.mockito.Mockito.mock(KnnPluginCapability.class);
+
   @Test
   void testValueOfThrows() {
     VectorSearchTableFunctionImplementation impl = createImpl();
@@ -61,6 +67,28 @@ void testApplyArguments() {
     assertTrue(table instanceof VectorSearchIndex);
   }
 
+  @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();
+    FunctionName functionName = FunctionName.of("vectorsearch");
+    List<Expression> args =
+        List.of(
+            DSL.namedArgument("table", DSL.literal("my-index")),
+            DSL.namedArgument("field", DSL.literal("embedding")),
+            DSL.namedArgument("vector", DSL.literal("[1.0, 2.0]")),
+            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"));
+  }
+
   @Test
   void testApplyArgumentsWithBracketedVector() {
     VectorSearchTableFunctionImplementation impl =
@@ -183,7 +211,8 @@ void testMissingArgumentThrows() {
             DSL.namedArgument("field", DSL.literal("embedding")),
             DSL.namedArgument("vector", DSL.literal("[1.0, 2.0]")));
     VectorSearchTableFunctionImplementation impl =
-        new VectorSearchTableFunctionImplementation(functionName, args, client, settings);
+        new VectorSearchTableFunctionImplementation(
+            functionName, args, client, settings, knnCapability);
     ExpressionEvaluationException ex =
         assertThrows(ExpressionEvaluationException.class, () -> impl.applyArguments());
     assertEquals("Missing required argument: option", ex.getMessage());
@@ -297,7 +326,8 @@ void testNonNamedArgThrows() {
     FunctionName functionName = FunctionName.of("vectorsearch");
     List<Expression> args = List.of(DSL.literal("my-index"));
     VectorSearchTableFunctionImplementation impl =
-        new VectorSearchTableFunctionImplementation(functionName, args, client, settings);
+        new VectorSearchTableFunctionImplementation(
+            functionName, args, client, settings, knnCapability);
     ExpressionEvaluationException ex =
         assertThrows(ExpressionEvaluationException.class, () -> impl.applyArguments());
     assertTrue(ex.getMessage().contains("requires named arguments"));
@@ -313,7 +343,8 @@ void testNullArgNameThrows() {
             DSL.namedArgument("vector", DSL.literal("[1.0, 2.0]")),
             DSL.namedArgument("option", DSL.literal("k=5")));
     VectorSearchTableFunctionImplementation impl =
-        new VectorSearchTableFunctionImplementation(functionName, args, client, settings);
+        new VectorSearchTableFunctionImplementation(
+            functionName, args, client, settings, knnCapability);
     ExpressionEvaluationException ex =
         assertThrows(ExpressionEvaluationException.class, () -> impl.applyArguments());
     assertTrue(ex.getMessage().contains("requires named arguments"));
@@ -383,7 +414,8 @@ void testCaseInsensitiveArgLookup() {
             DSL.namedArgument("VECTOR", DSL.literal("[1.0, 2.0]")),
             DSL.namedArgument("OPTION", DSL.literal("k=5")));
     VectorSearchTableFunctionImplementation impl =
-        new VectorSearchTableFunctionImplementation(functionName, args, client, settings);
+        new VectorSearchTableFunctionImplementation(
+            functionName, args, client, settings, knnCapability);
     Table table = impl.applyArguments();
     assertTrue(table instanceof VectorSearchIndex);
   }
@@ -398,7 +430,8 @@ void testInvalidFilterTypeRejects() {
             DSL.namedArgument("vector", DSL.literal("[1.0, 2.0]")),
             DSL.namedArgument("option", DSL.literal("k=5,filter_type=invalid")));
     VectorSearchTableFunctionImplementation impl =
-        new VectorSearchTableFunctionImplementation(functionName, args, client, settings);
+        new VectorSearchTableFunctionImplementation(
+            functionName, args, client, settings, knnCapability);
     ExpressionEvaluationException ex =
         assertThrows(ExpressionEvaluationException.class, impl::applyArguments);
     assertTrue(ex.getMessage().contains("filter_type must be one of"));
@@ -440,6 +473,7 @@ private VectorSearchTableFunctionImplementation createImplWithArgs(
             DSL.namedArgument("field", DSL.literal(field)),
             DSL.namedArgument("vector", DSL.literal(vector)),
             DSL.namedArgument("option", DSL.literal(option)));
-    return new VectorSearchTableFunctionImplementation(functionName, args, client, settings);
+    return new VectorSearchTableFunctionImplementation(
+        functionName, args, client, settings, knnCapability);
   }
 }