Set max=1 in join as default when plugins.ppl.syntax.legacy.preferred=false

[LantaoJin]

Description

For performance purpose, set max=1 in join as default when plugins.ppl.syntax.legacy.preferred=false

Related Issues

#5056

Check List

• New functionality includes testing.
• New functionality has been documented.
• New functionality has javadoc added.
• New functionality has a user manual doc added.
• New PPL command checklist all confirmed.
• API changes companion pull request created.
• Commits are signed per the DCO using --signoff or -s.
• Public documentation issue/PR created.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation

  • Updated join command and admin settings documentation regarding max parameter defaults.

• Features

  • Join command max parameter now has a conditional default value based on syntax preference configuration.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

The changes introduce conditional default value behavior for the join command's max parameter based on a new plugins.ppl.syntax.legacy.preferred setting. When legacy mode is disabled, the parser injects a default max value of 1. Documentation is updated accordingly, and comprehensive tests validate both legacy and non-legacy execution paths.

Changes

Cohort / File(s)	Summary
Documentation docs/user/ppl/admin/settings.md, docs/user/ppl/cmd/join.md	Added note about default value for max in join command; clarified that default is 0 (unlimited) in legacy mode and 1 in non-legacy mode.
Core Logic ppl/src/main/java/org/opensearch/sql/ppl/parser/AstBuilder.java	Conditionally injects default max argument with value 1 in visitJoinCommand when legacy mode is not preferred and no explicit max argument exists.
Unit Tests ppl/src/test/java/org/opensearch/sql/ppl/calcite/CalcitePPLJoinTest.java	Added testJoinWhenLegacyNotPreferred() to validate join query execution and output when legacy syntax is disabled.
Integration Tests integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteExplainIT.java, CalcitePPLJoinIT.java	Added integration tests testJoinWhenLegacyNotPreferred() in both classes to validate join behavior, explain plans, and schema when legacy mode is disabled.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

testing

Suggested reviewers

• ps48
• kavithacm
• penghuo
• ykmr1224
• joshuali925
• anirudha
• yuancu
• derek-ho
• Swiddis

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: setting a default max=1 for join commands when legacy syntax is not preferred.
Description check	✅ Passed	The description is related to the changeset, explaining the performance rationale for setting max=1 as default in join when legacy mode is disabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In
`@integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalcitePPLJoinIT.java`:
- Around line 882-928: The first query in testJoinWhenLegacyNotPreferred (the
executeQuery that sets actual) only verifies schema but not that the join
defaulted to max=1; add a data assertion after verifySchema that calls
verifyDataRows against actual to assert the returned rows reflect max=1 behavior
(use the same expected single-row-per-key results as in the second query, but
include all columns checked in schema: name, age, state, country, year, month,
occupation, salary). Locate the test method testJoinWhenLegacyNotPreferred and
the executeQuery/verifySchema calls to insert the verifyDataRows(actual, ...)
call immediately after verifySchema to validate the new default max logic.

[yuancu]

LGTM

[opensearch-trigger-bot]

The backport to 2.19-dev failed:

The process '/usr/bin/git' failed with exit code 128

To backport manually, run these commands in your terminal:

# Navigate to the root of your repository
cd $(git rev-parse --show-toplevel)
# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add ../.worktrees/sql/backport-2.19-dev 2.19-dev
# Navigate to the new working tree
pushd ../.worktrees/sql/backport-2.19-dev
# Create a new branch
git switch --create backport/backport-5057-to-2.19-dev
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 d31769dd37b44f8c61ee10f71fd016b8ce4d2401
# Push it to GitHub
git push --set-upstream origin backport/backport-5057-to-2.19-dev
# Go back to the original working tree
popd
# Delete the working tree
git worktree remove ../.worktrees/sql/backport-2.19-dev

Then, create a pull request where the base branch is 2.19-dev and the compare/head branch is backport/backport-5057-to-2.19-dev.