feat: add human-readable formatting to EXPLAIN ANALYZE metrics

Author: Dmitrii Bugakov

Cargo.lock

@@ -1824,7 +1824,7 @@ STORED AS PARQUET;
     assert!(explain.contains("output_rows=128")); // Read 1 row group
     assert!(explain.contains("t@0 < 1372708809")); // Dynamic filter was applied
     assert!(
-        explain.contains("pushdown_rows_matched=128, pushdown_rows_pruned=99872"),
+        explain.contains("pushdown_rows_matched=128, pushdown_rows_pruned=99.87 K"),
         "{explain}"
     );
     // Pushdown pruned most rows

datafusion/core/tests/physical_optimizer/filter_pushdown/mod.rs

@@ -503,6 +503,56 @@ pub fn human_readable_size(size: usize) -> String {
     format!("{value:.1} {unit}")
 }
 
+/// Present count in human-readable form with K, M, B, T suffixes
+pub fn human_readable_count(count: usize) -> String {
+    let count = count as u64;
+    let (value, unit) = {
+        if count >= 1_000_000_000_000 {
+            (count as f64 / 1_000_000_000_000.0, " T")
+        } else if count >= 1_000_000_000 {
+            (count as f64 / 1_000_000_000.0, " B")
+        } else if count >= 1_000_000 {
+            (count as f64 / 1_000_000.0, " M")
+        } else if count >= 1_000 {
+            (count as f64 / 1_000.0, " K")
+        } else {
+            return count.to_string();
+        }
+    };
+
+    // Format with appropriate precision
+    // For values >= 100, show 1 decimal place (e.g., 123.4 K)
+    // For values < 100, show 2 decimal places (e.g., 10.12 K)
+    if value >= 100.0 {
+        format!("{value:.1}{unit}")
+    } else {
+        format!("{value:.2}{unit}")
+    }
+}
+
+/// Present duration in human-readable form with 2 decimal places
+pub fn human_readable_duration(nanos: u64) -> String {
+    const NANOS_PER_SEC: f64 = 1_000_000_000.0;
+    const NANOS_PER_MILLI: f64 = 1_000_000.0;
+    const NANOS_PER_MICRO: f64 = 1_000.0;
+
+    let nanos_f64 = nanos as f64;
+
+    if nanos >= 1_000_000_000 {
+        // >= 1 second: show in seconds
+        format!("{:.2}s", nanos_f64 / NANOS_PER_SEC)
+    } else if nanos >= 1_000_000 {
+        // >= 1 millisecond: show in milliseconds
+        format!("{:.2}ms", nanos_f64 / NANOS_PER_MILLI)
+    } else if nanos >= 1_000 {
+        // >= 1 microsecond: show in microseconds
+        format!("{:.2}µs", nanos_f64 / NANOS_PER_MICRO)
+    } else {
+        // < 1 microsecond: show in nanoseconds
+        format!("{nanos}ns")
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -599,4 +649,57 @@ mod tests {
         assert_eq!(r2.size(), 25);
         assert_eq!(pool.reserved(), 28);
     }
+
+    #[test]
+    fn test_human_readable_count() {
+        // Test small numbers (< 1000) - should display as-is
+        assert_eq!(human_readable_count(0), "0");
+        assert_eq!(human_readable_count(1), "1");
+        assert_eq!(human_readable_count(999), "999");
+
+        // Test thousands (K)
+        assert_eq!(human_readable_count(1_000), "1.00 K");
+        assert_eq!(human_readable_count(10_100), "10.10 K");
+        assert_eq!(human_readable_count(1_532), "1.53 K");
+        assert_eq!(human_readable_count(99_999), "100.00 K");
+
+        // Test millions (M)
+        assert_eq!(human_readable_count(1_000_000), "1.00 M");
+        assert_eq!(human_readable_count(1_532_000), "1.53 M");
+        assert_eq!(human_readable_count(99_000_000), "99.00 M");
+        assert_eq!(human_readable_count(123_456_789), "123.5 M");
+
+        // Test billions (B)
+        assert_eq!(human_readable_count(1_000_000_000), "1.00 B");
+        assert_eq!(human_readable_count(1_532_000_000), "1.53 B");
+        assert_eq!(human_readable_count(999_999_999_999), "1000.0 B");
+
+        // Test trillions (T)
+        assert_eq!(human_readable_count(1_000_000_000_000), "1.00 T");
+        assert_eq!(human_readable_count(42_000_000_000_000), "42.00 T");
+    }
+
+    #[test]
+    fn test_human_readable_duration() {
+        // Test nanoseconds (< 1µs)
+        assert_eq!(human_readable_duration(0), "0ns");
+        assert_eq!(human_readable_duration(1), "1ns");
+        assert_eq!(human_readable_duration(999), "999ns");
+
+        // Test microseconds (1µs to < 1ms)
+        assert_eq!(human_readable_duration(1_000), "1.00µs");
+        assert_eq!(human_readable_duration(1_234), "1.23µs");
+        assert_eq!(human_readable_duration(999_999), "1000.00µs");
+
+        // Test milliseconds (1ms to < 1s)
+        assert_eq!(human_readable_duration(1_000_000), "1.00ms");
+        assert_eq!(human_readable_duration(11_295_377), "11.30ms");
+        assert_eq!(human_readable_duration(1_234_567), "1.23ms");
+        assert_eq!(human_readable_duration(999_999_999), "1000.00ms");
+
+        // Test seconds (>= 1s)
+        assert_eq!(human_readable_duration(1_000_000_000), "1.00s");
+        assert_eq!(human_readable_duration(1_234_567_890), "1.23s");
+        assert_eq!(human_readable_duration(42_000_000_000), "42.00s");
+    }
 }

datafusion/execution/src/memory_pool/mod.rs

@@ -20,7 +20,9 @@
 use super::CustomMetricValue;
 use chrono::{DateTime, Utc};
 use datafusion_common::instant::Instant;
-use datafusion_execution::memory_pool::human_readable_size;
+use datafusion_execution::memory_pool::{
+    human_readable_count, human_readable_duration, human_readable_size,
+};
 use parking_lot::Mutex;
 use std::{
     borrow::{Borrow, Cow},
@@ -49,7 +51,7 @@ impl PartialEq for Count {
 
 impl Display for Count {
     fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
-        write!(f, "{}", self.value())
+        write!(f, "{}", human_readable_count(self.value()))
     }
 }
 
@@ -169,8 +171,7 @@ impl PartialEq for Time {
 
 impl Display for Time {
     fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
-        let duration = Duration::from_nanos(self.value() as u64);
-        write!(f, "{duration:?}")
+        write!(f, "{}", human_readable_duration(self.value() as u64))
     }
 }
 
@@ -379,7 +380,12 @@ impl Display for PruningMetrics {
         let matched = self.matched.load(Ordering::Relaxed);
         let total = self.pruned.load(Ordering::Relaxed) + matched;
 
-        write!(f, "{total} total → {matched} matched")
+        write!(
+            f,
+            "{} total → {} matched",
+            human_readable_count(total),
+            human_readable_count(matched)
+        )
     }
 }
 
@@ -506,12 +512,18 @@ impl Display for RatioMetrics {
             if part == 0 {
                 write!(f, "N/A (0/0)")
             } else {
-                write!(f, "N/A ({part}/0)")
+                write!(f, "N/A ({}/0)", human_readable_count(part))
             }
         } else {
             let percentage = (part as f64 / total as f64) * 100.0;
 
-            write!(f, "{}% ({part}/{total})", fmt_significant(percentage, 2))
+            write!(
+                f,
+                "{}% ({}/{})",
+                fmt_significant(percentage, 2),
+                human_readable_count(part),
+                human_readable_count(total)
+            )
         }
     }
 }
@@ -939,8 +951,14 @@ impl Display for MetricValue {
                 let readable_count = human_readable_size(count.value());
                 write!(f, "{readable_count}")
             }
-            Self::CurrentMemoryUsage(gauge) | Self::Gauge { gauge, .. } => {
-                write!(f, "{gauge}")
+            Self::CurrentMemoryUsage(gauge) => {
+                // CurrentMemoryUsage is in bytes, format like SpilledBytes
+                let readable_size = human_readable_size(gauge.value());
+                write!(f, "{readable_size}")
+            }
+            Self::Gauge { gauge, .. } => {
+                // Generic gauge metrics - format with human-readable count
+                write!(f, "{}", human_readable_count(gauge.value()))
             }
             Self::ElapsedCompute(time) | Self::Time { time, .. } => {
                 // distinguish between no time recorded and very small
@@ -1110,7 +1128,7 @@ mod tests {
 
         time.add_duration(Duration::from_nanos(1042));
         for value in &values {
-            assert_eq!("1.042µs", value.to_string(), "value {value:?}");
+            assert_eq!("1.04µs", value.to_string(), "value {value:?}");
         }
     }
 
@@ -1137,7 +1155,7 @@ mod tests {
         };
         tiny_ratio_metrics.add_part(1);
         tiny_ratio_metrics.add_total(3000);
-        assert_eq!("0.033% (1/3000)", tiny_ratio.to_string());
+        assert_eq!("0.033% (1/3.00 K)", tiny_ratio.to_string());
     }
 
     #[test]