top and head: allow limit keywords

[Swiddis]

Description

A small set of improvements:

• Allows setting limit=N for head and top, similar to what timechart supports. Helps makes queries slightly more readable if storing them somewhere.
• Adds limit to the available keyword field names (wasn't added by timechart).
• Broke out AstPlanningTest to help split up AstBuilderTest, since that class is pretty large/unwieldy.

Related Issues

N/A

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.

[RyanL1997]

Thanks for the change, in generally LGTM.

[opensearch-trigger-bot]

This PR is stalled because it has been open for 2 weeks with no activity.

[opensearch-trigger-bot]

This PR is stalled because it has been open for 2 weeks with no activity.

[opensearch-trigger-bot]

This PR is stalled because it has been open for 2 weeks with no activity.

[Swiddis]

Closing since this has stalled multiple times, repeatedly gets merge conflicts, & isn't urgent -- can reopen later if it comes up again

[Swiddis]

it came up again.

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit 16ffe92)

Here are some key observations to aid the review process:

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 Multiple PR themes Sub-PR theme: Refactor test base class extraction Relevant files: ppl/src/test/java/org/opensearch/sql/ppl/AstPlanningTestBase.java ppl/src/test/java/org/opensearch/sql/ppl/parser/AstBuilderTest.java ppl/src/test/java/org/opensearch/sql/ppl/parser/AstEquivalenceTest.java ppl/src/test/java/org/opensearch/sql/ppl/rewrite/SpathRewriteTest.java Sub-PR theme: Add limit keyword support to head and top commands Relevant files: ppl/src/main/antlr/OpenSearchPPLParser.g4 docs/user/ppl/cmd/head.md docs/user/ppl/cmd/top.md

⚡ No major issues detected

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Enforce LIMIT requires EQUAL sign The grammar allows LIMIT without EQUAL to be parsed, which could lead to ambiguous parsing. Ensure that when LIMIT is present, EQUAL must follow to avoid parsing conflicts with the optional integer literal. ppl/src/main/antlr/OpenSearchPPLParser.g4 [345-347] headCommand - : HEAD ((LIMIT EQUAL)? number = integerLiteral)? (FROM from = integerLiteral)? + : HEAD ((LIMIT EQUAL number = integerLiteral) | number = integerLiteral)? (FROM from = integerLiteral)? ; Suggestion importance[1-10]: 7 __ Why: The current grammar ((LIMIT EQUAL)? number = integerLiteral)? allows LIMIT without EQUAL, which could create ambiguity. The improved code enforces that when LIMIT is present, EQUAL must follow, making the grammar more explicit and preventing potential parsing conflicts.	Medium

[github-actions]

Persistent review updated to latest commit 16ffe92