feat(docs): clarify distinction between enumeration arguments and options by benbellick · Pull Request #1005 · substrait-io/substrait

benbellick · 2026-03-12T16:32:32Z

The spec has two distinct mechanisms for passing fixed-set string values to functions: enumeration arguments and options. The existing docs described options as "similar to a required enumeration" which muddied the distinction. This PR clarifies that enumeration arguments are always required and represent choices core to the function's semantics, while options are always optional and represent engine-level behavioral preferences.

Also removes the misleading add(optional enumeration, ...) example from the extensions index (the add function has options, not enum arguments) and drops the "Required Enumeration" / "optional enumeration" terminology in favor of just "Enumeration".

These changes are being proposed in light of the community sync conversation yesterday (Mar 11, 2026).

Closes #995

Note: These changes were made with Claude's assistance. All code has been reviewed by me.

This change is

…ions

benbellick · 2026-03-12T16:37:48Z

 * Type arguments: arguments that are used only to inform the evaluation and/or type derivation of the function. For example, you might have a function which is `truncate(<type> DECIMAL<P0,S0>, <value> DECIMAL<P1, S1>, <value> i32)`. This function declares two value arguments and a type argument. The difference between them is that the type argument has no value at runtime, while the value arguments do.
-* Enumeration: arguments that support a fixed set of declared values as constant arguments. These arguments must be specified as part of an expression. While these could also have been implemented as constant string value arguments, they are formally included to improve validation/contextual help/etc. for frontend processors and IDEs. An example might be `extract([DAY|YEAR|MONTH], <date value>)`. In this example, a producer must specify a type of date part to extract. Note, the value of a required enumeration cannot be used in type derivation.
+* Enumeration: arguments that require the caller to specify exactly one value from a fixed set of declared string values. They represent choices that are integral to the function's core semantics. An example is `extract([DAY|YEAR|MONTH], <date value>)`, where the caller must specify which date part to extract. Note, the value of an enumeration argument cannot be used in type derivation.



I thought it made sense to drop the line about "while these could also have been implement as constant string..." as I thought that seemed like more of an implementation detail. People are generally familiar with the concept of an enum IMO.

I actually do not want to use string but somehow declare the enum in the YAML and reference... The key idea remains the same though.

benbellick · 2026-03-12T16:39:15Z

 | Name        | A human-readable name for this argument to help clarify use.        | Optional, defaults to a name based on position (e.g. `arg0`) |
 | Description | Additional description of this argument.                            | Optional                                                   |

-#### Required Enumeration Properties


Consistent with the above now.

benbellick · 2026-03-12T16:41:57Z

+
 | Function Signature                                | Function Name       |
 | ------------------------------------------------- | ------------------- |
-| `add(optional enumeration, i8, i8) => i8`         | `add:i8_i8`         |


add doesn't take an enum, it takes an option. It is confusing to refer to this as an "optional enumeration"

yongchul · 2026-03-19T06:39:00Z

+
+!!! warning "YAML keyword overlap"
+
+    In the YAML extension format, both enumeration arguments and function-level options use the keyword `options`. An enumeration argument appears inside `args` as `options: [VAL1, VAL2, ...]`, while a function-level option appears under a top-level `options` key with named sub-keys and a `values` list. Take care not to confuse the two when reading or writing extension YAML files.


I am confused. 😆 perhaps a short snippet with comment would work?

Sorry getting back to you late here. I can include an example. Another option would be to just drop this section entirely and open up a ticket to make this more clear in the future. As an example here:

- name: "add" description: "Add two values." impls: - args: - name: x value: i8 - name: y value: i8 options: # this is an option overflow: values: [ SILENT, SATURATE, ERROR ] return: i8

- name: extract # ... - args: - name: component options: [ YEAR, ISO_YEAR, US_YEAR, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, SUBSECOND, UNIX_TIME ] # and this is an enum description: The part of the value to extract. - name: x value: timestamp

I was just trying to call out that both use the YAML key name options which could be confusing 🤔

…ums-vs-options # Conflicts: # site/docs/extensions/index.md

yongchul · 2026-05-13T18:48:03Z

 * Type arguments: arguments that are used only to inform the evaluation and/or type derivation of the function. For example, you might have a function which is `truncate(<type> DECIMAL<P0,S0>, <value> DECIMAL<P1, S1>, <value> i32)`. This function declares two value arguments and a type argument. The difference between them is that the type argument has no value at runtime, while the value arguments do.
