diff --git a/datafusion/functions/src/math/abs.rs b/datafusion/functions/src/math/abs.rs index 5c5ad40b98fa..8af8e4c2c849 100644 --- a/datafusion/functions/src/math/abs.rs +++ b/datafusion/functions/src/math/abs.rs @@ -108,6 +108,14 @@ fn create_abs_function(input_data_type: &DataType) -> Result doc_section(label = "Math Functions"), description = "Returns the absolute value of a number.", syntax_example = "abs(numeric_expression)", + sql_example = r#"```sql +> SELECT abs(-5); ++----------+ +| abs(-5) | ++----------+ +| 5 | ++----------+ +```"#, standard_argument(name = "numeric_expression", prefix = "Numeric") )] #[derive(Debug, PartialEq, Eq, Hash)] diff --git a/datafusion/functions/src/math/cot.rs b/datafusion/functions/src/math/cot.rs index 8006be2effea..43f2012d073d 100644 --- a/datafusion/functions/src/math/cot.rs +++ b/datafusion/functions/src/math/cot.rs @@ -32,6 +32,14 @@ use datafusion_macros::user_doc; doc_section(label = "Math Functions"), description = "Returns the cotangent of a number.", syntax_example = r#"cot(numeric_expression)"#, + sql_example = r#"```sql +> SELECT cot(1); ++---------+ +| cot(1) | ++---------+ +| 0.64209 | ++---------+ +```"#, standard_argument(name = "numeric_expression", prefix = "Numeric") )] #[derive(Debug, PartialEq, Eq, Hash)] diff --git a/datafusion/functions/src/math/factorial.rs b/datafusion/functions/src/math/factorial.rs index 1423eeafed7d..79f6da94dd0e 100644 --- a/datafusion/functions/src/math/factorial.rs +++ b/datafusion/functions/src/math/factorial.rs @@ -37,6 +37,14 @@ use datafusion_macros::user_doc; doc_section(label = "Math Functions"), description = "Factorial. Returns 1 if value is less than 2.", syntax_example = "factorial(numeric_expression)", + sql_example = r#"```sql +> SELECT factorial(5); ++---------------+ +| factorial(5) | ++---------------+ +| 120 | ++---------------+ +```"#, standard_argument(name = "numeric_expression", prefix = "Numeric") )] #[derive(Debug, PartialEq, Eq, Hash)] diff --git a/datafusion/functions/src/math/gcd.rs b/datafusion/functions/src/math/gcd.rs index 714718c5e87a..0b85e7b54a78 100644 --- a/datafusion/functions/src/math/gcd.rs +++ b/datafusion/functions/src/math/gcd.rs @@ -34,6 +34,14 @@ use datafusion_macros::user_doc; doc_section(label = "Math Functions"), description = "Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero.", syntax_example = "gcd(expression_x, expression_y)", + sql_example = r#"```sql +> SELECT gcd(48, 18); ++------------+ +| gcd(48,18) | ++------------+ +| 6 | ++------------+ +```"#, standard_argument(name = "expression_x", prefix = "First numeric"), standard_argument(name = "expression_y", prefix = "Second numeric") )] diff --git a/datafusion/functions/src/math/iszero.rs b/datafusion/functions/src/math/iszero.rs index ec1200f443eb..68cd3aca28fd 100644 --- a/datafusion/functions/src/math/iszero.rs +++ b/datafusion/functions/src/math/iszero.rs @@ -36,6 +36,14 @@ use crate::utils::make_scalar_function; doc_section(label = "Math Functions"), description = "Returns true if a given number is +0.0 or -0.0 otherwise returns false.", syntax_example = "iszero(numeric_expression)", + sql_example = r#"```sql +> SELECT iszero(0); ++------------+ +| iszero(0) | ++------------+ +| true | ++------------+ +```"#, standard_argument(name = "numeric_expression", prefix = "Numeric") )] #[derive(Debug, PartialEq, Eq, Hash)] diff --git a/datafusion/functions/src/math/lcm.rs b/datafusion/functions/src/math/lcm.rs index 8b2d849ef8ea..bfb20dfd5ce4 100644 --- a/datafusion/functions/src/math/lcm.rs +++ b/datafusion/functions/src/math/lcm.rs @@ -37,6 +37,14 @@ use crate::utils::make_scalar_function; doc_section(label = "Math Functions"), description = "Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero.", syntax_example = "lcm(expression_x, expression_y)", + sql_example = r#"```sql +> SELECT lcm(4, 5); ++----------+ +| lcm(4,5) | ++----------+ +| 20 | ++----------+ +```"#, standard_argument(name = "expression_x", prefix = "First numeric"), standard_argument(name = "expression_y", prefix = "Second numeric") )] diff --git a/datafusion/functions/src/math/log.rs b/datafusion/functions/src/math/log.rs index 6604f9ee2291..ff1fd0cd4b37 100644 --- a/datafusion/functions/src/math/log.rs +++ b/datafusion/functions/src/math/log.rs @@ -48,6 +48,14 @@ use datafusion_macros::user_doc; description = "Returns the base-x logarithm of a number. Can either provide a specified base, or if omitted then takes the base-10 of a number.", syntax_example = r#"log(base, numeric_expression) log(numeric_expression)"#, + sql_example = r#"```sql +> SELECT log(10); ++---------+ +| log(10) | ++---------+ +| 1.0 | ++---------+ +```"#, standard_argument(name = "base", prefix = "Base numeric"), standard_argument(name = "numeric_expression", prefix = "Numeric") )] diff --git a/datafusion/functions/src/math/monotonicity.rs b/datafusion/functions/src/math/monotonicity.rs index baa3147f6258..7870dc95629a 100644 --- a/datafusion/functions/src/math/monotonicity.rs +++ b/datafusion/functions/src/math/monotonicity.rs @@ -45,6 +45,16 @@ static DOCUMENTATION_ACOS: LazyLock = LazyLock::new(|| { "acos(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT acos(1); ++----------+ +| acos(1) | ++----------+ +| 0.0 | ++----------+ +```"#, + ) .build() }); @@ -69,15 +79,24 @@ pub fn acosh_order(input: &[ExprProperties]) -> Result { } } -static DOCUMENTATION_ACOSH: LazyLock = LazyLock::new(|| { - Documentation::builder( +static DOCUMENTATION_ACOSH: LazyLock = + LazyLock::new(|| { + Documentation::builder( DOC_SECTION_MATH, "Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number.", "acosh(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example(r#"```sql +> SELECT acosh(2); ++------------+ +| acosh(2) | ++------------+ +| 1.31696 | ++------------+ +```"#) .build() -}); + }); pub fn get_acosh_doc() -> &'static Documentation { &DOCUMENTATION_ACOSH @@ -105,6 +124,16 @@ static DOCUMENTATION_ASIN: LazyLock = LazyLock::new(|| { "asin(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT asin(0.5); ++------------+ +| asin(0.5) | ++------------+ +| 0.5235988 | ++------------+ +```"#, + ) .build() }); @@ -124,6 +153,16 @@ static DOCUMENTATION_ASINH: LazyLock = LazyLock::new(|| { "asinh(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#" ```sql +> SELECT asinh(1); ++------------+ +| asinh(1) | ++------------+ +| 0.8813736 | ++------------+ +```"#, + ) .build() }); @@ -143,6 +182,16 @@ static DOCUMENTATION_ATAN: LazyLock = LazyLock::new(|| { "atan(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql + > SELECT atan(1); ++-----------+ +| atan(1) | ++-----------+ +| 0.7853982 | ++-----------+ +```"#, + ) .build() }); @@ -165,15 +214,24 @@ pub fn atanh_order(input: &[ExprProperties]) -> Result { } } -static DOCUMENTATION_ATANH: LazyLock = LazyLock::new(|| { - Documentation::builder( +static DOCUMENTATION_ATANH: LazyLock = + LazyLock::new(|| { + Documentation::builder( DOC_SECTION_MATH, "Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number.", "atanh(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example(r#"```sql + > SELECT atanh(0.5); ++-------------+ +| atanh(0.5) | ++-------------+ +| 0.5493061 | ++-------------+ +```"#) .build() -}); + }); pub fn get_atanh_doc() -> &'static Documentation { &DOCUMENTATION_ATANH @@ -185,8 +243,9 @@ pub fn atan2_order(_input: &[ExprProperties]) -> Result { Ok(SortProperties::Unordered) } -static DOCUMENTATION_ATANH2: LazyLock = LazyLock::new(|| { - Documentation::builder( +static DOCUMENTATION_ATANH2: LazyLock = + LazyLock::new(|| { + Documentation::builder( DOC_SECTION_MATH, "Returns the arc tangent or inverse tangent of `expression_y / expression_x`.", "atan2(expression_y, expression_x)", @@ -201,8 +260,16 @@ Can be a constant, column, or function, and any combination of arithmetic operat r#"Second numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators."#, ) + .with_sql_example(r#"```sql +> SELECT atan2(1, 1); ++------------+ +| atan2(1,1) | ++------------+ +| 0.7853982 | ++------------+ +```"#) .build() -}); + }); pub fn get_atan2_doc() -> &'static Documentation { &DOCUMENTATION_ATANH2 @@ -220,6 +287,16 @@ static DOCUMENTATION_CBRT: LazyLock = LazyLock::new(|| { "cbrt(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT cbrt(27); ++-----------+ +| cbrt(27) | ++-----------+ +| 3.0 | ++-----------+ +```"#, + ) .build() }); @@ -239,6 +316,16 @@ static DOCUMENTATION_CEIL: LazyLock = LazyLock::new(|| { "ceil(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql + > SELECT ceil(3.14); ++------------+ +| ceil(3.14) | ++------------+ +| 4.0 | ++------------+ +```"#, + ) .build() }); @@ -260,6 +347,16 @@ static DOCUMENTATION_COS: LazyLock = LazyLock::new(|| { "cos(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT cos(0); ++--------+ +| cos(0) | ++--------+ +| 1.0 | ++--------+ +```"#, + ) .build() }); @@ -290,6 +387,16 @@ static DOCUMENTATION_COSH: LazyLock = LazyLock::new(|| { "cosh(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT cosh(1); ++-----------+ +| cosh(1) | ++-----------+ +| 1.5430806 | ++-----------+ +```"#, + ) .build() }); @@ -309,6 +416,16 @@ static DOCUMENTATION_DEGREES: LazyLock = LazyLock::new(|| { "degrees(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql + > SELECT degrees(pi()); ++------------+ +| degrees(0) | ++------------+ +| 180.0 | ++------------+ +```"#, + ) .build() }); @@ -328,6 +445,16 @@ static DOCUMENTATION_EXP: LazyLock = LazyLock::new(|| { "exp(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT exp(1); ++---------+ +| exp(1) | ++---------+ +| 2.71828 | ++---------+ +```"#, + ) .build() }); @@ -347,6 +474,16 @@ static DOCUMENTATION_FLOOR: LazyLock = LazyLock::new(|| { "floor(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT floor(3.14); ++-------------+ +| floor(3.14) | ++-------------+ +| 3.0 | ++-------------+ +```"#, + ) .build() }); @@ -375,6 +512,16 @@ static DOCUMENTATION_LN: LazyLock = LazyLock::new(|| { "ln(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT ln(2.71828); ++-------------+ +| ln(2.71828) | ++-------------+ +| 1.0 | ++-------------+ +```"#, + ) .build() }); @@ -403,6 +550,16 @@ static DOCUMENTATION_LOG2: LazyLock = LazyLock::new(|| { "log2(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT log2(8); ++-----------+ +| log2(8) | ++-----------+ +| 3.0 | ++-----------+ +```"#, + ) .build() }); @@ -431,6 +588,16 @@ static DOCUMENTATION_LOG10: LazyLock = LazyLock::new(|| { "log10(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT log10(100); ++-------------+ +| log10(100) | ++-------------+ +| 2.0 | ++-------------+ +```"#, + ) .build() }); @@ -443,18 +610,28 @@ pub fn radians_order(input: &[ExprProperties]) -> Result { Ok(input[0].sort_properties) } -static DOCUMENTATION_RADIONS: LazyLock = LazyLock::new(|| { +static DOCUMENTATION_RADIANS: LazyLock = LazyLock::new(|| { Documentation::builder( DOC_SECTION_MATH, "Converts degrees to radians.", "radians(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT radians(180); ++----------------+ +| radians(180) | ++----------------+ +| 3.14159265359 | ++----------------+ +```"#, + ) .build() }); pub fn get_radians_doc() -> &'static Documentation { - &DOCUMENTATION_RADIONS + &DOCUMENTATION_RADIANS } /// Non-decreasing on \[0, π\] and then non-increasing on \[π, 2π\]. @@ -471,6 +648,16 @@ static DOCUMENTATION_SIN: LazyLock = LazyLock::new(|| { "sin(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT sin(0); ++----------+ +| sin(0) | ++----------+ +| 0.0 | ++----------+ +```"#, + ) .build() }); @@ -490,6 +677,16 @@ static DOCUMENTATION_SINH: LazyLock = LazyLock::new(|| { "sinh(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT sinh(1); ++-----------+ +| sinh(1) | ++-----------+ +| 1.1752012 | ++-----------+ +```"#, + ) .build() }); @@ -539,6 +736,16 @@ static DOCUMENTATION_TAN: LazyLock = LazyLock::new(|| { "tan(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql +> SELECT tan(pi()/4); ++--------------+ +| tan(PI()/4) | ++--------------+ +| 1.0 | ++--------------+ +```"#, + ) .build() }); @@ -558,6 +765,16 @@ static DOCUMENTATION_TANH: LazyLock = LazyLock::new(|| { "tanh(numeric_expression)", ) .with_standard_argument("numeric_expression", Some("Numeric")) + .with_sql_example( + r#"```sql + > SELECT tanh(20); + +----------+ + | tanh(20) | + +----------+ + | 1.0 | + +----------+ + ```"#, + ) .build() }); diff --git a/datafusion/functions/src/math/nans.rs b/datafusion/functions/src/math/nans.rs index ef9b2eff20d4..759b0f5fd50a 100644 --- a/datafusion/functions/src/math/nans.rs +++ b/datafusion/functions/src/math/nans.rs @@ -31,6 +31,14 @@ use std::sync::Arc; doc_section(label = "Math Functions"), description = "Returns true if a given number is +NaN or -NaN otherwise returns false.", syntax_example = "isnan(numeric_expression)", + sql_example = r#"```sql +> SELECT isnan(1); ++----------+ +| isnan(1) | ++----------+ +| false | ++----------+ +```"#, standard_argument(name = "numeric_expression", prefix = "Numeric") )] #[derive(Debug, PartialEq, Eq, Hash)] diff --git a/datafusion/functions/src/math/nanvl.rs b/datafusion/functions/src/math/nanvl.rs index 3d05a03e5aa6..f0835b4d48a0 100644 --- a/datafusion/functions/src/math/nanvl.rs +++ b/datafusion/functions/src/math/nanvl.rs @@ -36,6 +36,14 @@ use datafusion_macros::user_doc; description = r#"Returns the first argument if it's not _NaN_. Returns the second argument otherwise."#, syntax_example = "nanvl(expression_x, expression_y)", + sql_example = r#"```sql +> SELECT nanvl(0, 5); ++------------+ +| nanvl(0,5) | ++------------+ +| 0 | ++------------+ +```"#, argument( name = "expression_x", description = "Numeric expression to return if it's not _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators." diff --git a/datafusion/functions/src/math/power.rs b/datafusion/functions/src/math/power.rs index a0db444421d7..ad2e795d086e 100644 --- a/datafusion/functions/src/math/power.rs +++ b/datafusion/functions/src/math/power.rs @@ -39,6 +39,14 @@ use datafusion_macros::user_doc; doc_section(label = "Math Functions"), description = "Returns a base expression raised to the power of an exponent.", syntax_example = "power(base, exponent)", + sql_example = r#"```sql +> SELECT power(2, 3); ++-------------+ +| power(2,3) | ++-------------+ +| 8 | ++-------------+ +```"#, standard_argument(name = "base", prefix = "Numeric"), standard_argument(name = "exponent", prefix = "Exponent numeric") )] diff --git a/datafusion/functions/src/math/random.rs b/datafusion/functions/src/math/random.rs index f9c4b198d1dd..d63e76a06d01 100644 --- a/datafusion/functions/src/math/random.rs +++ b/datafusion/functions/src/math/random.rs @@ -32,7 +32,15 @@ use datafusion_macros::user_doc; doc_section(label = "Math Functions"), description = r#"Returns a random float value in the range [0, 1). The random seed is unique to each row."#, - syntax_example = "random()" + syntax_example = "random()", + sql_example = r#"```sql +> SELECT random(); ++------------------+ +| random() | ++------------------+ +| 0.7389238902938 | ++------------------+ +```"# )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct RandomFunc { diff --git a/datafusion/functions/src/math/round.rs b/datafusion/functions/src/math/round.rs index e13d6b8f9a52..de5c0930e0af 100644 --- a/datafusion/functions/src/math/round.rs +++ b/datafusion/functions/src/math/round.rs @@ -41,7 +41,15 @@ use datafusion_macros::user_doc; argument( name = "decimal_places", description = "Optional. The number of decimal places to round to. Defaults to 0." - ) + ), + sql_example = r#"```sql +> SELECT round(3.14159); ++--------------+ +| round(3.14159)| ++--------------+ +| 3.0 | ++--------------+ +```"# )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct RoundFunc { diff --git a/datafusion/functions/src/math/signum.rs b/datafusion/functions/src/math/signum.rs index 73931f303b86..bbe6178f39b7 100644 --- a/datafusion/functions/src/math/signum.rs +++ b/datafusion/functions/src/math/signum.rs @@ -38,7 +38,15 @@ use crate::utils::make_scalar_function; Negative numbers return `-1`. Zero and positive numbers return `1`."#, syntax_example = "signum(numeric_expression)", - standard_argument(name = "numeric_expression", prefix = "Numeric") + standard_argument(name = "numeric_expression", prefix = "Numeric"), + sql_example = r#"```sql +> SELECT signum(-42); ++-------------+ +| signum(-42) | ++-------------+ +| -1 | ++-------------+ +```"# )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct SignumFunc { diff --git a/datafusion/functions/src/math/trunc.rs b/datafusion/functions/src/math/trunc.rs index c8e2de502b26..9d1b4336f638 100644 --- a/datafusion/functions/src/math/trunc.rs +++ b/datafusion/functions/src/math/trunc.rs @@ -45,7 +45,16 @@ use datafusion_macros::user_doc; `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`."# - ) + ), + sql_example = r#" + ```sql + > SELECT trunc(42.738); + +----------------+ + | trunc(42.738) | + +----------------+ + | 42 | + +----------------+ + ```"# )] #[derive(Debug, PartialEq, Eq, Hash)] pub struct TruncFunc { diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md index b0811ab7811b..4a1069d4fd60 100644 --- a/docs/source/user-guide/sql/scalar_functions.md +++ b/docs/source/user-guide/sql/scalar_functions.md @@ -81,6 +81,17 @@ abs(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT abs(-5); ++----------+ +| abs(-5) | ++----------+ +| 5 | ++----------+ +``` + ### `acos` Returns the arc cosine or inverse cosine of a number. @@ -93,6 +104,17 @@ acos(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT acos(1); ++----------+ +| acos(1) | ++----------+ +| 0.0 | ++----------+ +``` + ### `acosh` Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number. @@ -105,6 +127,17 @@ acosh(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT acosh(2); ++------------+ +| acosh(2) | ++------------+ +| 1.31696 | ++------------+ +``` + ### `asin` Returns the arc sine or inverse sine of a number. @@ -117,6 +150,17 @@ asin(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT asin(0.5); ++------------+ +| asin(0.5) | ++------------+ +| 0.5235988 | ++------------+ +``` + ### `asinh` Returns the area hyperbolic sine or inverse hyperbolic sine of a number. @@ -129,6 +173,17 @@ asinh(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT asinh(1); ++------------+ +| asinh(1) | ++------------+ +| 0.8813736 | ++------------+ +``` + ### `atan` Returns the arc tangent or inverse tangent of a number. @@ -141,6 +196,17 @@ atan(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql + > SELECT atan(1); ++-----------+ +| atan(1) | ++-----------+ +| 0.7853982 | ++-----------+ +``` + ### `atan2` Returns the arc tangent or inverse tangent of `expression_y / expression_x`. @@ -156,6 +222,17 @@ atan2(expression_y, expression_x) - **expression_x**: Second numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. +#### Example + +```sql +> SELECT atan2(1, 1); ++------------+ +| atan2(1,1) | ++------------+ +| 0.7853982 | ++------------+ +``` + ### `atanh` Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. @@ -168,6 +245,17 @@ atanh(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql + > SELECT atanh(0.5); ++-------------+ +| atanh(0.5) | ++-------------+ +| 0.5493061 | ++-------------+ +``` + ### `cbrt` Returns the cube root of a number. @@ -180,6 +268,17 @@ cbrt(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT cbrt(27); ++-----------+ +| cbrt(27) | ++-----------+ +| 3.0 | ++-----------+ +``` + ### `ceil` Returns the nearest integer greater than or equal to a number. @@ -192,6 +291,17 @@ ceil(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql + > SELECT ceil(3.14); ++------------+ +| ceil(3.14) | ++------------+ +| 4.0 | ++------------+ +``` + ### `cos` Returns the cosine of a number. @@ -204,6 +314,17 @@ cos(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT cos(0); ++--------+ +| cos(0) | ++--------+ +| 1.0 | ++--------+ +``` + ### `cosh` Returns the hyperbolic cosine of a number. @@ -216,6 +337,17 @@ cosh(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT cosh(1); ++-----------+ +| cosh(1) | ++-----------+ +| 1.5430806 | ++-----------+ +``` + ### `cot` Returns the cotangent of a number. @@ -228,6 +360,17 @@ cot(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT cot(1); ++---------+ +| cot(1) | ++---------+ +| 0.64209 | ++---------+ +``` + ### `degrees` Converts radians to degrees. @@ -240,6 +383,17 @@ degrees(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql + > SELECT degrees(pi()); ++------------+ +| degrees(0) | ++------------+ +| 180.0 | ++------------+ +``` + ### `exp` Returns the base-e exponential of a number. @@ -252,6 +406,17 @@ exp(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT exp(1); ++---------+ +| exp(1) | ++---------+ +| 2.71828 | ++---------+ +``` + ### `factorial` Factorial. Returns 1 if value is less than 2. @@ -264,6 +429,17 @@ factorial(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT factorial(5); ++---------------+ +| factorial(5) | ++---------------+ +| 120 | ++---------------+ +``` + ### `floor` Returns the nearest integer less than or equal to a number. @@ -276,6 +452,17 @@ floor(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT floor(3.14); ++-------------+ +| floor(3.14) | ++-------------+ +| 3.0 | ++-------------+ +``` + ### `gcd` Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero. @@ -289,6 +476,17 @@ gcd(expression_x, expression_y) - **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. +#### Example + +```sql +> SELECT gcd(48, 18); ++------------+ +| gcd(48,18) | ++------------+ +| 6 | ++------------+ +``` + ### `isnan` Returns true if a given number is +NaN or -NaN otherwise returns false. @@ -301,6 +499,17 @@ isnan(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT isnan(1); ++----------+ +| isnan(1) | ++----------+ +| false | ++----------+ +``` + ### `iszero` Returns true if a given number is +0.0 or -0.0 otherwise returns false. @@ -313,6 +522,17 @@ iszero(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT iszero(0); ++------------+ +| iszero(0) | ++------------+ +| true | ++------------+ +``` + ### `lcm` Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero. @@ -326,6 +546,17 @@ lcm(expression_x, expression_y) - **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. +#### Example + +```sql +> SELECT lcm(4, 5); ++----------+ +| lcm(4,5) | ++----------+ +| 20 | ++----------+ +``` + ### `ln` Returns the natural logarithm of a number. @@ -338,6 +569,17 @@ ln(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT ln(2.71828); ++-------------+ +| ln(2.71828) | ++-------------+ +| 1.0 | ++-------------+ +``` + ### `log` Returns the base-x logarithm of a number. Can either provide a specified base, or if omitted then takes the base-10 of a number. @@ -352,6 +594,17 @@ 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. +#### Example + +```sql +> SELECT log(10); ++---------+ +| log(10) | ++---------+ +| 1.0 | ++---------+ +``` + ### `log10` Returns the base-10 logarithm of a number. @@ -364,6 +617,17 @@ log10(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT log10(100); ++-------------+ +| log10(100) | ++-------------+ +| 2.0 | ++-------------+ +``` + ### `log2` Returns the base-2 logarithm of a number. @@ -376,6 +640,17 @@ log2(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT log2(8); ++-----------+ +| log2(8) | ++-----------+ +| 3.0 | ++-----------+ +``` + ### `nanvl` Returns the first argument if it's not _NaN_. @@ -390,6 +665,17 @@ nanvl(expression_x, expression_y) - **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. +#### Example + +```sql +> SELECT nanvl(0, 5); ++------------+ +| nanvl(0,5) | ++------------+ +| 0 | ++------------+ +``` + ### `pi` Returns an approximate value of π. @@ -415,6 +701,17 @@ power(base, exponent) - **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. +#### Example + +```sql +> SELECT power(2, 3); ++-------------+ +| power(2,3) | ++-------------+ +| 8 | ++-------------+ +``` + #### Aliases - pow @@ -431,6 +728,17 @@ radians(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT radians(180); ++----------------+ +| radians(180) | ++----------------+ +| 3.14159265359 | ++----------------+ +``` + ### `random` Returns a random float value in the range [0, 1). @@ -440,6 +748,17 @@ The random seed is unique to each row. random() ``` +#### Example + +```sql +> SELECT random(); ++------------------+ +| random() | ++------------------+ +| 0.7389238902938 | ++------------------+ +``` + ### `round` Rounds a number to the nearest integer. @@ -453,6 +772,17 @@ round(numeric_expression[, decimal_places]) - **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. +#### Example + +```sql +> SELECT round(3.14159); ++--------------+ +| round(3.14159)| ++--------------+ +| 3.0 | ++--------------+ +``` + ### `signum` Returns the sign of a number. @@ -467,6 +797,17 @@ signum(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT signum(-42); ++-------------+ +| signum(-42) | ++-------------+ +| -1 | ++-------------+ +``` + ### `sin` Returns the sine of a number. @@ -479,6 +820,17 @@ sin(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT sin(0); ++----------+ +| sin(0) | ++----------+ +| 0.0 | ++----------+ +``` + ### `sinh` Returns the hyperbolic sine of a number. @@ -491,6 +843,17 @@ sinh(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT sinh(1); ++-----------+ +| sinh(1) | ++-----------+ +| 1.1752012 | ++-----------+ +``` + ### `sqrt` Returns the square root of a number. @@ -515,6 +878,17 @@ tan(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT tan(pi()/4); ++--------------+ +| tan(PI()/4) | ++--------------+ +| 1.0 | ++--------------+ +``` + ### `tanh` Returns the hyperbolic tangent of a number. @@ -527,6 +901,17 @@ tanh(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql + > SELECT tanh(20); + +----------+ + | tanh(20) | + +----------+ + | 1.0 | + +----------+ +``` + ### `trunc` Truncates a number to a whole number or truncated to the specified decimal places. @@ -544,6 +929,17 @@ trunc(numeric_expression[, decimal_places]) right of the decimal point. If `decimal_places` is a negative integer, replaces digits to the left of the decimal point with `0`. +#### Example + +```sql +> SELECT trunc(42.738); ++----------------+ +| trunc(42.738) | ++----------------+ +| 42 | ++----------------+ +``` + ## Conditional Functions - [coalesce](#coalesce)