Struct UnionVariants 

pub struct UnionVariants(/* private fields */);

Type information for a union array.

A UnionVariants describes the possible alternative types for each row of a union, along with a per-variant u8 type tag. We use the term variants (rather than “fields”) because a union is a sum type: each row chooses exactly one alternative.

By default, tag i selects the child at offset i (type_ids = [0, 1, ..., N-1]). Vortex uses unsigned tags and supports up to 256 variants.

Schemas may also use non-consecutive tags (e.g. [0, 5, 7]), in which case the value of type_ids[i] is the tag used in the data to select the child at offset i. Supporting non-consecutive tags lets the schema remove children without renumbering the remaining tags.

Variant names must be distinct. Unlike StructFields, which permits duplicate field names for Arrow/Parquet round-trip fidelity, duplicates have no meaningful semantics in a sum type and are rejected at construction.

Note that the Arrow spec does not require distinct names (children are selected by the type-id buffer, never by name), but DuckDB requires distinct member names for its UNION type and resolves members by name (e.g. in union_extract), so permitting duplicates would break DuckDB round-trips while enabling no useful semantics.

use vortex_array::dtype::{DType, Nullability, PType, UnionVariants};

let variants = UnionVariants::new(
    ["a", "b"].into(),
    vec![
        DType::Primitive(PType::I32, Nullability::NonNullable),
        DType::Utf8(Nullability::NonNullable),
    ],
)
.unwrap();

assert_eq!(variants.len(), 2);
assert_eq!(variants.type_ids(), &[0, 1]);

Implementations

impl UnionVariants

pub fn empty() -> Self

The variants of the empty union.

pub fn try_new( names: FieldNames, dtypes: Vec<DType>, type_ids: Vec<u8>, ) -> VortexResult<Self>

Create a new UnionVariants with explicit type_ids.

Errors

Returns an error if names, dtypes, or type IDs do not all have the same length, or if there are any duplicate names or type IDs, or if there are more than 256 variants.

pub fn new(names: FieldNames, dtypes: Vec<DType>) -> VortexResult<Self>

Create a new UnionVariants with consecutive type_ids = [0, 1, ..., N-1].

Errors

names and dtypes must have the same length, and names.len() cannot be more than u8::MAX as usize + 1 (256).

pub fn names(&self) -> &FieldNames

Get the names of the variants in the union.

pub fn len(&self) -> usize

Returns the number of variants in the union.

pub fn is_empty(&self) -> bool

Returns true if the union has no variants.

pub fn type_ids(&self) -> &[u8]

Returns the per-variant type tag vector. Entry i is the tag that the data uses to select the variant at offset i.

pub fn is_consecutive(&self) -> bool

Returns true if the type tags are the consecutive sequence [0, 1, ..., N-1].

pub fn find(&self, name: impl AsRef<str>) -> Option<usize>

Find the offset of a variant by name. Returns None if no variant has the name.

This is a linear scan over Self::names. A union has at most 256 variants (and usually far fewer), so a linear scan beats building and probing a HashMap in practice.

pub fn variant(&self, name: impl AsRef<str>) -> Option<DType>

Get the DType of a variant by name. Returns None if no variant has the name.

pub fn variant_by_index(&self, index: usize) -> Option<DType>

Get the DType of a variant by offset.

pub fn variants(&self) -> impl ExactSizeIterator<Item = DType> + '_

Returns an ordered iterator over the variants.

pub fn tag_to_child_index(&self, tag: u8) -> Option<usize>

Convert a data-level type tag to a child offset. Returns None if the tag is not in type_ids.

This is a linear scan over Self::type_ids. The number of variants is bounded by 256, so a linear scan is faster than a HashMap lookup in practice for the small unions typically encountered.

pub fn child_index_to_tag(&self, index: usize) -> u8

Convert a child offset to its data-level type tag.

Panics

Panics if index >= self.len().

Trait Implementations

impl Clone for UnionVariants

fn clone(&self) -> UnionVariants

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UnionVariants

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for UnionVariants

fn default() -> Self

Returns the “default value” for a type.

impl Display for UnionVariants

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for UnionVariants

impl Hash for UnionVariants

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for UnionVariants

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for UnionVariants

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.