Bridge PPL_REX_MAX_MATCH_LIMIT into UnifiedQueryContext on the unified query path

[RyanL1997]

Description

The PPL rex command's AstBuilder reads Settings.Key.PPL_REX_MAX_MATCH_LIMIT unconditionally and unboxes the result to int. On the unified query path, UnifiedQueryContext builds its Settings map with only a small whitelist of planning-required keys; for any unregistered key, getSettingValue returns null and the auto-unbox NPEs the planner before any operator-level capability check runs. Every rex query through /_analytics/ppl hits this NPE today.

This PR ships two changes that together let the unified path execute rex correctly:

1. Default PPL_REX_MAX_MATCH_LIMIT=10 in UnifiedQueryContext

Adds the key to the static settings map so AstBuilder.visitRexCommand no longer NPEs. The value mirrors the cluster-side default of 10 registered by OpenSearchSettings.PPL_REX_MAX_MATCH_LIMIT_SETTING, so unified-path behavior matches v2-path behavior when neither has an explicit cluster override. Mirrors the precedent Kai introduced for CALCITE_ENGINE_ENABLED in #5413.

2. Bridge live cluster settings for PPL_REX_MAX_MATCH_LIMIT only

Without this, every key in the static map resolves to its hardcoded default and _cluster/settings updates are invisible to the unified path. CalciteRexCommandIT.testRexMaxMatchConfigurableLimit exercises this: it sets the cluster-side limit to 5 and asserts that max_match=0 caps at 5, but on the unified path the static 10 keeps winning.

Adds a Builder.liveSettings(Settings) hook so the REST handler can inject the cluster's live OpenSearchSettings instance. At build() time the Builder snapshots the live value of PPL_REX_MAX_MATCH_LIMIT into the static map, overriding the hardcoded default when the operator has set a cluster value. Snapshot-at-build matches the per-HTTP-request lifecycle of UnifiedQueryContext and avoids per-call lookup overhead.

RestUnifiedQueryAction gains a pluginSettings field (the same OpenSearchSettings instance bound in the Guice module) and forwards it to the Builder in both buildContext and buildParsingContext. Both construction sites — SQLPlugin.createSqlAnalyticsRouter and TransportPPLQueryAction.<init> — are updated.

Why scoped to PPL_REX_MAX_MATCH_LIMIT only

The same architectural gap exists for every key in the static map (QUERY_SIZE_LIMIT, PPL_SUBSEARCH_MAXOUT, PPL_JOIN_SUBSEARCH_MAXOUT, CALCITE_ENGINE_ENABLED). For three of those, the static defaults are fine in practice (no test overrides them mid-run; head N covers QUERY_SIZE_LIMIT per-query). CALCITE_ENGINE_ENABLED is intentionally pinned to true for the unified path — a cluster override toggling it off would defeat the point of routing here. So this PR widens only the one key that demonstrably needs it; widening the snapshot to the rest is a future scope decision tied to whichever new IT first depends on it.

Companion PR

opensearch-project/OpenSearch#21550 — onboards PPL rex to DataFusion via the analytics-engine path. Without this PR's fixes, every rex query through /_analytics/ppl NPEs at parse time and never reaches the planner.

Test results

CalciteRexCommandIT through the analytics-engine route (every PPL query forced through /_analytics/ppl via tests.analytics.force_routing=true):

• Without this PR: 0/18 — every test NPEs in AstBuilder.visitRexCommand.
• With change 1 only (default 10): 17/18 — testRexMaxMatchConfigurableLimit fails with expected:<5> but was:<10>.
• With both changes: 18/18, 100% — all testRexMaxMatch* variants honor the cluster setting.

Signed-off-by: Jialiang Liang jiallian@amazon.com

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit aa0ae82)

Here are some key observations to aid the review process:

🧪 No relevant tests

🔒 No security concerns identified

✅ No TODO sections

🔀 No multiple PR themes

