Adding commands
A command touches the parser, the compiler and the catalog. It reaches the engine through IR operators, so most commands need no engine change.
- Syntax. Add the command's node to
pkg/ppl/ast/commands.goand a parse function topkg/ppl/parser/commands.go, dispatched fromparser.command(orparser.sourceCommandfor a source command). Match keywords withatKw/acceptKwso they stay usable as field names, read options withargs, and report errors throughfailso they carry a position and the expected tokens. - Lowering. Handle the node in
compiler.command(pkg/ppl/commands.go) and lower it inpkg/ppl/commands*.goto existing IR operators. Resolve every field against the input schema (resolve), compile expressions withectx, and returnsemanticErr,typeErrorunsupportedFeatureat the offending node. Reject options LynxDB does not execute withunsupportedFeature; never ignore them silently. - New operators, only when needed. When no composition of operators
expresses the semantics, add an operator to
pkg/ir/plan.gowith its schema derivation and label, its validation inpkg/ir/validate.go, its expression listing inpkg/ir/walk.go, its column handling inpkg/ir/opt/prune.goif it should not stop column pruning, and its row operator inpkg/engine/physicalandpkg/engine/pipeline. When the columnar executor should run it too, translate it inpkg/colstore/exec/irplan; an operator that the translation refuses is run by the row operators. - Catalog. Record the support level and notes in
pkg/ppl/catalog.go. Notes state the limitations and deviations from OpenSearch PPL; for an unsupported command they state the reason. - Tests. Add a compile golden pair under
pkg/ppl/testdata/compile(name.ppland the expectedname.ir) and an execution case inpkg/database/execute_test.go. Parser-only cases go inpkg/ppl/parser/corpus_test.go. - Documentation. Regenerate the reference tables with
go run ./internal/docgenand describe the command in the command guide when it is commonly used.
An unsupported command still needs a parse rule (often skipping to the next
|) so that it fails with UNSUPPORTED_COMMAND and its catalog reason
rather than a syntax error.