Apache DataFusion SQL Query Engine
docs: clarify difference between try_cast_literal_to_type and ScalarValue::cast_to (#22592)
Andrew Lambeedae1154bf2
diff --git a/datafusion/common/src/scalar/mod.rs b/datafusion/common/src/scalar/mod.rsindex 1a98547785..73088dd942 100644--- a/datafusion/common/src/scalar/mod.rs+++ b/datafusion/common/src/scalar/mod.rs@@ -4212,12 +4212,31 @@ impl ScalarValue {Some(v.as_ref().map(|v| v.as_str()))}- /// Try to cast this value to a ScalarValue of type `data_type`+ /// Cast this value to a `ScalarValue` of type `target_type` using the+ /// default [`CastOptions`].+ ///+ /// This is a general-purpose cast with the same semantics as the Arrow+ /// [`cast_with_options`] kernel and can therefore **lose information** --+ /// for example casting the floating point value `123.45` to the integer+ /// `123`.+ ///+ /// Returns an error for casts the Arrow kernel cannot perform.+ ///+ /// # See Also+ /// - [`try_cast_literal_to_type`]: for a *value-preserving* cast+ ///+ /// [`try_cast_literal_to_type`]: https://docs.rs/datafusion/latest/datafusion/logical_expr_common/casts/fn.try_cast_literal_to_type.htmlpub fn cast_to(&self, target_type: &DataType) -> Result<Self> {self.cast_to_with_options(target_type, &DEFAULT_CAST_OPTIONS)}- /// Try to cast this value to a ScalarValue of type `data_type` with [`CastOptions`]+ /// Cast this value to type `target_type` with the given [`CastOptions`].+ ///+ /// # See Also+ /// - [`ScalarValue::cast_to`] for more details.+ /// - [`try_cast_literal_to_type`]: for a *value-preserving* cast+ ///+ /// [`try_cast_literal_to_type`]: https://docs.rs/datafusion/latest/datafusion/logical_expr_common/casts/fn.try_cast_literal_to_type.htmlpub fn cast_to_with_options(&self,target_type: &DataType,diff --git a/datafusion/expr-common/src/casts.rs b/datafusion/expr-common/src/casts.rsindex dad589e4bf..d18c3d4f04 100644--- a/datafusion/expr-common/src/casts.rs+++ b/datafusion/expr-common/src/casts.rs@@ -31,7 +31,31 @@ use arrow::datatypes::{use arrow::temporal_conversions::{MICROSECONDS, MILLISECONDS, NANOSECONDS};use datafusion_common::ScalarValue;-/// Convert a literal value from one data type to another+/// Convert a literal [`ScalarValue`] to `target_type`, preserving the exact value.+///+/// Returns `None` if the value cannot be represented in `target_type`+/// *exactly*.+///+/// This is a restricted, value-preserving cast used to rewrite comparison+/// predicates of the form `CAST(col AS target_type) <op> literal` into+/// `col <op> try_cast_literal_to_type(literal, col_type)`. That rewrite is+/// only valid when the cast cannot change the comparison result.+///+/// # Supported Casts+/// * numeric → numeric, including integers, decimals, `Date32`/`Date64` and+/// `Timestamp`s, rejecting values outside the target's range or that would+/// lose decimal digits+/// * string → string between `Utf8`, `LargeUtf8` and `Utf8View`+/// * wrapping a value into, or unwrapping it out of, a `Dictionary` whose value+/// type matches the literal's type+/// * `Binary` → `FixedSizeBinary` of the matching length+/// * `Timestamp` → `Timestamp` cast between different time units is allowed even+/// though it can truncate (for example nanoseconds → seconds), and a unit+/// conversion that overflows yields a `NULL` literal rather than `None`.+///+/// # See Also+/// - [`ScalarValue::cast_to`]: a general-purpose cast that can lose information+/// or change a value's meaning.pub fn try_cast_literal_to_type(lit_value: &ScalarValue,target_type: &DataType,