Skip to content

docs: variadic functions clarification #851

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+3 −14
Open

docs: variadic functions clarification #851

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
74c5958
docs: inconsistent wording about minimum args for variadic functions
lorenarosati Aug 6, 2025
d69c202
docs: inconsistent wording about minimum args for variadic functions
lorenarosati Aug 6, 2025
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
2 changes: 1 addition & 1 deletion site/docs/expressions/scalar_functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ A function is a scalar function if that function takes in values from a single r
| List of arguments | Argument properties are defined below. Arguments can be fully defined or calculated with a type expression. See further details below. | Optional, defaults to niladic. |
| Deterministic | Whether this function is expected to reproduce the same output when it is invoked multiple times with the same input. This informs a plan consumer on whether it can constant-reduce the defined function. An example would be a random() function, which is typically expected to be evaluated repeatedly despite having the same set of inputs. | Optional, defaults to true. |
| Session Dependent | Whether this function is influenced by the session context it is invoked within. For example, a function may be influenced by a user who is invoking the function, the time zone of a session, or some other non-obvious parameter. This can inform caching systems on whether a particular function is cacheable. | Optional, defaults to false. |
| Variadic Behavior | Whether the last argument of the function is variadic or a single argument. If variadic, the argument can optionally have a lower bound (minimum number of instances) and an upper bound (maximum number of instances). | Optional, defaults to single value. |
| Variadic Behavior | Whether the last argument of the function is variadic or a single argument. If variadic, the argument can optionally have a lower bound (minimum number of instances) and an upper bound (maximum number of instances). The lower bound is the minimum specified in the function signature (inclusive) and the upper bound is the maximum specified in the function signature - 1 (exclusive). | Optional, defaults to single value. |
| Nullability Handling | Describes how nullability of input arguments maps to nullability of output arguments. Three options are: `MIRROR`, `DECLARED_OUTPUT` and `DISCRETE`. More details about nullability handling are listed below. | Optional, defaults to `MIRROR` |
| Description | Additional description of function for implementers or users. Should be written human-readable to allow exposure to end users. Presented as a map with language => description mappings. E.g. `{ "en": "This adds two numbers together.", "fr": "cela ajoute deux nombres"}`. | Optional |
| Return Value | The output type of the expression. Return types can be expressed as a fully-defined type or a type expression. See below for more on type expressions. | Required |
Expand Down
15 changes: 2 additions & 13 deletions site/docs/types/type_classes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ parameters:

This specifies a vector that can be either 2- or 3-dimensional. Note however that it's not currently possible to put constraints on data type, string, or (technically) boolean parameters.

Similar to function arguments, the last parameter may be specified to be variadic, allowing it to be specified one or more times instead of only once. For example:
Similar to function arguments, the last parameter may be specified to be variadic, allowing it to be specified zero or more times instead of only once. For example:
Copy link
Member

@EpsilonPrime EpsilonPrime Aug 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So the difference between the last parameter being optional and not optional is no longer relevant? The previous definition basically comes down to two rules:

  1. If the function is variadic then it allows the last argument to be repeated multiple times (i.e. maximum is increased.
  2. If the last argument is optional, then the last argument can be omitted (minimum is now 0).

Copy link
Contributor Author

@lorenarosati lorenarosati Aug 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page was inconsistent with other explanations, which implied that the argument can be specified zero or more times if the minimum is zero. If the explanation with the last parameter being optional is the definition that we want, then other areas should be changed to explain that the argument can be specified one or more times if the minimum is zero. Should I revert to the previous definition and make that consistent instead? @vbarua

Copy link
Member

@vbarua vbarua Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@EpsilonPrime When you say

So the difference between the last parameter being optional

what do you mean? Are you talking about the last argument being nullable? That's not the same as being allowed to omit it entirely.

Thinking about this from a function resolution perspective, I wonder if it makes sense to require at least one argument for all variadic functions. You could imagine having something like:

-
    name: concat_to_string
      - args:
          - value: "varchar<L1>"
            name: "input"
        variadic:
          min: 0
        return: "string"
      - args:
          - value: "string"
            name: "input"
        variadic:
          min: 0
        return: "string"

and if the function call doesn't have any arguments you can't distinguish between the 2. If folks end up wanting the 0 argument variant, they could define it explicitly like:

-
    name: concat_to_string
        return: "string"

In the core spec right now, all variadic functions but and and or require at least 1 argument.

You could make the case that producers should simplify and() directly to true and or() directly to false.


```yaml
name: union
Expand All @@ -175,15 +175,4 @@ parameters:
variadic: true
```

This defines a type that can be parameterized with one or more other data types, for example `union<i32, i64>` but also `union<bool>`. Zero or more is also possible, by making the last argument optional:

```yaml
name: tuple
parameters:
- name: T
type: dataType
optional: true
variadic: true
```

This would also allow for `tuple<>`, to define a zero-tuple.
This defines a type that can be parameterized with zero or more other data types, for example `union<i32, i64>` but also `union<>`.
Loading