Skip to main content

vortex_array/scalar_fn/fns/variant_get/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::fmt;
5use std::fmt::Display;
6use std::fmt::Formatter;
7
8use itertools::Itertools;
9use prost::Message;
10use vortex_error::VortexResult;
11use vortex_error::vortex_ensure;
12use vortex_error::vortex_err;
13use vortex_session::VortexSession;
14use vortex_session::registry::CachedId;
15use vortex_utils::aliases::StringEscape;
16
17use crate::ArrayRef;
18use crate::ExecutionCtx;
19use crate::IntoArray;
20use crate::arrays::ChunkedArray;
21use crate::arrays::ConstantArray;
22use crate::arrays::ScalarFnArray;
23use crate::arrays::VariantArray;
24use crate::builders::builder_with_capacity_in;
25use crate::dtype::DType;
26use crate::dtype::FieldName;
27use crate::dtype::Nullability;
28use crate::expr::display::ExprDisplay;
29use crate::proto::expr as pb;
30use crate::proto::expr::variant_path_element;
31use crate::scalar::Scalar;
32use crate::scalar_fn::Arity;
33use crate::scalar_fn::ChildName;
34use crate::scalar_fn::ExecutionArgs;
35use crate::scalar_fn::ScalarFnId;
36use crate::scalar_fn::ScalarFnVTable;
37use crate::scalar_fn::ScalarFnVTableExt;
38
39/// Extracts a field/index path from Variant values.
40///
41/// Missing paths, type mismatches while traversing, and failed casts produce nulls. Without a
42/// requested dtype, results are returned as nullable Variant values; with one, results are cast to
43/// that dtype with nullable nullability. Encodings may serve perfectly shredded paths directly,
44/// but must fall back to the core Variant value for paths not represented by shredded storage.
45#[derive(Clone)]
46pub struct VariantGet;
47
48impl VariantGet {
49    /// Creates a lazy extraction from Variant `input`.
50    ///
51    /// # Errors
52    ///
53    /// Returns an error if `input` is not Variant data.
54    pub fn try_new(input: ArrayRef, options: VariantGetOptions) -> VortexResult<ScalarFnArray> {
55        ScalarFnArray::try_new(VariantGet.bind(options), [input])
56    }
57}
58
59impl ScalarFnVTable for VariantGet {
60    type Options = VariantGetOptions;
61
62    fn id(&self) -> ScalarFnId {
63        static ID: CachedId = CachedId::new("vortex.variant_get");
64        *ID
65    }
66
67    fn serialize(&self, options: &Self::Options) -> VortexResult<Option<Vec<u8>>> {
68        let path = options
69            .path()
70            .elements()
71            .iter()
72            .map(VariantPathElement::to_proto)
73            .collect();
74        let dtype = options.dtype().map(TryInto::try_into).transpose()?;
75
76        Ok(Some(pb::VariantGetOpts { path, dtype }.encode_to_vec()))
77    }
78
79    fn deserialize(&self, metadata: &[u8], session: &VortexSession) -> VortexResult<Self::Options> {
80        let opts = pb::VariantGetOpts::decode(metadata)?;
81        let path = opts
82            .path
83            .into_iter()
84            .map(VariantPathElement::from_proto)
85            .collect::<VortexResult<_>>()?;
86        let dtype = opts
87            .dtype
88            .as_ref()
89            .map(|dtype| DType::from_proto(dtype, session))
90            .transpose()?;
91
92        Ok(VariantGetOptions::new(path, dtype))
93    }
94
95    fn arity(&self, _options: &Self::Options) -> Arity {
96        Arity::Exact(1)
97    }
98
99    fn child_name(&self, _options: &Self::Options, child_idx: usize) -> ChildName {
100        match child_idx {
101            0 => ChildName::from("input"),
102            _ => unreachable!("Invalid child index {child_idx} for VariantGet expression"),
103        }
104    }
105
106    fn fmt_sql(
107        &self,
108        options: &Self::Options,
109        expr: &dyn ExprDisplay,
110        f: &mut Formatter<'_>,
111    ) -> fmt::Result {
112        write!(f, "variant_get(")?;
113        Display::fmt(expr.display_child(0), f)?;
114        let path = options.path().to_string();
115        write!(f, ", \"{}\"", StringEscape(&path))?;
116        if let Some(dtype) = options.dtype() {
117            write!(f, ", {dtype}")?;
118        }
119        write!(f, ")")
120    }
121
122    fn return_dtype(&self, options: &Self::Options, arg_dtypes: &[DType]) -> VortexResult<DType> {
123        let input_dtype = &arg_dtypes[0];
124        vortex_ensure!(
125            matches!(input_dtype, DType::Variant(_)),
126            "VariantGet input must be Variant, found {input_dtype}"
127        );
128
129        // Missing paths, traversal mismatches, and cast failures all produce nulls.
130        Ok(options
131            .dtype()
132            .map_or(DType::Variant(Nullability::Nullable), DType::as_nullable))
133    }
134
135    fn execute(
136        &self,
137        options: &Self::Options,
138        args: &dyn ExecutionArgs,
139        ctx: &mut ExecutionCtx,
140    ) -> VortexResult<ArrayRef> {
141        let input = args.get(0)?;
142        // Missing paths, traversal mismatches, and cast failures all produce nulls.
143        let dtype = options
144            .dtype()
145            .map_or(DType::Variant(Nullability::Nullable), DType::as_nullable);
146
147        if !dtype.is_variant() {
148            let mut builder = builder_with_capacity_in(&dtype, input.len(), ctx.allocator());
149            for idx in 0..input.len() {
150                let scalar = input.execute_scalar(idx, ctx)?;
151                let output = variant_get_scalar(&scalar, options, &dtype)?;
152                builder.append_scalar(&output)?;
153            }
154
155            return Ok(builder.finish());
156        }
157
158        // TODO(variant): replace this with a Variant builder once one exists.
159        // Chunked<Variant> canonicalizes to VariantArray, so this row-wise fallback is safe.
160        let chunks = (0..input.len()).map(|idx| -> VortexResult<_> {
161            let scalar = input.execute_scalar(idx, ctx)?;
162            let output = variant_get_scalar(&scalar, options, &dtype)?;
163            Ok(ConstantArray::new(output, 1).into_array())
164        });
165        let array = chunks.process_results(|chunks| {
166            // SAFETY: each output scalar is constructed with the requested variant dtype.
167            unsafe { ChunkedArray::new_unchecked_sized(chunks, dtype.clone(), input.len()) }
168                .into_array()
169        })?;
170        VariantArray::try_new(array, None).map(|array| array.into_array())
171    }
172
173    fn is_strict(&self, _options: &Self::Options) -> bool {
174        true
175    }
176}
177
178fn variant_get_scalar(
179    scalar: &Scalar,
180    options: &VariantGetOptions,
181    output_dtype: &DType,
182) -> VortexResult<Scalar> {
183    let Some(value) = variant_path_scalar(scalar, options.path().elements())? else {
184        return Ok(Scalar::null(output_dtype.clone()));
185    };
186
187    if options.dtype().is_none_or(DType::is_variant) {
188        return Scalar::variant(value).cast(output_dtype);
189    }
190
191    if value.is_null() {
192        return Ok(Scalar::null(output_dtype.clone()));
193    }
194
195    value
196        .cast(output_dtype)
197        .or_else(|_| Ok(Scalar::null(output_dtype.clone())))
198}
199
200fn variant_path_scalar(
201    scalar: &Scalar,
202    path: &[VariantPathElement],
203) -> VortexResult<Option<Scalar>> {
204    let mut current = match variant_payload(scalar.clone()) {
205        Some(value) => value,
206        None => return Ok(None),
207    };
208
209    for element in path {
210        current = match variant_payload(current) {
211            Some(value) => value,
212            None => return Ok(None),
213        };
214
215        if current.is_null() {
216            return Ok(None);
217        }
218
219        current = match element {
220            VariantPathElement::Field(name) => {
221                let Some(struct_scalar) = current.as_struct_opt() else {
222                    return Ok(None);
223                };
224                if struct_scalar.is_null() {
225                    return Ok(None);
226                }
227                let Some(field) = struct_scalar.field(name.as_ref()) else {
228                    return Ok(None);
229                };
230                field
231            }
232            VariantPathElement::Index(index) => {
233                let Ok(index) = usize::try_from(*index) else {
234                    return Ok(None);
235                };
236                let Some(list_scalar) = current.as_list_opt() else {
237                    return Ok(None);
238                };
239                let Some(element) = list_scalar.element(index) else {
240                    return Ok(None);
241                };
242                element
243            }
244        };
245    }
246
247    Ok(variant_payload(current))
248}
249
250fn variant_payload(scalar: Scalar) -> Option<Scalar> {
251    if scalar.dtype().is_variant() {
252        scalar.as_variant().value().cloned()
253    } else {
254        Some(scalar)
255    }
256}
257
258/// Options for [`VariantGet`].
259#[derive(Clone, Debug, PartialEq, Eq, Hash)]
260pub struct VariantGetOptions {
261    path: VariantPath,
262    dtype: Option<DType>,
263}
264
265impl VariantGetOptions {
266    /// Creates options for extracting `path`, returning Variant values when `dtype` is `None`.
267    pub fn new(path: VariantPath, dtype: Option<DType>) -> Self {
268        Self { path, dtype }
269    }
270
271    /// Returns the path to extract.
272    pub fn path(&self) -> &VariantPath {
273        &self.path
274    }
275
276    /// Returns the requested output dtype, if any.
277    pub fn dtype(&self) -> Option<&DType> {
278        self.dtype.as_ref()
279    }
280}
281
282impl Display for VariantGetOptions {
283    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
284        write!(f, "{}", self.path)?;
285        if let Some(dtype) = &self.dtype {
286            write!(f, " as {dtype}")?;
287        }
288        Ok(())
289    }
290}
291
292/// A strict Variant path made from object fields and list indexes.
293#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
294pub struct VariantPath(Vec<VariantPathElement>);
295
296impl VariantPath {
297    /// Creates a path from explicit elements.
298    pub fn new(elements: impl IntoIterator<Item = VariantPathElement>) -> Self {
299        Self(elements.into_iter().collect())
300    }
301
302    /// Creates the root path.
303    pub fn root() -> Self {
304        Self::default()
305    }
306
307    /// Creates a path containing one object field.
308    pub fn field(field: impl Into<FieldName>) -> Self {
309        Self(vec![VariantPathElement::field(field)])
310    }
311
312    /// Returns the path elements.
313    pub fn elements(&self) -> &[VariantPathElement] {
314        &self.0
315    }
316
317    /// Returns whether this path references the root Variant value.
318    pub fn is_root(&self) -> bool {
319        self.0.is_empty()
320    }
321}
322
323impl FromIterator<VariantPathElement> for VariantPath {
324    fn from_iter<T: IntoIterator<Item = VariantPathElement>>(iter: T) -> Self {
325        Self(iter.into_iter().collect())
326    }
327}
328
329impl From<VariantPathElement> for VariantPath {
330    fn from(value: VariantPathElement) -> Self {
331        Self(vec![value])
332    }
333}
334
335impl Display for VariantPath {
336    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
337        write!(f, "$")?;
338        for element in self.elements() {
339            match element {
340                VariantPathElement::Field(name) => write!(f, ".{name}")?,
341                VariantPathElement::Index(index) => write!(f, "[{index}]")?,
342            }
343        }
344        Ok(())
345    }
346}
347
348/// A single field or index step in a [`VariantPath`].
349#[derive(Clone, Debug, PartialEq, Eq, Hash)]
350pub enum VariantPathElement {
351    /// Select an object field by name.
352    Field(FieldName),
353    /// Select a list element by zero-based index.
354    Index(u64),
355}
356
357impl VariantPathElement {
358    /// Creates an object-field path element.
359    pub fn field(field: impl Into<FieldName>) -> Self {
360        Self::Field(field.into())
361    }
362
363    /// Creates a list-index path element.
364    pub fn index(index: u64) -> Self {
365        Self::Index(index)
366    }
367
368    /// Decodes a path element from its protobuf representation.
369    pub fn from_proto(value: pb::VariantPathElement) -> VortexResult<Self> {
370        match value
371            .element
372            .ok_or_else(|| vortex_err!("Variant path element missing value"))?
373        {
374            variant_path_element::Element::Field(field) => Ok(Self::field(field)),
375            variant_path_element::Element::Index(index) => Ok(Self::index(index)),
376        }
377    }
378
379    /// Encodes this path element into its protobuf representation.
380    pub fn to_proto(&self) -> pb::VariantPathElement {
381        match self {
382            VariantPathElement::Field(name) => pb::VariantPathElement {
383                element: Some(variant_path_element::Element::Field(
384                    name.as_ref().to_string(),
385                )),
386            },
387            VariantPathElement::Index(index) => pb::VariantPathElement {
388                element: Some(variant_path_element::Element::Index(*index)),
389            },
390        }
391    }
392}
393
394impl From<FieldName> for VariantPathElement {
395    fn from(value: FieldName) -> Self {
396        Self::field(value)
397    }
398}
399
400impl From<&str> for VariantPathElement {
401    fn from(value: &str) -> Self {
402        Self::field(value)
403    }
404}
405
406impl From<u64> for VariantPathElement {
407    fn from(value: u64) -> Self {
408        Self::index(value)
409    }
410}
411
412#[cfg(test)]
413mod tests {
414    use std::sync::LazyLock;
415
416    use vortex_error::VortexResult;
417    use vortex_error::vortex_bail;
418    use vortex_error::vortex_ensure;
419    use vortex_error::vortex_err;
420    use vortex_session::VortexSession;
421
422    use crate::ArrayRef;
423    use crate::Canonical;
424    use crate::IntoArray;
425    use crate::VortexSessionExecute;
426    use crate::arrays::Chunked;
427    use crate::arrays::ChunkedArray;
428    use crate::arrays::ConstantArray;
429    use crate::arrays::PrimitiveArray;
430    use crate::arrays::VariantArray;
431    use crate::arrays::variant::VariantArraySlotsExt;
432    use crate::assert_arrays_eq;
433    use crate::assert_nth_scalar_is_null;
434    use crate::dtype::DType;
435    use crate::dtype::FieldName;
436    use crate::dtype::FieldNames;
437    use crate::dtype::Nullability;
438    use crate::dtype::PType;
439    use crate::dtype::StructFields;
440    use crate::expr::Expression;
441    use crate::expr::proto::ExprSerializeProtoExt;
442    use crate::expr::root;
443    use crate::expr::variant_get;
444    use crate::scalar::Scalar;
445    use crate::scalar::ScalarValue;
446    use crate::scalar_fn::ScalarFnVTable;
447    use crate::scalar_fn::fns::variant_get::VariantGet;
448    use crate::scalar_fn::fns::variant_get::VariantGetOptions;
449    use crate::scalar_fn::fns::variant_get::VariantPath;
450    use crate::scalar_fn::fns::variant_get::VariantPathElement;
451
452    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
453
454    fn variant_object(fields: impl IntoIterator<Item = (&'static str, Scalar)>) -> Scalar {
455        let fields = fields.into_iter().collect::<Vec<_>>();
456        let names = FieldNames::from_iter(fields.iter().map(|(name, _)| FieldName::from(*name)));
457        let dtypes = vec![DType::Variant(Nullability::NonNullable); fields.len()];
458        let values = fields
459            .into_iter()
460            .map(|(_, value)| Scalar::variant(value).into_value())
461            .collect();
462        Scalar::try_new(
463            DType::Struct(StructFields::new(names, dtypes), Nullability::NonNullable),
464            Some(ScalarValue::Tuple(values)),
465        )
466        .unwrap()
467    }
468
469    fn variant_rows(rows: impl IntoIterator<Item = Scalar>) -> VortexResult<ArrayRef> {
470        let dtype = DType::Variant(Nullability::Nullable);
471        let chunks = rows
472            .into_iter()
473            .map(|row| ConstantArray::new(row.cast(&dtype).unwrap(), 1).into_array());
474        ChunkedArray::try_new(chunks, dtype.clone()).map(|array| array.into_array())
475    }
476
477    /// Test-only syntax for keeping `variant_get` cases compact without committing
478    /// to a public string grammar yet.
479    fn parse_path(path: &str) -> VortexResult<VariantPath> {
480        if path.is_empty() || path == "$" {
481            return Ok(VariantPath::root());
482        }
483
484        let mut elements = Vec::new();
485        let mut pos = usize::from(path.as_bytes().first() == Some(&b'$'));
486        if pos == 1
487            && path
488                .as_bytes()
489                .get(pos)
490                .is_some_and(|byte| !matches!(byte, b'.' | b'['))
491        {
492            vortex_bail!("Invalid Variant path {path:?}: expected '.' or '[' after '$'");
493        }
494
495        while pos < path.len() {
496            match path.as_bytes()[pos] {
497                b'.' => {
498                    pos += 1;
499                    let (field, next_pos) = parse_field(path, pos)?;
500                    elements.push(VariantPathElement::field(field));
501                    pos = next_pos;
502                }
503                b'[' => {
504                    let (index, next_pos) = parse_index(path, pos + 1)?;
505                    elements.push(VariantPathElement::index(index));
506                    pos = next_pos;
507                }
508                _ if pos == 0 => {
509                    let (field, next_pos) = parse_field(path, pos)?;
510                    elements.push(VariantPathElement::field(field));
511                    pos = next_pos;
512                }
513                _ => {
514                    vortex_bail!("Invalid Variant path {path:?}: expected '.', '[', or end of path")
515                }
516            }
517        }
518
519        Ok(VariantPath::new(elements))
520    }
521
522    fn parse_field(path: &str, start: usize) -> VortexResult<(&str, usize)> {
523        let mut pos = start;
524        while path
525            .as_bytes()
526            .get(pos)
527            .is_some_and(|byte| byte.is_ascii_alphanumeric() || *byte == b'_')
528        {
529            pos += 1;
530        }
531        vortex_ensure!(
532            pos > start,
533            "Invalid Variant path {path:?}: expected field name"
534        );
535        Ok((&path[start..pos], pos))
536    }
537
538    fn parse_index(path: &str, start: usize) -> VortexResult<(u64, usize)> {
539        let mut pos = start;
540        while path
541            .as_bytes()
542            .get(pos)
543            .is_some_and(|byte| byte.is_ascii_digit())
544        {
545            pos += 1;
546        }
547        vortex_ensure!(
548            pos > start,
549            "Invalid Variant path {path:?}: expected list index"
550        );
551        vortex_ensure!(
552            path.as_bytes().get(pos) == Some(&b']'),
553            "Invalid Variant path {path:?}: expected closing ']'"
554        );
555        let index = path[start..pos]
556            .parse()
557            .map_err(|_| vortex_err!("Invalid Variant path {path:?}: list index is too large"))?;
558        Ok((index, pos + 1))
559    }
560
561    fn execute_variant_get(
562        array: ArrayRef,
563        path: &str,
564        dtype: Option<DType>,
565    ) -> VortexResult<ArrayRef> {
566        let expr = variant_get(root(), parse_path(path)?, dtype);
567        array
568            .apply(&expr)?
569            .execute::<ArrayRef>(&mut SESSION.create_execution_ctx())
570    }
571
572    #[test]
573    fn variant_get_path_parse_and_display() {
574        let path = parse_path("$.data[1].a").unwrap();
575        assert_eq!(
576            path.elements(),
577            &[
578                VariantPathElement::field("data"),
579                VariantPathElement::index(1),
580                VariantPathElement::field("a")
581            ]
582        );
583        assert_eq!(path.to_string(), "$.data[1].a");
584
585        let bare_path = parse_path("data[2]").unwrap();
586        assert_eq!(bare_path.to_string(), "$.data[2]");
587    }
588
589    #[test]
590    fn variant_get_return_dtype_is_nullable_variant_without_requested_dtype() {
591        let expr = variant_get(root(), VariantPath::field("data"), None);
592        let dtype = expr
593            .return_dtype(&DType::Variant(Nullability::NonNullable))
594            .unwrap();
595
596        assert_eq!(dtype, DType::Variant(Nullability::Nullable));
597    }
598
599    #[test]
600    fn variant_get_return_dtype_makes_requested_dtype_nullable() {
601        let requested = DType::Primitive(PType::I64, Nullability::NonNullable);
602        let expr = variant_get(root(), VariantPath::field("data"), Some(requested));
603        let dtype = expr
604            .return_dtype(&DType::Variant(Nullability::NonNullable))
605            .unwrap();
606
607        assert_eq!(dtype, DType::Primitive(PType::I64, Nullability::Nullable));
608    }
609
610    #[test]
611    fn variant_get_rejects_non_variant_input() {
612        let expr = variant_get(root(), VariantPath::field("data"), None);
613        let err = expr
614            .return_dtype(&DType::Utf8(Nullability::NonNullable))
615            .unwrap_err();
616
617        assert!(err.to_string().contains("VariantGet input must be Variant"));
618    }
619
620    #[test]
621    fn variant_get_formats_sql() {
622        let expr = variant_get(
623            root(),
624            parse_path("$.data[1].a").unwrap(),
625            Some(DType::Utf8(Nullability::NonNullable)),
626        );
627
628        assert_eq!(expr.to_string(), "variant_get($, \"$.data[1].a\", utf8)");
629    }
630
631    #[test]
632    fn variant_get_options_roundtrip_serialization() {
633        let options = VariantGetOptions::new(
634            VariantPath::new([
635                VariantPathElement::field("data"),
636                VariantPathElement::index(1),
637                VariantPathElement::field("a"),
638            ]),
639            Some(DType::Primitive(PType::I32, Nullability::NonNullable)),
640        );
641        let metadata = VariantGet.serialize(&options).unwrap().unwrap();
642        let actual = VariantGet.deserialize(&metadata, &SESSION).unwrap();
643
644        assert_eq!(actual, options);
645    }
646
647    #[test]
648    fn variant_get_expression_roundtrip_serialization() {
649        let expr: Expression = variant_get(
650            root(),
651            parse_path("$.data[1].a").unwrap(),
652            Some(DType::Primitive(PType::I32, Nullability::NonNullable)),
653        );
654        let proto = expr.serialize_proto().unwrap();
655        let actual = Expression::from_proto(&proto, &SESSION).unwrap();
656
657        assert_eq!(actual, expr);
658    }
659
660    #[test]
661    fn variant_get_generic_fallback_extracts_field_and_list_index() -> VortexResult<()> {
662        let items = Scalar::list(
663            DType::Variant(Nullability::NonNullable),
664            vec![
665                Scalar::variant(Scalar::primitive(10i32, Nullability::NonNullable)),
666                Scalar::variant(Scalar::primitive(20i32, Nullability::NonNullable)),
667            ],
668            Nullability::NonNullable,
669        );
670        let array = variant_rows([
671            Scalar::variant(variant_object([("items", items)])),
672            Scalar::variant(variant_object([(
673                "items",
674                Scalar::list_empty(
675                    DType::Variant(Nullability::NonNullable).into(),
676                    Nullability::NonNullable,
677                ),
678            )])),
679            Scalar::variant(variant_object([(
680                "items",
681                Scalar::list(
682                    DType::Variant(Nullability::NonNullable),
683                    vec![
684                        Scalar::variant(Scalar::utf8("x", Nullability::NonNullable)),
685                        Scalar::variant(Scalar::utf8("wrong", Nullability::NonNullable)),
686                    ],
687                    Nullability::NonNullable,
688                ),
689            )])),
690        ])?;
691
692        let result = execute_variant_get(
693            array,
694            "$.items[1]",
695            Some(DType::Primitive(PType::I32, Nullability::NonNullable)),
696        )?;
697        let mut ctx = SESSION.create_execution_ctx();
698
699        assert_arrays_eq!(
700            result,
701            PrimitiveArray::from_option_iter([Some(20i32), None, None]),
702            &mut ctx
703        );
704        Ok(())
705    }
706
707    #[test]
708    fn variant_get_reads_chunked_variant_input() -> VortexResult<()> {
709        let array = variant_rows([
710            Scalar::variant(variant_object([(
711                "a",
712                Scalar::primitive(10i32, Nullability::NonNullable),
713            )])),
714            Scalar::variant(variant_object([(
715                "b",
716                Scalar::primitive(20i32, Nullability::NonNullable),
717            )])),
718            Scalar::variant(variant_object([(
719                "a",
720                Scalar::primitive(30i32, Nullability::NonNullable),
721            )])),
722            Scalar::null(DType::Variant(Nullability::Nullable)),
723        ])?;
724        assert!(array.is::<Chunked>());
725
726        let result = execute_variant_get(
727            array,
728            "$.a",
729            Some(DType::Primitive(PType::I32, Nullability::NonNullable)),
730        )?;
731        let mut ctx = SESSION.create_execution_ctx();
732
733        assert_arrays_eq!(
734            result,
735            PrimitiveArray::from_option_iter([Some(10i32), None, Some(30), None]),
736            &mut ctx
737        );
738        Ok(())
739    }
740
741    #[test]
742    fn variant_get_fallback_typed_output_is_contiguous() -> VortexResult<()> {
743        let array = variant_rows([
744            Scalar::variant(variant_object([(
745                "a",
746                Scalar::primitive(10i32, Nullability::NonNullable),
747            )])),
748            Scalar::variant(variant_object([(
749                "a",
750                Scalar::primitive(20i32, Nullability::NonNullable),
751            )])),
752            Scalar::variant(variant_object([(
753                "b",
754                Scalar::primitive(30i32, Nullability::NonNullable),
755            )])),
756        ])?;
757
758        let result = execute_variant_get(
759            array,
760            "$.a",
761            Some(DType::Primitive(PType::I32, Nullability::NonNullable)),
762        )?;
763
764        assert!(!result.is::<Chunked>());
765        let mut ctx = SESSION.create_execution_ctx();
766        assert_arrays_eq!(
767            result,
768            PrimitiveArray::from_option_iter([Some(10i32), Some(20), None]),
769            &mut ctx
770        );
771        Ok(())
772    }
773
774    #[test]
775    fn variant_get_generic_fallback_preserves_variant_null() -> VortexResult<()> {
776        let array = variant_rows([
777            Scalar::variant(variant_object([(
778                "a",
779                Scalar::utf8("ok", Nullability::NonNullable),
780            )])),
781            Scalar::null(DType::Variant(Nullability::Nullable)),
782            Scalar::variant(variant_object([("a", Scalar::null(DType::Null))])),
783            Scalar::variant(variant_object([(
784                "b",
785                Scalar::primitive(2i32, Nullability::NonNullable),
786            )])),
787        ])?;
788
789        let result = execute_variant_get(array, "$.a", None)?;
790
791        let mut ctx = SESSION.create_execution_ctx();
792        let row0 = result.execute_scalar(0, &mut ctx)?;
793        assert_eq!(
794            row0.as_variant()
795                .value()
796                .and_then(|value| value.as_utf8().value())
797                .map(|value| value.as_str()),
798            Some("ok")
799        );
800        assert_nth_scalar_is_null!(result, 1, &mut ctx);
801        assert_eq!(
802            result
803                .execute_scalar(2, &mut ctx)?
804                .as_variant()
805                .is_variant_null(),
806            Some(true)
807        );
808        assert_nth_scalar_is_null!(result, 3, &mut ctx);
809        Ok(())
810    }
811
812    #[test]
813    fn variant_get_fallback_variant_output_canonicalizes() -> VortexResult<()> {
814        let array = variant_rows([
815            Scalar::variant(variant_object([(
816                "a",
817                Scalar::primitive(10i32, Nullability::NonNullable),
818            )])),
819            Scalar::variant(variant_object([(
820                "a",
821                Scalar::primitive(20i32, Nullability::NonNullable),
822            )])),
823        ])?;
824
825        let result = execute_variant_get(array, "$.a", None)?;
826        let variant = result
827            .clone()
828            .execute::<VariantArray>(&mut SESSION.create_execution_ctx())?;
829        let canonical = result.execute::<Canonical>(&mut SESSION.create_execution_ctx())?;
830        let Canonical::Variant(canonical_variant) = canonical else {
831            vortex_bail!("expected Variant canonical array");
832        };
833
834        assert_eq!(variant.len(), 2);
835        assert_eq!(canonical_variant.len(), 2);
836        assert_eq!(variant.core_storage().dtype(), variant.dtype());
837        assert_eq!(variant.core_storage().len(), variant.len());
838
839        let mut ctx = SESSION.create_execution_ctx();
840        for array in [variant, canonical_variant] {
841            assert_eq!(array.dtype(), &DType::Variant(Nullability::Nullable));
842            for (idx, expected) in [10i32, 20].into_iter().enumerate() {
843                let scalar = array.execute_scalar(idx, &mut ctx)?;
844                let actual = scalar
845                    .as_variant()
846                    .value()
847                    .and_then(|value| value.as_primitive().as_::<i32>());
848                assert_eq!(actual, Some(expected), "row {idx}");
849            }
850        }
851        Ok(())
852    }
853}