-* Enumeration: arguments that support a fixed set of declared values as constant arguments. These arguments must be specified as part of an expression. While these could also have been implemented as constant string value arguments, they are formally included to improve validation/contextual help/etc. for frontend processors and IDEs. An example might be `extract([DAY|YEAR|MONTH], <date value>)`. In this example, a producer must specify a type of date part to extract. Note, the value of a required enumeration cannot be used in type derivation.
+* Enumeration: arguments that require the caller to specify exactly one value from a fixed set of declared string values. They represent choices that are integral to the function's core semantics. An example is `extract([DAY|YEAR|MONTH], <date value>)`, where the caller must specify which date part to extract. Note, the value of an enumeration argument cannot be used in type derivation.



I actually do not want to use string but somehow declare the enum in the YAML and reference... The key idea remains the same though.

yongchul · 2026-05-13T19:28:14Z

+| Required? | Yes, must be specified by the producer | No, may be omitted |
+| Semantics | Core to the function's operation (e.g., which date component to extract) | Behavioral preference for corner cases or engine-specific behavior (e.g., overflow handling) |
+| Position | Positional, part of the argument list | Named, separate from arguments |
+| In function signature? | Yes (as `req`) | No |


perhaps we may revisit this req at some point...

yongchul · 2026-05-13T19:30:21Z

+1. I see a couple of follow ups but not a blocker for this PR.

feat(docs): clarify distinction between enumeration arguments and opt…

790fd80

…ions

benbellick commented Mar 12, 2026

View reviewed changes

benbellick marked this pull request as ready for review March 12, 2026 16:44

benbellick requested review from EpsilonPrime, cpcloud, jacques-n, vbarua, westonpace and yongchul as code owners March 12, 2026 16:44

nielspardon reviewed Mar 16, 2026

View reviewed changes

Comment thread site/docs/expressions/scalar_functions.md

nielspardon mentioned this pull request Mar 17, 2026

fix(extensions): add signatures with distribution enum arg for std_dev and variance #1011

Merged

docs: add warning about YAML keyword overlap between enums and options

583bc2c

yongchul approved these changes Mar 19, 2026

View reviewed changes

benbellick mentioned this pull request Mar 23, 2026

feat(extensions): add subscript_operator and index_of functions #1020

Open

benbellick added 2 commits May 13, 2026 14:10

Merge remote-tracking branch 'origin/main' into benbellick/clarify-en…

1612bfe

…ums-vs-options # Conflicts: # site/docs/extensions/index.md

docs: clarify YAML options keyword overlap

2c3f608

yongchul approved these changes May 13, 2026

View reviewed changes

benbellick merged commit 51ff9fa into main May 14, 2026
14 checks passed

benbellick deleted the benbellick/clarify-enums-vs-options branch May 14, 2026 14:35

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): clarify distinction between enumeration arguments and options#1005

feat(docs): clarify distinction between enumeration arguments and options#1005
benbellick merged 4 commits into
mainfrom
benbellick/clarify-enums-vs-options

benbellick commented Mar 12, 2026 •

edited by jacques-n

Loading

Uh oh!

benbellick Mar 12, 2026

Uh oh!

yongchul May 13, 2026

Uh oh!

benbellick Mar 12, 2026

Uh oh!

benbellick Mar 12, 2026

Uh oh!

Uh oh!

yongchul Mar 19, 2026

Uh oh!

benbellick Apr 1, 2026

Uh oh!

yongchul May 13, 2026

Uh oh!

yongchul May 13, 2026

Uh oh!

yongchul commented May 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		!!! warning "YAML keyword overlap"

		In the YAML extension format, both enumeration arguments and function-level options use the keyword `options`. An enumeration argument appears inside `args` as `options: [VAL1, VAL2, ...]`, while a function-level option appears under a top-level `options` key with named sub-keys and a `values` list. Take care not to confuse the two when reading or writing extension YAML files.

Conversation

benbellick commented Mar 12, 2026 • edited by jacques-n Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yongchul commented May 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

benbellick commented Mar 12, 2026 •

edited by jacques-n

Loading