parquet_variant/builder/
object.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17use crate::builder::list::ListBuilder;
18use crate::builder::metadata::MetadataBuilder;
19use crate::decoder::VariantBasicType;
20use crate::{
21    BASIC_TYPE_BITS, BuilderSpecificState, ParentState, ValueBuilder, Variant, VariantBuilderExt,
22    int_size,
23};
24use arrow_schema::ArrowError;
25use indexmap::IndexMap;
26
27fn object_header<const LARGE_BIT: u8, const ID_SIZE: u8, const OFFSET_SIZE: u8>() -> u8 {
28    (LARGE_BIT << (BASIC_TYPE_BITS + 4))
29        | ((ID_SIZE - 1) << (BASIC_TYPE_BITS + 2))
30        | ((OFFSET_SIZE - 1) << BASIC_TYPE_BITS)
31        | VariantBasicType::Object as u8
32}
33
34struct ObjectHeaderWriter<const OFFSET_SIZE: u8, const ID_SIZE: u8>();
35
36impl<const OFFSET_SIZE: u8, const ID_SIZE: u8> ObjectHeaderWriter<OFFSET_SIZE, ID_SIZE> {
37    fn write(
38        dst: &mut Vec<u8>,
39        num_fields: usize,
40        field_ids: impl Iterator<Item = u32>,
41        offsets: impl Iterator<Item = usize>,
42        data_size: usize,
43    ) {
44        let is_large = num_fields > u8::MAX as usize;
45        // num_fields will consume 4 bytes when it is larger than u8::MAX
46        if is_large {
47            dst.push(object_header::<1, { ID_SIZE }, { OFFSET_SIZE }>());
48            append_packed_u32::<4>(dst, num_fields);
49        } else {
50            dst.push(object_header::<0, { ID_SIZE }, { OFFSET_SIZE }>());
51            append_packed_u32::<1>(dst, num_fields);
52        }
53
54        for id in field_ids {
55            append_packed_u32::<ID_SIZE>(dst, id as usize);
56        }
57
58        for off in offsets {
59            append_packed_u32::<OFFSET_SIZE>(dst, off);
60        }
61
62        append_packed_u32::<OFFSET_SIZE>(dst, data_size);
63    }
64}
65
66#[inline(always)]
67fn append_packed_u32<const SIZE: u8>(dest: &mut Vec<u8>, value: usize) {
68    dest.extend_from_slice(&value.to_le_bytes()[..SIZE as usize]);
69}
70
71/// A builder for creating [`Variant::Object`] values.
72///
73/// See the examples on [`VariantBuilder`] for usage.
74///
75/// [`VariantBuilder`]: crate::VariantBuilder
76#[derive(Debug)]
77pub struct ObjectBuilder<'a, S: BuilderSpecificState> {
78    parent_state: ParentState<'a, S>,
79    pub(crate) fields: IndexMap<u32, usize>, // (field_id, offset)
80    validate_unique_fields: bool,
81}
82
83impl<'a, S: BuilderSpecificState> ObjectBuilder<'a, S> {
84    /// Creates a new object builder, nested on top of the given parent state.
85    pub fn new(parent_state: ParentState<'a, S>, validate_unique_fields: bool) -> Self {
86        Self {
87            parent_state,
88            fields: IndexMap::new(),
89            validate_unique_fields,
90        }
91    }
92
93    /// Add a field with key and value to the object
94    ///
95    /// # See Also
96    /// - [`ObjectBuilder::try_insert`] for a fallible version.
97    /// - [`ObjectBuilder::with_field`] for a builder-style API.
98    ///
99    /// # Panics
100    ///
101    /// This method will panic if the variant contains duplicate field names in objects
102    /// when validation is enabled. For a fallible version, use [`ObjectBuilder::try_insert`]
103    pub fn insert<'m, 'd, T: Into<Variant<'m, 'd>>>(&mut self, key: &str, value: T) {
104        let (state, _) = self.parent_state(key).unwrap();
105        ValueBuilder::append_variant(state, value.into())
106    }
107
108    /// Add a field with key and value to the object
109    ///
110    /// # See Also
111    /// - [`ObjectBuilder::insert`] for an infallible version that panics
112    /// - [`ObjectBuilder::try_with_field`] for a builder-style API.
113    ///
114    /// # Note
115    /// Attempting to insert a duplicate field name produces an error if unique field
116    /// validation is enabled. Otherwise, the new value overwrites the previous field mapping
117    /// without erasing the old value, resulting in a larger variant
118    pub fn try_insert<'m, 'd, T: Into<Variant<'m, 'd>>>(
119        &mut self,
120        key: &str,
121        value: T,
122    ) -> Result<(), ArrowError> {
123        let (state, _) = self.parent_state(key)?;
124        ValueBuilder::try_append_variant(state, value.into())
125    }
126
127    /// Add a field with key and value to the object by copying raw bytes when possible.
128    ///
129    /// For objects and lists, this directly copies their underlying byte representation instead of
130    /// performing a logical copy, and without touching the metadata builder. For other variant
131    /// types, this falls back to the standard append behavior.
132    ///
133    /// The caller must ensure that the metadata dictionary is already built and correct for
134    /// any objects or lists being appended, but the value's new field name is handled normally.
135    ///
136    /// # Panics
137    ///
138    /// This method will panic if the variant contains duplicate field names in objects
139    /// when validation is enabled. For a fallible version, use [`ObjectBuilder::try_insert_bytes`]
140    pub fn insert_bytes<'m, 'd>(&mut self, key: &str, value: impl Into<Variant<'m, 'd>>) {
141        self.try_insert_bytes(key, value).unwrap()
142    }
143
144    /// Add a field with key and value to the object by copying raw bytes when possible.
145    ///
146    /// For objects and lists, this directly copies their underlying byte representation instead of
147    /// performing a logical copy, and without touching the metadata builder. For other variant
148    /// types, this falls back to the standard append behavior.
149    ///
150    /// The caller must ensure that the metadata dictionary is already built and correct for
151    /// any objects or lists being appended, but the value's new field name is handled normally.
152    ///
153    /// # Note
154    /// When inserting duplicate keys, the new value overwrites the previous mapping,
155    /// but the old value remains in the buffer, resulting in a larger variant
156    pub fn try_insert_bytes<'m, 'd>(
157        &mut self,
158        key: &str,
159        value: impl Into<Variant<'m, 'd>>,
160    ) -> Result<(), ArrowError> {
161        let (state, _) = self.parent_state(key)?;
162        ValueBuilder::append_variant_bytes(state, value.into());
163        Ok(())
164    }
165
166    /// Builder style API for adding a field with key and value to the object
167    ///
168    /// Same as [`ObjectBuilder::insert`], but returns `self` for chaining.
169    pub fn with_field<'m, 'd, T: Into<Variant<'m, 'd>>>(mut self, key: &str, value: T) -> Self {
170        self.insert(key, value);
171        self
172    }
173
174    /// Builder style API for adding a field with key and value to the object
175    ///
176    /// Same as [`ObjectBuilder::try_insert`], but returns `self` for chaining.
177    pub fn try_with_field<'m, 'd, T: Into<Variant<'m, 'd>>>(
178        mut self,
179        key: &str,
180        value: T,
181    ) -> Result<Self, ArrowError> {
182        self.try_insert(key, value)?;
183        Ok(self)
184    }
185
186    /// Enables validation for unique field keys when inserting into this object.
187    ///
188    /// When this is enabled, calling [`ObjectBuilder::finish`] will return an error
189    /// if any duplicate field keys were added using [`ObjectBuilder::insert`].
190    pub fn with_validate_unique_fields(mut self, validate_unique_fields: bool) -> Self {
191        self.validate_unique_fields = validate_unique_fields;
192        self
193    }
194
195    // Returns validate_unique_fields because we can no longer reference self once this method returns.
196    fn parent_state<'b>(
197        &'b mut self,
198        field_name: &str,
199    ) -> Result<(ParentState<'b, ObjectState<'b>>, bool), ArrowError> {
200        let validate_unique_fields = self.validate_unique_fields;
201        let state = ParentState::try_object(
202            self.parent_state.value_builder,
203            self.parent_state.metadata_builder,
204            &mut self.fields,
205            self.parent_state.saved_value_builder_offset,
206            field_name,
207            validate_unique_fields,
208        )?;
209        Ok((state, validate_unique_fields))
210    }
211
212    /// Returns an object builder that can be used to append a new (nested) object to this object.
213    ///
214    /// WARNING: The builder will have no effect unless/until [`ObjectBuilder::finish`] is called.
215    ///
216    /// # Panics
217    ///
218    /// Panics if the proposed key was a duplicate
219    pub fn new_object<'b>(&'b mut self, key: &'b str) -> ObjectBuilder<'b, ObjectState<'b>> {
220        self.try_new_object(key).unwrap()
221    }
222
223    /// Returns an object builder that can be used to append a new (nested) object to this object.
224    ///
225    /// Fails if the proposed key was a duplicate
226    ///
227    /// WARNING: The builder will have no effect unless/until [`ObjectBuilder::finish`] is called.
228    pub fn try_new_object<'b>(
229        &'b mut self,
230        key: &str,
231    ) -> Result<ObjectBuilder<'b, ObjectState<'b>>, ArrowError> {
232        let (parent_state, validate_unique_fields) = self.parent_state(key)?;
233        Ok(ObjectBuilder::new(parent_state, validate_unique_fields))
234    }
235
236    /// Returns a list builder that can be used to append a new (nested) list to this object.
237    ///
238    /// WARNING: The builder will have no effect unless/until [`ListBuilder::finish`] is called.
239    ///
240    /// # Panics
241    ///
242    /// Panics if the proposed key was a duplicate
243    pub fn new_list<'b>(&'b mut self, key: &str) -> ListBuilder<'b, ObjectState<'b>> {
244        self.try_new_list(key).unwrap()
245    }
246
247    /// Returns a list builder that can be used to append a new (nested) list to this object.
248    ///
249    /// Fails if the proposed key was a duplicate
250    ///
251    /// WARNING: The builder will have no effect unless/until [`ListBuilder::finish`] is called.
252    pub fn try_new_list<'b>(
253        &'b mut self,
254        key: &str,
255    ) -> Result<ListBuilder<'b, ObjectState<'b>>, ArrowError> {
256        let (parent_state, validate_unique_fields) = self.parent_state(key)?;
257        Ok(ListBuilder::new(parent_state, validate_unique_fields))
258    }
259
260    /// Finalizes this object and appends it to its parent, which otherwise remains unmodified.
261    pub fn finish(mut self) {
262        let metadata_builder = self.parent_state.metadata_builder();
263
264        self.fields.sort_by(|&field_a_id, _, &field_b_id, _| {
265            let field_a_name = metadata_builder.field_name(field_a_id as usize);
266            let field_b_name = metadata_builder.field_name(field_b_id as usize);
267            field_a_name.cmp(field_b_name)
268        });
269
270        let max_id = self.fields.iter().map(|(i, _)| *i).max().unwrap_or(0);
271        let id_size = int_size(max_id as usize);
272
273        let starting_offset = self.parent_state.saved_value_builder_offset;
274        let value_builder = self.parent_state.value_builder();
275        let current_offset = value_builder.offset();
276        // Current object starts from `object_start_offset`
277        let data_size = current_offset - starting_offset;
278        let offset_size = int_size(data_size);
279
280        let num_fields = self.fields.len();
281        let is_large = num_fields > u8::MAX as usize;
282
283        let header_size = 1 + // header byte
284            (if is_large { 4 } else { 1 }) + // num_fields
285            (num_fields * id_size as usize) + // field IDs
286            ((num_fields + 1) * offset_size as usize); // field offsets + data_size
287
288        let mut bytes_to_splice = Vec::with_capacity(header_size);
289
290        macro_rules! write_header {
291            ($offset_size:expr, $id_size:expr) => {
292                ObjectHeaderWriter::<{ $offset_size as u8 }, { $id_size as u8 }>::write(
293                    &mut bytes_to_splice,
294                    num_fields,
295                    self.fields.keys().copied(),
296                    self.fields.values().copied(),
297                    data_size,
298                )
299            };
300        }
301
302        use crate::decoder::OffsetSizeBytes::*;
303        match (offset_size, id_size) {
304            (One, One) => write_header!(One, One),
305            (One, Two) => write_header!(One, Two),
306            (One, Three) => write_header!(One, Three),
307            (One, Four) => write_header!(One, Four),
308            (Two, One) => write_header!(Two, One),
309            (Two, Two) => write_header!(Two, Two),
310            (Two, Three) => write_header!(Two, Three),
311            (Two, Four) => write_header!(Two, Four),
312            (Three, One) => write_header!(Three, One),
313            (Three, Two) => write_header!(Three, Two),
314            (Three, Three) => write_header!(Three, Three),
315            (Three, Four) => write_header!(Three, Four),
316            (Four, One) => write_header!(Four, One),
317            (Four, Two) => write_header!(Four, Two),
318            (Four, Three) => write_header!(Four, Three),
319            (Four, Four) => write_header!(Four, Four),
320        }
321
322        // Shift existing data to make room for the header
323        value_builder
324            .inner_mut()
325            .splice(starting_offset..starting_offset, bytes_to_splice);
326
327        self.parent_state.finish();
328    }
329}
330
331impl<'m, 'v, S, K, V> Extend<(K, V)> for ObjectBuilder<'_, S>
332where
333    S: BuilderSpecificState,
334    K: AsRef<str>,
335    V: Into<Variant<'m, 'v>>,
336{
337    fn extend<T: IntoIterator<Item = (K, V)>>(&mut self, iter: T) {
338        for (key, value) in iter {
339            self.insert(key.as_ref(), value);
340        }
341    }
342}
343
344/// Internal state for object building
345#[derive(Debug)]
346pub struct ObjectState<'a> {
347    fields: &'a mut IndexMap<u32, usize>,
348    saved_fields_size: usize,
349}
350
351// `ObjectBuilder::finish()` eagerly updates the field offsets, which we should rollback on failure.
352impl BuilderSpecificState for ObjectState<'_> {
353    fn rollback(&mut self) {
354        self.fields.truncate(self.saved_fields_size);
355    }
356}
357
358impl<'a> ParentState<'a, ObjectState<'a>> {
359    /// Creates a new instance suitable for an [`ObjectBuilder`]. The value and metadata builder state
360    /// is checkpointed and will roll back on drop, unless [`Self::finish`] is called. The new
361    /// field's name and offset are also captured eagerly and will also roll back if not finished.
362    ///
363    /// The call fails if the field name is invalid (e.g. because it duplicates an existing field).
364    pub fn try_object(
365        value_builder: &'a mut ValueBuilder,
366        metadata_builder: &'a mut dyn MetadataBuilder,
367        fields: &'a mut IndexMap<u32, usize>,
368        saved_parent_value_builder_offset: usize,
369        field_name: &str,
370        validate_unique_fields: bool,
371    ) -> Result<Self, ArrowError> {
372        // The saved_parent_buffer_offset is the buffer size as of when the parent builder was
373        // constructed. The saved_buffer_offset is the buffer size as of now (when a child builder
374        // is created). The variant field_offset entry for this field is their difference.
375        let saved_value_builder_offset = value_builder.offset();
376        let saved_fields_size = fields.len();
377        let saved_metadata_builder_dict_size = metadata_builder.num_field_names();
378        let field_id = metadata_builder.try_upsert_field_name(field_name)?;
379        let field_start = saved_value_builder_offset - saved_parent_value_builder_offset;
380        if fields.insert(field_id, field_start).is_some() && validate_unique_fields {
381            return Err(ArrowError::InvalidArgumentError(format!(
382                "Duplicate field name: {field_name}"
383            )));
384        }
385
386        let builder_state = ObjectState {
387            fields,
388            saved_fields_size,
389        };
390        Ok(Self {
391            saved_metadata_builder_dict_size,
392            saved_value_builder_offset,
393            value_builder,
394            metadata_builder,
395            builder_state,
396            finished: false,
397        })
398    }
399}
400
401/// A [`VariantBuilderExt`] that inserts a new field into a variant object.
402pub struct ObjectFieldBuilder<'o, 'v, 's, S: BuilderSpecificState> {
403    key: &'s str,
404    builder: &'o mut ObjectBuilder<'v, S>,
405}
406
407impl<'o, 'v, 's, S: BuilderSpecificState> ObjectFieldBuilder<'o, 'v, 's, S> {
408    pub fn new(key: &'s str, builder: &'o mut ObjectBuilder<'v, S>) -> Self {
409        Self { key, builder }
410    }
411}
412
413impl<S: BuilderSpecificState> VariantBuilderExt for ObjectFieldBuilder<'_, '_, '_, S> {
414    type State<'a>
415        = ObjectState<'a>
416    where
417        Self: 'a;
418
419    /// A NULL object field is interpreted as missing, so nothing gets inserted at all.
420    fn append_null(&mut self) {}
421    fn append_value<'m, 'v>(&mut self, value: impl Into<Variant<'m, 'v>>) {
422        self.builder.insert(self.key, value);
423    }
424
425    fn try_new_list(&mut self) -> Result<ListBuilder<'_, Self::State<'_>>, ArrowError> {
426        self.builder.try_new_list(self.key)
427    }
428
429    fn try_new_object(&mut self) -> Result<ObjectBuilder<'_, Self::State<'_>>, ArrowError> {
430        self.builder.try_new_object(self.key)
431    }
432}
433
434#[cfg(test)]
435mod tests {
436    use crate::{
437        ParentState, ValueBuilder, Variant, VariantBuilder, VariantMetadata,
438        WritableMetadataBuilder,
439        builder::{metadata::ReadOnlyMetadataBuilder, object::ObjectBuilder},
440        decoder::VariantBasicType,
441    };
442
443    #[test]
444    fn test_object() {
445        let mut builder = VariantBuilder::new();
446
447        builder
448            .new_object()
449            .with_field("name", "John")
450            .with_field("age", 42i8)
451            .finish();
452
453        let (metadata, value) = builder.finish();
454        assert!(!metadata.is_empty());
455        assert!(!value.is_empty());
456    }
457
458    #[test]
459    fn test_object_field_ordering() {
460        let mut builder = VariantBuilder::new();
461
462        builder
463            .new_object()
464            .with_field("zebra", "stripes")
465            .with_field("apple", "red")
466            .with_field("banana", "yellow")
467            .finish();
468
469        let (_, value) = builder.finish();
470
471        let header = value[0];
472        assert_eq!(header & 0x03, VariantBasicType::Object as u8);
473
474        let field_count = value[1] as usize;
475        assert_eq!(field_count, 3);
476
477        // Get field IDs from the object header
478        let field_ids: Vec<u8> = value[2..5].to_vec();
479
480        // apple(1), banana(2), zebra(0)
481        assert_eq!(field_ids, vec![1, 2, 0]);
482    }
483
484    #[test]
485    fn test_duplicate_fields_in_object() {
486        let mut builder = VariantBuilder::new();
487        builder
488            .new_object()
489            .with_field("name", "Ron Artest")
490            .with_field("name", "Metta World Peace") // Duplicate field
491            .finish();
492
493        let (metadata, value) = builder.finish();
494        let variant = Variant::try_new(&metadata, &value).unwrap();
495
496        let obj = variant.as_object().unwrap();
497        assert_eq!(obj.len(), 1);
498        assert_eq!(obj.field(0).unwrap(), Variant::from("Metta World Peace"));
499
500        assert_eq!(
501            vec![("name", Variant::from("Metta World Peace"))],
502            obj.iter().collect::<Vec<_>>()
503        );
504    }
505
506    #[test]
507    fn test_read_only_metadata_builder() {
508        // First create some metadata with a few field names
509        let mut default_builder = WritableMetadataBuilder::default();
510        default_builder.upsert_field_name("name");
511        default_builder.upsert_field_name("age");
512        default_builder.upsert_field_name("active");
513        default_builder.finish();
514        let metadata_bytes = default_builder.into_inner();
515
516        // Use the metadata to build new variant values
517        let metadata = VariantMetadata::try_new(&metadata_bytes).unwrap();
518        let mut metadata_builder = ReadOnlyMetadataBuilder::new(&metadata);
519        let mut value_builder = ValueBuilder::new();
520
521        {
522            let state = ParentState::variant(&mut value_builder, &mut metadata_builder);
523            let mut obj = ObjectBuilder::new(state, false);
524
525            // These should succeed because the fields exist in the metadata
526            obj.insert("name", "Alice");
527            obj.insert("age", 30i8);
528            obj.insert("active", true);
529            obj.finish();
530        }
531
532        let value = value_builder.into_inner();
533
534        // Verify the variant was built correctly
535        let variant = Variant::try_new(&metadata_bytes, &value).unwrap();
536        let obj = variant.as_object().unwrap();
537        assert_eq!(obj.get("name"), Some(Variant::from("Alice")));
538        assert_eq!(obj.get("age"), Some(Variant::Int8(30)));
539        assert_eq!(obj.get("active"), Some(Variant::from(true)));
540    }
541
542    // matthew
543    #[test]
544    fn test_append_object() {
545        let (m1, v1) = make_object();
546        let variant = Variant::new(&m1, &v1);
547
548        let mut builder = VariantBuilder::new().with_metadata(VariantMetadata::new(&m1));
549
550        builder.append_value(variant.clone());
551
552        let (metadata, value) = builder.finish();
553        assert_eq!(variant, Variant::new(&metadata, &value));
554    }
555
556    /// make an object variant with field names in reverse lexicographical order
557    fn make_object() -> (Vec<u8>, Vec<u8>) {
558        let mut builder = VariantBuilder::new();
559
560        let mut obj = builder.new_object();
561
562        obj.insert("b", true);
563        obj.insert("a", false);
564        obj.finish();
565        builder.finish()
566    }
567
568    #[test]
569    fn test_append_nested_object() {
570        let (m1, v1) = make_nested_object();
571        let variant = Variant::new(&m1, &v1);
572
573        // because we can guarantee metadata is validated through the builder
574        let mut builder = VariantBuilder::new().with_metadata(VariantMetadata::new(&m1));
575        builder.append_value(variant.clone());
576
577        let (metadata, value) = builder.finish();
578        let result_variant = Variant::new(&metadata, &value);
579
580        assert_eq!(variant, result_variant);
581    }
582
583    /// make a nested object variant
584    fn make_nested_object() -> (Vec<u8>, Vec<u8>) {
585        let mut builder = VariantBuilder::new();
586
587        {
588            let mut outer_obj = builder.new_object();
589
590            {
591                let mut inner_obj = outer_obj.new_object("b");
592                inner_obj.insert("a", "inner_value");
593                inner_obj.finish();
594            }
595
596            outer_obj.finish();
597        }
598
599        builder.finish()
600    }
601
602    #[test]
603    fn test_nested_object() {
604        /*
605        {
606            "c": {
607                "b": "a"
608            }
609        }
610
611        */
612
613        let mut builder = VariantBuilder::new();
614        {
615            let mut outer_object_builder = builder.new_object();
616            {
617                let mut inner_object_builder = outer_object_builder.new_object("c");
618                inner_object_builder.insert("b", "a");
619                inner_object_builder.finish();
620            }
621
622            outer_object_builder.finish();
623        }
624
625        let (metadata, value) = builder.finish();
626        let variant = Variant::try_new(&metadata, &value).unwrap();
627        let outer_object = variant.as_object().unwrap();
628
629        assert_eq!(outer_object.len(), 1);
630        assert_eq!(outer_object.field_name(0).unwrap(), "c");
631
632        let inner_object_variant = outer_object.field(0).unwrap();
633        let inner_object = inner_object_variant.as_object().unwrap();
634
635        assert_eq!(inner_object.len(), 1);
636        assert_eq!(inner_object.field_name(0).unwrap(), "b");
637        assert_eq!(inner_object.field(0).unwrap(), Variant::from("a"));
638    }
639
640    #[test]
641    fn test_nested_object_with_duplicate_field_names_per_object() {
642        /*
643        {
644            "c": {
645                "b": false,
646                "c": "a"
647            },
648            "b": false,
649        }
650
651        */
652
653        let mut builder = VariantBuilder::new();
654        {
655            let mut outer_object_builder = builder.new_object();
656            {
657                let mut inner_object_builder = outer_object_builder.new_object("c");
658                inner_object_builder.insert("b", false);
659                inner_object_builder.insert("c", "a");
660
661                inner_object_builder.finish();
662            }
663
664            outer_object_builder.insert("b", false);
665            outer_object_builder.finish();
666        }
667
668        let (metadata, value) = builder.finish();
669        let variant = Variant::try_new(&metadata, &value).unwrap();
670        let outer_object = variant.as_object().unwrap();
671
672        assert_eq!(outer_object.len(), 2);
673        assert_eq!(outer_object.field_name(0).unwrap(), "b");
674
675        let inner_object_variant = outer_object.field(1).unwrap();
676        let inner_object = inner_object_variant.as_object().unwrap();
677
678        assert_eq!(inner_object.len(), 2);
679        assert_eq!(inner_object.field_name(0).unwrap(), "b");
680        assert_eq!(inner_object.field(0).unwrap(), Variant::from(false));
681        assert_eq!(inner_object.field_name(1).unwrap(), "c");
682        assert_eq!(inner_object.field(1).unwrap(), Variant::from("a"));
683    }
684
685    #[test]
686    fn test_nested_object_with_heterogeneous_fields() {
687        /*
688        {
689            "a": false,
690            "c": {
691                "b": "a",
692                "c": {
693                   "aa": "bb",
694                },
695                "d": {
696                    "cc": "dd"
697                }
698            },
699            "b": true,
700            "d": {
701               "e": 1,
702               "f": [1, true],
703               "g": ["tree", false],
704            }
705        }
706        */
707
708        let mut builder = VariantBuilder::new();
709        {
710            let mut outer_object_builder = builder.new_object();
711
712            outer_object_builder.insert("a", false);
713
714            {
715                let mut inner_object_builder = outer_object_builder.new_object("c");
716                inner_object_builder.insert("b", "a");
717
718                {
719                    let mut inner_inner_object_builder = inner_object_builder.new_object("c");
720                    inner_inner_object_builder.insert("aa", "bb");
721                    inner_inner_object_builder.finish();
722                }
723
724                {
725                    let mut inner_inner_object_builder = inner_object_builder.new_object("d");
726                    inner_inner_object_builder.insert("cc", "dd");
727                    inner_inner_object_builder.finish();
728                }
729                inner_object_builder.finish();
730            }
731
732            outer_object_builder.insert("b", true);
733
734            {
735                let mut inner_object_builder = outer_object_builder.new_object("d");
736                inner_object_builder.insert("e", 1);
737                {
738                    let mut inner_list_builder = inner_object_builder.new_list("f");
739                    inner_list_builder.append_value(1);
740                    inner_list_builder.append_value(true);
741
742                    inner_list_builder.finish();
743                }
744
745                {
746                    let mut inner_list_builder = inner_object_builder.new_list("g");
747                    inner_list_builder.append_value("tree");
748                    inner_list_builder.append_value(false);
749
750                    inner_list_builder.finish();
751                }
752
753                inner_object_builder.finish();
754            }
755
756            outer_object_builder.finish();
757        }
758
759        let (metadata, value) = builder.finish();
760
761        // note, object fields are now sorted lexigraphically by field name
762        /*
763         {
764            "a": false,
765            "b": true,
766            "c": {
767                "b": "a",
768                "c": {
769                   "aa": "bb",
770                },
771                "d": {
772                    "cc": "dd"
773                }
774            },
775            "d": {
776               "e": 1,
777               "f": [1, true],
778               "g": ["tree", false],
779            }
780        }
781        */
782
783        let variant = Variant::try_new(&metadata, &value).unwrap();
784        let outer_object = variant.as_object().unwrap();
785
786        assert_eq!(outer_object.len(), 4);
787
788        assert_eq!(outer_object.field_name(0).unwrap(), "a");
789        assert_eq!(outer_object.field(0).unwrap(), Variant::from(false));
790
791        assert_eq!(outer_object.field_name(2).unwrap(), "c");
792
793        let inner_object_variant = outer_object.field(2).unwrap();
794        let inner_object = inner_object_variant.as_object().unwrap();
795
796        assert_eq!(inner_object.len(), 3);
797        assert_eq!(inner_object.field_name(0).unwrap(), "b");
798        assert_eq!(inner_object.field(0).unwrap(), Variant::from("a"));
799
800        let inner_iner_object_variant_c = inner_object.field(1).unwrap();
801        let inner_inner_object_c = inner_iner_object_variant_c.as_object().unwrap();
802        assert_eq!(inner_inner_object_c.len(), 1);
803        assert_eq!(inner_inner_object_c.field_name(0).unwrap(), "aa");
804        assert_eq!(inner_inner_object_c.field(0).unwrap(), Variant::from("bb"));
805
806        let inner_iner_object_variant_d = inner_object.field(2).unwrap();
807        let inner_inner_object_d = inner_iner_object_variant_d.as_object().unwrap();
808        assert_eq!(inner_inner_object_d.len(), 1);
809        assert_eq!(inner_inner_object_d.field_name(0).unwrap(), "cc");
810        assert_eq!(inner_inner_object_d.field(0).unwrap(), Variant::from("dd"));
811
812        assert_eq!(outer_object.field_name(1).unwrap(), "b");
813        assert_eq!(outer_object.field(1).unwrap(), Variant::from(true));
814
815        let out_object_variant_d = outer_object.field(3).unwrap();
816        let out_object_d = out_object_variant_d.as_object().unwrap();
817        assert_eq!(out_object_d.len(), 3);
818        assert_eq!("e", out_object_d.field_name(0).unwrap());
819        assert_eq!(Variant::from(1), out_object_d.field(0).unwrap());
820        assert_eq!("f", out_object_d.field_name(1).unwrap());
821
822        let first_inner_list_variant_f = out_object_d.field(1).unwrap();
823        let first_inner_list_f = first_inner_list_variant_f.as_list().unwrap();
824        assert_eq!(2, first_inner_list_f.len());
825        assert_eq!(Variant::from(1), first_inner_list_f.get(0).unwrap());
826        assert_eq!(Variant::from(true), first_inner_list_f.get(1).unwrap());
827
828        let second_inner_list_variant_g = out_object_d.field(2).unwrap();
829        let second_inner_list_g = second_inner_list_variant_g.as_list().unwrap();
830        assert_eq!(2, second_inner_list_g.len());
831        assert_eq!(Variant::from("tree"), second_inner_list_g.get(0).unwrap());
832        assert_eq!(Variant::from(false), second_inner_list_g.get(1).unwrap());
833    }
834
835    #[test]
836    fn test_object_without_unique_field_validation() {
837        let mut builder = VariantBuilder::new();
838
839        // Root object with duplicates
840        let mut obj = builder.new_object();
841        obj.insert("a", 1);
842        obj.insert("a", 2);
843        obj.finish();
844
845        // Deeply nested list structure with duplicates
846        let mut builder = VariantBuilder::new();
847        let mut outer_list = builder.new_list();
848        let mut inner_list = outer_list.new_list();
849        let mut nested_obj = inner_list.new_object();
850        nested_obj.insert("x", 1);
851        nested_obj.insert("x", 2);
852        nested_obj.new_list("x").with_value(3).finish();
853        nested_obj.new_object("x").with_field("y", 4).finish();
854        nested_obj.finish();
855        inner_list.finish();
856        outer_list.finish();
857
858        // Verify the nested object is built correctly -- the nested object "x" should have "won"
859        let (metadata, value) = builder.finish();
860        let variant = Variant::try_new(&metadata, &value).unwrap();
861        let outer_element = variant.get_list_element(0).unwrap();
862        let inner_element = outer_element.get_list_element(0).unwrap();
863        let outer_field = inner_element.get_object_field("x").unwrap();
864        let inner_field = outer_field.get_object_field("y").unwrap();
865        assert_eq!(inner_field, Variant::from(4));
866    }
867
868    #[test]
869    fn test_object_with_unique_field_validation() {
870        let mut builder = VariantBuilder::new().with_validate_unique_fields(true);
871
872        // Root-level object with duplicates
873        let result = builder
874            .new_object()
875            .with_field("a", 1)
876            .with_field("b", 2)
877            .try_with_field("a", 3);
878        assert_eq!(
879            result.unwrap_err().to_string(),
880            "Invalid argument error: Duplicate field name: a"
881        );
882
883        // Deeply nested list -> list -> object with duplicate
884        let mut outer_list = builder.new_list();
885        let mut inner_list = outer_list.new_list();
886        let mut object = inner_list.new_object().with_field("x", 1);
887        let nested_result = object.try_insert("x", 2);
888        assert_eq!(
889            nested_result.unwrap_err().to_string(),
890            "Invalid argument error: Duplicate field name: x"
891        );
892        let nested_result = object.try_new_list("x");
893        assert_eq!(
894            nested_result.unwrap_err().to_string(),
895            "Invalid argument error: Duplicate field name: x"
896        );
897
898        let nested_result = object.try_new_object("x");
899        assert_eq!(
900            nested_result.unwrap_err().to_string(),
901            "Invalid argument error: Duplicate field name: x"
902        );
903
904        drop(object);
905        inner_list.finish();
906        outer_list.finish();
907
908        // Valid object should succeed (fresh builder — one top-level value per VariantBuilder)
909        let mut builder = VariantBuilder::new().with_validate_unique_fields(true);
910        let mut list = builder.new_list();
911        let mut valid_obj = list.new_object();
912        valid_obj.insert("m", 1);
913        valid_obj.insert("n", 2);
914
915        valid_obj.finish();
916        list.finish();
917    }
918}
parquet_variant/builder/object.rs

parquet_variant/builder/
object.rs
