Skip to content

Apache DataFusion SQL Query Engine

feat: deprecate AggregateUDFImpl::is_nullable in favour of return_field (#26746)

Yu-Chuan Hung5c861e1b2ccb
diff --git a/datafusion/expr/src/test/function_stub.rs b/datafusion/expr/src/test/function_stub.rs
index dd508ec119..849b4680ba 100644
--- a/datafusion/expr/src/test/function_stub.rs
+++ b/datafusion/expr/src/test/function_stub.rs
@@ -9,8 +9,9 @@
use arrow::datatypes::{
DECIMAL32_MAX_PRECISION, DECIMAL32_MAX_SCALE, DECIMAL64_MAX_PRECISION,
DECIMAL64_MAX_SCALE, DECIMAL128_MAX_PRECISION, DECIMAL128_MAX_SCALE,
- DECIMAL256_MAX_PRECISION, DECIMAL256_MAX_SCALE, DataType, FieldRef,
+ DECIMAL256_MAX_PRECISION, DECIMAL256_MAX_SCALE, DataType, Field, FieldRef,
};
+use std::sync::Arc;
use datafusion_common::plan_err;
use datafusion_common::{Result, exec_err, not_impl_err, utils::take_function_args};
@@ -239,6 +240,11 @@ impl AggregateUDFImpl for Count {
Ok(DataType::Int64)
}
+ fn return_field(&self, _arg_fields: &[FieldRef]) -> Result<FieldRef> {
+ Ok(Arc::new(Field::new(self.name(), DataType::Int64, false)))
+ }
+
+ // Keep the deprecated method consistent with `return_field` until it is removed
fn is_nullable(&self) -> bool {
false
}
diff --git a/datafusion/expr/src/udaf.rs b/datafusion/expr/src/udaf.rs
index b7ddfc598a..0cfba5786a 100644
--- a/datafusion/expr/src/udaf.rs
+++ b/datafusion/expr/src/udaf.rs
@@ -195,7 +195,9 @@ impl AggregateUDF {
self.inner.window_function_display_name(params)
}
+ #[deprecated(since = "56.0.0", note = "Use `AggregateUDF::return_field` instead.")]
pub fn is_nullable(&self) -> bool {
+ #[expect(deprecated)]
self.inner.is_nullable()
}
@@ -557,6 +559,7 @@ pub trait AggregateUDFImpl: Debug + DynEq + DynHash + Send + Sync + Any {
/// For example, aggregate functions like `COUNT` always return a non null value
/// but others like `MIN` will return `NULL` if there is nullable input.
/// Note that if the function is declared as *not* nullable, make sure the [`AggregateUDFImpl::default_value`] is `non-null`
+ #[deprecated(since = "56.0.0", note = "Use `return_field` instead.")]
fn is_nullable(&self) -> bool {
true
}
@@ -1501,6 +1504,7 @@ pub fn udaf_default_return_field<F: AggregateUDFImpl + ?Sized>(
Ok(Arc::new(Field::new(
func.name(),
data_type,
+ #[expect(deprecated)]
func.is_nullable(),
)))
}
@@ -1665,6 +1669,7 @@ impl AggregateUDFImpl for AliasedAggregateUDFImpl {
}
fn is_nullable(&self) -> bool {
+ #[expect(deprecated)]
self.inner.is_nullable()
}
diff --git a/datafusion/ffi/src/udaf/mod.rs b/datafusion/ffi/src/udaf/mod.rs
index ae8394d8d0..aaa67135e6 100644
--- a/datafusion/ffi/src/udaf/mod.rs
+++ b/datafusion/ffi/src/udaf/mod.rs
@@ -386,6 +386,7 @@ impl From<Arc<AggregateUDF>> for FFI_AggregateUDF {
let name = udaf.name().into();
let aliases = udaf.aliases().iter().map(|a| a.to_owned().into()).collect();
+ #[expect(deprecated)]
let is_nullable = udaf.is_nullable();
let volatility = udaf.signature().volatility.into();
diff --git a/datafusion/functions-aggregate/src/approx_distinct.rs b/datafusion/functions-aggregate/src/approx_distinct.rs
index c60725b5d0..ded210502a 100644
--- a/datafusion/functions-aggregate/src/approx_distinct.rs
+++ b/datafusion/functions-aggregate/src/approx_distinct.rs
@@ -733,6 +733,11 @@ impl AggregateUDFImpl for ApproxDistinct {
Ok(ScalarValue::UInt64(Some(0)))
}
+ fn return_field(&self, _arg_fields: &[FieldRef]) -> Result<FieldRef> {
+ Ok(Arc::new(Field::new(self.name(), DataType::UInt64, false)))
+ }
+
+ // Keep the deprecated method consistent with `return_field` until it is removed
fn is_nullable(&self) -> bool {
false
}
diff --git a/datafusion/functions-aggregate/src/count.rs b/datafusion/functions-aggregate/src/count.rs
index ceec1ce668..0a8d4387da 100644
--- a/datafusion/functions-aggregate/src/count.rs
+++ b/datafusion/functions-aggregate/src/count.rs
@@ -287,6 +287,11 @@ impl AggregateUDFImpl for Count {
Ok(DataType::Int64)
}
+ fn return_field(&self, _arg_fields: &[FieldRef]) -> Result<FieldRef> {
+ Ok(Arc::new(Field::new(self.name(), DataType::Int64, false)))
+ }
+
+ // Keep the deprecated method consistent with `return_field` until it is removed
fn is_nullable(&self) -> bool {
false
}
diff --git a/datafusion/functions-aggregate/src/lib.rs b/datafusion/functions-aggregate/src/lib.rs
index 2f0fa7901c..376342c345 100644
--- a/datafusion/functions-aggregate/src/lib.rs
+++ b/datafusion/functions-aggregate/src/lib.rs
@@ -196,8 +196,13 @@ pub fn register_all(registry: &mut dyn FunctionRegistry) -> Result<()> {
#[cfg(test)]
mod tests {
use crate::all_default_aggregate_functions;
+ use crate::approx_distinct::approx_distinct_udaf;
+ use crate::count::count_udaf;
+ use crate::regr::{regr_count_udaf, regr_slope_udaf};
+ use arrow::datatypes::{DataType, Field};
use datafusion_common::Result;
use std::collections::HashSet;
+ use std::sync::Arc;
#[test]
fn test_no_duplicate_name() -> Result<()> {
@@ -217,4 +222,33 @@ mod tests {
}
Ok(())
}
+
+ #[test]
+ #[expect(deprecated)]
+ fn test_is_nullable_matches_return_field() -> Result<()> {
+ let int64 = Arc::new(Field::new("a", DataType::Int64, true));
+ let float64 = Arc::new(Field::new("a", DataType::Float64, true));
+ let cases = [
+ (count_udaf(), vec![Arc::clone(&int64)]),
+ (approx_distinct_udaf(), vec![Arc::clone(&int64)]),
+ (
+ regr_count_udaf(),
+ vec![Arc::clone(&float64), Arc::clone(&float64)],
+ ),
+ (
+ regr_slope_udaf(),
+ vec![Arc::clone(&float64), Arc::clone(&float64)],
+ ),
+ ];
+ for (udaf, arg_fields) in cases {
+ let field = udaf.return_field(&arg_fields)?;
+ assert_eq!(
+ udaf.is_nullable(),
+ field.is_nullable(),
+ "is_nullable and return_field disagree for {}",
+ udaf.name()
+ );
+ }
+ Ok(())
+ }
}
diff --git a/datafusion/functions-aggregate/src/regr.rs b/datafusion/functions-aggregate/src/regr.rs
index 423982966d..a2d32a52e2 100644
--- a/datafusion/functions-aggregate/src/regr.rs
+++ b/datafusion/functions-aggregate/src/regr.rs
@@ -452,6 +452,17 @@ impl AggregateUDFImpl for Regr {
}
}
+ fn return_field(&self, arg_fields: &[FieldRef]) -> Result<FieldRef> {
+ let arg_types: Vec<_> =
+ arg_fields.iter().map(|f| f.data_type()).cloned().collect();
+ Ok(Arc::new(Field::new(
+ self.name(),
+ self.return_type(&arg_types)?,
+ self.regr_type != RegrType::Count,
+ )))
+ }
+
+ // Keep the deprecated method consistent with `return_field` until it is removed
fn is_nullable(&self) -> bool {
self.regr_type != RegrType::Count
}
diff --git a/datafusion/physical-expr/src/aggregate.rs b/datafusion/physical-expr/src/aggregate.rs
index 62455a30f4..4b6af0a434 100644
--- a/datafusion/physical-expr/src/aggregate.rs
+++ b/datafusion/physical-expr/src/aggregate.rs
@@ -288,7 +288,6 @@ impl AggregateExprBuilder {
if let Some(output_metadata) = output_metadata {
return_field = output_metadata.add_to_field_ref(return_field);
}
- let is_nullable = fun.is_nullable();
let Some(name) = alias else {
return internal_err!(
"AggregateExprBuilder::alias must be provided prior to calling build"
@@ -317,7 +316,6 @@ impl AggregateExprBuilder {
is_distinct,
input_fields: input_exprs_fields,
is_reversed,
- is_nullable,
})
}
@@ -667,7 +665,6 @@ pub struct AggregateFunctionExpr {
is_distinct: bool,
is_reversed: bool,
input_fields: Vec<FieldRef>,
- is_nullable: bool,
}
impl AggregateFunctionExpr {
@@ -728,7 +725,7 @@ impl AggregateFunctionExpr {
/// Return if the aggregation is nullable
pub fn is_nullable(&self) -> bool {
- self.is_nullable
+ self.return_field.is_nullable()
}
/// the field of the final result of this aggregation.
@@ -1091,7 +1088,6 @@ impl AggregateFunctionExpr {
is_distinct: self.is_distinct,
is_reversed: false,
input_fields: self.input_fields.clone(),
- is_nullable: self.is_nullable,
})
}
diff --git a/docs/source/library-user-guide/upgrading/56.0.0.md b/docs/source/library-user-guide/upgrading/56.0.0.md
index 9e09a53377..78e2a2cf90 100644
--- a/docs/source/library-user-guide/upgrading/56.0.0.md
+++ b/docs/source/library-user-guide/upgrading/56.0.0.md
@@ -1432,3 +1432,30 @@ final plan instead.
A custom rule list that left out `SanityCheckPlan` is now checked too. A plan
whose requirements do not hold, such as a `SortMergeJoinExec` over unsorted
input, now fails to plan instead of possibly returning wrong results.
+
+### `AggregateUDFImpl::is_nullable` is deprecated
+
+`AggregateUDFImpl::is_nullable` is deprecated; set the nullability in the field
+returned by `AggregateUDFImpl::return_field` instead. The compiler does not
+warn about existing overrides. Keep them, consistent with `return_field`,
+until the method is removed, as callers of the deprecated method still use them.
+
+**Migration guide:**
+
+```rust,ignore
+// Before
+fn is_nullable(&self) -> bool {
+ false
+}
+
+// After
+fn return_field(&self, _arg_fields: &[FieldRef]) -> Result<FieldRef> {
+ Ok(Arc::new(Field::new(self.name(), DataType::Int64, false)))
+}
+
+fn is_nullable(&self) -> bool {
+ false
+}
+```
+
+See [issue #18882](https://github.com/apache/datafusion/issues/18882) for details.