feat: BuiltinScalarFunction::Cbrt (#5839)

* feat: BuiltinScalarFunction::Cbrt

* fix: "ScalarFunction::Cbrt" covered in "datafusion.proto" and "pbjson.rs"

* feat: add documentation for "cbrt" function

* fix: use prettier

* fix: use regen.sh

* fix: remove useless docstring

datafusion/core/tests/sql/expr.rs

@@ -676,6 +676,7 @@ async fn test_boolean_expressions() -> Result<()> {
 #[tokio::test]
 async fn test_mathematical_expressions_with_null() -> Result<()> {
     test_expression!("sqrt(NULL)", "NULL");
+    test_expression!("cbrt(NULL)", "NULL");
     test_expression!("sin(NULL)", "NULL");
     test_expression!("cos(NULL)", "NULL");
     test_expression!("tan(NULL)", "NULL");
@@ -1629,6 +1630,18 @@ async fn csv_query_sqrt_sqrt() -> Result<()> {
     Ok(())
 }
 
+#[tokio::test]
+async fn csv_query_cbrt_cbrt() -> Result<()> {
+    let ctx = create_ctx();
+    register_aggregate_csv(&ctx).await?;
+    let sql = "SELECT cbrt(cbrt(c12)) FROM aggregate_test_100 LIMIT 1";
+    let actual = execute(&ctx, sql).await;
+    // cbrt(cbrt(c12=0.9294097332465232)) = 0.9918990366780552
+    let expected = vec![vec!["0.9918990366780552"]];
+    assert_float_eq(&expected, &actual);
+    Ok(())
+}
+
 #[tokio::test]
 async fn nested_subquery() -> Result<()> {
     let ctx = SessionContext::new();

datafusion/expr/src/built_in_function.rs

@@ -66,6 +66,8 @@ pub enum BuiltinScalarFunction {
     Sin,
     /// sqrt
     Sqrt,
+    /// cbrt
+    Cbrt,
     /// tan
     Tan,
     /// trunc
@@ -212,6 +214,7 @@ impl BuiltinScalarFunction {
             BuiltinScalarFunction::Signum => Volatility::Immutable,
             BuiltinScalarFunction::Sin => Volatility::Immutable,
             BuiltinScalarFunction::Sqrt => Volatility::Immutable,
+            BuiltinScalarFunction::Cbrt => Volatility::Immutable,
             BuiltinScalarFunction::Tan => Volatility::Immutable,
             BuiltinScalarFunction::Trunc => Volatility::Immutable,
             BuiltinScalarFunction::MakeArray => Volatility::Immutable,
@@ -304,6 +307,7 @@ impl FromStr for BuiltinScalarFunction {
             "signum" => BuiltinScalarFunction::Signum,
             "sin" => BuiltinScalarFunction::Sin,
             "sqrt" => BuiltinScalarFunction::Sqrt,
+            "cbrt" => BuiltinScalarFunction::Cbrt,
             "tan" => BuiltinScalarFunction::Tan,
             "trunc" => BuiltinScalarFunction::Trunc,
 

datafusion/expr/src/expr_fn.rs

@@ -446,6 +446,7 @@ macro_rules! nary_scalar_expr {
 
 // math functions
 scalar_expr!(Sqrt, sqrt, num, "square root of a number");
+scalar_expr!(Cbrt, cbrt, num, "cube root of a number");
 scalar_expr!(Sin, sin, num, "sine");
 scalar_expr!(Cos, cos, num, "cosine");
 scalar_expr!(Tan, tan, num, "tangent");
@@ -758,6 +759,7 @@ mod test {
     #[test]
     fn scalar_function_definitions() {
         test_unary_scalar_expr!(Sqrt, sqrt);
+        test_unary_scalar_expr!(Cbrt, cbrt);
         test_unary_scalar_expr!(Sin, sin);
         test_unary_scalar_expr!(Cos, cos);
         test_unary_scalar_expr!(Tan, tan);

datafusion/expr/src/function.rs

@@ -277,6 +277,7 @@ pub fn return_type(
         | BuiltinScalarFunction::Signum
         | BuiltinScalarFunction::Sin
         | BuiltinScalarFunction::Sqrt
+        | BuiltinScalarFunction::Cbrt
         | BuiltinScalarFunction::Tan
         | BuiltinScalarFunction::Trunc => match input_expr_types[0] {
             DataType::Float32 => Ok(DataType::Float32),

datafusion/physical-expr/src/functions.rs

@@ -353,6 +353,7 @@ pub fn create_physical_fun(
         BuiltinScalarFunction::Signum => Arc::new(math_expressions::signum),
         BuiltinScalarFunction::Sin => Arc::new(math_expressions::sin),
         BuiltinScalarFunction::Sqrt => Arc::new(math_expressions::sqrt),
+        BuiltinScalarFunction::Cbrt => Arc::new(math_expressions::cbrt),
         BuiltinScalarFunction::Tan => Arc::new(math_expressions::tan),
         BuiltinScalarFunction::Trunc => Arc::new(math_expressions::trunc),
         BuiltinScalarFunction::Power => {

datafusion/physical-expr/src/math_expressions.rs

@@ -128,6 +128,7 @@ macro_rules! make_function_inputs2 {
 }
 
 math_unary_function!("sqrt", sqrt);
+math_unary_function!("cbrt", cbrt);
 math_unary_function!("sin", sin);
 math_unary_function!("cos", cos);
 math_unary_function!("tan", tan);

datafusion/proto/proto/datafusion.proto

@@ -523,6 +523,7 @@ enum ScalarFunction {
   CurrentDate = 70;
   CurrentTime = 71;
   Uuid = 72;
+  Cbrt = 73;
 }
 
 message ScalarFunctionNode {

datafusion/proto/src/logical_plan/from_proto.rs

@@ -33,7 +33,7 @@ use datafusion_common::{
     ScalarValue,
 };
 use datafusion_expr::{
-    abs, acos, array, ascii, asin, atan, atan2, bit_length, btrim, ceil,
+    abs, acos, array, ascii, asin, atan, atan2, bit_length, btrim, cbrt, ceil,
     character_length, chr, coalesce, concat_expr, concat_ws_expr, cos, date_bin,
     date_part, date_trunc, digest, exp,
     expr::{self, Sort, WindowFunction},
@@ -400,6 +400,7 @@ impl From<&protobuf::ScalarFunction> for BuiltinScalarFunction {
         use protobuf::ScalarFunction;
         match f {
             ScalarFunction::Sqrt => Self::Sqrt,
+            ScalarFunction::Cbrt => Self::Cbrt,
             ScalarFunction::Sin => Self::Sin,
             ScalarFunction::Cos => Self::Cos,
             ScalarFunction::Tan => Self::Tan,
@@ -1129,6 +1130,7 @@ pub fn parse_expr(
                         .collect::<Result<Vec<_>, _>>()?,
                 )),
                 ScalarFunction::Sqrt => Ok(sqrt(parse_expr(&args[0], registry)?)),
+                ScalarFunction::Cbrt => Ok(cbrt(parse_expr(&args[0], registry)?)),
                 ScalarFunction::Sin => Ok(sin(parse_expr(&args[0], registry)?)),
                 ScalarFunction::Cos => Ok(cos(parse_expr(&args[0], registry)?)),
                 ScalarFunction::Tan => Ok(tan(parse_expr(&args[0], registry)?)),

datafusion/proto/src/logical_plan/to_proto.rs

@@ -1251,6 +1251,7 @@ impl TryFrom<&BuiltinScalarFunction> for protobuf::ScalarFunction {
     fn try_from(scalar: &BuiltinScalarFunction) -> Result<Self, Self::Error> {
         let scalar_function = match scalar {
             BuiltinScalarFunction::Sqrt => Self::Sqrt,
+            BuiltinScalarFunction::Cbrt => Self::Cbrt,
             BuiltinScalarFunction::Sin => Self::Sin,
             BuiltinScalarFunction::Cos => Self::Cos,
             BuiltinScalarFunction::Tan => Self::Tan,

docs/source/user-guide/expressions.md

@@ -85,6 +85,7 @@ expressions such as `col("a") + col("b")` to be used.
 | signum(x)             | sign of the argument (-1, 0, +1)                  |
 | sin(x)                | sine                                              |
 | sqrt(x)               | square root                                       |
+| cbrt(x)               | cube root                                         |
 | tan(x)                | tangent                                           |
 | trunc(x)              | truncate toward zero                              |
 

docs/source/user-guide/sql/scalar_functions.md

@@ -39,6 +39,7 @@
 - [signum](#signum)
 - [sin](#sin)
 - [sqrt](#sqrt)
+- [cbrt](#cbrt)
 - [tan](#tan)
 - [trunc](#trunc)
 
@@ -275,6 +276,19 @@ sqrt(numeric_expression)
 
 #### Arguments
 
+- **numeric_expression**: 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.