The spec provides two mechanisms for functions to accept a choice from a set of values, enum arguments and function options, but doesn't document when to use which. Both are used in core extensions but the extensions docs only show enum arguments in signature examples without explaining the distinction.
For example, extract uses an enum argument for the component:
|
- args: |
|
- name: component |
|
options: [ YEAR, ISO_YEAR, US_YEAR, HOUR, MINUTE, SECOND, |
|
MILLISECOND, MICROSECOND, SUBSECOND, PICOSECOND, UNIX_TIME, TIMEZONE_OFFSET ] |
|
description: The part of the value to extract. |
|
- name: x |
While add uses a function option for overflow behavior:
|
value: i8 |
|
options: |
|
overflow: |
|
values: [ SILENT, SATURATE, ERROR ] |
|
return: i8 |
They also look very similar in YAML, with both using the keyword options.
The extensions docs should clarify the difference between these two mechanisms and provide guidance on when to use each.
Related: #254
The spec provides two mechanisms for functions to accept a choice from a set of values, enum arguments and function options, but doesn't document when to use which. Both are used in core extensions but the extensions docs only show enum arguments in signature examples without explaining the distinction.
For example,
extractuses an enum argument for the component:substrait/extensions/functions_datetime.yaml
Lines 71 to 76 in e4ce3f8
While
adduses a function option for overflow behavior:substrait/extensions/functions_arithmetic.yaml
Lines 13 to 17 in e4ce3f8
They also look very similar in YAML, with both using the keyword
options.The extensions docs should clarify the difference between these two mechanisms and provide guidance on when to use each.
Related: #254