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 <jeffrey.vo.australia@gmail.com>

* Update datafusion/functions/src/math/monotonicity.rs

Co-authored-by: Jeffrey Vo <jeffrey.vo.australia@gmail.com>

* Update datafusion/functions/src/math/monotonicity.rs

Co-authored-by: Jeffrey Vo <jeffrey.vo.australia@gmail.com>

* Update datafusion/functions/src/math/nans.rs

Co-authored-by: Jeffrey Vo <jeffrey.vo.australia@gmail.com>

* Update datafusion/functions/src/math/nanvl.rs

Co-authored-by: Jeffrey Vo <jeffrey.vo.australia@gmail.com>

* Fix tanh example to be tanh not trunc

* Run update_function_docs.sh

---------

Co-authored-by: Jeffrey Vo <jeffrey.vo.australia@gmail.com>

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)]

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)]

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)]

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")
 )]

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)]

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")
 )]

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")
 )]

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()
 });
 

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)]

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."

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")
 )]

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 {

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 {

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 {

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 {

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)