Skip to content

clarify none and missing in docs - #7638

Open
mccanne wants to merge 1 commit into
mainfrom
clarify-missing
Open

mccanne wants to merge 1 commit into
mainfrom
clarify-missing

Conversation

@mccanne

@mccanne mccanne commented Nov 10, 2026

Copy link
Copy Markdown
Collaborator

No description provided.

When values of different shapes are described by one type, e.g., after
[type fusion](../type-fusion.md), the type must say which fields are absent
from some of the values. A field of type `int64|missing`, for instance,
is an `int64` where it's present and absent elsewhere.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
is an `int64` where it's present and absent elsewhere.
is an `int64` in the values that include the field and absent from the rest.

I paused for a long time on "present". I'm not sure if my suggested alternative is correct/clearer, though.


The `none` of an [option type](../../formats/model.md#29-option), e.g.,
`none::int64`, isn't a plain `none`. It's a value of its option type, so
it's kept like any other value.

@philrz philrz Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
it's kept like any other value.
it isn't dropped from records, arrays, or the output of `values`.

My Claude paused here because "kept like any other value" could be read as saying none of the "handled quietly" rules above apply to an option-type none. But it still shares some of those behaviors with plain none, as summarized below, hence the narrower wording.

"Handled quietly" rule for plain none Applies to none::int64?
dropped from values output no: none::int64 is output
disappears from records, arrays no: {a?:none::int64}, [1,none::int64]
aggregates skip it mixed: sum(this) skips it, collect(this) keeps it ([1,none::int64])
?? replaces it yes: 5
?. passes it through yes

Comment thread book/src/formats/model.md
Comment on lines +81 to 83
one type, e.g., in a record type formed by
[type fusion](../super-sql/type-fusion.md), the value of
a field that is absent from the original record.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
one type, e.g., in a record type formed by
[type fusion](../super-sql/type-fusion.md), the value of
a field that is absent from the original record.
one type, e.g., a field of a record type formed by
[type fusion](../super-sql/type-fusion.md) that is absent from some of the original records.

Comment on lines +98 to +105
# spq
values {a:1},{b:2} | values a.ok(), a.ok() ?? 0
# input

# expected output
1
1
0

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
# spq
values {a:1},{b:2} | values a.ok(), a.ok() ?? 0
# input
# expected output
1
1
0
# spq
values {a:1},{b:2} | values {input:this, ok:a.ok(), with_default:a.ok() ?? 0}
# input
# expected output
{input:{a:1},ok:1,with_default:1}
{input:{b:2},with_default:0}

I paused a bit at the combination of 2 inputs + 2 values args but only three output values. I think this way may more clearly show where the none is being dropped.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants