Skip to content

Support plan-level AdvancedExtension in the text format #161

Description

@wackywendell

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions