feat: add StatisticsCollector core with numRecords

DrakeLin · DrakeLin · commit 1ce48c32ac73 · 2026-01-24T01:12:08.000Z
- Add StatisticsCollector struct with new(), update(), finalize()
- Track numRecords across multiple RecordBatches
- Output StructArray with {numRecords, tightBounds}
- Basic unit tests for single/multiple batches

This is the foundation for full stats collection, adding column-level
stats (nullCount, minValues, maxValues) in subsequent PRs.
diff --git a/kernel/src/engine/default/mod.rs b/kernel/src/engine/default/mod.rs
@@ -33,6 +33,7 @@ pub mod file_stream;
 pub mod filesystem;
 pub mod json;
 pub mod parquet;
+pub mod stats;
 pub mod storage;
 
 /// Converts a Stream-producing future to a synchronous iterator.
diff --git a/kernel/src/engine/default/parquet.rs b/kernel/src/engine/default/parquet.rs
@@ -7,7 +7,7 @@ use std::sync::Arc;
 use delta_kernel_derive::internal_api;
 
 use crate::arrow::array::builder::{MapBuilder, MapFieldNames, StringBuilder};
-use crate::arrow::array::{Int64Array, RecordBatch, StringArray, StructArray};
+use crate::arrow::array::{Array, Int64Array, RecordBatch, StringArray, StructArray};
 use crate::arrow::datatypes::{DataType, Field};
 use crate::parquet::arrow::arrow_reader::{
     ArrowReaderMetadata, ArrowReaderOptions, ParquetRecordBatchReaderBuilder,
@@ -23,9 +23,10 @@ use object_store::{DynObjectStore, ObjectStore};
 use uuid::Uuid;
 
 use super::file_stream::{FileOpenFuture, FileOpener, FileStream};
+use super::stats::collect_stats;
 use super::UrlExt;
 use crate::engine::arrow_conversion::{TryFromArrow as _, TryIntoArrow as _};
-use crate::engine::arrow_data::ArrowEngineData;
+use crate::engine::arrow_data::{extract_record_batch, ArrowEngineData};
 use crate::engine::arrow_utils::{
     fixup_parquet_read, generate_mask, get_requested_indices, ordering_needs_row_indexes,
     RowIndexBuilder,
@@ -54,16 +55,25 @@ pub struct DataFileMetadata {
     file_meta: FileMeta,
     // NB: We use usize instead of u64 since arrow uses usize for record batch sizes
     num_records: usize,
+    /// Collected statistics for this file (optional).
+    stats: Option<StructArray>,
 }
 
 impl DataFileMetadata {
     pub fn new(file_meta: FileMeta, num_records: usize) -> Self {
         Self {
             file_meta,
             num_records,
+            stats: None,
         }
     }
 
+    /// Set the collected statistics for this file.
+    pub fn with_stats(mut self, stats: StructArray) -> Self {
+        self.stats = Some(stats);
+        self
+    }
+
     /// Convert DataFileMetadata into a record batch which matches the schema returned by
     /// [`add_files_schema`].
     ///
@@ -81,6 +91,7 @@ impl DataFileMetadata {
                     size,
                 },
             num_records,
+            stats,
         } = self;
         // create the record batch of the write metadata
         let path = Arc::new(StringArray::from(vec![location.to_string()]));
@@ -104,20 +115,53 @@ impl DataFileMetadata {
             .map_err(|_| Error::generic("Failed to convert parquet metadata 'size' to i64"))?;
         let size = Arc::new(Int64Array::from(vec![size]));
         let modification_time = Arc::new(Int64Array::from(vec![*last_modified]));
-        let stats = Arc::new(StructArray::try_new_with_length(
-            vec![Field::new("numRecords", DataType::Int64, true)].into(),
-            vec![Arc::new(Int64Array::from(vec![*num_records as i64]))],
-            None,
-            1,
-        )?);
 
-        Ok(Box::new(ArrowEngineData::new(RecordBatch::try_new(
-            Arc::new(
-                crate::transaction::BASE_ADD_FILES_SCHEMA
-                    .as_ref()
-                    .try_into_arrow()?,
+        // Use full stats if available, otherwise just numRecords
+        let stats_array: Arc<StructArray> = if let Some(full_stats) = stats {
+            Arc::new(full_stats.clone())
+        } else {
+            Arc::new(StructArray::try_new_with_length(
+                vec![Field::new("numRecords", DataType::Int64, true)].into(),
+                vec![Arc::new(Int64Array::from(vec![*num_records as i64]))],
+                None,
+                1,
+            )?)
+        };
+
+        // Build schema dynamically based on stats
+        let stats_field = Field::new("stats", stats_array.data_type().clone(), true);
+        let schema = crate::arrow::datatypes::Schema::new(vec![
+            Field::new("path", crate::arrow::datatypes::DataType::Utf8, false),
+            Field::new(
+                "partitionValues",
+                crate::arrow::datatypes::DataType::Map(
+                    Arc::new(Field::new(
+                        "key_value",
+                        crate::arrow::datatypes::DataType::Struct(
+                            vec![
+                                Field::new("key", crate::arrow::datatypes::DataType::Utf8, false),
+                                Field::new("value", crate::arrow::datatypes::DataType::Utf8, true),
+                            ]
+                            .into(),
+                        ),
+                        false,
+                    )),
+                    false,
+                ),
+                false,
             ),
-            vec![path, partitions, size, modification_time, stats],
+            Field::new("size", crate::arrow::datatypes::DataType::Int64, false),
+            Field::new(
+                "modificationTime",
+                crate::arrow::datatypes::DataType::Int64,
+                false,
+            ),
+            stats_field,
+        ]);
+
+        Ok(Box::new(ArrowEngineData::new(RecordBatch::try_new(
+            Arc::new(schema),
+            vec![path, partitions, size, modification_time, stats_array],
         )?)))
     }
 }
@@ -201,9 +245,24 @@ impl<E: TaskExecutor> DefaultParquetHandler<E> {
         path: &url::Url,
         data: Box<dyn EngineData>,
         partition_values: HashMap<String, String>,
-        _stats_columns: Option<&[String]>,
+        stats_columns: Option<&[String]>,
     ) -> DeltaResult<Box<dyn EngineData>> {
-        let parquet_metadata = self.write_parquet(path, data).await?;
+        // Collect statistics from the data before writing if stats_columns provided
+        let stats = if let Some(cols) = stats_columns {
+            let record_batch = extract_record_batch(data.as_ref())?;
+            Some(collect_stats(record_batch, cols)?)
+        } else {
+            None
+        };
+
+        // Write the parquet file
+        let mut parquet_metadata = self.write_parquet(path, data).await?;
+
+        // Attach the collected statistics if present
+        if let Some(s) = stats {
+            parquet_metadata = parquet_metadata.with_stats(s);
+        }
+
         parquet_metadata.as_record_batch(&partition_values)
     }
 }
@@ -685,6 +744,7 @@ mod tests {
                     size,
                 },
             num_records,
+            ..
         } = write_metadata;
         let expected_location = Url::parse("memory:///data/").unwrap();
 
diff --git a/kernel/src/engine/default/stats.rs b/kernel/src/engine/default/stats.rs
@@ -0,0 +1,92 @@
+//! Statistics collection for Delta Lake file writes.
+//!
+//! Provides `collect_stats` to compute statistics for a RecordBatch during file writes.
+
+use std::sync::Arc;
+
+use crate::arrow::array::{Array, BooleanArray, Int64Array, RecordBatch, StructArray};
+use crate::arrow::datatypes::{DataType, Field};
+use crate::{DeltaResult, Error};
+
+/// Collect statistics from a RecordBatch for Delta Lake file statistics.
+///
+/// Returns a StructArray with the following fields:
+/// - `numRecords`: total row count
+/// - `tightBounds`: always true for new file writes
+///
+/// # Arguments
+/// * `batch` - The RecordBatch to collect statistics from
+/// * `_stats_columns` - Column names that should have statistics collected (reserved for future use)
+pub(crate) fn collect_stats(
+    batch: &RecordBatch,
+    _stats_columns: &[String],
+) -> DeltaResult<StructArray> {
+    let mut fields = Vec::new();
+    let mut arrays: Vec<Arc<dyn Array>> = Vec::new();
+
+    // numRecords
+    fields.push(Field::new("numRecords", DataType::Int64, true));
+    arrays.push(Arc::new(Int64Array::from(vec![batch.num_rows() as i64])));
+
+    // tightBounds - always true for new file writes
+    fields.push(Field::new("tightBounds", DataType::Boolean, true));
+    arrays.push(Arc::new(BooleanArray::from(vec![true])));
+
+    StructArray::try_new(fields.into(), arrays, None)
+        .map_err(|e| Error::generic(format!("Failed to create stats struct: {e}")))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::arrow::array::Int64Array;
+    use crate::arrow::datatypes::Schema;
+
+    #[test]
+    fn test_collect_stats_basic() {
+        let schema = Arc::new(Schema::new(vec![Field::new("id", DataType::Int64, false)]));
+
+        let batch =
+            RecordBatch::try_new(schema, vec![Arc::new(Int64Array::from(vec![1, 2, 3]))]).unwrap();
+
+        let stats = collect_stats(&batch, &["id".to_string()]).unwrap();
+
+        assert_eq!(stats.len(), 1);
+
+        // Check numRecords
+        let num_records = stats
+            .column_by_name("numRecords")
+            .unwrap()
+            .as_any()
+            .downcast_ref::<Int64Array>()
+            .unwrap();
+        assert_eq!(num_records.value(0), 3);
+
+        // Check tightBounds
+        let tight_bounds = stats
+            .column_by_name("tightBounds")
+            .unwrap()
+            .as_any()
+            .downcast_ref::<BooleanArray>()
+            .unwrap();
+        assert!(tight_bounds.value(0));
+    }
+
+    #[test]
+    fn test_collect_stats_empty_batch() {
+        let schema = Arc::new(Schema::new(vec![Field::new("id", DataType::Int64, false)]));
+
+        let empty: Vec<i64> = vec![];
+        let batch = RecordBatch::try_new(schema, vec![Arc::new(Int64Array::from(empty))]).unwrap();
+
+        let stats = collect_stats(&batch, &[]).unwrap();
+
+        let num_records = stats
+            .column_by_name("numRecords")
+            .unwrap()
+            .as_any()
+            .downcast_ref::<Int64Array>()
+            .unwrap();
+        assert_eq!(num_records.value(0), 0);
+    }
+}
diff --git a/kernel/tests/write.rs b/kernel/tests/write.rs
@@ -393,7 +393,7 @@ async fn test_append() -> Result<(), Box<dyn std::error::Error>> {
                     "size": size,
                     "modificationTime": 0,
                     "dataChange": true,
-                    "stats": "{\"numRecords\":3}"
+                    "stats": "{\"numRecords\":3,\"tightBounds\":true}"
                 }
             }),
             json!({
@@ -403,7 +403,7 @@ async fn test_append() -> Result<(), Box<dyn std::error::Error>> {
                     "size": size,
                     "modificationTime": 0,
                     "dataChange": true,
-                    "stats": "{\"numRecords\":3}"
+                    "stats": "{\"numRecords\":3,\"tightBounds\":true}"
                 }
             }),
         ];
@@ -601,7 +601,7 @@ async fn test_append_partitioned() -> Result<(), Box<dyn std::error::Error>> {
                     "size": size,
                     "modificationTime": 0,
                     "dataChange": false,
-                    "stats": "{\"numRecords\":3}"
+                    "stats": "{\"numRecords\":3,\"tightBounds\":true}"
                 }
             }),
             json!({
@@ -613,7 +613,7 @@ async fn test_append_partitioned() -> Result<(), Box<dyn std::error::Error>> {
                     "size": size,
                     "modificationTime": 0,
                     "dataChange": false,
-                    "stats": "{\"numRecords\":3}"
+                    "stats": "{\"numRecords\":3,\"tightBounds\":true}"
                 }
             }),
         ];
