opensearch-project / opensearch-project/sql
[FEATURE] Reduce boilerplate for adding new PPL commands and functions
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 176
- Forks
- 229
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 43
Description
Is your feature request related to a problem?
Adding new PPL commands or functions requires extensive boilerplate code across multiple layers of the codebase, making it error-prone and time-consuming. Developers must manually:
- Update ANTLR grammar files (lexer and parser)
- Create AST node classes and implement AST/RelNode visitor pattern methods
- Register functions in multiple locations (PPLBuiltinOperators, PPLFuncImpTable, BuiltinFunctionName)
- Create unit tests that validate the translation pipeline and Spark SQL generated
- Create multiple integration test classes (IT, Yaml IT, ExplainIT, AnonymousIT, CrossClusterIT)
- Remember engine-specific setup (e.g.,
enableCalcite()for V3-only functions) - Update documentation following the latest doc structure
This repetitive process leads to:
- Human errors: Easy to miss required steps or files - some are subtle even if reference similar PRs.
- Inconsistency: Different developers may structure code differently.
- Slow onboarding: New contributors face a steep learning curve.
- Maintenance burden: Changes to architecture require updating many files.
What solution would you like?
Below are several ideas that address the problem from different levels (tooling, specs, and architecture):
-
Interactive scaffolding tool: Add a Gradle task that generates the required files and code insertions from a few prompts, with a strict “expected files changed” checklist to prevent missed steps (human or AI) and copy-paste drift.
-
Spec-driven code generation: Define a YAML/Markdown spec as the single source of truth for commands/functions (metadata, signatures, engine support, tests/docs) and generate the repetitive glue at build time—AI-friendly by design.
-
Better abstractions: Introduce a small DSL for AST → RelNode translation and shared test base classes/mixins to standardize setup. This reduces long-term maintenance and makes both scaffolding and codegen simpler and safer.
What alternatives have you considered?
- Better documentation only: Document the process better, but doesn't prevent human errors
- Copy-paste from examples: Current approach, leads to inconsistencies and forgotten steps
- Code review checklists: Helpful but reactive - catches errors after they're made
Do you have any additional context?
- This issue was motivated by where backport PR failure below due to missing
enableCalcite(). However, more broadly, it highlights a recurring friction point in PPL development: adding new PPL features requires too much scattered, easy-to-miss boilerplate, and we should improve the end-to-end developer workflow to make contributions safer and more consistent.- #4947
- #4959
- Success metrics may include:
- Time to add new PPL command/function reduced by X%+
- New contributors can onboard and ship first PR within X days
- Consistent code structure across all commands/functions
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review related issues #4947 and #4959, then trace the ANTLR grammar, AST/RelNode visitor, registration points, and integration-test classes listed in the issue. Define a bounded first milestone and its expected files or checklist; done should include an agreed approach and evidence that adding a command or function requires less repetitive work.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, spark
- Domain
- build-system, developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100