Skip to content

GH-22342: [Format][Documentation] Clarify Union type ids #50839

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

Merged
pitrou merged 4 commits into from
Oct 6, 2026
Merged

GH-22342: [Format][Documentation] Clarify Union type ids #50839

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bb88474
GH-22342: [C++] [Documentation] Clarify Union type ids
erichanwang Aug 10, 2026
a6bedc2
GH-22342: [C++] [Documentation] Wrap Union type id text
erichanwang Aug 10, 2026
659c116
Clarify terminology
pitrou Oct 6, 2026
6b3e358
Clarify terminology
pitrou Oct 6, 2026
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
14 changes: 10 additions & 4 deletions docs/source/format/Columnar.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -864,6 +864,12 @@ A union is defined by an ordered sequence of types; each slot in the
union can have a value chosen from these types. The types are named
like a struct's fields, and the names are part of the type metadata.

Each child type in a union has a logical type id (an 8-bit signed integer)
that identifies it in the types buffer. By default, these type ids
correspond directly to the child array indices (0, 1, ...), but an optional
``typeIds`` metadata array can provide an explicit mapping from child array

@tustvold tustvold Sep 17, 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.

It isn't clear from this how they actually do this, I think an example would make it clear.

@paleolimbot paleolimbot Sep 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Also possibly calling it just typeIds metadata (the term "array" here I believe is talking about a different kind of array than it is later in the paragraph)

index to type id.

Unlike other data types, unions do not have their own validity bitmap. Instead,
the nullness of each slot is determined exclusively by the child arrays which
are composed to create the union.
Expand All @@ -878,10 +884,10 @@ Dense union represents a mixed-type array with 5 bytes of overhead for
each value. Its physical layout is as follows:

* One child array for each type
* Types buffer: A buffer of 8-bit signed integers. Each type in the
union has a corresponding type id whose values are found in this
buffer. A union with more than 128 possible types can be modeled as
a union of unions.
* Types buffer: A buffer of 8-bit signed integers, indicating the logical type
id of each slot. Note that these type ids are not necessarily the
same as the child array index (see above). A union with more than 128
Comment thread
pitrou marked this conversation as resolved.
possible types can be modeled as a union of unions.
* Offsets buffer: A buffer of signed Int32 values indicating the
relative offset into the respective child array for the type in a
given slot. The respective offsets for each child value array must
Expand Down
Loading