Skip to content

docs: clarify nullability explanations #850

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
Open

docs: clarify nullability explanations #850

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2ea9122
docs: expand nullability explanation
lorenarosati Aug 6, 2025
d501497
docs: refined explanations of nullability
lorenarosati Aug 8, 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
4 changes: 2 additions & 2 deletions site/docs/expressions/scalar_functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,9 @@ A producer may specify multiple values for an option. If the producer does so t

| Mode | Description |
| --------------- | ------------------------------------------------------------ |
| MIRROR | This means that the function has the behavior that if at least one of the input arguments are nullable, the return type is also nullable. If all arguments are non-nullable, the return type will be non-nullable. An example might be the `+` function. |
| MIRROR | This means that the function has the behavior that if at least one of the input arguments are nullable, the return type is also nullable. If all arguments are non-nullable, the return type will be non-nullable. The nullability of the expected return type in the function definition can be disregarded, as the nullability of the output is determined by the nullability of the inputs. An example might be the `+` function. |
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.

Beyond the scope of this PR, but I filed #853 to capture the fact that setting the nullability of the return type in these cases is meaningless.

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.

suggestion:
An example might be the + function.
to
An example of a function with MIRROR nullability is the add function

With your addition, I read the example as an example of disregarding the nullability in the definition.

| DECLARED_OUTPUT | Input arguments are accepted of any mix of nullability. The nullability of the output function is whatever the return type expression states. Example use might be the function `is_null()` where the output is always `boolean` independent of the nullability of the input. |
| DISCRETE | The input and arguments all define concrete nullability and can only be bound to the types that have those nullability. For example, if a type input is declared `i64?` and one has an `i64` literal, the `i64` literal must be specifically cast to `i64?` to allow the operation to bind. |
| DISCRETE | DISCRETE nullability follows DECLARED_OUTPUT rules, in the sense that the output nullability must match the return type expression's nullability. However, the input and arguments all define concrete nullability and can only be bound to the types that have those nullability. For example, if a type input is declared `i64?` and one has an `i64` literal, the `i64` literal must be specifically cast to `i64?` to allow the operation to bind. |
Copy link
Contributor

@yongchul yongchul Aug 8, 2025

Choose a reason for hiding this comment

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

nit: follows DECLARED_OUTPUT rules -> follows DECLARED_OUTPUT rule

Copy link
Contributor

@yongchul yongchul Aug 8, 2025

Choose a reason for hiding this comment

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

nit: cast to -> casted to

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.

suggestion:

DISCRETE nullability extends DECLARED_OUTPUT. The output nullability must still match the return type expression's nullability. Additionally, the

Effectively:

  • Removing the in the sense for precision
  • Using Additionally instead of However as the new constraints are additive and not instead of.




Expand Down
Loading