substrait-explain should support the top-level Plan.advanced_extensions field when parsing and formatting the text format.
This is related to #160, which adds === Header and Plan.version support. Version support should land first so the document-level parser/textifier path has a clear place for top-level plan fields. Plan-level advanced extensions should be a separate issue because their best placement is a distinct syntax decision.
The existing text format already supports relation-level advanced extensions with + Enh: and + Opt: addenda attached below a relation. For the top-level Plan.advanced_extensions field, one option is to place them directly under === Plan, before root relations:
=== Plan
+ Enh:SomePlanEnhancement[...]
+ Opt:SomePlanOptimization[...]
Read[table => col:i32]
That keeps + Enh: / + Opt: attached to the same conceptual area as relation addenda, while using top-level indentation to distinguish plan-level advanced extensions from relation-level ones.
Alternative Placements
One alternative is to put them in === Header, because Plan.advanced_extensions is a top-level Plan field:
=== Header
Version: 0.64.0
Advanced Extensions:
+ Enh:SomePlanEnhancement[...]
+ Opt:SomePlanOptimization[...]
Another alternative is to put them in === Extensions, because the payloads are extension-shaped and registry-backed:
=== Extensions
URNs:
@ 1: extension:io.substrait:functions_arithmetic
Advanced Extensions:
+ Enh:SomePlanEnhancement[...]
+ Opt:SomePlanOptimization[...]
I prefer putting them directly under === Plan because they modify the plan rather than declaring extension anchors or describing decode compatibility, but either alternate is workable if we want all top-level fields in one place.
Acceptance Criteria
- Parse plan-level
+ Enh: / + Opt: lines into Plan.advanced_extensions.
- Format
Plan.advanced_extensions back into text.
- Preserve relation-level advanced extension behavior.
- Add parser/textifier roundtrip coverage.
- Update
GRAMMAR.md and doc tests as needed.
substrait-explainshould support the top-levelPlan.advanced_extensionsfield when parsing and formatting the text format.This is related to #160, which adds
=== HeaderandPlan.versionsupport. Version support should land first so the document-level parser/textifier path has a clear place for top-level plan fields. Plan-level advanced extensions should be a separate issue because their best placement is a distinct syntax decision.The existing text format already supports relation-level advanced extensions with
+ Enh:and+ Opt:addenda attached below a relation. For the top-levelPlan.advanced_extensionsfield, one option is to place them directly under=== Plan, before root relations:That keeps
+ Enh:/+ Opt:attached to the same conceptual area as relation addenda, while using top-level indentation to distinguish plan-level advanced extensions from relation-level ones.Alternative Placements
One alternative is to put them in
=== Header, becausePlan.advanced_extensionsis a top-levelPlanfield:Another alternative is to put them in
=== Extensions, because the payloads are extension-shaped and registry-backed:I prefer putting them directly under
=== Planbecause they modify the plan rather than declaring extension anchors or describing decode compatibility, but either alternate is workable if we want all top-level fields in one place.Acceptance Criteria
+ Enh:/+ Opt:lines intoPlan.advanced_extensions.Plan.advanced_extensionsback into text.GRAMMAR.mdand doc tests as needed.