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    /// Panics if the proposed key was a duplicate
215    ///
216    /// WARNING: The builder will have no effect unless/until [`ObjectBuilder::finish`] is called.
217    pub fn new_object<'b>(&'b mut self, key: &'b str) -> ObjectBuilder<'b, ObjectState<'b>> {
218        self.try_new_object(key).unwrap()
219    }
220
221    /// Returns an object builder that can be used to append a new (nested) object to this object.
222    ///
223    /// Fails if the proposed key was a duplicate
224    ///
225    /// WARNING: The builder will have no effect unless/until [`ObjectBuilder::finish`] is called.
226    pub fn try_new_object<'b>(
227        &'b mut self,
228        key: &str,
229    ) -> Result<ObjectBuilder<'b, ObjectState<'b>>, ArrowError> {
230        let (parent_state, validate_unique_fields) = self.parent_state(key)?;
231        Ok(ObjectBuilder::new(parent_state, validate_unique_fields))
232    }
233
234    /// Returns a list builder that can be used to append a new (nested) list to this object.
235    ///
236    /// Panics if the proposed key was a duplicate
237    ///
238    /// WARNING: The builder will have no effect unless/until [`ListBuilder::finish`] is called.
239    pub fn new_list<'b>(&'b mut self, key: &str) -> ListBuilder<'b, ObjectState<'b>> {
240        self.try_new_list(key).unwrap()
241    }
242
243    /// Returns a list builder that can be used to append a new (nested) list to this object.
244    ///
245    /// Fails if the proposed key was a duplicate
246    ///
247    /// WARNING: The builder will have no effect unless/until [`ListBuilder::finish`] is called.
248    pub fn try_new_list<'b>(
249        &'b mut self,
250        key: &str,
251    ) -> Result<ListBuilder<'b, ObjectState<'b>>, ArrowError> {
252        let (parent_state, validate_unique_fields) = self.parent_state(key)?;
253        Ok(ListBuilder::new(parent_state, validate_unique_fields))
254    }
255
256    /// Finalizes this object and appends it to its parent, which otherwise remains unmodified.
257    pub fn finish(mut self) {
258        let metadata_builder = self.parent_state.metadata_builder();
259
260        self.fields.sort_by(|&field_a_id, _, &field_b_id, _| {
261            let field_a_name = metadata_builder.field_name(field_a_id as usize);
262            let field_b_name = metadata_builder.field_name(field_b_id as usize);
263            field_a_name.cmp(field_b_name)
264        });
265
266        let max_id = self.fields.iter().map(|(i, _)| *i).max().unwrap_or(0);
267        let id_size = int_size(max_id as usize);
268
269        let starting_offset = self.parent_state.saved_value_builder_offset;
270        let value_builder = self.parent_state.value_builder();
271        let current_offset = value_builder.offset();
272        // Current object starts from `object_start_offset`
273        let data_size = current_offset - starting_offset;
274        let offset_size = int_size(data_size);
275
276        let num_fields = self.fields.len();
277        let is_large = num_fields > u8::MAX as usize;
278
279        let header_size = 1 + // header byte
280            (if is_large { 4 } else { 1 }) + // num_fields
281            (num_fields * id_size as usize) + // field IDs
282            ((num_fields + 1) * offset_size as usize); // field offsets + data_size
283
284        let mut bytes_to_splice = Vec::with_capacity(header_size);
285
286        macro_rules! write_header {
287            ($offset_size:expr, $id_size:expr) => {
288                ObjectHeaderWriter::<{ $offset_size as u8 }, { $id_size as u8 }>::write(
289                    &mut bytes_to_splice,
290                    num_fields,
291                    self.fields.keys().copied(),
292                    self.fields.values().copied(),
293                    data_size,
294                )
295            };
296        }
297
298        use crate::decoder::OffsetSizeBytes::*;
299        match (offset_size, id_size) {
300            (One, One) => write_header!(One, One),
301            (One, Two) => write_header!(One, Two),
302            (One, Three) => write_header!(One, Three),
303            (One, Four) => write_header!(One, Four),
304            (Two, One) => write_header!(Two, One),
305            (Two, Two) => write_header!(Two, Two),
306            (Two, Three) => write_header!(Two, Three),
307            (Two, Four) => write_header!(Two, Four),
308            (Three, One) => write_header!(Three, One),
309            (Three, Two) => write_header!(Three, Two),
310            (Three, Three) => write_header!(Three, Three),
311            (Three, Four) => write_header!(Three, Four),
312            (Four, One) => write_header!(Four, One),
313            (Four, Two) => write_header!(Four, Two),
314            (Four, Three) => write_header!(Four, Three),
315            (Four, Four) => write_header!(Four, Four),
316        }
317
318        // Shift existing data to make room for the header
319        value_builder
320            .inner_mut()
321            .splice(starting_offset..starting_offset, bytes_to_splice);
322
323        self.parent_state.finish();
324    }
325}
326
327impl<'a, 'm, 'v, S, K, V> Extend<(K, V)> for ObjectBuilder<'a, S>
328where
329    S: BuilderSpecificState,
330    K: AsRef<str>,
331    V: Into<Variant<'m, 'v>>,
332{
333    fn extend<T: IntoIterator<Item = (K, V)>>(&mut self, iter: T) {
334        for (key, value) in iter.into_iter() {
335            self.insert(key.as_ref(), value);
336        }
337    }
338}
339
340/// Internal state for object building
341#[derive(Debug)]
342pub struct ObjectState<'a> {
343    fields: &'a mut IndexMap<u32, usize>,
344    saved_fields_size: usize,
345}
346
347// `ObjectBuilder::finish()` eagerly updates the field offsets, which we should rollback on failure.
348impl BuilderSpecificState for ObjectState<'_> {
349    fn rollback(&mut self) {
350        self.fields.truncate(self.saved_fields_size);
351    }
352}
353
354impl<'a> ParentState<'a, ObjectState<'a>> {
355    /// Creates a new instance suitable for an [`ObjectBuilder`]. The value and metadata builder state
356    /// is checkpointed and will roll back on drop, unless [`Self::finish`] is called. The new
357    /// field's name and offset are also captured eagerly and will also roll back if not finished.
358    ///
359    /// The call fails if the field name is invalid (e.g. because it duplicates an existing field).
360    pub fn try_object(
361        value_builder: &'a mut ValueBuilder,
362        metadata_builder: &'a mut dyn MetadataBuilder,
363        fields: &'a mut IndexMap<u32, usize>,
364        saved_parent_value_builder_offset: usize,
365        field_name: &str,
366        validate_unique_fields: bool,
367    ) -> Result<Self, ArrowError> {
368        // The saved_parent_buffer_offset is the buffer size as of when the parent builder was
369        // constructed. The saved_buffer_offset is the buffer size as of now (when a child builder
370        // is created). The variant field_offset entry for this field is their difference.
371        let saved_value_builder_offset = value_builder.offset();
372        let saved_fields_size = fields.len();
373        let saved_metadata_builder_dict_size = metadata_builder.num_field_names();
374        let field_id = metadata_builder.try_upsert_field_name(field_name)?;
375        let field_start = saved_value_builder_offset - saved_parent_value_builder_offset;
376        if fields.insert(field_id, field_start).is_some() && validate_unique_fields {
377            return Err(ArrowError::InvalidArgumentError(format!(
378                "Duplicate field name: {field_name}"
379            )));
380        }
381
382        let builder_state = ObjectState {
383            fields,
384            saved_fields_size,
385        };
386        Ok(Self {
387            saved_metadata_builder_dict_size,
388            saved_value_builder_offset,
389            value_builder,
390            metadata_builder,
391            builder_state,
392            finished: false,
393        })
394    }
395}
396
397/// A [`VariantBuilderExt`] that inserts a new field into a variant object.
398pub struct ObjectFieldBuilder<'o, 'v, 's, S: BuilderSpecificState> {
399    key: &'s str,
400    builder: &'o mut ObjectBuilder<'v, S>,
401}
402
403impl<'o, 'v, 's, S: BuilderSpecificState> ObjectFieldBuilder<'o, 'v, 's, S> {
404    pub fn new(key: &'s str, builder: &'o mut ObjectBuilder<'v, S>) -> Self {
405        Self { key, builder }
406    }
407}
408
409impl<S: BuilderSpecificState> VariantBuilderExt for ObjectFieldBuilder<'_, '_, '_, S> {
410    type State<'a>
411        = ObjectState<'a>
412    where
413        Self: 'a;
414
415    /// A NULL object field is interpreted as missing, so nothing gets inserted at all.
416    fn append_null(&mut self) {}
417    fn append_value<'m, 'v>(&mut self, value: impl Into<Variant<'m, 'v>>) {
418        self.builder.insert(self.key, value);
419    }
420
421    fn try_new_list(&mut self) -> Result<ListBuilder<'_, Self::State<'_>>, ArrowError> {
422        self.builder.try_new_list(self.key)
423    }
424
425    fn try_new_object(&mut self) -> Result<ObjectBuilder<'_, Self::State<'_>>, ArrowError> {
426        self.builder.try_new_object(self.key)
427    }
428}
429
430#[cfg(test)]
431mod tests {
432    use crate::{
433        ParentState, ValueBuilder, Variant, VariantBuilder, VariantMetadata,
434        builder::{metadata::ReadOnlyMetadataBuilder, object::ObjectBuilder},
435        decoder::VariantBasicType,
436    };
437
438    #[test]
439    fn test_object() {
440        let mut builder = VariantBuilder::new();
441
442        builder
443            .new_object()
444            .with_field("name", "John")
445            .with_field("age", 42i8)
446            .finish();
447
448        let (metadata, value) = builder.finish();
449        assert!(!metadata.is_empty());
450        assert!(!value.is_empty());
451    }
452
453    #[test]
454    fn test_object_field_ordering() {
455        let mut builder = VariantBuilder::new();
456
457        builder
458            .new_object()
459            .with_field("zebra", "stripes")
460            .with_field("apple", "red")
461            .with_field("banana", "yellow")
462            .finish();
463
464        let (_, value) = builder.finish();
465
466        let header = value[0];
467        assert_eq!(header & 0x03, VariantBasicType::Object as u8);
468
469        let field_count = value[1] as usize;
470        assert_eq!(field_count, 3);
471
472        // Get field IDs from the object header
473        let field_ids: Vec<u8> = value[2..5].to_vec();
474
475        // apple(1), banana(2), zebra(0)
476        assert_eq!(field_ids, vec![1, 2, 0]);
477    }
478
479    #[test]
480    fn test_duplicate_fields_in_object() {
481        let mut builder = VariantBuilder::new();
482        builder
483            .new_object()
484            .with_field("name", "Ron Artest")
485            .with_field("name", "Metta World Peace") // Duplicate field
486            .finish();
487
488        let (metadata, value) = builder.finish();
489        let variant = Variant::try_new(&metadata, &value).unwrap();
490
491        let obj = variant.as_object().unwrap();
492        assert_eq!(obj.len(), 1);
493        assert_eq!(obj.field(0).unwrap(), Variant::from("Metta World Peace"));
494
495        assert_eq!(
496            vec![("name", Variant::from("Metta World Peace"))],
497            obj.iter().collect::<Vec<_>>()
498        );
499    }
500
501    #[test]
502    fn test_read_only_metadata_builder() {
503        // First create some metadata with a few field names
504        let mut default_builder = VariantBuilder::new();
505        default_builder.add_field_name("name");
506        default_builder.add_field_name("age");
507        default_builder.add_field_name("active");
508        let (metadata_bytes, _) = default_builder.finish();
509
510        // Use the metadata to build new variant values
511        let metadata = VariantMetadata::try_new(&metadata_bytes).unwrap();
512        let mut metadata_builder = ReadOnlyMetadataBuilder::new(&metadata);
513        let mut value_builder = ValueBuilder::new();
514
515        {
516            let state = ParentState::variant(&mut value_builder, &mut metadata_builder);
517            let mut obj = ObjectBuilder::new(state, false);
518
519            // These should succeed because the fields exist in the metadata
520            obj.insert("name", "Alice");
521            obj.insert("age", 30i8);
522            obj.insert("active", true);
523            obj.finish();
524        }
525
526        let value = value_builder.into_inner();
527
528        // Verify the variant was built correctly
529        let variant = Variant::try_new(&metadata_bytes, &value).unwrap();
530        let obj = variant.as_object().unwrap();
531        assert_eq!(obj.get("name"), Some(Variant::from("Alice")));
532        assert_eq!(obj.get("age"), Some(Variant::Int8(30)));
533        assert_eq!(obj.get("active"), Some(Variant::from(true)));
534    }
535
536    // matthew
537    #[test]
538    fn test_append_object() {
539        let (m1, v1) = make_object();
540        let variant = Variant::new(&m1, &v1);
541
542        let mut builder = VariantBuilder::new().with_metadata(VariantMetadata::new(&m1));
543
544        builder.append_value(variant.clone());
545
546        let (metadata, value) = builder.finish();
547        assert_eq!(variant, Variant::new(&metadata, &value));
548    }
549
550    /// make an object variant with field names in reverse lexicographical order
551    fn make_object() -> (Vec<u8>, Vec<u8>) {
552        let mut builder = VariantBuilder::new();
553
554        let mut obj = builder.new_object();
555
556        obj.insert("b", true);
557        obj.insert("a", false);
558        obj.finish();
559        builder.finish()
560    }
561
562    #[test]
563    fn test_append_nested_object() {
564        let (m1, v1) = make_nested_object();
565        let variant = Variant::new(&m1, &v1);
566
567        // because we can guarantee metadata is validated through the builder
568        let mut builder = VariantBuilder::new().with_metadata(VariantMetadata::new(&m1));
569        builder.append_value(variant.clone());
570
571        let (metadata, value) = builder.finish();
572        let result_variant = Variant::new(&metadata, &value);
573
574        assert_eq!(variant, result_variant);
575    }
576
577    /// make a nested object variant
578    fn make_nested_object() -> (Vec<u8>, Vec<u8>) {
579        let mut builder = VariantBuilder::new();
580
581        {
582            let mut outer_obj = builder.new_object();
583
584            {
585                let mut inner_obj = outer_obj.new_object("b");
586                inner_obj.insert("a", "inner_value");
587                inner_obj.finish();
588            }
589
590            outer_obj.finish();
591        }
592
593        builder.finish()
594    }
595
596    #[test]
597    fn test_nested_object() {
598        /*
599        {
600            "c": {
601                "b": "a"
602            }
603        }
604
605        */
606
607        let mut builder = VariantBuilder::new();
608        {
609            let mut outer_object_builder = builder.new_object();
610            {
611                let mut inner_object_builder = outer_object_builder.new_object("c");
612                inner_object_builder.insert("b", "a");
613                inner_object_builder.finish();
614            }
615
616            outer_object_builder.finish();
617        }
618
619        let (metadata, value) = builder.finish();
620        let variant = Variant::try_new(&metadata, &value).unwrap();
621        let outer_object = variant.as_object().unwrap();
622
623        assert_eq!(outer_object.len(), 1);
624        assert_eq!(outer_object.field_name(0).unwrap(), "c");
625
626        let inner_object_variant = outer_object.field(0).unwrap();
627        let inner_object = inner_object_variant.as_object().unwrap();
628
629        assert_eq!(inner_object.len(), 1);
630        assert_eq!(inner_object.field_name(0).unwrap(), "b");
631        assert_eq!(inner_object.field(0).unwrap(), Variant::from("a"));
632    }
633
634    #[test]
635    fn test_nested_object_with_duplicate_field_names_per_object() {
636        /*
637        {
638            "c": {
639                "b": false,
640                "c": "a"
641            },
642            "b": false,
643        }
644
645        */
646
647        let mut builder = VariantBuilder::new();
648        {
649            let mut outer_object_builder = builder.new_object();
650            {
651                let mut inner_object_builder = outer_object_builder.new_object("c");
652                inner_object_builder.insert("b", false);
653                inner_object_builder.insert("c", "a");
654
655                inner_object_builder.finish();
656            }
657
658            outer_object_builder.insert("b", false);
659            outer_object_builder.finish();
660        }
661
662        let (metadata, value) = builder.finish();
663        let variant = Variant::try_new(&metadata, &value).unwrap();
664        let outer_object = variant.as_object().unwrap();
665
666        assert_eq!(outer_object.len(), 2);
667        assert_eq!(outer_object.field_name(0).unwrap(), "b");
668
669        let inner_object_variant = outer_object.field(1).unwrap();
670        let inner_object = inner_object_variant.as_object().unwrap();
671
672        assert_eq!(inner_object.len(), 2);
673        assert_eq!(inner_object.field_name(0).unwrap(), "b");
674        assert_eq!(inner_object.field(0).unwrap(), Variant::from(false));
675        assert_eq!(inner_object.field_name(1).unwrap(), "c");
676        assert_eq!(inner_object.field(1).unwrap(), Variant::from("a"));
677    }
678
679    #[test]
680    fn test_nested_object_with_heterogeneous_fields() {
681        /*
682        {
683            "a": false,
684            "c": {
685                "b": "a",
686                "c": {
687                   "aa": "bb",
688                },
689                "d": {
690                    "cc": "dd"
691                }
692            },
693            "b": true,
694            "d": {
695               "e": 1,
696               "f": [1, true],
697               "g": ["tree", false],
698            }
699        }
700        */
701
702        let mut builder = VariantBuilder::new();
703        {
704            let mut outer_object_builder = builder.new_object();
705
706            outer_object_builder.insert("a", false);
707
708            {
709                let mut inner_object_builder = outer_object_builder.new_object("c");
710                inner_object_builder.insert("b", "a");
711
712                {
713                    let mut inner_inner_object_builder = inner_object_builder.new_object("c");
714                    inner_inner_object_builder.insert("aa", "bb");
715                    inner_inner_object_builder.finish();
716                }
717
718                {
719                    let mut inner_inner_object_builder = inner_object_builder.new_object("d");
720                    inner_inner_object_builder.insert("cc", "dd");
721                    inner_inner_object_builder.finish();
722                }
723                inner_object_builder.finish();
724            }
725
726            outer_object_builder.insert("b", true);
727
728            {
729                let mut inner_object_builder = outer_object_builder.new_object("d");
730                inner_object_builder.insert("e", 1);
731                {
732                    let mut inner_list_builder = inner_object_builder.new_list("f");
733                    inner_list_builder.append_value(1);
734                    inner_list_builder.append_value(true);
735
736                    inner_list_builder.finish();
737                }
738
739                {
740                    let mut inner_list_builder = inner_object_builder.new_list("g");
741                    inner_list_builder.append_value("tree");
742                    inner_list_builder.append_value(false);
743
744                    inner_list_builder.finish();
745                }
746
747                inner_object_builder.finish();
748            }
749
750            outer_object_builder.finish();
751        }
752
753        let (metadata, value) = builder.finish();
754
755        // note, object fields are now sorted lexigraphically by field name
756        /*
757         {
758            "a": false,
759            "b": true,
760            "c": {
761                "b": "a",
762                "c": {
763                   "aa": "bb",
764                },
765                "d": {
766                    "cc": "dd"
767                }
768            },
769            "d": {
770               "e": 1,
771               "f": [1, true],
772               "g": ["tree", false],
773            }
774        }
775        */
776
777        let variant = Variant::try_new(&metadata, &value).unwrap();
778        let outer_object = variant.as_object().unwrap();
779
780        assert_eq!(outer_object.len(), 4);
781
782        assert_eq!(outer_object.field_name(0).unwrap(), "a");
783        assert_eq!(outer_object.field(0).unwrap(), Variant::from(false));
784
785        assert_eq!(outer_object.field_name(2).unwrap(), "c");
786
787        let inner_object_variant = outer_object.field(2).unwrap();
788        let inner_object = inner_object_variant.as_object().unwrap();
789
790        assert_eq!(inner_object.len(), 3);
791        assert_eq!(inner_object.field_name(0).unwrap(), "b");
792        assert_eq!(inner_object.field(0).unwrap(), Variant::from("a"));
793
794        let inner_iner_object_variant_c = inner_object.field(1).unwrap();
795        let inner_inner_object_c = inner_iner_object_variant_c.as_object().unwrap();
796        assert_eq!(inner_inner_object_c.len(), 1);
797        assert_eq!(inner_inner_object_c.field_name(0).unwrap(), "aa");
798        assert_eq!(inner_inner_object_c.field(0).unwrap(), Variant::from("bb"));
799
800        let inner_iner_object_variant_d = inner_object.field(2).unwrap();
801        let inner_inner_object_d = inner_iner_object_variant_d.as_object().unwrap();
802        assert_eq!(inner_inner_object_d.len(), 1);
803        assert_eq!(inner_inner_object_d.field_name(0).unwrap(), "cc");
804        assert_eq!(inner_inner_object_d.field(0).unwrap(), Variant::from("dd"));
805
806        assert_eq!(outer_object.field_name(1).unwrap(), "b");
807        assert_eq!(outer_object.field(1).unwrap(), Variant::from(true));
808
809        let out_object_variant_d = outer_object.field(3).unwrap();
810        let out_object_d = out_object_variant_d.as_object().unwrap();
811        assert_eq!(out_object_d.len(), 3);
812        assert_eq!("e", out_object_d.field_name(0).unwrap());
813        assert_eq!(Variant::from(1), out_object_d.field(0).unwrap());
814        assert_eq!("f", out_object_d.field_name(1).unwrap());
815
816        let first_inner_list_variant_f = out_object_d.field(1).unwrap();
817        let first_inner_list_f = first_inner_list_variant_f.as_list().unwrap();
818        assert_eq!(2, first_inner_list_f.len());
819        assert_eq!(Variant::from(1), first_inner_list_f.get(0).unwrap());
820        assert_eq!(Variant::from(true), first_inner_list_f.get(1).unwrap());
821
822        let second_inner_list_variant_g = out_object_d.field(2).unwrap();
823        let second_inner_list_g = second_inner_list_variant_g.as_list().unwrap();
824        assert_eq!(2, second_inner_list_g.len());
825        assert_eq!(Variant::from("tree"), second_inner_list_g.get(0).unwrap());
826        assert_eq!(Variant::from(false), second_inner_list_g.get(1).unwrap());
827    }
828
829    #[test]
830    fn test_object_without_unique_field_validation() {
831        let mut builder = VariantBuilder::new();
832
833        // Root object with duplicates
834        let mut obj = builder.new_object();
835        obj.insert("a", 1);
836        obj.insert("a", 2);
837        obj.finish();
838
839        // Deeply nested list structure with duplicates
840        let mut builder = VariantBuilder::new();
841        let mut outer_list = builder.new_list();
842        let mut inner_list = outer_list.new_list();
843        let mut nested_obj = inner_list.new_object();
844        nested_obj.insert("x", 1);
845        nested_obj.insert("x", 2);
846        nested_obj.new_list("x").with_value(3).finish();
847        nested_obj.new_object("x").with_field("y", 4).finish();
848        nested_obj.finish();
849        inner_list.finish();
850        outer_list.finish();
851
852        // Verify the nested object is built correctly -- the nested object "x" should have "won"
853        let (metadata, value) = builder.finish();
854        let variant = Variant::try_new(&metadata, &value).unwrap();
855        let outer_element = variant.get_list_element(0).unwrap();
856        let inner_element = outer_element.get_list_element(0).unwrap();
857        let outer_field = inner_element.get_object_field("x").unwrap();
858        let inner_field = outer_field.get_object_field("y").unwrap();
859        assert_eq!(inner_field, Variant::from(4));
860    }
861
862    #[test]
863    fn test_object_with_unique_field_validation() {
864        let mut builder = VariantBuilder::new().with_validate_unique_fields(true);
865
866        // Root-level object with duplicates
867        let result = builder
868            .new_object()
869            .with_field("a", 1)
870            .with_field("b", 2)
871            .try_with_field("a", 3);
872        assert_eq!(
873            result.unwrap_err().to_string(),
874            "Invalid argument error: Duplicate field name: a"
875        );
876
877        // Deeply nested list -> list -> object with duplicate
878        let mut outer_list = builder.new_list();
879        let mut inner_list = outer_list.new_list();
880        let mut object = inner_list.new_object().with_field("x", 1);
881        let nested_result = object.try_insert("x", 2);
882        assert_eq!(
883            nested_result.unwrap_err().to_string(),
884            "Invalid argument error: Duplicate field name: x"
885        );
886        let nested_result = object.try_new_list("x");
887        assert_eq!(
888            nested_result.unwrap_err().to_string(),
889            "Invalid argument error: Duplicate field name: x"
890        );
891
892        let nested_result = object.try_new_object("x");
893        assert_eq!(
894            nested_result.unwrap_err().to_string(),
895            "Invalid argument error: Duplicate field name: x"
896        );
897
898        drop(object);
899        inner_list.finish();
900        outer_list.finish();
901
902        // Valid object should succeed
903        let mut list = builder.new_list();
904        let mut valid_obj = list.new_object();
905        valid_obj.insert("m", 1);
906        valid_obj.insert("n", 2);
907
908        valid_obj.finish();
909        list.finish();
910    }
911}
parquet_variant/builder/object.rs

parquet_variant/builder/
object.rs
