Apache DataFusion SQL Query Engine
fix: avoid overflow and underflow in vector functions (#25289)
namanjain24-sudo7deda309436f
diff --git a/datafusion/functions-nested/src/array_normalize.rs b/datafusion/functions-nested/src/array_normalize.rsindex 8f4342cd83..988e2679b9 100644--- a/datafusion/functions-nested/src/array_normalize.rs+++ b/datafusion/functions-nested/src/array_normalize.rs@@ -17,7 +17,7 @@//! [`ScalarUDFImpl`] definitions for array_normalize function.-use crate::utils::make_scalar_function;+use crate::utils::{make_scalar_function, needs_norm_scale, norm_scale};use arrow::array::{Array, ArrayRef, Float64Array, GenericListArray, NullBufferBuilder, OffsetSizeTrait,};@@ -181,6 +181,22 @@ fn general_array_normalize<O: OffsetSizeTrait>(arrays: &[ArrayRef]) -> Result<Arsq_sum += vals[i] * vals[i];}+ // If a square may have overflowed or underflowed, recompute with scaled+ // values. Dividing the scaled values by the scaled magnitude gives the+ // same unit vector.+ let scale = if needs_norm_scale(sq_sum, len) {+ norm_scale(vals.iter().copied())+ } else {+ None+ };+ if let Some(scale) = scale {+ sq_sum = 0.0;+ for i in 0..len {+ let scaled = vals[i] * scale;+ sq_sum += scaled * scaled;+ }+ }+// Zero magnitude: undefined normalization. Emit NULL row.if sq_sum == 0.0 {nulls.append_null();@@ -189,8 +205,9 @@ fn general_array_normalize<O: OffsetSizeTrait>(arrays: &[ArrayRef]) -> Result<Ar}let mag = sq_sum.sqrt();- for i in 0..len {- new_values.push(vals[i] / mag);+ match scale {+ Some(scale) => new_values.extend(vals.iter().map(|v| v * scale / mag)),+ None => new_values.extend(vals.iter().map(|v| v / mag)),}nulls.append_non_null();new_offsets.push(new_offsets[row] + O::usize_as(len));diff --git a/datafusion/functions-nested/src/cosine_distance.rs b/datafusion/functions-nested/src/cosine_distance.rsindex 56ca071234..1637b2cea1 100644--- a/datafusion/functions-nested/src/cosine_distance.rs+++ b/datafusion/functions-nested/src/cosine_distance.rs@@ -17,7 +17,7 @@//! [`ScalarUDFImpl`] definitions for cosine_distance function.-use crate::utils::make_scalar_function;+use crate::utils::{make_scalar_function, needs_norm_scale, norm_scale};use arrow::array::{Array, ArrayRef, Float64Array, OffsetSizeTrait};use arrow::datatypes::{DataType,@@ -197,15 +197,30 @@ fn general_cosine_distance<O: OffsetSizeTrait>(arrays: &[ArrayRef]) -> Result<Arlet vals1 = slice1.values();let vals2 = slice2.values();- let mut dot = 0.0;- let mut sq1 = 0.0;- let mut sq2 = 0.0;- for i in 0..len1 {- let a = vals1[i];- let b = vals2[i];- dot += a * b;- sq1 += a * a;- sq2 += b * b;+ let (mut dot, mut sq1, mut sq2) = dot_and_squares(vals1, vals2, 1.0, 1.0);+ // Cosine distance does not change when either vector is multiplied by a+ // positive factor, so scale only a vector whose own sum of squares is+ // out of range, and recompute only if there is something to scale. A+ // vector whose sum is in range can stay unscaled: its products cannot+ // overflow, and its underflow error is already negligible.+ let rescale_both = !dot.is_finite();+ let scale1 = if rescale_both || needs_norm_scale(sq1, len1) {+ norm_scale(vals1.iter().copied())+ } else {+ None+ };+ let scale2 = if rescale_both || needs_norm_scale(sq2, len1) {+ norm_scale(vals2.iter().copied())+ } else {+ None+ };+ if scale1.is_some() || scale2.is_some() {+ (dot, sq1, sq2) = dot_and_squares(+ vals1,+ vals2,+ scale1.unwrap_or(1.0),+ scale2.unwrap_or(1.0),+ );}if sq1 == 0.0 || sq2 == 0.0 {@@ -217,3 +232,25 @@ fn general_cosine_distance<O: OffsetSizeTrait>(arrays: &[ArrayRef]) -> Result<ArOk(Arc::new(builder.finish()) as ArrayRef)}++/// Returns the dot product of `vals1 * scale1` and `vals2 * scale2`, and the+/// sum of squares of each.+#[inline]+fn dot_and_squares(+ vals1: &[f64],+ vals2: &[f64],+ scale1: f64,+ scale2: f64,+) -> (f64, f64, f64) {+ let mut dot = 0.0;+ let mut sq1 = 0.0;+ let mut sq2 = 0.0;+ for (a, b) in vals1.iter().zip(vals2) {+ let a = a * scale1;+ let b = b * scale2;+ dot += a * b;+ sq1 += a * a;+ sq2 += b * b;+ }+ (dot, sq1, sq2)+}diff --git a/datafusion/functions-nested/src/distance.rs b/datafusion/functions-nested/src/distance.rsindex d9182e871f..36b263870d 100644--- a/datafusion/functions-nested/src/distance.rs+++ b/datafusion/functions-nested/src/distance.rs@@ -17,7 +17,7 @@//! [ScalarUDFImpl] definitions for array_distance function.-use crate::utils::make_scalar_function;+use crate::utils::{make_scalar_function, needs_norm_scale, norm_scale};use arrow::array::{Array, ArrayRef, Float64Array, OffsetSizeTrait};use arrow::datatypes::{DataType,@@ -189,16 +189,33 @@ fn compute_array_distance(return exec_err!("Both arrays must have the same length");}- let sum_squares: f64 = values1- .iter()- .zip(values2.iter())- .map(|(v1, v2)| {- let diff = v1.unwrap_or(0.0) - v2.unwrap_or(0.0);- diff * diff- })- .sum();-- Ok(Some(sum_squares.sqrt()))+ let diffs = || {+ values1+ .values()+ .iter()+ .zip(values2.values().iter())+ .map(|(v1, v2)| v1 - v2)+ };++ let sum_squares: f64 = diffs().map(|diff| diff * diff).sum();+ if !needs_norm_scale(sum_squares, values1.len()) {+ return Ok(Some(sum_squares.sqrt()));+ }++ let distance = match norm_scale(diffs()) {+ Some(scale) => {+ let scaled_sum_squares: f64 = diffs()+ .map(|diff| {+ let scaled = diff * scale;+ scaled * scaled+ })+ .sum();+ scaled_sum_squares.sqrt() / scale+ }+ None => sum_squares.sqrt(),+ };++ Ok(Some(distance))}/// Converts an array of any numeric type to a Float64Array.diff --git a/datafusion/functions-nested/src/utils.rs b/datafusion/functions-nested/src/utils.rsindex 2906250ec6..a6a93ed5df 100644--- a/datafusion/functions-nested/src/utils.rs+++ b/datafusion/functions-nested/src/utils.rs@@ -463,6 +463,49 @@ where)?))}+/// Returns a power of two that brings the largest magnitude in `values` close+/// to 1, so that squaring the scaled values neither overflows nor underflows.+///+/// Squaring a large finite value overflows (`1e200 * 1e200` is infinity) and+/// squaring a small one underflows (`1e-200 * 1e-200` is zero), even when the+/// norm itself is representable. The factor is a power of two, so scaling is+/// exact whenever the scaled value is normal. A value that becomes subnormal is+/// rounded, so an `array_normalize` element that is itself subnormal can differ+/// from the unscaled result in its last bit.+///+/// Returns `None` when `values` is empty, all zero, or contains an infinity.+/// The unscaled computation already gives the expected result for those inputs.+/// NaN values are ignored, and the scaled computation still produces NaN.+pub(crate) fn norm_scale(values: impl IntoIterator<Item = f64>) -> Option<f64> {+ // No early return inside the loop, so that it vectorizes. `f64::max` skips+ // NaN, so only an infinity can make `max` non-finite.+ let mut max = 0.0_f64;+ for value in values {+ max = max.max(value.abs());+ }+ if max == 0.0 || !max.is_finite() {+ return None;+ }+ // Unbiased exponent of `max`. Subnormal values store a biased exponent of 0,+ // so clamp them to the smallest normal exponent.+ let exponent = ((max.to_bits() >> 52) as i32 - 1023).max(-1022);+ Some(2.0_f64.powi(-exponent))+}++/// Returns whether a sum of `len` squares computed without scaling may be+/// wrong because a square overflowed or underflowed, in which case it should be+/// recomputed with the factor from [`norm_scale`].+///+/// An overflowing square makes the sum infinite. An underflowing square is off+/// by at most half the smallest subnormal value, so `len` of them move the sum+/// by at most `len * 2^-1075`. A sum of at least `len * 2^-1012` is therefore+/// off by less than `2^-63` of itself, far below its rounding precision.+pub(crate) fn needs_norm_scale(sum_of_squares: f64, len: usize) -> bool {+ // 2^-1012 = 2^10 * f64::MIN_POSITIVE+ let min_unscaled = 1024.0 * len as f64 * f64::MIN_POSITIVE;+ !(min_unscaled..f64::INFINITY).contains(&sum_of_squares)+}+#[cfg(test)]mod tests {use super::*;@@ -518,4 +561,45 @@ mod tests {expected_dim);}++ #[test]+ fn norm_scale_brings_largest_magnitude_close_to_one() {+ assert_eq!(norm_scale([3e200, -4e200]), Some(2.0_f64.powi(-666)));+ assert_eq!(norm_scale([3.0, 4.0]), Some(0.25));+ // 2^-1023 and 2^1022, pinned by bit pattern rather than computed+ assert_eq!(norm_scale([f64::MAX]), Some(f64::from_bits(1 << 51)));+ assert_eq!(+ norm_scale([f64::MIN_POSITIVE / 4.0]),+ Some(f64::from_bits(2045 << 52))+ );+ // NaN is ignored; the scaled computation still produces NaN+ assert_eq!(norm_scale([f64::NAN, 3.0, 4.0]), Some(0.25));+ }++ #[test]+ fn norm_scale_skips_inputs_the_unscaled_computation_handles() {+ assert_eq!(norm_scale([]), None);+ assert_eq!(norm_scale([0.0, -0.0]), None);+ assert_eq!(norm_scale([f64::NAN, 0.0]), None);+ assert_eq!(norm_scale([f64::INFINITY, 1.0]), None);+ assert_eq!(norm_scale([1.0, f64::NAN, f64::NEG_INFINITY]), None);+ }++ #[test]+ fn needs_norm_scale_only_for_sums_that_may_have_overflowed_or_underflowed() {+ assert!(!needs_norm_scale(1.0, 1));+ assert!(!needs_norm_scale(f64::MAX, 1));+ // The square of 1e-100 is 1e-200, which is far from underflowing.+ assert!(!needs_norm_scale(1e-200, 1));+ assert!(!needs_norm_scale(1e-200, 1536));++ let min_unscaled = 1024.0 * f64::MIN_POSITIVE;+ assert!(!needs_norm_scale(min_unscaled, 1));+ assert!(needs_norm_scale(min_unscaled, 2));+ assert!(needs_norm_scale(min_unscaled / 2.0, 1));++ assert!(needs_norm_scale(0.0, 1));+ assert!(needs_norm_scale(f64::INFINITY, 1));+ assert!(needs_norm_scale(f64::NAN, 1));+ }}diff --git a/datafusion/sqllogictest/test_files/array/array_length.slt b/datafusion/sqllogictest/test_files/array/array_length.sltindex 7741d815bc..bbfda57811 100644--- a/datafusion/sqllogictest/test_files/array/array_length.slt+++ b/datafusion/sqllogictest/test_files/array/array_length.slt@@ -197,6 +197,23 @@ select----NULL NULL+# array_distance scales the differences before squaring them, so finite+# inputs whose squares overflow or underflow still give the correct distance+query RR+select+ array_distance([CAST(1e-200 AS DOUBLE)], [CAST(0 AS DOUBLE)]) / 1e-200,+ array_distance([CAST(3e200 AS DOUBLE)], [CAST(-1e200 AS DOUBLE)]) / 1e200;+----+1 4++# non-finite inputs propagate as before+query RR+select+ array_distance([CAST('Infinity' AS DOUBLE)], [CAST(0 AS DOUBLE)]),+ array_distance([CAST('NaN' AS DOUBLE)], [CAST(0 AS DOUBLE)]);+----+Infinity NaN+# invalid argument count and typesquery error DataFusion error: Error during planning: Execution error: Function 'array_distance' user-defined coercion failed with: Execution error: array_distance function requires 2 argumentsselect array_distance();diff --git a/datafusion/sqllogictest/test_files/array_normalize.slt b/datafusion/sqllogictest/test_files/array_normalize.sltindex ba4711d02c..f9fbc14144 100644--- a/datafusion/sqllogictest/test_files/array_normalize.slt+++ b/datafusion/sqllogictest/test_files/array_normalize.slt@@ -144,3 +144,18 @@ select list_normalize(column1) from (values----[0.6, 0.8]NULL++# array_normalize scales the values before squaring them, so finite inputs+# whose squares overflow or underflow still normalize correctly+query ??+select+ array_normalize([3 * power(2.0, 700), 4 * power(2.0, 700)]),+ array_normalize([3 * power(2.0, -700), -4 * power(2.0, -700)]);+----+[0.6, 0.8] [0.6, -0.8]++# non-finite inputs propagate as before+query ?+select array_normalize([CAST('Infinity' AS DOUBLE), 1.0]);+----+[NaN, 0.0]diff --git a/datafusion/sqllogictest/test_files/cosine_distance.slt b/datafusion/sqllogictest/test_files/cosine_distance.sltindex 9142aac8cf..12bc5621ed 100644--- a/datafusion/sqllogictest/test_files/cosine_distance.slt+++ b/datafusion/sqllogictest/test_files/cosine_distance.slt@@ -165,3 +165,30 @@ query RTselect cosine_distance([1.0, 0.0], [0.0, 1.0]), arrow_typeof(cosine_distance([1.0, 0.0], [0.0, 1.0]));----1 Float64++# cosine_distance scales each vector before multiplying, so finite inputs+# whose products overflow or underflow still give the correct distance+query RRR+select+ cosine_distance([CAST(3e200 AS DOUBLE), CAST(4e200 AS DOUBLE)], [CAST(3e200 AS DOUBLE), CAST(4e200 AS DOUBLE)]),+ cosine_distance([CAST(1e-200 AS DOUBLE), CAST(2e-200 AS DOUBLE)], [CAST(1e-200 AS DOUBLE), CAST(2e-200 AS DOUBLE)]),+ cosine_distance([CAST(1e200 AS DOUBLE), CAST(0 AS DOUBLE)], [CAST(-1e-200 AS DOUBLE), CAST(0 AS DOUBLE)]);+----+0 0 2++# non-finite inputs propagate as before+query RR+select+ cosine_distance([CAST('NaN' AS DOUBLE), 1.0], [1.0, 1.0]),+ cosine_distance([CAST('Infinity' AS DOUBLE), 1.0], [1.0, 1.0]);+----+NaN NaN++# only one vector's sum of squares is out of range, so only that vector is+# scaled and the dot product mixes a scaled value with an unscaled one+query RR+select+ cosine_distance([CAST(1e200 AS DOUBLE), CAST(0 AS DOUBLE)], [CAST(1 AS DOUBLE), CAST(0 AS DOUBLE)]),+ cosine_distance([CAST(1e200 AS DOUBLE), CAST(1 AS DOUBLE)], [CAST(1e-200 AS DOUBLE), CAST(1 AS DOUBLE)]);+----+0 1