This is an automated email from the ASF dual-hosted git repository.
github-bot pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new 84b327c564 doc: add missing examples for multiple math functions
(#17018)
84b327c564 is described below
commit 84b327c564e642fda0799a37d0d1766526765834
Author: aditya singh rathore <[email protected]>
AuthorDate: Tue Sep 23 06:05:43 2025 +0530
doc: add missing examples for multiple math functions (#17018)
* Update Scalar_functions.md
* pretier fix
* Updated files
* Updated Scalar functions
* Update datafusion/functions/src/math/log.rs
Co-authored-by: Jeffrey Vo <[email protected]>
* Update datafusion/functions/src/math/monotonicity.rs
Co-authored-by: Jeffrey Vo <[email protected]>
* Update datafusion/functions/src/math/monotonicity.rs
Co-authored-by: Jeffrey Vo <[email protected]>
* Update datafusion/functions/src/math/nans.rs
Co-authored-by: Jeffrey Vo <[email protected]>
* Update datafusion/functions/src/math/nanvl.rs
Co-authored-by: Jeffrey Vo <[email protected]>
* Fix tanh example to be tanh not trunc
* Run update_function_docs.sh
---------
Co-authored-by: Jeffrey Vo <[email protected]>
---
datafusion/functions/src/math/abs.rs | 8 +
datafusion/functions/src/math/cot.rs | 8 +
datafusion/functions/src/math/factorial.rs | 8 +
datafusion/functions/src/math/gcd.rs | 8 +
datafusion/functions/src/math/iszero.rs | 8 +
datafusion/functions/src/math/lcm.rs | 8 +
datafusion/functions/src/math/log.rs | 8 +
datafusion/functions/src/math/monotonicity.rs | 239 ++++++++++++++-
datafusion/functions/src/math/nans.rs | 8 +
datafusion/functions/src/math/nanvl.rs | 8 +
datafusion/functions/src/math/power.rs | 8 +
datafusion/functions/src/math/random.rs | 10 +-
datafusion/functions/src/math/round.rs | 10 +-
datafusion/functions/src/math/signum.rs | 10 +-
datafusion/functions/src/math/trunc.rs | 11 +-
docs/source/user-guide/sql/scalar_functions.md | 396 +++++++++++++++++++++++++
16 files changed, 741 insertions(+), 15 deletions(-)
diff --git a/datafusion/functions/src/math/abs.rs
b/datafusion/functions/src/math/abs.rs
index 5c5ad40b98..8af8e4c2c8 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<MathArrayFunction>
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 8006be2eff..43f2012d07 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 1423eeafed..79f6da94dd 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 714718c5e8..0b85e7b54a 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 ec1200f443..68cd3aca28 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 8b2d849ef8..bfb20dfd5c 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 6604f9ee22..ff1fd0cd4b 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 baa3147f62..7870dc9562 100644
--- a/datafusion/functions/src/math/monotonicity.rs
+++ b/datafusion/functions/src/math/monotonicity.rs
@@ -45,6 +45,16 @@ static DOCUMENTATION_ACOS: LazyLock<Documentation> =
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<SortProperties> {
}
}
-static DOCUMENTATION_ACOSH: LazyLock<Documentation> = LazyLock::new(|| {
- Documentation::builder(
+static DOCUMENTATION_ACOSH: LazyLock<Documentation> =
+ 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<Documentation> =
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<Documentation> =
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<Documentation> =
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<SortProperties> {
}
}
-static DOCUMENTATION_ATANH: LazyLock<Documentation> = LazyLock::new(|| {
- Documentation::builder(
+static DOCUMENTATION_ATANH: LazyLock<Documentation> =
+ 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<SortProperties> {
Ok(SortProperties::Unordered)
}
-static DOCUMENTATION_ATANH2: LazyLock<Documentation> = LazyLock::new(|| {
- Documentation::builder(
+static DOCUMENTATION_ATANH2: LazyLock<Documentation> =
+ 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<Documentation> =
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<Documentation> =
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<Documentation> =
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<Documentation> =
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<Documentation> =
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<Documentation> =
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<Documentation> =
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<Documentation> =
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<Documentation> =
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<Documentation> =
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<SortProperties> {
Ok(input[0].sort_properties)
}
-static DOCUMENTATION_RADIONS: LazyLock<Documentation> = LazyLock::new(|| {
+static DOCUMENTATION_RADIANS: LazyLock<Documentation> = 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<Documentation> =
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<Documentation> =
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<Documentation> =
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<Documentation> =
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 ef9b2eff20..759b0f5fd5 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 3d05a03e5a..f0835b4d48 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 a0db444421..ad2e795d08 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 f9c4b198d1..d63e76a06d 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 e13d6b8f9a..de5c0930e0 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 73931f303b..bbe6178f39 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 c8e2de502b..9d1b4336f6 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 b0811ab781..4a1069d4fd 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)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
