Skip to content

docs: clarify output schema handling for extension relations #1018

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benbellick merged 1 commit into from
May 6, 2026
+10 −3
Merged

docs: clarify output schema handling for extension relations #1018

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions proto/substrait/algebra.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -447,20 +447,23 @@ message SetRel {
}
}

// Stub to support extension with a single input
// A custom relational operator with a single input. Producers and consumers
// must agree on how to derive the output schema of the relation.
message ExtensionSingleRel {
RelCommon common = 1;
Rel input = 2;
google.protobuf.Any detail = 3;
}

// Stub to support extension with a zero inputs
// A custom relational operator with zero inputs. Producers and consumers
// must agree on how to derive the output schema of the relation.
message ExtensionLeafRel {
RelCommon common = 1;
google.protobuf.Any detail = 2;
}

// Stub to support extension with multiple inputs
// A custom relational operator with multiple inputs. Producers and consumers
// must agree on how to derive the output schema of the relation.
message ExtensionMultiRel {
RelCommon common = 1;
repeated Rel inputs = 2;
Expand Down
4 changes: 4 additions & 0 deletions site/docs/extensions/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,10 @@ The third form of advanced extensions provides entirely new relational operation

These extension relations are first-class relation types in Substrait and can be used anywhere a standard relation would be used.

#### Output Schema

Unlike standard relations, Substrait cannot specify how to derive the output schema of extension relations. It is up to producers and consumers to agree on how to derive the schema from the inputs and the `detail` field. This derivation should be documented in the protobuf definition (or equivalent) used for the `detail` field.

### When to Use What

Custom relations are the most flexible option, but also the least interoperable. Prefer enhancements to existing relations when they can express your use case, since this preserves existing patterns and compatibility. As a general rule, choose the least powerful extension mechanism that solves the problem.
Loading