⚡ Recommended focus areas for review Possible Issue buildParsingContext now calls applyClusterOverrides, which reads from pluginSettings. If buildParsingContext is invoked before pluginSettings is initialized (e.g., during early initialization or from a code path that doesn't set it), accessing pluginSettings.getSettingValue will throw a NullPointerException. The old implementation was static and had no such dependency. private UnifiedQueryContext buildParsingContext(QueryType queryType) { return applyClusterOverrides(UnifiedQueryContext.builder().language(queryType)).build(); }

[github-actions]

PR Code Suggestions ✨

Latest suggestions up to aa0ae82

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Validate type before using setting value The method retrieves rexLimit as Object but doesn't validate its type before passing it to builder.setting(). If pluginSettings returns an unexpected type (e.g., String instead of Integer), this could cause runtime failures downstream when the value is unboxed. Add type validation or casting to ensure rexLimit is an Integer before using it. plugin/src/main/java/org/opensearch/sql/plugin/rest/RestUnifiedQueryAction.java [184-194] private UnifiedQueryContext.Builder applyClusterOverrides(UnifiedQueryContext.Builder builder) { Object rexLimit = pluginSettings.getSettingValue( org.opensearch.sql.common.setting.Settings.Key.PPL_REX_MAX_MATCH_LIMIT); - if (rexLimit != null) { + if (rexLimit instanceof Integer) { builder.setting( org.opensearch.sql.common.setting.Settings.Key.PPL_REX_MAX_MATCH_LIMIT.getKeyValue(), rexLimit); } return builder; } Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential type safety issue where rexLimit is retrieved as Object and could be an unexpected type. However, the improved code changes the behavior from passing through any non-null value to only passing Integer instances, which may be overly restrictive if the setting system guarantees type consistency. The score reflects a valid defensive programming improvement with moderate impact.	Medium

---

Previous suggestions

Suggestions up to commit c655e4a

Category	Suggestion	Impact
Possible issue	Add type safety for setting value The code retrieves liveRexLimit as Object but PPL_REX_MAX_MATCH_LIMIT expects an Integer. If the settings return a different numeric type (e.g., Long), this could cause a ClassCastException when getSettingValue unboxes to int in AstBuilder.visitRexCommand. Add type validation or safe casting to ensure the value is an Integer before inserting it into defaults. api/src/main/java/org/opensearch/sql/api/UnifiedQueryContext.java [277-282] if (settings != null) { Object liveRexLimit = settings.getSettingValue(PPL_REX_MAX_MATCH_LIMIT); - if (liveRexLimit != null) { + if (liveRexLimit instanceof Integer) { defaults.put(PPL_REX_MAX_MATCH_LIMIT, liveRexLimit); } } Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential type safety issue where liveRexLimit is retrieved as Object and could cause a ClassCastException if it's not an Integer. However, this is primarily a defensive programming improvement rather than a critical bug, as the settings system likely returns the correct type. The score reflects its value as a safety enhancement.	Medium

Suggestions up to commit 6d0dc2c

Category	Suggestion	Impact
Possible issue	Add type validation for setting value The code retrieves liveRexLimit as Object but doesn't validate its type before inserting into the settings map. If getSettingValue returns an unexpected type (e.g., String instead of Integer), this could cause runtime failures when the value is later unboxed to int in AstBuilder.visitRexCommand. Add type validation or safe casting to ensure the value is an Integer before insertion. api/src/main/java/org/opensearch/sql/api/UnifiedQueryContext.java [261-266] if (liveSettings != null) { Object liveRexLimit = liveSettings.getSettingValue(PPL_REX_MAX_MATCH_LIMIT); - if (liveRexLimit != null) { + if (liveRexLimit instanceof Integer) { settings.put(PPL_REX_MAX_MATCH_LIMIT, liveRexLimit); } } Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential type safety issue where liveRexLimit is retrieved as Object and could be an unexpected type. Adding instanceof Integer check prevents runtime failures during unboxing. However, the PR context shows this is a controlled setting value that should already be typed correctly, making this a defensive improvement rather than fixing a critical bug.	Medium
General	Validate pluginSettings parameter for null The constructor accepts pluginSettings but doesn't validate it for null. Since buildParsingContext and buildContext methods call liveSettings(pluginSettings) without null checks, a null pluginSettings parameter could lead to unexpected behavior. Add null validation in the constructor to fail fast with a clear error message. plugin/src/main/java/org/opensearch/sql/plugin/rest/RestUnifiedQueryAction.java [64-73] public RestUnifiedQueryAction( NodeClient client, ClusterService clusterService, QueryPlanExecutor<RelNode, Iterable<Object[]>> planExecutor, org.opensearch.sql.common.setting.Settings pluginSettings) { this.client = client; this.clusterService = clusterService; this.analyticsEngine = new AnalyticsExecutionEngine(planExecutor); - this.pluginSettings = pluginSettings; + this.pluginSettings = Objects.requireNonNull(pluginSettings, "pluginSettings cannot be null"); } Suggestion importance[1-10]: 6 __ Why: The suggestion adds defensive null checking for pluginSettings parameter. While this improves robustness, the PR shows pluginSettings is always instantiated before being passed to the constructor (in SQLPlugin.java and TransportPPLQueryAction.java), making null unlikely. The null check in build() method (line 261) already handles null liveSettings gracefully, so this is a minor defensive improvement.	Low

Suggestions up to commit e46eaa0

Category	Suggestion	Impact
Possible issue	Add type validation before storing setting The code retrieves liveRexLimit as Object and puts it directly into the settings map without type validation. If getSettingValue returns an unexpected type (e.g., String instead of Integer), this could cause runtime ClassCastException when the value is later unboxed to int in AstBuilder.visitRexCommand. api/src/main/java/org/opensearch/sql/api/UnifiedQueryContext.java [251-256] if (liveSettings != null) { Object liveRexLimit = liveSettings.getSettingValue(PPL_REX_MAX_MATCH_LIMIT); - if (liveRexLimit != null) { + if (liveRexLimit instanceof Integer) { settings.put(PPL_REX_MAX_MATCH_LIMIT, liveRexLimit); } } Suggestion importance[1-10]: 7 __ Why: Valid concern about type safety. The code retrieves liveRexLimit as Object and stores it without validation. Adding an instanceof Integer check prevents potential ClassCastException when the value is later unboxed to int in AstBuilder.visitRexCommand. However, this is defensive programming rather than fixing a critical bug, as the Settings implementation should return the correct type.	Medium

Suggestions up to commit 62d617d

Category	Suggestion	Impact
Possible issue	Validate type before storing setting value The code retrieves liveRexLimit as Object but doesn't validate its type before putting it into the settings map. If getSettingValue returns an unexpected type, downstream code expecting an int (as mentioned in the javadoc about unboxing) could fail with a ClassCastException. api/src/main/java/org/opensearch/sql/api/UnifiedQueryContext.java [251-256] if (liveSettings != null) { Object liveRexLimit = liveSettings.getSettingValue(PPL_REX_MAX_MATCH_LIMIT); - if (liveRexLimit != null) { + if (liveRexLimit instanceof Integer) { settings.put(PPL_REX_MAX_MATCH_LIMIT, liveRexLimit); } } Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential type safety issue where liveRexLimit is retrieved as Object without type validation. While the javadoc mentions unboxing to int, adding an instanceof Integer check would prevent potential ClassCastException downstream. However, this is defensive programming rather than fixing a critical bug, as the setting system likely returns the correct type.	Medium

Suggestions up to commit 0f1c8ce

Category	Suggestion	Impact
General	Extract hardcoded default to constant The hardcoded value 10 for PPL_REX_MAX_MATCH_LIMIT creates a maintenance burden and potential inconsistency if the default changes elsewhere. Consider extracting this default value to a constant in SysLimit or the settings definition class, similar to how other limits are accessed via SysLimit.DEFAULT. api/src/main/java/org/opensearch/sql/api/UnifiedQueryContext.java [135-142] private final Map<Settings.Key, Object> settings = new HashMap<Settings.Key, Object>( Map.of( QUERY_SIZE_LIMIT, SysLimit.DEFAULT.querySizeLimit(), PPL_SUBSEARCH_MAXOUT, SysLimit.DEFAULT.subsearchLimit(), PPL_JOIN_SUBSEARCH_MAXOUT, SysLimit.DEFAULT.joinSubsearchLimit(), CALCITE_ENGINE_ENABLED, true, - PPL_REX_MAX_MATCH_LIMIT, 10)); + PPL_REX_MAX_MATCH_LIMIT, SysLimit.DEFAULT.rexMaxMatchLimit())); Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that hardcoding 10 for PPL_REX_MAX_MATCH_LIMIT creates maintenance burden. Extracting to a constant like SysLimit.DEFAULT.rexMaxMatchLimit() would improve consistency with other limits and make future changes easier. However, this is a code quality improvement rather than a critical bug fix.	Medium

[github-actions]

Persistent review updated to latest commit 0f1c8ce

[github-actions]

Persistent review updated to latest commit 62d617d

[github-actions]

Persistent review updated to latest commit e46eaa0

[github-actions]

Persistent review updated to latest commit 6d0dc2c

[github-actions]

Persistent review updated to latest commit c655e4a

[github-actions]

Persistent review updated to latest commit aa0ae82