Apache DataFusion SQL Query Engine
fix: account for every partition in local TopK and limit statistics (#25654)
Muhammad Hassaanf4ca8a87aa8a
diff --git a/datafusion/core/tests/custom_sources_cases/statistics.rs b/datafusion/core/tests/custom_sources_cases/statistics.rsindex 7701ca0279..2899acb3a1 100644--- a/datafusion/core/tests/custom_sources_cases/statistics.rs+++ b/datafusion/core/tests/custom_sources_cases/statistics.rs@@ -296,7 +296,10 @@ async fn sql_limit() -> Result<()> {// and cap NDV at the new row countlet limit_stats = StatisticsContext::new().compute(physical_plan.as_ref(), &StatisticsArgs::new())?;- assert_eq!(limit_stats.num_rows, Precision::Exact(5));+ // Each of the table's two partitions is limited to 5 rows before the global+ // limit. How the 13 rows are split between the partitions is unknown, so the+ // local limits' output is only an estimate, and so is the global count.+ assert_eq!(limit_stats.num_rows, Precision::Inexact(5));// c1: NDV=2 stays at 2 (already below limit of 5)assert_eq!(limit_stats.column_statistics[0].distinct_count,diff --git a/datafusion/physical-plan/src/coalesce_batches.rs b/datafusion/physical-plan/src/coalesce_batches.rsindex 9da7df822f..59d833ee26 100644--- a/datafusion/physical-plan/src/coalesce_batches.rs+++ b/datafusion/physical-plan/src/coalesce_batches.rs@@ -24,7 +24,7 @@ use std::task::{Context, Poll};use super::metrics::{BaselineMetrics, ExecutionPlanMetricsSet, MetricsSet};use super::{DisplayAs, ExecutionPlanProperties, PlanProperties, Statistics};use crate::projection::ProjectionExec;-use crate::statistics::{ChildStats, StatisticsArgs};+use crate::statistics::{ChildStats, StatisticsArgs, with_per_partition_fetch};use crate::stream::EmptyRecordBatchStream;use crate::{ChildrenPropertiesMode, DisplayFormatType, ExecutionPlan, RecordBatchStream,@@ -248,10 +248,15 @@ impl ExecutionPlan for CoalesceBatchesExec {fn statistics_from_inputs(&self,input_stats: &[Arc<Statistics>],- _args: &StatisticsArgs,+ args: &StatisticsArgs,) -> Result<Arc<Statistics>> {let stats = input_stats[0].as_ref().clone();- Ok(Arc::new(stats.with_fetch(self.fetch, 0, 1)?))+ Ok(Arc::new(with_per_partition_fetch(+ stats,+ self.fetch,+ self.properties().output_partitioning().partition_count(),+ args,+ )?))}fn with_fetch(&self, limit: Option<usize>) -> Option<Arc<dyn ExecutionPlan>> {@@ -493,3 +498,45 @@ impl RecordBatchStream for CoalesceBatchesStream {self.coalescer.schema()}}++#[cfg(test)]+#[expect(deprecated)]+mod tests {+ use super::*;+ use crate::collect;+ use crate::statistics::StatisticsContext;+ use crate::test::scan_partitioned;+ use datafusion_common::stats::Precision;+ use datafusion_execution::TaskContext;++ /// `fetch` stops each partition separately, so the overall statistics must+ /// allow for the rows of every partition.+ #[tokio::test]+ async fn fetch_statistics_count_every_partition() -> Result<()> {+ // Four partitions of 100 rows each.+ let coalesce: Arc<dyn ExecutionPlan> = Arc::new(+ CoalesceBatchesExec::new(scan_partitioned(4), 8192).with_fetch(Some(10)),+ );+ let emitted: usize =+ collect(Arc::clone(&coalesce), Arc::new(TaskContext::default()))+ .await?+ .iter()+ .map(|batch| batch.num_rows())+ .sum();+ assert_eq!(emitted, 40);++ let num_rows = |partition| {+ StatisticsContext::new()+ .compute(+ coalesce.as_ref(),+ &StatisticsArgs::new().with_partition(partition),+ )+ .map(|stats| stats.num_rows)+ };+ assert_eq!(num_rows(None)?, Precision::Inexact(40));+ // The scan has no statistics for a single partition, so there the fetch+ // alone bounds the estimate.+ assert_eq!(num_rows(Some(0))?, Precision::Inexact(10));+ Ok(())+ }+}diff --git a/datafusion/physical-plan/src/joins/hash_join/exec.rs b/datafusion/physical-plan/src/joins/hash_join/exec.rsindex 1bffdb1ab2..fda40cb7c8 100644--- a/datafusion/physical-plan/src/joins/hash_join/exec.rs+++ b/datafusion/physical-plan/src/joins/hash_join/exec.rs@@ -51,7 +51,7 @@ use crate::projection::{try_pushdown_through_join_with_column_indices,};use crate::repartition::REPARTITION_RANDOM_STATE;-use crate::statistics::{ChildStats, StatisticsArgs};+use crate::statistics::{ChildStats, StatisticsArgs, with_per_partition_fetch};use crate::{ChildrenPropertiesMode, ExecutionPlanProperties, ReplaceChildrenOptions,validate_child_count,@@ -1883,7 +1883,7 @@ impl ExecutionPlan for HashJoinExec {fn statistics_from_inputs(&self,input_stats: &[Arc<Statistics>],- _args: &StatisticsArgs,+ args: &StatisticsArgs,) -> Result<Arc<Statistics>> {let left_stats = if let Some(prepared) = &self.prepared_build {// The declared left child supplies the schema but is never executed.@@ -1903,8 +1903,13 @@ impl ExecutionPlan for HashJoinExec {)?;// Project statistics if there is a projectionlet stats = stats.project(self.projection.as_ref());- // Apply fetch limit to statistics- Ok(Arc::new(stats.with_fetch(self.fetch, 0, 1)?))+ // Apply the fetch, which limits each output partition separately+ Ok(Arc::new(with_per_partition_fetch(+ stats,+ self.fetch,+ self.properties().output_partitioning().partition_count(),+ args,+ )?))}/// Tries to push `projection` down through `hash_join`. If possible, performs the@@ -3443,6 +3448,7 @@ mod tests {use crate::execution_plan::Boundedness;use crate::filter::FilterExecBuilder;use crate::joins::hash_join::stream::lookup_join_hashmap;+ use crate::statistics::StatisticsContext;use crate::test::{TestMemoryExec, assert_join_metrics};use crate::{ChildrenPropertiesMode, ReplaceChildrenOptions};use crate::{@@ -3458,6 +3464,7 @@ mod tests {use arrow::buffer::NullBuffer;use arrow::datatypes::{DataType, Field, Int32Type};use datafusion_common::hash_utils::create_hashes;+ use datafusion_common::stats::Precision;use datafusion_common::test_util::{batches_to_sort_string, batches_to_string};use datafusion_common::{ScalarValue, assert_batches_eq, assert_batches_sorted_eq, assert_contains,@@ -4854,6 +4861,50 @@ mod tests {Ok(())}+ /// `fetch` stops each output partition separately, so the overall+ /// statistics must allow for the rows of every partition.+ #[tokio::test]+ async fn join_fetch_statistics_count_every_output_partition() -> Result<()> {+ let values: Vec<i32> = (0..100).collect();+ let left = build_table(("a1", &values), ("b1", &values), ("c1", &values));+ let batch = build_table_i32(("a2", &values), ("b2", &values), ("c2", &values));+ let schema = batch.schema();+ let right = TestMemoryExec::try_new_exec(&vec![vec![batch]; 4], schema, None)?;+ let on = vec![(+ Arc::new(Column::new_with_schema("b1", &left.schema())?) as _,+ Arc::new(Column::new_with_schema("b2", &right.schema())?) as _,+ )];+ let join: Arc<dyn ExecutionPlan> = Arc::new(+ HashJoinExecBuilder::new(left, right, on, JoinType::Inner)+ .with_partition_mode(PartitionMode::CollectLeft)+ .with_fetch(Some(10))+ .build()?,+ );+ assert_eq!(join.properties().output_partitioning().partition_count(), 4);++ // Each right row matches one left row, and each of the four output+ // partitions stops after 10 rows.+ let emitted: usize =+ crate::collect(Arc::clone(&join), prepare_task_ctx(8192, false))+ .await?+ .iter()+ .map(|batch| batch.num_rows())+ .sum();+ assert_eq!(emitted, 40);++ let num_rows = |partition| {+ StatisticsContext::new()+ .compute(+ join.as_ref(),+ &StatisticsArgs::new().with_partition(partition),+ )+ .map(|stats| stats.num_rows)+ };+ assert_eq!(num_rows(None)?, Precision::Inexact(40));+ assert_eq!(num_rows(Some(0))?, Precision::Inexact(10));+ Ok(())+ }+#[apply(hash_join_exec_configs)]#[tokio::test]async fn join_full_multi_batch(diff --git a/datafusion/physical-plan/src/limit.rs b/datafusion/physical-plan/src/limit.rsindex 73d98d8105..b9020a512b 100644--- a/datafusion/physical-plan/src/limit.rs+++ b/datafusion/physical-plan/src/limit.rs@@ -27,7 +27,7 @@ use super::{SendableRecordBatchStream, Statistics,};use crate::execution_plan::{Boundedness, CardinalityEffect};-use crate::statistics::{ChildStats, StatisticsArgs};+use crate::statistics::{ChildStats, StatisticsArgs, with_per_partition_fetch};use crate::{ChildrenPropertiesMode, DisplayFormatType, Distribution, ExecutionPlan, Partitioning,ReplaceChildrenOptions, validate_child_count,@@ -531,10 +531,15 @@ impl ExecutionPlan for LocalLimitExec {fn statistics_from_inputs(&self,input_stats: &[Arc<Statistics>],- _args: &StatisticsArgs,+ args: &StatisticsArgs,) -> Result<Arc<Statistics>> {let stats = input_stats[0].as_ref().clone();- Ok(Arc::new(stats.with_fetch(Some(self.fetch), 0, 1)?))+ Ok(Arc::new(with_per_partition_fetch(+ stats,+ Some(self.fetch),+ self.properties().output_partitioning().partition_count(),+ args,+ )?))}fn fetch(&self) -> Option<usize> {@@ -1040,7 +1045,17 @@ mod tests {#[test]fn test_row_number_statistics_for_local_limit() -> Result<()> {+ // Each of four partitions of 100 rows keeps 10 of them. How the rows+ // are spread over the partitions is unknown, so the count is inexact.let row_count = row_number_statistics_for_local_limit(4, 10)?;+ assert_eq!(row_count, Precision::Inexact(40));++ // A limit as large as the whole input cannot drop any row.+ let row_count = row_number_statistics_for_local_limit(4, 400)?;+ assert_eq!(row_count, Precision::Exact(400));++ // A single partition keeps exactly `fetch` rows.+ let row_count = row_number_statistics_for_local_limit(1, 10)?;assert_eq!(row_count, Precision::Exact(10));Ok(())diff --git a/datafusion/physical-plan/src/sorts/sort.rs b/datafusion/physical-plan/src/sorts/sort.rsindex 9a149cc7c3..7c34545b77 100644--- a/datafusion/physical-plan/src/sorts/sort.rs+++ b/datafusion/physical-plan/src/sorts/sort.rs@@ -46,7 +46,7 @@ use crate::sorts::streaming_merge::{SortedSpillFile, StreamingMergeBuilder};use crate::spill::get_record_batch_memory_size;use crate::spill::in_progress_spill_file::InProgressSpillFile;use crate::spill::spill_manager::{GetSlicedSize, SpillManager};-use crate::statistics::{ChildStats, StatisticsArgs};+use crate::statistics::{ChildStats, StatisticsArgs, with_per_partition_fetch};use crate::stream::ReservationStream;use crate::stream::{ObservedStream, RecordBatchStreamAdapter};use crate::topk::TopK;@@ -1559,10 +1559,16 @@ impl ExecutionPlan for SortExec {fn statistics_from_inputs(&self,input_stats: &[Arc<Statistics>],- _args: &StatisticsArgs,+ args: &StatisticsArgs,) -> Result<Arc<Statistics>> {let stats = input_stats[0].as_ref().clone();- Ok(Arc::new(stats.with_fetch(self.fetch, 0, 1)?))+ // With `preserve_partitioning`, the fetch applies to each partition.+ Ok(Arc::new(with_per_partition_fetch(+ stats,+ self.fetch,+ self.properties().output_partitioning().partition_count(),+ args,+ )?))}fn with_fetch(&self, limit: Option<usize>) -> Option<Arc<dyn ExecutionPlan>> {@@ -2168,6 +2174,7 @@ mod tests {use crate::execution_plan::Boundedness;use crate::expressions::col;use crate::filter_pushdown::{FilterPushdownPhase, PushedDown};+ use crate::statistics::StatisticsContext;use crate::test;use crate::test::TestMemoryExec;use crate::test::exec::{BlockingExec, assert_strong_count_converges_to_zero};@@ -2181,6 +2188,7 @@ mod tests {use datafusion_common::ScalarValue;use datafusion_common::cast::as_primitive_array;use datafusion_common::config::ConfigOptions;+ use datafusion_common::stats::Precision;use datafusion_common::test_util::batches_to_string;use datafusion_execution::RecordBatchStream;use datafusion_execution::config::SessionConfig;@@ -4233,4 +4241,51 @@ mod tests {assert_eq!(desc.self_filters()[0].len(), 1);Ok(())}++ /// A TopK that preserves partitioning keeps `fetch` rows from every+ /// partition, so its overall statistics must count all of them.+ #[tokio::test]+ async fn test_partitioned_topk_statistics_count_every_partition() -> Result<()> {+ // Four partitions of 100 rows each.+ let input = test::scan_partitioned(4);+ let ordering = LexOrdering::new(vec![PhysicalSortExpr {+ expr: col("i", &input.schema())?,+ options: SortOptions::default(),+ }])+ .unwrap();+ let topk = |preserve_partitioning| -> Arc<dyn ExecutionPlan> {+ Arc::new(+ SortExec::new(ordering.clone(), Arc::clone(&input))+ .with_fetch(Some(10))+ .with_preserve_partitioning(preserve_partitioning),+ )+ };+ let num_rows = |plan: &Arc<dyn ExecutionPlan>, partition| {+ StatisticsContext::new()+ .compute(+ plan.as_ref(),+ &StatisticsArgs::new().with_partition(partition),+ )+ .map(|stats| stats.num_rows)+ };++ let per_partition = topk(true);+ let emitted: usize =+ collect(Arc::clone(&per_partition), Arc::new(TaskContext::default()))+ .await?+ .iter()+ .map(|batch| batch.num_rows())+ .sum();+ // The partitions share the TopK's dynamic filter, which can prune a few+ // rows, but together they emit far more than one partition's 10.+ assert!((11..=40).contains(&emitted), "emitted {emitted} rows");+ assert_eq!(num_rows(&per_partition, None)?, Precision::Inexact(40));+ // The scan has no statistics for a single partition, so there the fetch+ // alone bounds the estimate.+ assert_eq!(num_rows(&per_partition, Some(0))?, Precision::Inexact(10));++ // Sorting the whole input keeps 10 rows in total.+ assert_eq!(num_rows(&topk(false), None)?, Precision::Exact(10));+ Ok(())+ }}diff --git a/datafusion/physical-plan/src/statistics.rs b/datafusion/physical-plan/src/statistics.rsindex 603a8e40a1..b4194d61e6 100644--- a/datafusion/physical-plan/src/statistics.rs+++ b/datafusion/physical-plan/src/statistics.rs@@ -26,6 +26,7 @@ use crate::operator_statistics::{ExtendedStatistics, StatisticsRegistry, StatisticsResult,};use datafusion_common::extensions::Extensions;+use datafusion_common::stats::Precision;use datafusion_common::{Result, Statistics, assert_eq_or_internal_err, assert_or_internal_err,};@@ -105,6 +106,40 @@ impl StatisticsArgs {}}+/// Applies `fetch` to the `input` statistics of an operator that stops *each*+/// of its `n_partitions` output partitions after `fetch` rows, such as+/// `LocalLimitExec` or a `SortExec` with a fetch that preserves partitioning.+///+/// `input` must cover what `args` asks for: one partition's rows when `args`+/// names a partition, and the rows of every partition otherwise.+///+/// For a single partition this is [`Statistics::with_fetch`]. Overall, though,+/// every partition can emit up to `fetch` rows, so the output can reach+/// `fetch * n_partitions` rows, and never more than the input. How the input+/// rows are spread over the partitions is unknown, so the result is inexact+/// unless an exact input count shows that `fetch` cannot drop any row.+pub(crate) fn with_per_partition_fetch(+ input: Statistics,+ fetch: Option<usize>,+ n_partitions: usize,+ args: &StatisticsArgs,+) -> Result<Statistics> {+ let Some(fetch) = fetch else {+ return Ok(input);+ };+ if args.partition().is_some() || n_partitions <= 1 {+ return input.with_fetch(Some(fetch), 0, 1);+ }+ // No partition can hold more than `fetch` rows, so none is dropped. Only+ // an exact count proves that: an estimate below `fetch` may be wrong.+ if matches!(input.num_rows, Precision::Exact(num_rows) if num_rows <= fetch) {+ return Ok(input);+ }+ Ok(input+ .with_fetch(Some(fetch.saturating_mul(n_partitions)), 0, 1)?+ .to_inexact())+}+/// Directive returned by [`ExecutionPlan::child_stats_requests`] describing/// how the [`StatisticsContext`] should obtain each child's statistics.#[derive(Debug, Clone, Copy, PartialEq, Eq)]@@ -993,4 +1028,81 @@ mod tests {let overall = ctx.compute(union.as_ref(), &StatisticsArgs::new()).unwrap();assert_eq!(overall.num_rows, Precision::Exact(999));}++ /// Only an exact row count can show that a fetch on each of four partitions+ /// drops no row. An estimate cannot, so the result becomes inexact, column+ /// statistics included.+ #[test]+ fn per_partition_fetch_keeps_exactness_only_for_exact_counts() -> Result<()> {+ let schema = Schema::new(vec![Field::new("a", DataType::Int32, true)]);+ let fetch_10_of_4 = |num_rows| {+ let mut input = Statistics::new_unknown(&schema);+ input.num_rows = num_rows;+ input.column_statistics[0].null_count = Precision::Exact(3);+ with_per_partition_fetch(input, Some(10), 4, &StatisticsArgs::new())+ };++ let exact = fetch_10_of_4(Precision::Exact(8))?;+ assert_eq!(exact.num_rows, Precision::Exact(8));+ assert_eq!(exact.column_statistics[0].null_count, Precision::Exact(3));++ let estimate = fetch_10_of_4(Precision::Inexact(8))?;+ assert_eq!(estimate.num_rows, Precision::Inexact(8));+ assert_eq!(+ estimate.column_statistics[0].null_count,+ Precision::Inexact(3)+ );+ Ok(())+ }++ /// Row counts under a fetch that applies to each of four partitions.+ #[test]+ fn per_partition_fetch_counts_every_partition() -> Result<()> {+ let schema = Schema::new(vec![Field::new("a", DataType::Int32, false)]);+ let overall = StatisticsArgs::new();+ let first_partition = StatisticsArgs::new().with_partition(Some(0));+ let num_rows = |input_rows, fetch, n_partitions, args: &StatisticsArgs| {+ let mut input = Statistics::new_unknown(&schema);+ input.num_rows = input_rows;+ with_per_partition_fetch(input, fetch, n_partitions, args)+ .map(|stats| stats.num_rows)+ };++ // Every partition keeps up to 10 rows. How the 400 rows are spread over+ // the partitions is unknown, so the count is an estimate.+ assert_eq!(+ num_rows(Precision::Exact(400), Some(10), 4, &overall)?,+ Precision::Inexact(40)+ );+ // The output never has more rows than the input.+ assert_eq!(+ num_rows(Precision::Exact(25), Some(10), 4, &overall)?,+ Precision::Inexact(25)+ );+ // A fetch that cannot drop any row leaves the input exact.+ assert_eq!(+ num_rows(Precision::Exact(8), Some(10), 4, &overall)?,+ Precision::Exact(8)+ );+ // Without an input estimate, the fetch still bounds every partition.+ assert_eq!(+ num_rows(Precision::Absent, Some(10), 4, &overall)?,+ Precision::Inexact(40)+ );+ // A single partition, or a single output partition, keeps `fetch` rows.+ assert_eq!(+ num_rows(Precision::Exact(100), Some(10), 4, &first_partition)?,+ Precision::Exact(10)+ );+ assert_eq!(+ num_rows(Precision::Exact(400), Some(10), 1, &overall)?,+ Precision::Exact(10)+ );+ // Without a fetch, nothing changes.+ assert_eq!(+ num_rows(Precision::Exact(400), None, 4, &overall)?,+ Precision::Exact(400)+ );+ Ok(())+ }}diff --git a/datafusion/sqllogictest/test_files/explain.slt b/datafusion/sqllogictest/test_files/explain.sltindex de69f17085..6c910b9681 100644--- a/datafusion/sqllogictest/test_files/explain.slt+++ b/datafusion/sqllogictest/test_files/explain.slt@@ -294,6 +294,30 @@ physical_plan01)ProjectionExec: expr=[CAST(a@0 AS Int64) as cast_statistics.a], statistics=[Rows=Exact(2), Bytes=Exact(16), [(Col[0]: Null=Exact(1))]]02)--DataSourceExec: partitions=1, partition_sizes=[1], statistics=[Rows=Exact(2), Bytes=Exact(176), [(Col[0]: Null=Exact(1))]]+# A TopK that preserves partitioning keeps up to `fetch` rows from each of its+# partitions, so its estimate must count all of them, while the merge above it+# keeps the global limit.+statement ok+set datafusion.execution.target_partitions = 4;++statement ok+CREATE TABLE topk_statistics AS SELECT value % 100 AS k, value AS v FROM generate_series(1, 1000);++query TT+EXPLAIN SELECT k, sum(v) AS s FROM topk_statistics GROUP BY k ORDER BY s DESC LIMIT 10;+----+physical_plan+01)SortPreservingMergeExec: [s@1 DESC], fetch=10, statistics=[Rows=Inexact(10), Bytes=Inexact(160), [(Col[0]:),(Col[1]:)]]+02)--ProjectionExec: expr=[k@0 as k, sum(topk_statistics.v)@1 as s], statistics=[Rows=Inexact(40), Bytes=Inexact(640), [(Col[0]:),(Col[1]:)]]+03)----SortExec: TopK(fetch=10), expr=[sum(topk_statistics.v)@1 DESC], preserve_partitioning=[true], statistics=[Rows=Inexact(40), Bytes=Inexact(2949), [(Col[0]:),(Col[1]:)]]+04)------AggregateExec: mode=FinalPartitioned, gby=[k@0 as k], aggr=[sum(topk_statistics.v)], statistics=[Rows=Inexact(1000), Bytes=Inexact(73728), [(Col[0]:),(Col[1]:)]]+05)--------RepartitionExec: partitioning=Hash([k@0], 4), input_partitions=4, statistics=[Rows=Inexact(1000), Bytes=Inexact(73728), [(Col[0]:),(Col[1]:)]]+06)----------AggregateExec: mode=Partial, gby=[k@0 as k], aggr=[sum(topk_statistics.v)], statistics=[Rows=Inexact(1000), Bytes=Inexact(73728), [(Col[0]:),(Col[1]:)]]+07)------------DataSourceExec: partitions=4, partition_sizes=[1, 0, 0, 0], statistics=[Rows=Exact(1000), Bytes=Exact(73728), [(Col[0]: Null=Exact(0)),(Col[1]: Null=Exact(0))]]++statement ok+DROP TABLE topk_statistics;+# CSV scan with empty statisticsquery TTEXPLAIN SELECT a, b, c FROM simple_explain_test limit 10;