From a9b202c9824caff41dd648382643c1ba891f3d90 Mon Sep 17 00:00:00 2001 From: juroberttyb Date: Tue, 15 Oct 2024 22:27:58 +0800 Subject: [PATCH] Migrate documentation for all math functions from scalar_functions.md to code (#12908) * migrate: math doc from static to code gen * remove: documentation for pow * use: fmt * rm: unused import --------- Co-authored-by: Andrew Lamb --- datafusion/functions/src/macros.rs | 20 +- datafusion/functions/src/math/abs.rs | 25 +- datafusion/functions/src/math/factorial.rs | 25 +- datafusion/functions/src/math/gcd.rs | 29 +- datafusion/functions/src/math/iszero.rs | 28 +- datafusion/functions/src/math/lcm.rs | 29 +- datafusion/functions/src/math/mod.rs | 75 ++- datafusion/functions/src/math/monotonicity.rs | 341 +++++++++++ datafusion/functions/src/math/nans.rs | 25 +- datafusion/functions/src/math/nanvl.rs | 30 +- datafusion/functions/src/math/pi.rs | 23 +- datafusion/functions/src/math/power.rs | 26 +- datafusion/functions/src/math/random.rs | 25 +- datafusion/functions/src/math/round.rs | 29 +- datafusion/functions/src/math/signum.rs | 30 +- datafusion/functions/src/math/trunc.rs | 32 +- .../source/user-guide/sql/scalar_functions.md | 528 ------------------ .../user-guide/sql/scalar_functions_new.md | 486 ++++++++++++++++ 18 files changed, 1221 insertions(+), 585 deletions(-) diff --git a/datafusion/functions/src/macros.rs b/datafusion/functions/src/macros.rs index e850673ef8af..cf25ff832896 100644 --- a/datafusion/functions/src/macros.rs +++ b/datafusion/functions/src/macros.rs @@ -161,7 +161,7 @@ macro_rules! downcast_arg { /// $UNARY_FUNC: the unary function to apply to the argument /// $OUTPUT_ORDERING: the output ordering calculation method of the function macro_rules! make_math_unary_udf { - ($UDF:ident, $GNAME:ident, $NAME:ident, $UNARY_FUNC:ident, $OUTPUT_ORDERING:expr, $EVALUATE_BOUNDS:expr) => { + ($UDF:ident, $GNAME:ident, $NAME:ident, $UNARY_FUNC:ident, $OUTPUT_ORDERING:expr, $EVALUATE_BOUNDS:expr, $GET_DOC:expr) => { make_udf_function!($NAME::$UDF, $GNAME, $NAME); mod $NAME { @@ -173,7 +173,9 @@ macro_rules! make_math_unary_udf { use datafusion_common::{exec_err, DataFusionError, Result}; use datafusion_expr::interval_arithmetic::Interval; use datafusion_expr::sort_properties::{ExprProperties, SortProperties}; - use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; + use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, + }; #[derive(Debug)] pub struct $UDF { @@ -257,6 +259,10 @@ macro_rules! make_math_unary_udf { }; Ok(ColumnarValue::Array(arr)) } + + fn documentation(&self) -> Option<&Documentation> { + Some($GET_DOC()) + } } } }; @@ -273,7 +279,7 @@ macro_rules! make_math_unary_udf { /// $BINARY_FUNC: the binary function to apply to the argument /// $OUTPUT_ORDERING: the output ordering calculation method of the function macro_rules! make_math_binary_udf { - ($UDF:ident, $GNAME:ident, $NAME:ident, $BINARY_FUNC:ident, $OUTPUT_ORDERING:expr) => { + ($UDF:ident, $GNAME:ident, $NAME:ident, $BINARY_FUNC:ident, $OUTPUT_ORDERING:expr, $GET_DOC:expr) => { make_udf_function!($NAME::$UDF, $GNAME, $NAME); mod $NAME { @@ -285,7 +291,9 @@ macro_rules! make_math_binary_udf { use datafusion_common::{exec_err, DataFusionError, Result}; use datafusion_expr::sort_properties::{ExprProperties, SortProperties}; use datafusion_expr::TypeSignature; - use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; + use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, + }; #[derive(Debug)] pub struct $UDF { @@ -366,6 +374,10 @@ macro_rules! make_math_binary_udf { }; Ok(ColumnarValue::Array(arr)) } + + fn documentation(&self) -> Option<&Documentation> { + Some($GET_DOC()) + } } } }; diff --git a/datafusion/functions/src/math/abs.rs b/datafusion/functions/src/math/abs.rs index f7a17f0caf94..5dcbb99eae65 100644 --- a/datafusion/functions/src/math/abs.rs +++ b/datafusion/functions/src/math/abs.rs @@ -18,7 +18,7 @@ //! math expressions use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use arrow::array::{ ArrayRef, Decimal128Array, Decimal256Array, Float32Array, Float64Array, Int16Array, @@ -28,8 +28,11 @@ use arrow::datatypes::DataType; use arrow::error::ArrowError; use datafusion_common::{exec_err, not_impl_err, DataFusionError, Result}; use datafusion_expr::interval_arithmetic::Interval; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; use datafusion_expr::sort_properties::{ExprProperties, SortProperties}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; type MathArrayFunction = fn(&Vec) -> Result; @@ -184,4 +187,22 @@ impl ScalarUDFImpl for AbsFunc { Ok(SortProperties::Unordered) } } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_abs_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_abs_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the absolute value of a number.") + .with_syntax_example("abs(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) } diff --git a/datafusion/functions/src/math/factorial.rs b/datafusion/functions/src/math/factorial.rs index 74ad2c738a93..ac04c03190ae 100644 --- a/datafusion/functions/src/math/factorial.rs +++ b/datafusion/functions/src/math/factorial.rs @@ -20,14 +20,17 @@ use arrow::{ error::ArrowError, }; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use arrow::datatypes::DataType; use arrow::datatypes::DataType::Int64; use crate::utils::make_scalar_function; use datafusion_common::{arrow_datafusion_err, exec_err, DataFusionError, Result}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; #[derive(Debug)] pub struct FactorialFunc { @@ -68,6 +71,24 @@ impl ScalarUDFImpl for FactorialFunc { fn invoke(&self, args: &[ColumnarValue]) -> Result { make_scalar_function(factorial, vec![])(args) } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_factorial_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_factorial_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Factorial. Returns 1 if value is less than 2.") + .with_syntax_example("factorial(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) } /// Factorial SQL function diff --git a/datafusion/functions/src/math/gcd.rs b/datafusion/functions/src/math/gcd.rs index 10faf9f390bb..5e56dacb9380 100644 --- a/datafusion/functions/src/math/gcd.rs +++ b/datafusion/functions/src/math/gcd.rs @@ -19,15 +19,17 @@ use arrow::array::{ArrayRef, Int64Array}; use arrow::error::ArrowError; use std::any::Any; use std::mem::swap; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use arrow::datatypes::DataType; use arrow::datatypes::DataType::Int64; use crate::utils::make_scalar_function; use datafusion_common::{arrow_datafusion_err, exec_err, DataFusionError, Result}; -use datafusion_expr::ColumnarValue; -use datafusion_expr::{ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; #[derive(Debug)] pub struct GcdFunc { @@ -69,6 +71,27 @@ impl ScalarUDFImpl for GcdFunc { fn invoke(&self, args: &[ColumnarValue]) -> Result { make_scalar_function(gcd, vec![])(args) } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_gcd_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_gcd_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero.", + ) + .with_syntax_example("gcd(expression_x, expression_y)") + .with_standard_argument("expression_x", "First numeric") + .with_standard_argument("expression_y", "Second numeric") + .build() + .unwrap() + }) } /// Gcd SQL function diff --git a/datafusion/functions/src/math/iszero.rs b/datafusion/functions/src/math/iszero.rs index 74611b65aaba..b8deee2c6125 100644 --- a/datafusion/functions/src/math/iszero.rs +++ b/datafusion/functions/src/math/iszero.rs @@ -16,16 +16,18 @@ // under the License. use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use arrow::array::{ArrayRef, AsArray, BooleanArray}; use arrow::datatypes::DataType::{Boolean, Float32, Float64}; use arrow::datatypes::{DataType, Float32Type, Float64Type}; use datafusion_common::{exec_err, Result}; -use datafusion_expr::ColumnarValue; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; use datafusion_expr::TypeSignature::Exact; -use datafusion_expr::{ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use crate::utils::make_scalar_function; @@ -72,6 +74,26 @@ impl ScalarUDFImpl for IsZeroFunc { fn invoke(&self, args: &[ColumnarValue]) -> Result { make_scalar_function(iszero, vec![])(args) } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_iszero_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_iszero_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns true if a given number is +0.0 or -0.0 otherwise returns false.", + ) + .with_syntax_example("iszero(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) } /// Iszero SQL function diff --git a/datafusion/functions/src/math/lcm.rs b/datafusion/functions/src/math/lcm.rs index 21c201657e90..844dbfd39d38 100644 --- a/datafusion/functions/src/math/lcm.rs +++ b/datafusion/functions/src/math/lcm.rs @@ -16,7 +16,7 @@ // under the License. use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use arrow::array::{ArrayRef, Int64Array}; use arrow::datatypes::DataType; @@ -24,8 +24,10 @@ use arrow::datatypes::DataType::Int64; use arrow::error::ArrowError; use datafusion_common::{arrow_datafusion_err, exec_err, DataFusionError, Result}; -use datafusion_expr::ColumnarValue; -use datafusion_expr::{ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use super::gcd::unsigned_gcd; use crate::utils::make_scalar_function; @@ -70,6 +72,27 @@ impl ScalarUDFImpl for LcmFunc { fn invoke(&self, args: &[ColumnarValue]) -> Result { make_scalar_function(lcm, vec![])(args) } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_lcm_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_lcm_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero.", + ) + .with_syntax_example("lcm(expression_x, expression_y)") + .with_standard_argument("expression_x", "First numeric") + .with_standard_argument("expression_y", "Second numeric") + .build() + .unwrap() + }) } /// Lcm SQL function diff --git a/datafusion/functions/src/math/mod.rs b/datafusion/functions/src/math/mod.rs index b221fb900cfa..1452bfdee5a0 100644 --- a/datafusion/functions/src/math/mod.rs +++ b/datafusion/functions/src/math/mod.rs @@ -47,7 +47,8 @@ make_math_unary_udf!( acos, acos, super::acos_order, - super::bounds::acos_bounds + super::bounds::acos_bounds, + super::get_acos_doc ); make_math_unary_udf!( AcoshFunc, @@ -55,7 +56,8 @@ make_math_unary_udf!( acosh, acosh, super::acosh_order, - super::bounds::acosh_bounds + super::bounds::acosh_bounds, + super::get_acosh_doc ); make_math_unary_udf!( AsinFunc, @@ -63,7 +65,8 @@ make_math_unary_udf!( asin, asin, super::asin_order, - super::bounds::asin_bounds + super::bounds::asin_bounds, + super::get_asin_doc ); make_math_unary_udf!( AsinhFunc, @@ -71,7 +74,8 @@ make_math_unary_udf!( asinh, asinh, super::asinh_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_asinh_doc ); make_math_unary_udf!( AtanFunc, @@ -79,7 +83,8 @@ make_math_unary_udf!( atan, atan, super::atan_order, - super::bounds::atan_bounds + super::bounds::atan_bounds, + super::get_atan_doc ); make_math_unary_udf!( AtanhFunc, @@ -87,16 +92,25 @@ make_math_unary_udf!( atanh, atanh, super::atanh_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_atanh_doc +); +make_math_binary_udf!( + Atan2, + ATAN2, + atan2, + atan2, + super::atan2_order, + super::get_atan2_doc ); -make_math_binary_udf!(Atan2, ATAN2, atan2, atan2, super::atan2_order); make_math_unary_udf!( CbrtFunc, CBRT, cbrt, cbrt, super::cbrt_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_cbrt_doc ); make_math_unary_udf!( CeilFunc, @@ -104,7 +118,8 @@ make_math_unary_udf!( ceil, ceil, super::ceil_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_ceil_doc ); make_math_unary_udf!( CosFunc, @@ -112,7 +127,8 @@ make_math_unary_udf!( cos, cos, super::cos_order, - super::bounds::cos_bounds + super::bounds::cos_bounds, + super::get_cos_doc ); make_math_unary_udf!( CoshFunc, @@ -120,7 +136,8 @@ make_math_unary_udf!( cosh, cosh, super::cosh_order, - super::bounds::cosh_bounds + super::bounds::cosh_bounds, + super::get_cosh_doc ); make_udf_function!(cot::CotFunc, COT, cot); make_math_unary_udf!( @@ -129,7 +146,8 @@ make_math_unary_udf!( degrees, to_degrees, super::degrees_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_degrees_doc ); make_math_unary_udf!( ExpFunc, @@ -137,7 +155,8 @@ make_math_unary_udf!( exp, exp, super::exp_order, - super::bounds::exp_bounds + super::bounds::exp_bounds, + super::get_exp_doc ); make_udf_function!(factorial::FactorialFunc, FACTORIAL, factorial); make_math_unary_udf!( @@ -146,7 +165,8 @@ make_math_unary_udf!( floor, floor, super::floor_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_floor_doc ); make_udf_function!(log::LogFunc, LOG, log); make_udf_function!(gcd::GcdFunc, GCD, gcd); @@ -159,7 +179,8 @@ make_math_unary_udf!( ln, ln, super::ln_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_ln_doc ); make_math_unary_udf!( Log2Func, @@ -167,7 +188,8 @@ make_math_unary_udf!( log2, log2, super::log2_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_log2_doc ); make_math_unary_udf!( Log10Func, @@ -175,7 +197,8 @@ make_math_unary_udf!( log10, log10, super::log10_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_log10_doc ); make_udf_function!(nanvl::NanvlFunc, NANVL, nanvl); make_udf_function!(pi::PiFunc, PI, pi); @@ -186,7 +209,8 @@ make_math_unary_udf!( radians, to_radians, super::radians_order, - super::bounds::radians_bounds + super::bounds::radians_bounds, + super::get_radians_doc ); make_udf_function!(random::RandomFunc, RANDOM, random); make_udf_function!(round::RoundFunc, ROUND, round); @@ -197,7 +221,8 @@ make_math_unary_udf!( sin, sin, super::sin_order, - super::bounds::sin_bounds + super::bounds::sin_bounds, + super::get_sin_doc ); make_math_unary_udf!( SinhFunc, @@ -205,7 +230,8 @@ make_math_unary_udf!( sinh, sinh, super::sinh_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_sinh_doc ); make_math_unary_udf!( SqrtFunc, @@ -213,7 +239,8 @@ make_math_unary_udf!( sqrt, sqrt, super::sqrt_order, - super::bounds::sqrt_bounds + super::bounds::sqrt_bounds, + super::get_sqrt_doc ); make_math_unary_udf!( TanFunc, @@ -221,7 +248,8 @@ make_math_unary_udf!( tan, tan, super::tan_order, - super::bounds::unbounded_bounds + super::bounds::unbounded_bounds, + super::get_tan_doc ); make_math_unary_udf!( TanhFunc, @@ -229,7 +257,8 @@ make_math_unary_udf!( tanh, tanh, super::tanh_order, - super::bounds::tanh_bounds + super::bounds::tanh_bounds, + super::get_tanh_doc ); make_udf_function!(trunc::TruncFunc, TRUNC, trunc); diff --git a/datafusion/functions/src/math/monotonicity.rs b/datafusion/functions/src/math/monotonicity.rs index 52f2ec517198..959434d74f82 100644 --- a/datafusion/functions/src/math/monotonicity.rs +++ b/datafusion/functions/src/math/monotonicity.rs @@ -15,9 +15,13 @@ // specific language governing permissions and limitations // under the License. +use std::sync::OnceLock; + use datafusion_common::{exec_err, Result, ScalarValue}; use datafusion_expr::interval_arithmetic::Interval; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; use datafusion_expr::sort_properties::{ExprProperties, SortProperties}; +use datafusion_expr::Documentation; /// Non-increasing on the interval \[−1, 1\], undefined otherwise. pub fn acos_order(input: &[ExprProperties]) -> Result { @@ -34,6 +38,20 @@ pub fn acos_order(input: &[ExprProperties]) -> Result { } } +static DOCUMENTATION_ACOS: OnceLock = OnceLock::new(); + +pub fn get_acos_doc() -> &'static Documentation { + DOCUMENTATION_ACOS.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the arc cosine or inverse cosine of a number.") + .with_syntax_example("acos(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for x ≥ 1, undefined otherwise. pub fn acosh_order(input: &[ExprProperties]) -> Result { let arg = &input[0]; @@ -51,6 +69,22 @@ pub fn acosh_order(input: &[ExprProperties]) -> Result { } } +static DOCUMENTATION_ACOSH: OnceLock = OnceLock::new(); + +pub fn get_acosh_doc() -> &'static Documentation { + DOCUMENTATION_ACOSH.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number.", + ) + .with_syntax_example("acosh(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing on the interval \[−1, 1\], undefined otherwise. pub fn asin_order(input: &[ExprProperties]) -> Result { let arg = &input[0]; @@ -66,16 +100,60 @@ pub fn asin_order(input: &[ExprProperties]) -> Result { } } +static DOCUMENTATION_ASIN: OnceLock = OnceLock::new(); + +pub fn get_asin_doc() -> &'static Documentation { + DOCUMENTATION_ASIN.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the arc sine or inverse sine of a number.") + .with_syntax_example("asin(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for all real numbers. pub fn asinh_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } +static DOCUMENTATION_ASINH: OnceLock = OnceLock::new(); + +pub fn get_asinh_doc() -> &'static Documentation { + DOCUMENTATION_ASINH.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns the area hyperbolic sine or inverse hyperbolic sine of a number.", + ) + .with_syntax_example("asinh(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for all real numbers. pub fn atan_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } +static DOCUMENTATION_ATAN: OnceLock = OnceLock::new(); + +pub fn get_atan_doc() -> &'static Documentation { + DOCUMENTATION_ATAN.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the arc tangent or inverse tangent of a number.") + .with_syntax_example("atan(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing on the interval \[−1, 1\], undefined otherwise. pub fn atanh_order(input: &[ExprProperties]) -> Result { let arg = &input[0]; @@ -91,22 +169,87 @@ pub fn atanh_order(input: &[ExprProperties]) -> Result { } } +static DOCUMENTATION_ATANH: OnceLock = OnceLock::new(); + +pub fn get_atanh_doc() -> &'static Documentation { + DOCUMENTATION_ATANH.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number.", + ) + .with_syntax_example("atanh(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Order depends on the quadrant. // TODO: Implement ordering rule of the ATAN2 function. pub fn atan2_order(_input: &[ExprProperties]) -> Result { Ok(SortProperties::Unordered) } +static DOCUMENTATION_ATANH2: OnceLock = OnceLock::new(); + +pub fn get_atan2_doc() -> &'static Documentation { + DOCUMENTATION_ATANH2.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns the arc tangent or inverse tangent of `expression_y / expression_x`.", + ) + .with_syntax_example("atan2(expression_y, expression_x)") + .with_argument("expression_y", r#"First numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators."#) + .with_argument("expression_x", r#"Second numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators."#) + .build() + .unwrap() + }) +} + /// Non-decreasing for all real numbers. pub fn cbrt_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } +static DOCUMENTATION_CBRT: OnceLock = OnceLock::new(); + +pub fn get_cbrt_doc() -> &'static Documentation { + DOCUMENTATION_CBRT.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the cube root of a number.") + .with_syntax_example("cbrt(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for all real numbers. pub fn ceil_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } +static DOCUMENTATION_CEIL: OnceLock = OnceLock::new(); + +pub fn get_ceil_doc() -> &'static Documentation { + DOCUMENTATION_CEIL.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns the nearest integer greater than or equal to a number.", + ) + .with_syntax_example("ceil(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-increasing on \[0, π\] and then non-decreasing on \[π, 2π\]. /// This pattern repeats periodically with a period of 2π. // TODO: Implement ordering rule of the ATAN2 function. @@ -114,6 +257,20 @@ pub fn cos_order(_input: &[ExprProperties]) -> Result { Ok(SortProperties::Unordered) } +static DOCUMENTATION_COS: OnceLock = OnceLock::new(); + +pub fn get_cos_doc() -> &'static Documentation { + DOCUMENTATION_COS.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the cosine of a number.") + .with_syntax_example("cos(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for x ≥ 0 and symmetrically non-increasing for x ≤ 0. pub fn cosh_order(input: &[ExprProperties]) -> Result { let arg = &input[0]; @@ -130,21 +287,79 @@ pub fn cosh_order(input: &[ExprProperties]) -> Result { } } +static DOCUMENTATION_COSH: OnceLock = OnceLock::new(); + +pub fn get_cosh_doc() -> &'static Documentation { + DOCUMENTATION_COSH.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the hyperbolic cosine of a number.") + .with_syntax_example("cosh(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing function that converts radians to degrees. pub fn degrees_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } +static DOCUMENTATION_DEGREES: OnceLock = OnceLock::new(); + +pub fn get_degrees_doc() -> &'static Documentation { + DOCUMENTATION_DEGREES.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Converts radians to degrees.") + .with_syntax_example("degrees(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for all real numbers. pub fn exp_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } +static DOCUMENTATION_EXP: OnceLock = OnceLock::new(); + +pub fn get_exp_doc() -> &'static Documentation { + DOCUMENTATION_EXP.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the base-e exponential of a number.") + .with_syntax_example("exp(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for all real numbers. pub fn floor_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } +static DOCUMENTATION_FLOOR: OnceLock = OnceLock::new(); + +pub fn get_floor_doc() -> &'static Documentation { + DOCUMENTATION_FLOOR.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns the nearest integer less than or equal to a number.", + ) + .with_syntax_example("floor(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for x ≥ 0, undefined otherwise. pub fn ln_order(input: &[ExprProperties]) -> Result { let arg = &input[0]; @@ -159,6 +374,20 @@ pub fn ln_order(input: &[ExprProperties]) -> Result { } } +static DOCUMENTATION_LN: OnceLock = OnceLock::new(); + +pub fn get_ln_doc() -> &'static Documentation { + DOCUMENTATION_LN.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the natural logarithm of a number.") + .with_syntax_example("ln(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for x ≥ 0, undefined otherwise. pub fn log2_order(input: &[ExprProperties]) -> Result { let arg = &input[0]; @@ -173,6 +402,20 @@ pub fn log2_order(input: &[ExprProperties]) -> Result { } } +static DOCUMENTATION_LOG2: OnceLock = OnceLock::new(); + +pub fn get_log2_doc() -> &'static Documentation { + DOCUMENTATION_LOG2.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the base-2 logarithm of a number.") + .with_syntax_example("log2(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for x ≥ 0, undefined otherwise. pub fn log10_order(input: &[ExprProperties]) -> Result { let arg = &input[0]; @@ -187,11 +430,39 @@ pub fn log10_order(input: &[ExprProperties]) -> Result { } } +static DOCUMENTATION_LOG10: OnceLock = OnceLock::new(); + +pub fn get_log10_doc() -> &'static Documentation { + DOCUMENTATION_LOG10.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the base-10 logarithm of a number.") + .with_syntax_example("log10(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for all real numbers x. pub fn radians_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } +static DOCUMENTATION_RADIONS: OnceLock = OnceLock::new(); + +pub fn get_radians_doc() -> &'static Documentation { + DOCUMENTATION_RADIONS.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Converts degrees to radians.") + .with_syntax_example("radians(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing on \[0, π\] and then non-increasing on \[π, 2π\]. /// This pattern repeats periodically with a period of 2π. // TODO: Implement ordering rule of the SIN function. @@ -199,11 +470,39 @@ pub fn sin_order(_input: &[ExprProperties]) -> Result { Ok(SortProperties::Unordered) } +static DOCUMENTATION_SIN: OnceLock = OnceLock::new(); + +pub fn get_sin_doc() -> &'static Documentation { + DOCUMENTATION_SIN.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the sine of a number.") + .with_syntax_example("sin(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for all real numbers. pub fn sinh_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } +static DOCUMENTATION_SINH: OnceLock = OnceLock::new(); + +pub fn get_sinh_doc() -> &'static Documentation { + DOCUMENTATION_SINH.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the hyperbolic sine of a number.") + .with_syntax_example("sinh(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for x ≥ 0, undefined otherwise. pub fn sqrt_order(input: &[ExprProperties]) -> Result { let arg = &input[0]; @@ -218,6 +517,20 @@ pub fn sqrt_order(input: &[ExprProperties]) -> Result { } } +static DOCUMENTATION_SQRT: OnceLock = OnceLock::new(); + +pub fn get_sqrt_doc() -> &'static Documentation { + DOCUMENTATION_SQRT.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the square root of a number.") + .with_syntax_example("sqrt(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing between vertical asymptotes at x = k * π ± π / 2 for any /// integer k. // TODO: Implement ordering rule of the TAN function. @@ -225,7 +538,35 @@ pub fn tan_order(_input: &[ExprProperties]) -> Result { Ok(SortProperties::Unordered) } +static DOCUMENTATION_TAN: OnceLock = OnceLock::new(); + +pub fn get_tan_doc() -> &'static Documentation { + DOCUMENTATION_TAN.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the tangent of a number.") + .with_syntax_example("tan(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} + /// Non-decreasing for all real numbers. pub fn tanh_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } + +static DOCUMENTATION_TANH: OnceLock = OnceLock::new(); + +pub fn get_tanh_doc() -> &'static Documentation { + DOCUMENTATION_TANH.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns the hyperbolic tangent of a number.") + .with_syntax_example("tanh(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) +} diff --git a/datafusion/functions/src/math/nans.rs b/datafusion/functions/src/math/nans.rs index 07747418ea46..79e4587958dc 100644 --- a/datafusion/functions/src/math/nans.rs +++ b/datafusion/functions/src/math/nans.rs @@ -22,9 +22,10 @@ use datafusion_common::{exec_err, Result}; use datafusion_expr::{ColumnarValue, TypeSignature}; use arrow::array::{ArrayRef, AsArray, BooleanArray}; -use datafusion_expr::{ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; +use datafusion_expr::{Documentation, ScalarUDFImpl, Signature, Volatility}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; #[derive(Debug)] pub struct IsNanFunc { @@ -90,4 +91,24 @@ impl ScalarUDFImpl for IsNanFunc { }; Ok(ColumnarValue::Array(arr)) } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_isnan_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_isnan_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns true if a given number is +NaN or -NaN otherwise returns false.", + ) + .with_syntax_example("isnan(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) } diff --git a/datafusion/functions/src/math/nanvl.rs b/datafusion/functions/src/math/nanvl.rs index d81a690843b6..b82ee0d45744 100644 --- a/datafusion/functions/src/math/nanvl.rs +++ b/datafusion/functions/src/math/nanvl.rs @@ -16,16 +16,18 @@ // under the License. use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use arrow::array::{ArrayRef, Float32Array, Float64Array}; use arrow::datatypes::DataType; use arrow::datatypes::DataType::{Float32, Float64}; use datafusion_common::{exec_err, DataFusionError, Result}; -use datafusion_expr::ColumnarValue; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; use datafusion_expr::TypeSignature::Exact; -use datafusion_expr::{ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use crate::utils::make_scalar_function; @@ -75,6 +77,28 @@ impl ScalarUDFImpl for NanvlFunc { fn invoke(&self, args: &[ColumnarValue]) -> Result { make_scalar_function(nanvl, vec![])(args) } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_nanvl_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_nanvl_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + r#"Returns the first argument if it's not _NaN_. +Returns the second argument otherwise."#, + ) + .with_syntax_example("nanvl(expression_x, expression_y)") + .with_argument("expression_x", "Numeric expression to return if it's not _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators.") + .with_argument("expression_y", "Numeric expression to return if the first expression is _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators.") + .build() + .unwrap() + }) } /// Nanvl SQL function diff --git a/datafusion/functions/src/math/pi.rs b/datafusion/functions/src/math/pi.rs index c2fe4efb1139..ea0f33161772 100644 --- a/datafusion/functions/src/math/pi.rs +++ b/datafusion/functions/src/math/pi.rs @@ -16,12 +16,16 @@ // under the License. use std::any::Any; +use std::sync::OnceLock; use arrow::datatypes::DataType; use arrow::datatypes::DataType::Float64; use datafusion_common::{not_impl_err, Result, ScalarValue}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; use datafusion_expr::sort_properties::{ExprProperties, SortProperties}; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; #[derive(Debug)] pub struct PiFunc { @@ -73,4 +77,21 @@ impl ScalarUDFImpl for PiFunc { // This function returns a constant value. Ok(SortProperties::Singleton) } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_pi_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_pi_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Returns an approximate value of π.") + .with_syntax_example("pi()") + .build() + .unwrap() + }) } diff --git a/datafusion/functions/src/math/power.rs b/datafusion/functions/src/math/power.rs index 831f983d5916..a99afaec97f7 100644 --- a/datafusion/functions/src/math/power.rs +++ b/datafusion/functions/src/math/power.rs @@ -24,13 +24,14 @@ use datafusion_common::{ DataFusionError, Result, ScalarValue, }; use datafusion_expr::expr::ScalarFunction; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; use datafusion_expr::simplify::{ExprSimplifyResult, SimplifyInfo}; -use datafusion_expr::{ColumnarValue, Expr, ScalarUDF, TypeSignature}; +use datafusion_expr::{ColumnarValue, Documentation, Expr, ScalarUDF, TypeSignature}; use arrow::array::{ArrayRef, Float64Array, Int64Array}; use datafusion_expr::{ScalarUDFImpl, Signature, Volatility}; use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use super::log::LogFunc; @@ -164,6 +165,27 @@ impl ScalarUDFImpl for PowerFunc { _ => Ok(ExprSimplifyResult::Original(vec![base, exponent])), } } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_power_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_power_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Returns a base expression raised to the power of an exponent.", + ) + .with_syntax_example("power(base, exponent)") + .with_standard_argument("base", "Numeric") + .with_standard_argument("exponent", "Exponent numeric") + .build() + .unwrap() + }) } /// Return true if this function call is a call to `Log` diff --git a/datafusion/functions/src/math/random.rs b/datafusion/functions/src/math/random.rs index 20591a02a930..cf564e5328a5 100644 --- a/datafusion/functions/src/math/random.rs +++ b/datafusion/functions/src/math/random.rs @@ -16,7 +16,7 @@ // under the License. use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use arrow::array::Float64Array; use arrow::datatypes::DataType; @@ -24,8 +24,9 @@ use arrow::datatypes::DataType::Float64; use rand::{thread_rng, Rng}; use datafusion_common::{not_impl_err, Result}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; use datafusion_expr::ColumnarValue; -use datafusion_expr::{ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::{Documentation, ScalarUDFImpl, Signature, Volatility}; #[derive(Debug)] pub struct RandomFunc { @@ -76,4 +77,24 @@ impl ScalarUDFImpl for RandomFunc { Ok(ColumnarValue::Array(Arc::new(array))) } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_random_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_random_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + r#"Returns a random float value in the range [0, 1). +The random seed is unique to each row."#, + ) + .with_syntax_example("random()") + .build() + .unwrap() + }) } diff --git a/datafusion/functions/src/math/round.rs b/datafusion/functions/src/math/round.rs index 89554a76febb..ae8eee0dbba2 100644 --- a/datafusion/functions/src/math/round.rs +++ b/datafusion/functions/src/math/round.rs @@ -16,7 +16,7 @@ // under the License. use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use crate::utils::make_scalar_function; @@ -27,9 +27,12 @@ use arrow::datatypes::DataType::{Float32, Float64, Int32}; use datafusion_common::{ exec_datafusion_err, exec_err, DataFusionError, Result, ScalarValue, }; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; use datafusion_expr::sort_properties::{ExprProperties, SortProperties}; use datafusion_expr::TypeSignature::Exact; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; #[derive(Debug)] pub struct RoundFunc { @@ -97,6 +100,28 @@ impl ScalarUDFImpl for RoundFunc { Ok(SortProperties::Unordered) } } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_round_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_round_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description("Rounds a number to the nearest integer.") + .with_syntax_example("round(numeric_expression[, decimal_places])") + .with_standard_argument("numeric_expression", "Numeric") + .with_argument( + "decimal_places", + "Optional. The number of decimal places to round to. Defaults to 0.", + ) + .build() + .unwrap() + }) } /// Round SQL function diff --git a/datafusion/functions/src/math/signum.rs b/datafusion/functions/src/math/signum.rs index 15b73f930343..6c020b0ce52a 100644 --- a/datafusion/functions/src/math/signum.rs +++ b/datafusion/functions/src/math/signum.rs @@ -16,16 +16,18 @@ // under the License. use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use arrow::array::{ArrayRef, AsArray}; use arrow::datatypes::DataType::{Float32, Float64}; use arrow::datatypes::{DataType, Float32Type, Float64Type}; use datafusion_common::{exec_err, Result}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; use datafusion_expr::sort_properties::{ExprProperties, SortProperties}; -use datafusion_expr::ColumnarValue; -use datafusion_expr::{ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; use crate::utils::make_scalar_function; @@ -81,6 +83,28 @@ impl ScalarUDFImpl for SignumFunc { fn invoke(&self, args: &[ColumnarValue]) -> Result { make_scalar_function(signum, vec![])(args) } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_signum_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_signum_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + r#"Returns the sign of a number. +Negative numbers return `-1`. +Zero and positive numbers return `1`."#, + ) + .with_syntax_example("signum(numeric_expression)") + .with_standard_argument("numeric_expression", "Numeric") + .build() + .unwrap() + }) } /// signum SQL function diff --git a/datafusion/functions/src/math/trunc.rs b/datafusion/functions/src/math/trunc.rs index 3344438454c4..355d1e52d65d 100644 --- a/datafusion/functions/src/math/trunc.rs +++ b/datafusion/functions/src/math/trunc.rs @@ -16,7 +16,7 @@ // under the License. use std::any::Any; -use std::sync::Arc; +use std::sync::{Arc, OnceLock}; use crate::utils::make_scalar_function; @@ -25,9 +25,12 @@ use arrow::datatypes::DataType; use arrow::datatypes::DataType::{Float32, Float64}; use datafusion_common::ScalarValue::Int64; use datafusion_common::{exec_err, DataFusionError, Result}; +use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH; use datafusion_expr::sort_properties::{ExprProperties, SortProperties}; use datafusion_expr::TypeSignature::Exact; -use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility}; +use datafusion_expr::{ + ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility, +}; #[derive(Debug)] pub struct TruncFunc { @@ -100,6 +103,31 @@ impl ScalarUDFImpl for TruncFunc { Ok(SortProperties::Unordered) } } + + fn documentation(&self) -> Option<&Documentation> { + Some(get_trunc_doc()) + } +} + +static DOCUMENTATION: OnceLock = OnceLock::new(); + +fn get_trunc_doc() -> &'static Documentation { + DOCUMENTATION.get_or_init(|| { + Documentation::builder() + .with_doc_section(DOC_SECTION_MATH) + .with_description( + "Truncates a number to a whole number or truncated to the specified decimal places.", + ) + .with_syntax_example("trunc(numeric_expression[, decimal_places])") + .with_standard_argument("numeric_expression", "Numeric") + .with_argument("decimal_places", r#"Optional. The number of decimal places to + truncate to. Defaults to 0 (truncate to a whole number). If + `decimal_places` is a positive integer, truncates digits to the + right of the decimal point. If `decimal_places` is a negative + integer, replaces digits to the left of the decimal point with `0`."#) + .build() + .unwrap() + }) } /// Truncate(numeric, decimalPrecision) and trunc(numeric) SQL function diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md index 56145ec803e0..c5995bab3d9a 100644 --- a/docs/source/user-guide/sql/scalar_functions.md +++ b/docs/source/user-guide/sql/scalar_functions.md @@ -27,534 +27,6 @@ the rest of the documentation. [automatically created from the codebase]: https://github.com/apache/datafusion/issues/12740 -## Math Functions - -- [abs](#abs) -- [acos](#acos) -- [acosh](#acosh) -- [asin](#asin) -- [asinh](#asinh) -- [atan](#atan) -- [atanh](#atanh) -- [atan2](#atan2) -- [cbrt](#cbrt) -- [ceil](#ceil) -- [cos](#cos) -- [cosh](#cosh) -- [degrees](#degrees) -- [exp](#exp) -- [factorial](#factorial) -- [floor](#floor) -- [gcd](#gcd) -- [isnan](#isnan) -- [iszero](#iszero) -- [lcm](#lcm) -- [ln](#ln) -- [log10](#log10) -- [log2](#log2) -- [nanvl](#nanvl) -- [pi](#pi) -- [power](#power) -- [pow](#pow) -- [radians](#radians) -- [random](#random) -- [round](#round) -- [signum](#signum) -- [sin](#sin) -- [sinh](#sinh) -- [sqrt](#sqrt) -- [tan](#tan) -- [tanh](#tanh) -- [trunc](#trunc) - -### `abs` - -Returns the absolute value of a number. - -``` -abs(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `acos` - -Returns the arc cosine or inverse cosine of a number. - -``` -acos(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `acosh` - -Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number. - -``` -acosh(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `asin` - -Returns the arc sine or inverse sine of a number. - -``` -asin(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `asinh` - -Returns the area hyperbolic sine or inverse hyperbolic sine of a number. - -``` -asinh(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `atan` - -Returns the arc tangent or inverse tangent of a number. - -``` -atan(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `atanh` - -Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. - -``` -atanh(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `atan2` - -Returns the arc tangent or inverse tangent of `expression_y / expression_x`. - -``` -atan2(expression_y, expression_x) -``` - -#### Arguments - -- **expression_y**: First numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_x**: Second numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `cbrt` - -Returns the cube root of a number. - -``` -cbrt(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `ceil` - -Returns the nearest integer greater than or equal to a number. - -``` -ceil(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `cos` - -Returns the cosine of a number. - -``` -cos(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `cosh` - -Returns the hyperbolic cosine of a number. - -``` -cosh(numeric_expression) -``` - -### `degrees` - -Converts radians to degrees. - -``` -degrees(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `exp` - -Returns the base-e exponential of a number. - -``` -exp(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to use as the exponent. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `factorial` - -Factorial. Returns 1 if value is less than 2. - -``` -factorial(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `floor` - -Returns the nearest integer less than or equal to a number. - -``` -floor(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `gcd` - -Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero. - -``` -gcd(expression_x, expression_y) -``` - -#### Arguments - -- **expression_x**: First numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Second numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `isnan` - -Returns true if a given number is +NaN or -NaN otherwise returns false. - -``` -isnan(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `iszero` - -Returns true if a given number is +0.0 or -0.0 otherwise returns false. - -``` -iszero(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `lcm` - -Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero. - -``` -lcm(expression_x, expression_y) -``` - -#### Arguments - -- **expression_x**: First numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Second numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `ln` - -Returns the natural logarithm of a number. - -``` -ln(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `log10` - -Returns the base-10 logarithm of a number. - -``` -log10(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `log2` - -Returns the base-2 logarithm of a number. - -``` -log2(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `nanvl` - -Returns the first argument if it's not _NaN_. -Returns the second argument otherwise. - -``` -nanvl(expression_x, expression_y) -``` - -#### Arguments - -- **expression_x**: Numeric expression to return if it's not _NaN_. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **expression_y**: Numeric expression to return if the first expression is _NaN_. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `pi` - -Returns an approximate value of π. - -``` -pi() -``` - -### `power` - -Returns a base expression raised to the power of an exponent. - -``` -power(base, exponent) -``` - -#### Arguments - -- **base**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **exponent**: Exponent numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -#### Aliases - -- pow - -### `pow` - -_Alias of [power](#power)._ - -### `radians` - -Converts degrees to radians. - -``` -radians(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `random` - -Returns a random float value in the range [0, 1). -The random seed is unique to each row. - -``` -random() -``` - -### `round` - -Rounds a number to the nearest integer. - -``` -round(numeric_expression[, decimal_places]) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. -- **decimal_places**: Optional. The number of decimal places to round to. - Defaults to 0. - -### `signum` - -Returns the sign of a number. -Negative numbers return `-1`. -Zero and positive numbers return `1`. - -``` -signum(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `sin` - -Returns the sine of a number. - -``` -sin(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `sinh` - -Returns the hyperbolic sine of a number. - -``` -sinh(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `sqrt` - -Returns the square root of a number. - -``` -sqrt(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `tan` - -Returns the tangent of a number. - -``` -tan(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `tanh` - -Returns the hyperbolic tangent of a number. - -``` -tanh(numeric_expression) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -### `trunc` - -Truncates a number to a whole number or truncated to the specified decimal places. - -``` -trunc(numeric_expression[, decimal_places]) -``` - -#### Arguments - -- **numeric_expression**: Numeric expression to operate on. - Can be a constant, column, or function, and any combination of arithmetic operators. - -- **decimal_places**: Optional. The number of decimal places to - truncate to. Defaults to 0 (truncate to a whole number). If - `decimal_places` is a positive integer, truncates digits to the - right of the decimal point. If `decimal_places` is a negative - integer, replaces digits to the left of the decimal point with `0`. - ## Conditional Functions See the new documentation [`here`](https://datafusion.apache.org/user-guide/sql/scalar_functions_new.html) diff --git a/docs/source/user-guide/sql/scalar_functions_new.md b/docs/source/user-guide/sql/scalar_functions_new.md index 7d0261da0ad0..499fd7cd07a8 100644 --- a/docs/source/user-guide/sql/scalar_functions_new.md +++ b/docs/source/user-guide/sql/scalar_functions_new.md @@ -35,7 +35,301 @@ the rest of the documentation. ## Math Functions +- [abs](#abs) +- [acos](#acos) +- [acosh](#acosh) +- [asin](#asin) +- [asinh](#asinh) +- [atan](#atan) +- [atan2](#atan2) +- [atanh](#atanh) +- [cbrt](#cbrt) +- [ceil](#ceil) +- [cos](#cos) +- [cosh](#cosh) +- [degrees](#degrees) +- [exp](#exp) +- [factorial](#factorial) +- [floor](#floor) +- [gcd](#gcd) +- [isnan](#isnan) +- [iszero](#iszero) +- [lcm](#lcm) +- [ln](#ln) - [log](#log) +- [log10](#log10) +- [log2](#log2) +- [nanvl](#nanvl) +- [pi](#pi) +- [pow](#pow) +- [power](#power) +- [radians](#radians) +- [random](#random) +- [round](#round) +- [signum](#signum) +- [sin](#sin) +- [sinh](#sinh) +- [sqrt](#sqrt) +- [tan](#tan) +- [tanh](#tanh) +- [trunc](#trunc) + +### `abs` + +Returns the absolute value of a number. + +``` +abs(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `acos` + +Returns the arc cosine or inverse cosine of a number. + +``` +acos(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `acosh` + +Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number. + +``` +acosh(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `asin` + +Returns the arc sine or inverse sine of a number. + +``` +asin(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `asinh` + +Returns the area hyperbolic sine or inverse hyperbolic sine of a number. + +``` +asinh(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `atan` + +Returns the arc tangent or inverse tangent of a number. + +``` +atan(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `atan2` + +Returns the arc tangent or inverse tangent of `expression_y / expression_x`. + +``` +atan2(expression_y, expression_x) +``` + +#### Arguments + +- **expression_y**: First numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_x**: Second numeric expression to operate on. + Can be a constant, column, or function, and any combination of arithmetic operators. + +### `atanh` + +Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. + +``` +atanh(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `cbrt` + +Returns the cube root of a number. + +``` +cbrt(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `ceil` + +Returns the nearest integer greater than or equal to a number. + +``` +ceil(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `cos` + +Returns the cosine of a number. + +``` +cos(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `cosh` + +Returns the hyperbolic cosine of a number. + +``` +cosh(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `degrees` + +Converts radians to degrees. + +``` +degrees(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `exp` + +Returns the base-e exponential of a number. + +``` +exp(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `factorial` + +Factorial. Returns 1 if value is less than 2. + +``` +factorial(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `floor` + +Returns the nearest integer less than or equal to a number. + +``` +floor(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `gcd` + +Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero. + +``` +gcd(expression_x, expression_y) +``` + +#### Arguments + +- **expression_x**: First numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **expression_y**: Second numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `isnan` + +Returns true if a given number is +NaN or -NaN otherwise returns false. + +``` +isnan(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `iszero` + +Returns true if a given number is +0.0 or -0.0 otherwise returns false. + +``` +iszero(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `lcm` + +Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero. + +``` +lcm(expression_x, expression_y) +``` + +#### Arguments + +- **expression_x**: First numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **expression_y**: Second numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `ln` + +Returns the natural logarithm of a number. + +``` +ln(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. ### `log` @@ -51,6 +345,198 @@ log(numeric_expression) - **base**: Base numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +### `log10` + +Returns the base-10 logarithm of a number. + +``` +log10(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `log2` + +Returns the base-2 logarithm of a number. + +``` +log2(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `nanvl` + +Returns the first argument if it's not _NaN_. +Returns the second argument otherwise. + +``` +nanvl(expression_x, expression_y) +``` + +#### Arguments + +- **expression_x**: Numeric expression to return if it's not _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression_y**: Numeric expression to return if the first expression is _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators. + +### `pi` + +Returns an approximate value of π. + +``` +pi() +``` + +### `pow` + +_Alias of [power](#power)._ + +### `power` + +Returns a base expression raised to the power of an exponent. + +``` +power(base, exponent) +``` + +#### Arguments + +- **base**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **exponent**: Exponent numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +#### Aliases + +- pow + +### `radians` + +Converts degrees to radians. + +``` +radians(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `random` + +Returns a random float value in the range [0, 1). +The random seed is unique to each row. + +``` +random() +``` + +### `round` + +Rounds a number to the nearest integer. + +``` +round(numeric_expression[, decimal_places]) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **decimal_places**: Optional. The number of decimal places to round to. Defaults to 0. + +### `signum` + +Returns the sign of a number. +Negative numbers return `-1`. +Zero and positive numbers return `1`. + +``` +signum(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `sin` + +Returns the sine of a number. + +``` +sin(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `sinh` + +Returns the hyperbolic sine of a number. + +``` +sinh(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `sqrt` + +Returns the square root of a number. + +``` +sqrt(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `tan` + +Returns the tangent of a number. + +``` +tan(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `tanh` + +Returns the hyperbolic tangent of a number. + +``` +tanh(numeric_expression) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + +### `trunc` + +Truncates a number to a whole number or truncated to the specified decimal places. + +``` +trunc(numeric_expression[, decimal_places]) +``` + +#### Arguments + +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **decimal_places**: Optional. The number of decimal places to + truncate to. Defaults to 0 (truncate to a whole number). If + `decimal_places` is a positive integer, truncates digits to the + right of the decimal point. If `decimal_places` is a negative + integer, replaces digits to the left of the decimal point with `0`. + ## Conditional Functions - [coalesce](#coalesce)