refactor(integ-test): capability-based analytics-engine test gating (#5560)

Rename AnalyticsRouteLimitation to Capability and add a declarative
@RequiresCapability annotation (enforced by CapabilityRule) wired into
SQLIntegTestCase, so SQL and PPL ITs gate by capability instead of naming
a backend. Gate logic lives in BackendCapabilities. All assumeNotAnalytics(...)
calls migrated to @RequiresCapability, with per-test divergence comments
folded into the annotation note.

Signed-off-by: Chen Dai <daichen@amazon.com>

Author: dai-chen

integ-test/build.gradle

@@ -1084,8 +1084,8 @@ task integTestRemote(type: RestIntegTestTask) {
             excludeTestsMatching 'org.opensearch.sql.calcite.remote.CalciteAliasFieldAggregationIT'
 
             // === Excludes: WhereCommandIT / CalciteWhereCommandIT route divergences (#5546) ===
-            // Each test also carries an in-test assumeNotAnalytics(...) recording the reason (see
-            // AnalyticsRouteLimitation); listed here so the AE-route skip set stays countable in one
+            // Each test also carries an in-test requireCapability(...) recording the reason (see
+            // Capability); listed here so the AE-route skip set stays countable in one
             // place. Reasons:
             //  - Nested-field queries: the parquet/composite store has no nested-document support, so
             //    nested fields are stripped at load (#5541). Defined only in CalciteWhereCommandIT.
@@ -1104,8 +1104,8 @@ task integTestRemote(type: RestIntegTestTask) {
             excludeTestsMatching '*WhereCommandIT.testDoubleEqualWithSpecialCharacters'
 
             // === Excludes: CalciteMultisearchCommandIT route divergences ===
-            // Each test also carries an in-test assumeNotAnalytics(...) recording the reason (see
-            // AnalyticsRouteLimitation); listed here so the AE-route skip set stays countable.
+            // Each test also carries an in-test requireCapability(...) recording the reason (see
+            // Capability); listed here so the AE-route skip set stays countable.
             //  - Same-index subsearch conflation: when every subsearch reads the same index, the AE
             //    route applies the first subsearch's filter to all of them, so counts are wrong.
             excludeTestsMatching '*CalciteMultisearchCommandIT.testMultisearchWithThreeSubsearches'
@@ -1119,15 +1119,15 @@ task integTestRemote(type: RestIntegTestTask) {
             // bin on a time field then grouping by it: the AE route types the date-histogram bucket
             // column as string (not timestamp) AND produces a different bucket set (auto-histogram
             // span / empty-bucket filtering differ), so both schema and row counts diverge. Each
-            // test also carries an in-test assumeNotAnalytics(...) (see AnalyticsRouteLimitation).
+            // test also carries an in-test requireCapability(...) (see Capability).
             excludeTestsMatching '*CalciteBinCommandIT.testStatsWithBinsOnTimeField_Count'
             excludeTestsMatching '*CalciteBinCommandIT.testStatsWithBinsOnTimeField_Avg'
             excludeTestsMatching '*CalciteBinCommandIT.testStatsWithBinsOnTimeAndTermField_Count'
             excludeTestsMatching '*CalciteBinCommandIT.testStatsWithBinsOnTimeAndTermField_Avg'
 
             // === Excludes: CalcitePPLEnhancedCoalesceIT route divergences ===
-            // Each test also carries an in-test assumeNotAnalytics(...) recording the reason (see
-            // AnalyticsRouteLimitation). The other ordering-sensitive coalesce tests were fixed in
+            // Each test also carries an in-test requireCapability(...) recording the reason (see
+            // Capability). The other ordering-sensitive coalesce tests were fixed in
             // place with an explicit `sort` instead of being skipped.
             //  - COALESCE over all-untyped-null operands is rejected by the capability registry.
             excludeTestsMatching '*CalcitePPLEnhancedCoalesceIT.testCoalesceWithAllNonExistentFields'
@@ -1137,8 +1137,8 @@ task integTestRemote(type: RestIntegTestTask) {
             excludeTestsMatching '*CalcitePPLEnhancedCoalesceIT.testCoalesceBasic'
 
             // === Excludes: CalcitePPLScalarSubqueryIT / CalcitePPLInSubqueryIT route divergences ===
-            // Each test also carries an in-test assumeNotAnalytics(...) recording the reason (see
-            // AnalyticsRouteLimitation); listed here so the AE-route skip set stays countable.
+            // Each test also carries an in-test requireCapability(...) recording the reason (see
+            // Capability); listed here so the AE-route skip set stays countable.
             //  - Exact equality on an explicitly text-mapped field (department/occupation = '...')
             //    in the subsearch returns no rows on the AE route (analyzed text, no .keyword).
             excludeTestsMatching '*CalcitePPLScalarSubqueryIT.testTwoUncorrelatedScalarSubqueriesInOr'
@@ -1149,8 +1149,8 @@ task integTestRemote(type: RestIntegTestTask) {
             excludeTestsMatching '*CalcitePPLInSubqueryIT.testSubsearchMaxOut'
 
             // === Excludes: CalcitePPLConditionBuiltinFunctionIT route divergences ===
-            // Each test also carries an in-test assumeNotAnalytics(...) recording the reason (see
-            // AnalyticsRouteLimitation); listed here so the AE-route skip set stays countable.
+            // Each test also carries an in-test requireCapability(...) recording the reason (see
+            // Capability); listed here so the AE-route skip set stays countable.
             //  - isnull/isnotnull on the object/struct parent field big5.aws: objects are flattened
             //    to dotted leaf columns and the struct parent is not a queryable column.
             excludeTestsMatching '*CalcitePPLConditionBuiltinFunctionIT.testIsNullWithStruct'
@@ -1168,7 +1168,7 @@ task integTestRemote(type: RestIntegTestTask) {
             // === Excludes: CalcitePPLEvalMaxMinFunctionIT route divergences ===
             // The AnalyticsExecutionEngine ANY-rescue (this PR) fixes the homogeneous max()/min()
             // schema types, so most of the class now passes on the AE route. Three tests still
-            // diverge; each carries an in-test assumeNotAnalytics(...) (see AnalyticsRouteLimitation).
+            // diverge; each carries an in-test requireCapability(...) (see Capability).
             //  - Mixed numeric+string operands throw 'Cannot infer return type for GREATEST' (the
             //    DataFusion GREATEST/LEAST can't unify heterogeneous operand types).
             excludeTestsMatching '*CalcitePPLEvalMaxMinFunctionIT.testEvalMaxNumericAndString'

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteBinCommandIT.java

@@ -9,7 +9,7 @@
 import static org.junit.Assert.assertTrue;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.opensearch.sql.legacy.TestsConstants.*;
-import static org.opensearch.sql.util.AnalyticsRouteLimitation.BIN_TIME_FIELD_BUCKETING;
+import static org.opensearch.sql.util.Capability.BIN_TIME_FIELD_BUCKETING;
 import static org.opensearch.sql.util.MatcherUtils.rows;
 import static org.opensearch.sql.util.MatcherUtils.schema;
 import static org.opensearch.sql.util.MatcherUtils.verifyDataRows;
@@ -21,6 +21,7 @@
 import org.junit.jupiter.api.Test;
 import org.opensearch.client.ResponseException;
 import org.opensearch.sql.ppl.PPLIntegTestCase;
+import org.opensearch.sql.util.RequiresCapability;
 
 public class CalciteBinCommandIT extends PPLIntegTestCase {
   @Override
@@ -870,10 +871,10 @@ public void testBinFloatingPointSpanWithStatsCount() throws IOException {
   }
 
   @Test
+  @RequiresCapability(BIN_TIME_FIELD_BUCKETING)
   public void testStatsWithBinsOnTimeField_Count() throws IOException {
     // TODO: Remove this after addressing https://github.com/opensearch-project/sql/issues/4317
     enabledOnlyWhenPushdownIsEnabled();
-    assumeNotAnalytics(BIN_TIME_FIELD_BUCKETING);
 
     JSONObject result =
         executeQuery("source=events_null | bin @timestamp bins=3 | stats count() by @timestamp");
@@ -909,10 +910,10 @@ public void testStatsWithBinsOnTimeField_Count() throws IOException {
   }
 
   @Test
+  @RequiresCapability(BIN_TIME_FIELD_BUCKETING)
   public void testStatsWithBinsOnTimeField_Avg() throws IOException {
     // TODO: Remove this after addressing https://github.com/opensearch-project/sql/issues/4317
     enabledOnlyWhenPushdownIsEnabled();
-    assumeNotAnalytics(BIN_TIME_FIELD_BUCKETING);
 
     JSONObject result =
         executeQuery(
@@ -951,10 +952,10 @@ public void testStatsWithBinsOnTimeField_Avg() throws IOException {
   }
 
   @Test
+  @RequiresCapability(BIN_TIME_FIELD_BUCKETING)
   public void testStatsWithBinsOnTimeAndTermField_Count() throws IOException {
     // TODO: Remove this after addressing https://github.com/opensearch-project/sql/issues/4317
     enabledOnlyWhenPushdownIsEnabled();
-    assumeNotAnalytics(BIN_TIME_FIELD_BUCKETING);
 
     JSONObject result =
         executeQuery(
@@ -975,10 +976,10 @@ public void testStatsWithBinsOnTimeAndTermField_Count() throws IOException {
   }
 
   @Test
+  @RequiresCapability(BIN_TIME_FIELD_BUCKETING)
   public void testStatsWithBinsOnTimeAndTermField_Avg() throws IOException {
     // TODO: Remove this after addressing https://github.com/opensearch-project/sql/issues/4317
     enabledOnlyWhenPushdownIsEnabled();
-    assumeNotAnalytics(BIN_TIME_FIELD_BUCKETING);
 
     JSONObject result =
         executeQuery(

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteExpandCommandIT.java

@@ -7,7 +7,7 @@
 
 import static org.opensearch.sql.legacy.TestsConstants.TEST_INDEX_ARRAY;
 import static org.opensearch.sql.legacy.TestsConstants.TEST_INDEX_NESTED_SIMPLE;
-import static org.opensearch.sql.util.AnalyticsRouteLimitation.DOC_MUTATION;
+import static org.opensearch.sql.util.Capability.DOC_MUTATION;
 import static org.opensearch.sql.util.MatcherUtils.rows;
 import static org.opensearch.sql.util.MatcherUtils.schema;
 import static org.opensearch.sql.util.MatcherUtils.verifyDataRows;
@@ -20,6 +20,7 @@
 import org.junit.jupiter.api.Test;
 import org.opensearch.client.Request;
 import org.opensearch.sql.ppl.PPLIntegTestCase;
+import org.opensearch.sql.util.RequiresCapability;
 
 public class CalciteExpandCommandIT extends PPLIntegTestCase {
   @Override
@@ -295,8 +296,8 @@ public void testExpandWithEval() throws Exception {
   }
 
   @Test
+  @RequiresCapability(DOC_MUTATION)
   public void testExpandEmptyArray() throws Exception {
-    assumeNotAnalytics(DOC_MUTATION);
     final int docId = 6;
     Request insertRequest =
         new Request(
@@ -325,8 +326,8 @@ public void testExpandEmptyArray() throws Exception {
   }
 
   @Test
+  @RequiresCapability(DOC_MUTATION)
   public void testExpandOnNullField() throws Exception {
-    assumeNotAnalytics(DOC_MUTATION);
     final int docId = 6;
     Request insertRequest =
         new Request(

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteMultisearchCommandIT.java

@@ -6,8 +6,8 @@
 package org.opensearch.sql.calcite.remote;
 
 import static org.opensearch.sql.legacy.TestsConstants.*;
-import static org.opensearch.sql.util.AnalyticsRouteLimitation.MULTISEARCH_COLUMN_ORDER;
-import static org.opensearch.sql.util.AnalyticsRouteLimitation.MULTISEARCH_SAME_INDEX_CONFLATION;
+import static org.opensearch.sql.util.Capability.MULTISEARCH_COLUMN_ORDER;
+import static org.opensearch.sql.util.Capability.MULTISEARCH_SAME_INDEX_CONFLATION;
 import static org.opensearch.sql.util.MatcherUtils.rows;
 import static org.opensearch.sql.util.MatcherUtils.schema;
 import static org.opensearch.sql.util.MatcherUtils.verifyDataRows;
@@ -18,6 +18,7 @@
 import org.junit.jupiter.api.Test;
 import org.opensearch.client.ResponseException;
 import org.opensearch.sql.ppl.PPLIntegTestCase;
+import org.opensearch.sql.util.RequiresCapability;
 
 public class CalciteMultisearchCommandIT extends PPLIntegTestCase {
 
@@ -66,8 +67,8 @@ public void testMultisearchSuccessRatePattern() throws IOException {
   }
 
   @Test
+  @RequiresCapability(MULTISEARCH_SAME_INDEX_CONFLATION)
   public void testMultisearchWithThreeSubsearches() throws IOException {
-    assumeNotAnalytics(MULTISEARCH_SAME_INDEX_CONFLATION);
     JSONObject result =
         executeQuery(
             String.format(
@@ -83,8 +84,8 @@ public void testMultisearchWithThreeSubsearches() throws IOException {
   }
 
   @Test
+  @RequiresCapability(MULTISEARCH_SAME_INDEX_CONFLATION)
   public void testMultisearchWithComplexAggregation() throws IOException {
-    assumeNotAnalytics(MULTISEARCH_SAME_INDEX_CONFLATION);
     JSONObject result =
         executeQuery(
             String.format(
@@ -146,8 +147,8 @@ public void testMultisearchWithFieldsProjection() throws IOException {
   }
 
   @Test
+  @RequiresCapability(MULTISEARCH_COLUMN_ORDER)
   public void testMultisearchWithTimestampInterleaving() throws IOException {
-    assumeNotAnalytics(MULTISEARCH_COLUMN_ORDER);
     JSONObject result =
         executeQuery(
             "| multisearch [search"
@@ -357,8 +358,8 @@ public void testMultisearchCrossIndexFieldSelection() throws IOException {
 
   /** Reproduce #5145: multisearch without further processing should return all rows. */
   @Test
+  @RequiresCapability(MULTISEARCH_SAME_INDEX_CONFLATION)
   public void testMultisearchWithoutFurtherProcessing() throws IOException {
-    assumeNotAnalytics(MULTISEARCH_SAME_INDEX_CONFLATION);
     JSONObject result =
         executeQuery(
             "| multisearch [search source=opensearch-sql_test_index_time_data | where category ="

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalcitePPLConditionBuiltinFunctionIT.java

@@ -7,10 +7,10 @@
 
 import static org.opensearch.sql.legacy.TestUtils.isIndexExist;
 import static org.opensearch.sql.legacy.TestsConstants.*;
-import static org.opensearch.sql.util.AnalyticsRouteLimitation.CONCAT_NULL_AS_EMPTY;
-import static org.opensearch.sql.util.AnalyticsRouteLimitation.EARLIEST_LATEST_NOW_CLOCK;
-import static org.opensearch.sql.util.AnalyticsRouteLimitation.NESTED_FIELDS;
-import static org.opensearch.sql.util.AnalyticsRouteLimitation.STRUCT_PARENT_FIELD;
+import static org.opensearch.sql.util.Capability.CONCAT_NULL_AS_EMPTY;
+import static org.opensearch.sql.util.Capability.EARLIEST_LATEST_NOW_CLOCK;
+import static org.opensearch.sql.util.Capability.NESTED_FIELDS;
+import static org.opensearch.sql.util.Capability.STRUCT_PARENT_FIELD;
 import static org.opensearch.sql.util.MatcherUtils.*;
 import static org.opensearch.sql.util.MatcherUtils.rows;
 
@@ -20,6 +20,7 @@
 import org.junit.jupiter.api.Test;
 import org.opensearch.client.Request;
 import org.opensearch.sql.ppl.PPLIntegTestCase;
+import org.opensearch.sql.util.RequiresCapability;
 
 public class CalcitePPLConditionBuiltinFunctionIT extends PPLIntegTestCase {
   @Override
@@ -65,18 +66,20 @@ public void testIsNull() throws IOException {
   }
 
   @Test
+  @RequiresCapability(
+      value = STRUCT_PARENT_FIELD,
+      note = "Queries the object/struct parent field 'aws' directly.")
   public void testIsNullWithStruct() throws IOException {
-    // Queries the object/struct parent field 'aws' directly.
-    assumeNotAnalytics(STRUCT_PARENT_FIELD);
     JSONObject actual = executeQuery("source=big5 | where isnull(aws) | fields aws");
     verifySchema(actual, schema("aws", "struct"));
     verifyNumOfRows(actual, 0);
   }
 
   @Test
+  @RequiresCapability(
+      value = NESTED_FIELDS,
+      note = "Queries a nested field; the route strips nested fields at index creation.")
   public void testIsNullWithNested() throws IOException {
-    // Queries a nested field; the route strips nested fields at index creation.
-    assumeNotAnalytics(NESTED_FIELDS);
     JSONObject actual =
         executeQuery(
             String.format(
@@ -139,18 +142,20 @@ public void testIsNotNullWithSingleNotEquals() throws IOException {
   }
 
   @Test
+  @RequiresCapability(
+      value = STRUCT_PARENT_FIELD,
+      note = "Queries the object/struct parent field 'aws' directly.")
   public void testIsNotNullWithStruct() throws IOException {
-    // Queries the object/struct parent field 'aws' directly.
-    assumeNotAnalytics(STRUCT_PARENT_FIELD);
     JSONObject actual = executeQuery("source=big5 | where isnotnull(aws) | fields aws");
     verifySchema(actual, schema("aws", "struct"));
     verifyNumOfRows(actual, 3);
   }
 
   @Test
+  @RequiresCapability(
+      value = NESTED_FIELDS,
+      note = "Queries a nested field; the route strips nested fields at index creation.")
   public void testIsNotNullWithNested() throws IOException {
-    // Queries a nested field; the route strips nested fields at index creation.
-    assumeNotAnalytics(NESTED_FIELDS);
     JSONObject actual =
         executeQuery(
             String.format(
@@ -184,9 +189,11 @@ public void testNullIf() throws IOException {
   }
 
   @Test
+  @RequiresCapability(
+      value = CONCAT_NULL_AS_EMPTY,
+      note =
+          "concat('H', name) over the null-name row diverges (NULL-as-empty vs NULL-propagating).")
   public void testNullIfWithExpression() throws IOException {
-    // concat('H', name) over the null-name row diverges (NULL-as-empty vs NULL-propagating).
-    assumeNotAnalytics(CONCAT_NULL_AS_EMPTY);
     JSONObject actual =
         executeQuery(
             String.format(
@@ -375,9 +382,12 @@ public void testLatest() throws IOException {
   }
 
   @Test
+  @RequiresCapability(
+      value = EARLIEST_LATEST_NOW_CLOCK,
+      note =
+          "earliest('now', utc_timestamp()) resolves true on the route but false on v2 (clock"
+              + " source).")
   public void testEarliestWithEval() throws IOException {
-    // earliest('now', utc_timestamp()) resolves true on the route but false on v2 (clock source).
-    assumeNotAnalytics(EARLIEST_LATEST_NOW_CLOCK);
     JSONObject actual =
         executeQuery(
             String.format(

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalcitePPLEnhancedCoalesceIT.java

@@ -6,15 +6,16 @@
 package org.opensearch.sql.calcite.remote;
 
 import static org.opensearch.sql.legacy.TestsConstants.*;
-import static org.opensearch.sql.util.AnalyticsRouteLimitation.COALESCE_ALL_NULL_OPERANDS;
-import static org.opensearch.sql.util.AnalyticsRouteLimitation.HEAD_WITHOUT_STABLE_SORT;
+import static org.opensearch.sql.util.Capability.COALESCE_ALL_NULL_OPERANDS;
+import static org.opensearch.sql.util.Capability.HEAD_WITHOUT_STABLE_SORT;
 import static org.opensearch.sql.util.MatcherUtils.*;
 
 import java.io.IOException;
 import org.json.JSONObject;
 import org.junit.jupiter.api.Test;
 import org.opensearch.client.Request;
 import org.opensearch.sql.ppl.PPLIntegTestCase;
+import org.opensearch.sql.util.RequiresCapability;
 
 public class CalcitePPLEnhancedCoalesceIT extends PPLIntegTestCase {
   @Override
@@ -38,8 +39,8 @@ public void init() throws Exception {
   }
 
   @Test
+  @RequiresCapability(HEAD_WITHOUT_STABLE_SORT)
   public void testCoalesceBasic() throws IOException {
-    assumeNotAnalytics(HEAD_WITHOUT_STABLE_SORT);
     JSONObject actual =
         executeQuery(
             String.format(
@@ -54,8 +55,8 @@ public void testCoalesceBasic() throws IOException {
   }
 
   @Test
+  @RequiresCapability(HEAD_WITHOUT_STABLE_SORT)
   public void testCoalesceWithMixedTypes() throws IOException {
-    assumeNotAnalytics(HEAD_WITHOUT_STABLE_SORT);
     JSONObject actual =
         executeQuery(
             String.format(
@@ -164,8 +165,8 @@ public void testCoalesceWithMultipleNonExistentFields() throws IOException {
   }
 
   @Test
+  @RequiresCapability(COALESCE_ALL_NULL_OPERANDS)
   public void testCoalesceWithAllNonExistentFields() throws IOException {
-    assumeNotAnalytics(COALESCE_ALL_NULL_OPERANDS);
     JSONObject actual =
         executeQuery(
             String.format(