[Variant] Reserve capacity beforehand during large object building (#7922)

# Which issue does this PR close?

- Part of #7896

# Rationale for this change

In #7896, we saw that inserting a
large amount of field names takes a long time -- in this case ~45s to
insert 2**24 field names. The bulk of this time is spent just allocating
the strings, but we also see quite a bit of time spent reallocating the
`IndexSet` that we're inserting into.

`with_field_names` is an optimization to declare the field names upfront
which avoids having to reallocate and rehash the entire `IndexSet`
during field name insertion. Using this method requires at least 2
string allocations for each field name -- 1 to declare field names
upfront and 1 to insert the actual field name during object building.

This PR adds a new method `with_field_name_capacity` which allows you to
reserve space to the metadata builder, without needing to allocate the
field names themselves upfront. In this case, we see a modest
performance improvement when inserting the field names during object
building

Before: 
<img width="1512" height="829" alt="Screenshot 2025-07-13 at 12 08
43 PM"
src="https://github.com/user-attachments/assets/6ef0d9fe-1e08-4d3a-8f6b-703de550865c"
/>


After:
<img width="1512" height="805" alt="Screenshot 2025-07-13 at 12 08
55 PM"
src="https://github.com/user-attachments/assets/2faca4cb-0a51-441b-ab6c-5baa1dae84b3"
/>

Author: friendlymatthew

parquet-variant/benches/variant_builder.rs

@@ -495,6 +495,18 @@ fn bench_iteration_performance(c: &mut Criterion) {
     group.finish();
 }
 
+fn bench_extend_metadata_builder(c: &mut Criterion) {
+    let list = (0..400_000).map(|i| format!("id_{i}")).collect::<Vec<_>>();
+
+    c.bench_function("bench_extend_metadata_builder", |b| {
+        b.iter(|| {
+            std::hint::black_box(
+                VariantBuilder::new().with_field_names(list.iter().map(|s| s.as_str())),
+            );
+        })
+    });
+}
+
 criterion_group!(
     benches,
     bench_object_field_names_reverse_order,
@@ -505,7 +517,8 @@ criterion_group!(
     bench_object_partially_same_schema,
     bench_object_list_partially_same_schema,
     bench_validation_validated_vs_unvalidated,
-    bench_iteration_performance
+    bench_iteration_performance,
+    bench_extend_metadata_builder
 );
 
 criterion_main!(benches);

parquet-variant/src/builder.rs

@@ -402,6 +402,11 @@ impl<S: AsRef<str>> FromIterator<S> for MetadataBuilder {
 
 impl<S: AsRef<str>> Extend<S> for MetadataBuilder {
     fn extend<T: IntoIterator<Item = S>>(&mut self, iter: T) {
+        let iter = iter.into_iter();
+        let (min, _) = iter.size_hint();
+
+        self.field_names.reserve(min);
+
         for field_name in iter {
             self.upsert_field_name(field_name.as_ref());
         }
@@ -760,6 +765,13 @@ impl VariantBuilder {
         self
     }
 
+    /// This method reserves capacity for field names in the Variant metadata,
+    /// which can improve performance when you know the approximate number of unique field
+    /// names that will be used across all objects in the [`Variant`].
+    pub fn reserve(&mut self, capacity: usize) {
+        self.metadata_builder.field_names.reserve(capacity);
+    }
+
     /// Adds a single field name to the field name directory in the Variant metadata.
     ///
     /// This method does the same thing as [`VariantBuilder::with_field_names`] but adds one field name at a time.