From 2c7e10a0ad720da99cd76085609a134364db5e17 Mon Sep 17 00:00:00 2001 From: aditya singh rathore Date: Sat, 2 Aug 2025 12:17:47 +0530 Subject: [PATCH 1/9] Update Scalar_functions.md --- .../source/user-guide/sql/scalar_functions.md | 393 ++++++++++++++++++ 1 file changed, 393 insertions(+) diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md index d49fc22dabb4..dbda50ea25ed 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,18 @@ 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 +246,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 +269,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 +292,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 +315,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 +338,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 +361,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 +384,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) | ++------------+ +| 0.0 | ++------------+ +``` + ### `exp` Returns the base-e exponential of a number. @@ -252,6 +407,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 +430,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 +453,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 +477,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 +500,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) | ++----------+ +| true | ++----------+ +``` + ### `iszero` Returns true if a given number is +0.0 or -0.0 otherwise returns false. @@ -313,6 +523,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 +547,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 +570,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 +595,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(2.71828); ++--------------+ +| log(2.71828) | ++--------------+ +| 1.0 | ++--------------+ +``` + ### `log10` Returns the base-10 logarithm of a number. @@ -364,6 +618,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 +641,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 +666,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) | ++------------+ +| 5 | ++------------+ +``` + ### `pi` Returns an approximate value of π. @@ -415,6 +702,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 +729,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.1415 | ++-----------------+ +``` + ### `random` Returns a random float value in the range [0, 1). @@ -453,6 +762,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 +787,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 +810,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) | ++----------+ +| 1.0 | ++----------+ +``` + ### `sinh` Returns the hyperbolic sine of a number. @@ -491,6 +833,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. @@ -503,6 +856,17 @@ sqrt(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +#### Example + +```sql +> SELECT sqrt(16); ++----------+ +| sqrt(16) | ++----------+ +| 4.0 | ++----------+ +``` + ### `tan` Returns the tangent of a number. @@ -515,6 +879,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 +902,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(1); ++-----------+ +| tanh(1) | ++-----------+ +| 0.7615941 | ++-----------+ +``` + ### `trunc` Truncates a number to a whole number or truncated to the specified decimal places. @@ -544,6 +930,13 @@ 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(3.987, 2); + -- Output: 3.98 +``` + ## Conditional Functions - [coalesce](#coalesce) From 4e4d033d4429c1439f5662845db91c00f693785b Mon Sep 17 00:00:00 2001 From: aditya singh rathore Date: Sat, 2 Aug 2025 12:26:02 +0530 Subject: [PATCH 2/9] pretier fix --- docs/source/user-guide/sql/scalar_functions.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md index dbda50ea25ed..1914b858a374 100644 --- a/docs/source/user-guide/sql/scalar_functions.md +++ b/docs/source/user-guide/sql/scalar_functions.md @@ -233,7 +233,6 @@ atan2(expression_y, expression_x) +------------+ ``` - ### `atanh` Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number. @@ -933,9 +932,13 @@ trunc(numeric_expression[, decimal_places]) #### Example ```sql - SELECT trunc(3.987, 2); - -- Output: 3.98 -``` + > SELECT trunc(42.738); + +----------------+ + | trunc(42.738) | + +----------------+ + | 42 | + +----------------+ + ``` ## Conditional Functions @@ -2441,7 +2444,6 @@ date_bin(interval, expression, origin-timestamp) - **interval**: Bin interval. - **expression**: Time expression to operate on. Can be a constant, column, or function. - **origin-timestamp**: Optional. Starting point used to determine bin boundaries. If not specified defaults 1970-01-01T00:00:00Z (the UNIX epoch in UTC). The following intervals are supported: - - nanoseconds - microseconds - milliseconds @@ -2495,7 +2497,6 @@ date_part(part, expression) #### Arguments - **part**: Part of the date to return. The following date parts are supported: - - year - quarter (emits value in inclusive range [1, 4] based on which quartile of the year the date is in) - month @@ -2534,7 +2535,6 @@ date_trunc(precision, expression) #### Arguments - **precision**: Time precision to truncate to. The following precisions are supported: - - year / YEAR - quarter / QUARTER - month / MONTH From 8f3cadb0307c8442b44ee5bd0e324a3fc7777d2a Mon Sep 17 00:00:00 2001 From: aditya singh rathore <142787780+Adez017@users.noreply.github.com> Date: Wed, 6 Aug 2025 11:36:53 +0000 Subject: [PATCH 3/9] Updated files --- 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 +- .../user-guide/sql/aggregate_functions.md | 107 ++++---- 16 files changed, 391 insertions(+), 76 deletions(-) diff --git a/datafusion/functions/src/math/abs.rs b/datafusion/functions/src/math/abs.rs index 0c686a59016a..4bc97f9b7db6 100644 --- a/datafusion/functions/src/math/abs.rs +++ b/datafusion/functions/src/math/abs.rs @@ -110,6 +110,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)] diff --git a/datafusion/functions/src/math/cot.rs b/datafusion/functions/src/math/cot.rs index 4e56212ddbee..30bc6670bd3c 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)] diff --git a/datafusion/functions/src/math/factorial.rs b/datafusion/functions/src/math/factorial.rs index c2ac21b78f21..1fdb33d162fa 100644 --- a/datafusion/functions/src/math/factorial.rs +++ b/datafusion/functions/src/math/factorial.rs @@ -39,6 +39,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)] diff --git a/datafusion/functions/src/math/gcd.rs b/datafusion/functions/src/math/gcd.rs index 7fe253b4afbc..f702e8a0056b 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 bc12dfb7898e..6ba43d2c6f43 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)] diff --git a/datafusion/functions/src/math/lcm.rs b/datafusion/functions/src/math/lcm.rs index fc6bf9461f28..61b017aa4bbf 100644 --- a/datafusion/functions/src/math/lcm.rs +++ b/datafusion/functions/src/math/lcm.rs @@ -39,6 +39,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 23e267a323b9..9cb51a72b972 100644 --- a/datafusion/functions/src/math/log.rs +++ b/datafusion/functions/src/math/log.rs @@ -42,6 +42,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(2.71828); ++--------------+ +| log(2.71828) | ++--------------+ +| 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..cedba74df663 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) | ++------------+ +| 0.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) | ++----------+ +| 1.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 trunc(42.738); + +----------------+ + | trunc(42.738) | + +----------------+ + | 42 | + +----------------+ + ```"#, + ) .build() }); diff --git a/datafusion/functions/src/math/nans.rs b/datafusion/functions/src/math/nans.rs index 34a5c2a1c16b..ef8095f79807 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) | ++----------+ +| true | ++----------+ +```"#, standard_argument(name = "numeric_expression", prefix = "Numeric") )] #[derive(Debug)] diff --git a/datafusion/functions/src/math/nanvl.rs b/datafusion/functions/src/math/nanvl.rs index 9effb82896ee..52d870798885 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) | ++------------+ +| 5 | ++------------+ +```"#, 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 465844704f59..c4da40c90dcb 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 92b6ed1895ed..d96eb78bbb3e 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)] pub struct RandomFunc { diff --git a/datafusion/functions/src/math/round.rs b/datafusion/functions/src/math/round.rs index fc87b7e63a62..f42dcb2e671f 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)] pub struct RoundFunc { diff --git a/datafusion/functions/src/math/signum.rs b/datafusion/functions/src/math/signum.rs index ec6ef5a78c6a..c01ce712493d 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)] pub struct SignumFunc { diff --git a/datafusion/functions/src/math/trunc.rs b/datafusion/functions/src/math/trunc.rs index 2ac291204a0b..0415e53009dc 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)] pub struct TruncFunc { diff --git a/docs/source/user-guide/sql/aggregate_functions.md b/docs/source/user-guide/sql/aggregate_functions.md index 88241770a47d..0057ae484459 100644 --- a/docs/source/user-guide/sql/aggregate_functions.md +++ b/docs/source/user-guide/sql/aggregate_functions.md @@ -29,7 +29,7 @@ dev/update_function_docs.sh file for updating surrounding text. Aggregate functions operate on a set of values to compute a single result. -## General Functions +## General Functions - [array_agg](#array_agg) - [avg](#avg) @@ -62,13 +62,13 @@ This aggregation function can only mix DISTINCT and ORDER BY if the ordering exp ```sql array_agg(expression [ORDER BY expression]) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. #### Example + ```sql > SELECT array_agg(column_name ORDER BY other_column) FROM table_name; +-----------------------------------------------+ @@ -84,6 +84,8 @@ array_agg(expression [ORDER BY expression]) +--------------------------------------------------------+ ``` + + ### `avg` Returns the average of numeric values in the specified column. @@ -91,7 +93,6 @@ Returns the average of numeric values in the specified column. ```sql avg(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -108,7 +109,6 @@ avg(expression) ``` #### Aliases - - mean ### `bit_and` @@ -118,7 +118,6 @@ Computes the bitwise AND of all non-null input values. ```sql bit_and(expression) ``` - #### Arguments - **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -130,7 +129,6 @@ Computes the bitwise OR of all non-null input values. ```sql bit_or(expression) ``` - #### Arguments - **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -142,7 +140,6 @@ Computes the bitwise exclusive OR of all non-null input values. ```sql bit_xor(expression) ``` - #### Arguments - **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -154,7 +151,6 @@ Returns true if all non-null input values are true, otherwise false. ```sql bool_and(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -170,6 +166,7 @@ bool_and(expression) +----------------------------+ ``` + ### `bool_or` Returns true if all non-null input values are true, otherwise false. @@ -177,7 +174,6 @@ Returns true if all non-null input values are true, otherwise false. ```sql bool_and(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -193,6 +189,7 @@ bool_and(expression) +----------------------------+ ``` + ### `count` Returns the number of non-null values in the specified column. To include null values in the total count, use `count(*)`. @@ -200,7 +197,6 @@ Returns the number of non-null values in the specified column. To include null v ```sql count(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -223,6 +219,7 @@ count(expression) +------------------+ ``` + ### `first_value` Returns the first element in an aggregation group according to the requested ordering. If no ordering is given, returns an arbitrary element from the group. @@ -230,7 +227,6 @@ Returns the first element in an aggregation group according to the requested ord ```sql first_value(expression [ORDER BY expression]) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -246,6 +242,7 @@ first_value(expression [ORDER BY expression]) +-----------------------------------------------+ ``` + ### `grouping` Returns 1 if the data is aggregated across the specified column, or 0 if it is not aggregated in the result set. @@ -253,7 +250,6 @@ Returns 1 if the data is aggregated across the specified column, or 0 if it is n ```sql grouping(expression) ``` - #### Arguments - **expression**: Expression to evaluate whether data is aggregated across the specified column. Can be a constant, column, or function. @@ -273,6 +269,7 @@ grouping(expression) +-------------+-------------+ ``` + ### `last_value` Returns the last element in an aggregation group according to the requested ordering. If no ordering is given, returns an arbitrary element from the group. @@ -280,7 +277,6 @@ Returns the last element in an aggregation group according to the requested orde ```sql last_value(expression [ORDER BY expression]) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -296,6 +292,7 @@ last_value(expression [ORDER BY expression]) +-----------------------------------------------+ ``` + ### `max` Returns the maximum value in the specified column. @@ -303,7 +300,6 @@ Returns the maximum value in the specified column. ```sql max(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -320,7 +316,6 @@ max(expression) ``` ### `mean` - _Alias of [avg](#avg)._ ### `median` @@ -330,7 +325,6 @@ Returns the median value in the specified column. ```sql median(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -346,6 +340,7 @@ median(expression) +----------------------+ ``` + ### `min` Returns the minimum value in the specified column. @@ -353,7 +348,6 @@ Returns the minimum value in the specified column. ```sql min(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -369,6 +363,7 @@ min(expression) +----------------------+ ``` + ### `string_agg` Concatenates the values of string expressions and places separator values between them. If ordering is required, strings are concatenated in the specified order. This aggregation function can only mix DISTINCT and ORDER BY if the ordering expression is exactly the same as the first argument expression. @@ -376,7 +371,6 @@ Concatenates the values of string expressions and places separator values betwee ```sql string_agg([DISTINCT] expression, delimiter [ORDER BY expression]) ``` - #### Arguments - **expression**: The string expression to concatenate. Can be a column or any valid string expression. @@ -408,6 +402,7 @@ string_agg([DISTINCT] expression, delimiter [ORDER BY expression]) +--------------------------+ ``` + ### `sum` Returns the sum of all values in the specified column. @@ -415,7 +410,6 @@ Returns the sum of all values in the specified column. ```sql sum(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -431,6 +425,7 @@ sum(expression) +-----------------------+ ``` + ### `var` Returns the statistical sample variance of a set of numbers. @@ -438,15 +433,12 @@ Returns the statistical sample variance of a set of numbers. ```sql var(expression) ``` - #### Arguments - **expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. - #### Aliases - -- var_sample -- var_samp +- var\_sample +- var\_samp ### `var_pop` @@ -455,28 +447,19 @@ Returns the statistical population variance of a set of numbers. ```sql var_pop(expression) ``` - #### Arguments - **expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. - #### Aliases - -- var_population - +- var\_population ### `var_population` - _Alias of [var_pop](#var_pop)._ - ### `var_samp` - _Alias of [var](#var)._ - ### `var_sample` - _Alias of [var](#var)._ -## Statistical Functions +## Statistical Functions - [corr](#corr) - [covar](#covar) @@ -503,7 +486,6 @@ Returns the coefficient of correlation between two numeric values. ```sql corr(expression1, expression2) ``` - #### Arguments - **expression1**: First expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -521,7 +503,6 @@ corr(expression1, expression2) ``` ### `covar` - _Alias of [covar_samp](#covar_samp)._ ### `covar_pop` @@ -531,7 +512,6 @@ Returns the sample covariance of a set of number pairs. ```sql covar_samp(expression1, expression2) ``` - #### Arguments - **expression1**: First expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -548,6 +528,7 @@ covar_samp(expression1, expression2) +-----------------------------------+ ``` + ### `covar_samp` Returns the sample covariance of a set of number pairs. @@ -555,7 +536,6 @@ Returns the sample covariance of a set of number pairs. ```sql covar_samp(expression1, expression2) ``` - #### Arguments - **expression1**: First expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -573,7 +553,6 @@ covar_samp(expression1, expression2) ``` #### Aliases - - covar ### `nth_value` @@ -583,7 +562,6 @@ Returns the nth value in a group of values. ```sql nth_value(expression, n ORDER BY expression) ``` - #### Arguments - **expression**: The column or expression to retrieve the nth value from. @@ -605,6 +583,7 @@ nth_value(expression, n ORDER BY expression) +---------+--------+-------------------------+ ``` + ### `regr_avgx` Computes the average of the independent variable (input) expression_x for the non-null paired data points. @@ -612,7 +591,6 @@ Computes the average of the independent variable (input) expression_x for the no ```sql regr_avgx(expression_y, expression_x) ``` - #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -641,6 +619,8 @@ SELECT regr_avgx(total_sales, day) AS avg_day FROM daily_sales; +----------+ ``` + + ### `regr_avgy` Computes the average of the dependent variable (output) expression_y for the non-null paired data points. @@ -648,7 +628,6 @@ Computes the average of the dependent variable (output) expression_y for the non ```sql regr_avgy(expression_y, expression_x) ``` - #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -678,6 +657,8 @@ SELECT regr_avgy(temperature, day) AS avg_temperature FROM daily_temperature; +-----------------+ ``` + + ### `regr_count` Counts the number of non-null paired data points. @@ -685,7 +666,6 @@ Counts the number of non-null paired data points. ```sql regr_count(expression_y, expression_x) ``` - #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -714,6 +694,8 @@ SELECT regr_count(user_signups, day) AS valid_pairs FROM daily_metrics; +-------------+ ``` + + ### `regr_intercept` Computes the y-intercept of the linear regression line. For the equation (y = kx + b), this function returns b. @@ -721,7 +703,6 @@ Computes the y-intercept of the linear regression line. For the equation (y = kx ```sql regr_intercept(expression_y, expression_x) ``` - #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -751,6 +732,8 @@ SELECT regr_intercept(productivity_score, week) AS intercept FROM weekly_perform +----------+ ``` + + ### `regr_r2` Computes the square of the correlation coefficient between the independent and dependent variables. @@ -758,7 +741,6 @@ Computes the square of the correlation coefficient between the independent and d ```sql regr_r2(expression_y, expression_x) ``` - #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -787,14 +769,15 @@ SELECT regr_r2(user_signups, day) AS r_squared FROM weekly_performance; +---------+ ``` + + ### `regr_slope` -Returns the slope of the linear regression line for non-null pairs in aggregate columns. Given input column Y and X: regr_slope(Y, X) returns the slope (k in Y = k\*X + b) using minimal RSS fitting. +Returns the slope of the linear regression line for non-null pairs in aggregate columns. Given input column Y and X: regr_slope(Y, X) returns the slope (k in Y = k*X + b) using minimal RSS fitting. ```sql regr_slope(expression_y, expression_x) ``` - #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -823,6 +806,8 @@ SELECT regr_slope(user_signups, day) AS slope FROM weekly_performance; +--------+ ``` + + ### `regr_sxx` Computes the sum of squares of the independent variable. @@ -830,7 +815,6 @@ Computes the sum of squares of the independent variable. ```sql regr_sxx(expression_y, expression_x) ``` - #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -859,6 +843,8 @@ SELECT regr_sxx(test_score, hours) AS sxx FROM study_hours; +------+ ``` + + ### `regr_sxy` Computes the sum of products of paired data points. @@ -866,7 +852,6 @@ Computes the sum of products of paired data points. ```sql regr_sxy(expression_y, expression_x) ``` - #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -893,6 +878,8 @@ SELECT regr_sxy(productivity_score, week) AS sum_product_deviations FROM employe +------------------------+ ``` + + ### `regr_syy` Computes the sum of squares of the dependent variable. @@ -900,7 +887,6 @@ Computes the sum of squares of the dependent variable. ```sql regr_syy(expression_y, expression_x) ``` - #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -927,6 +913,8 @@ SELECT regr_syy(productivity_score, week) AS sum_squares_y FROM employee_product +---------------+ ``` + + ### `stddev` Returns the standard deviation of a set of numbers. @@ -934,7 +922,6 @@ Returns the standard deviation of a set of numbers. ```sql stddev(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -951,8 +938,7 @@ stddev(expression) ``` #### Aliases - -- stddev_samp +- stddev\_samp ### `stddev_pop` @@ -961,7 +947,6 @@ Returns the population standard deviation of a set of numbers. ```sql stddev_pop(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -978,10 +963,9 @@ stddev_pop(expression) ``` ### `stddev_samp` - _Alias of [stddev](#stddev)._ -## Approximate Functions +## Approximate Functions - [approx_distinct](#approx_distinct) - [approx_median](#approx_median) @@ -995,7 +979,6 @@ Returns the approximate number of distinct input values calculated using the Hyp ```sql approx_distinct(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -1011,6 +994,7 @@ approx_distinct(expression) +-----------------------------------+ ``` + ### `approx_median` Returns the approximate median (50th percentile) of input values. It is an alias of `approx_percentile_cont(0.5) WITHIN GROUP (ORDER BY x)`. @@ -1018,7 +1002,6 @@ Returns the approximate median (50th percentile) of input values. It is an alias ```sql approx_median(expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -1034,6 +1017,7 @@ approx_median(expression) +-----------------------------------+ ``` + ### `approx_percentile_cont` Returns the approximate percentile of input values using the t-digest algorithm. @@ -1041,7 +1025,6 @@ Returns the approximate percentile of input values using the t-digest algorithm. ```sql approx_percentile_cont(percentile, centroids) WITHIN GROUP (ORDER BY expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -1059,6 +1042,7 @@ approx_percentile_cont(percentile, centroids) WITHIN GROUP (ORDER BY expression) +-----------------------------------------------------------------------+ ``` + ### `approx_percentile_cont_with_weight` Returns the weighted approximate percentile of input values using the t-digest algorithm. @@ -1066,7 +1050,6 @@ Returns the weighted approximate percentile of input values using the t-digest a ```sql approx_percentile_cont_with_weight(weight, percentile) WITHIN GROUP (ORDER BY expression) ``` - #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -1083,3 +1066,5 @@ approx_percentile_cont_with_weight(weight, percentile) WITHIN GROUP (ORDER BY ex | 78.5 | +---------------------------------------------------------------------------------------------+ ``` + + From 915d28dfb0daca667d7be233e83ab7d9da5c8c13 Mon Sep 17 00:00:00 2001 From: aditya singh rathore <142787780+Adez017@users.noreply.github.com> Date: Sun, 24 Aug 2025 14:05:11 +0000 Subject: [PATCH 4/9] Updated Scalar functions --- .../user-guide/sql/aggregate_functions.md | 124 +++++++++++------- .../source/user-guide/sql/scalar_functions.md | 95 +++++++------- 2 files changed, 128 insertions(+), 91 deletions(-) diff --git a/docs/source/user-guide/sql/aggregate_functions.md b/docs/source/user-guide/sql/aggregate_functions.md index f210e0401f94..cdb51c64fc5c 100644 --- a/docs/source/user-guide/sql/aggregate_functions.md +++ b/docs/source/user-guide/sql/aggregate_functions.md @@ -29,7 +29,7 @@ dev/update_function_docs.sh file for updating surrounding text. Aggregate functions operate on a set of values to compute a single result. -## General Functions +## General Functions - [array_agg](#array_agg) - [avg](#avg) @@ -62,13 +62,13 @@ This aggregation function can only mix DISTINCT and ORDER BY if the ordering exp ```sql array_agg(expression [ORDER BY expression]) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. #### Example - ```sql > SELECT array_agg(column_name ORDER BY other_column) FROM table_name; +-----------------------------------------------+ @@ -84,8 +84,6 @@ array_agg(expression [ORDER BY expression]) +--------------------------------------------------------+ ``` - - ### `avg` Returns the average of numeric values in the specified column. @@ -93,6 +91,7 @@ Returns the average of numeric values in the specified column. ```sql avg(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -109,6 +108,7 @@ avg(expression) ``` #### Aliases + - mean ### `bit_and` @@ -118,6 +118,7 @@ Computes the bitwise AND of all non-null input values. ```sql bit_and(expression) ``` + #### Arguments - **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -129,6 +130,7 @@ Computes the bitwise OR of all non-null input values. ```sql bit_or(expression) ``` + #### Arguments - **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -140,6 +142,7 @@ Computes the bitwise exclusive OR of all non-null input values. ```sql bit_xor(expression) ``` + #### Arguments - **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -151,6 +154,7 @@ Returns true if all non-null input values are true, otherwise false. ```sql bool_and(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -166,7 +170,6 @@ bool_and(expression) +----------------------------+ ``` - ### `bool_or` Returns true if all non-null input values are true, otherwise false. @@ -174,6 +177,7 @@ Returns true if all non-null input values are true, otherwise false. ```sql bool_and(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -189,7 +193,6 @@ bool_and(expression) +----------------------------+ ``` - ### `count` Returns the number of non-null values in the specified column. To include null values in the total count, use `count(*)`. @@ -197,6 +200,7 @@ Returns the number of non-null values in the specified column. To include null v ```sql count(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -219,7 +223,6 @@ count(expression) +------------------+ ``` - ### `first_value` Returns the first element in an aggregation group according to the requested ordering. If no ordering is given, returns an arbitrary element from the group. @@ -227,6 +230,7 @@ Returns the first element in an aggregation group according to the requested ord ```sql first_value(expression [ORDER BY expression]) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -242,7 +246,6 @@ first_value(expression [ORDER BY expression]) +-----------------------------------------------+ ``` - ### `grouping` Returns 1 if the data is aggregated across the specified column, or 0 if it is not aggregated in the result set. @@ -250,6 +253,7 @@ Returns 1 if the data is aggregated across the specified column, or 0 if it is n ```sql grouping(expression) ``` + #### Arguments - **expression**: Expression to evaluate whether data is aggregated across the specified column. Can be a constant, column, or function. @@ -269,7 +273,6 @@ grouping(expression) +-------------+-------------+ ``` - ### `last_value` Returns the last element in an aggregation group according to the requested ordering. If no ordering is given, returns an arbitrary element from the group. @@ -277,6 +280,7 @@ Returns the last element in an aggregation group according to the requested orde ```sql last_value(expression [ORDER BY expression]) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -292,7 +296,6 @@ last_value(expression [ORDER BY expression]) +-----------------------------------------------+ ``` - ### `max` Returns the maximum value in the specified column. @@ -300,6 +303,7 @@ Returns the maximum value in the specified column. ```sql max(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -316,6 +320,7 @@ max(expression) ``` ### `mean` + _Alias of [avg](#avg)._ ### `median` @@ -325,6 +330,7 @@ Returns the median value in the specified column. ```sql median(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -340,7 +346,6 @@ median(expression) +----------------------+ ``` - ### `min` Returns the minimum value in the specified column. @@ -348,6 +353,7 @@ Returns the minimum value in the specified column. ```sql min(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -363,7 +369,6 @@ min(expression) +----------------------+ ``` - ### `string_agg` Concatenates the values of string expressions and places separator values between them. If ordering is required, strings are concatenated in the specified order. This aggregation function can only mix DISTINCT and ORDER BY if the ordering expression is exactly the same as the first argument expression. @@ -371,6 +376,7 @@ Concatenates the values of string expressions and places separator values betwee ```sql string_agg([DISTINCT] expression, delimiter [ORDER BY expression]) ``` + #### Arguments - **expression**: The string expression to concatenate. Can be a column or any valid string expression. @@ -402,7 +408,6 @@ string_agg([DISTINCT] expression, delimiter [ORDER BY expression]) +--------------------------+ ``` - ### `sum` Returns the sum of all values in the specified column. @@ -410,6 +415,7 @@ Returns the sum of all values in the specified column. ```sql sum(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -425,7 +431,6 @@ sum(expression) +-----------------------+ ``` - ### `var` Returns the statistical sample variance of a set of numbers. @@ -433,12 +438,15 @@ Returns the statistical sample variance of a set of numbers. ```sql var(expression) ``` + #### Arguments - **expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + #### Aliases -- var\_sample -- var\_samp + +- var_sample +- var_samp ### `var_pop` @@ -447,19 +455,28 @@ Returns the statistical population variance of a set of numbers. ```sql var_pop(expression) ``` + #### Arguments - **expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. + #### Aliases -- var\_population + +- var_population + ### `var_population` + _Alias of [var_pop](#var_pop)._ + ### `var_samp` + _Alias of [var](#var)._ + ### `var_sample` + _Alias of [var](#var)._ -## Statistical Functions +## Statistical Functions - [corr](#corr) - [covar](#covar) @@ -486,6 +503,7 @@ Returns the coefficient of correlation between two numeric values. ```sql corr(expression1, expression2) ``` + #### Arguments - **expression1**: First expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -503,6 +521,7 @@ corr(expression1, expression2) ``` ### `covar` + _Alias of [covar_samp](#covar_samp)._ ### `covar_pop` @@ -512,6 +531,7 @@ Returns the sample covariance of a set of number pairs. ```sql covar_samp(expression1, expression2) ``` + #### Arguments - **expression1**: First expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -528,7 +548,6 @@ covar_samp(expression1, expression2) +-----------------------------------+ ``` - ### `covar_samp` Returns the sample covariance of a set of number pairs. @@ -536,6 +555,7 @@ Returns the sample covariance of a set of number pairs. ```sql covar_samp(expression1, expression2) ``` + #### Arguments - **expression1**: First expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -553,6 +573,7 @@ covar_samp(expression1, expression2) ``` #### Aliases + - covar ### `nth_value` @@ -562,6 +583,7 @@ Returns the nth value in a group of values. ```sql nth_value(expression, n ORDER BY expression) ``` + #### Arguments - **expression**: The column or expression to retrieve the nth value from. @@ -583,7 +605,6 @@ nth_value(expression, n ORDER BY expression) +---------+--------+-------------------------+ ``` - ### `regr_avgx` Computes the average of the independent variable (input) expression_x for the non-null paired data points. @@ -591,6 +612,7 @@ Computes the average of the independent variable (input) expression_x for the no ```sql regr_avgx(expression_y, expression_x) ``` + #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -619,8 +641,6 @@ SELECT regr_avgx(total_sales, day) AS avg_day FROM daily_sales; +----------+ ``` - - ### `regr_avgy` Computes the average of the dependent variable (output) expression_y for the non-null paired data points. @@ -628,6 +648,7 @@ Computes the average of the dependent variable (output) expression_y for the non ```sql regr_avgy(expression_y, expression_x) ``` + #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -657,8 +678,6 @@ SELECT regr_avgy(temperature, day) AS avg_temperature FROM daily_temperature; +-----------------+ ``` - - ### `regr_count` Counts the number of non-null paired data points. @@ -666,6 +685,7 @@ Counts the number of non-null paired data points. ```sql regr_count(expression_y, expression_x) ``` + #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -694,8 +714,6 @@ SELECT regr_count(user_signups, day) AS valid_pairs FROM daily_metrics; +-------------+ ``` - - ### `regr_intercept` Computes the y-intercept of the linear regression line. For the equation (y = kx + b), this function returns b. @@ -703,6 +721,7 @@ Computes the y-intercept of the linear regression line. For the equation (y = kx ```sql regr_intercept(expression_y, expression_x) ``` + #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -732,8 +751,6 @@ SELECT regr_intercept(productivity_score, week) AS intercept FROM weekly_perform +----------+ ``` - - ### `regr_r2` Computes the square of the correlation coefficient between the independent and dependent variables. @@ -741,6 +758,7 @@ Computes the square of the correlation coefficient between the independent and d ```sql regr_r2(expression_y, expression_x) ``` + #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -769,15 +787,14 @@ SELECT regr_r2(user_signups, day) AS r_squared FROM weekly_performance; +---------+ ``` - - ### `regr_slope` -Returns the slope of the linear regression line for non-null pairs in aggregate columns. Given input column Y and X: regr_slope(Y, X) returns the slope (k in Y = k*X + b) using minimal RSS fitting. +Returns the slope of the linear regression line for non-null pairs in aggregate columns. Given input column Y and X: regr_slope(Y, X) returns the slope (k in Y = k\*X + b) using minimal RSS fitting. ```sql regr_slope(expression_y, expression_x) ``` + #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -806,8 +823,6 @@ SELECT regr_slope(user_signups, day) AS slope FROM weekly_performance; +--------+ ``` - - ### `regr_sxx` Computes the sum of squares of the independent variable. @@ -815,6 +830,7 @@ Computes the sum of squares of the independent variable. ```sql regr_sxx(expression_y, expression_x) ``` + #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -843,8 +859,6 @@ SELECT regr_sxx(test_score, hours) AS sxx FROM study_hours; +------+ ``` - - ### `regr_sxy` Computes the sum of products of paired data points. @@ -852,6 +866,7 @@ Computes the sum of products of paired data points. ```sql regr_sxy(expression_y, expression_x) ``` + #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -878,8 +893,6 @@ SELECT regr_sxy(productivity_score, week) AS sum_product_deviations FROM employe +------------------------+ ``` - - ### `regr_syy` Computes the sum of squares of the dependent variable. @@ -887,6 +900,7 @@ Computes the sum of squares of the dependent variable. ```sql regr_syy(expression_y, expression_x) ``` + #### Arguments - **expression_y**: Dependent variable expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -913,8 +927,6 @@ SELECT regr_syy(productivity_score, week) AS sum_squares_y FROM employee_product +---------------+ ``` - - ### `stddev` Returns the standard deviation of a set of numbers. @@ -922,6 +934,7 @@ Returns the standard deviation of a set of numbers. ```sql stddev(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -938,7 +951,8 @@ stddev(expression) ``` #### Aliases -- stddev\_samp + +- stddev_samp ### `stddev_pop` @@ -947,6 +961,7 @@ Returns the population standard deviation of a set of numbers. ```sql stddev_pop(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -963,9 +978,10 @@ stddev_pop(expression) ``` ### `stddev_samp` + _Alias of [stddev](#stddev)._ -## Approximate Functions +## Approximate Functions - [approx_distinct](#approx_distinct) - [approx_median](#approx_median) @@ -979,6 +995,7 @@ Returns the approximate number of distinct input values calculated using the Hyp ```sql approx_distinct(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -994,7 +1011,6 @@ approx_distinct(expression) +-----------------------------------+ ``` - ### `approx_median` Returns the approximate median (50th percentile) of input values. It is an alias of `approx_percentile_cont(0.5) WITHIN GROUP (ORDER BY x)`. @@ -1002,6 +1018,7 @@ Returns the approximate median (50th percentile) of input values. It is an alias ```sql approx_median(expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -1017,7 +1034,6 @@ approx_median(expression) +-----------------------------------+ ``` - ### `approx_percentile_cont` Returns the approximate percentile of input values using the t-digest algorithm. @@ -1025,6 +1041,7 @@ Returns the approximate percentile of input values using the t-digest algorithm. ```sql approx_percentile_cont(percentile [, centroids]) WITHIN GROUP (ORDER BY expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -1048,6 +1065,24 @@ approx_percentile_cont(percentile [, centroids]) WITHIN GROUP (ORDER BY expressi +-----------------------------------------------------------------------+ ``` +An alternate syntax is also supported: + +```sql +> SELECT approx_percentile_cont(column_name, 0.75) FROM table_name; ++-----------------------------------------------+ +| approx_percentile_cont(column_name, 0.75) | ++-----------------------------------------------+ +| 65.0 | ++-----------------------------------------------+ + +> SELECT approx_percentile_cont(column_name, 0.75, 100) FROM table_name; ++----------------------------------------------------------+ +| approx_percentile_cont(column_name, 0.75, 100) | ++----------------------------------------------------------+ +| 65.0 | ++----------------------------------------------------------+ +``` + ### `approx_percentile_cont_with_weight` Returns the weighted approximate percentile of input values using the t-digest algorithm. @@ -1055,6 +1090,7 @@ Returns the weighted approximate percentile of input values using the t-digest a ```sql approx_percentile_cont_with_weight(weight, percentile [, centroids]) WITHIN GROUP (ORDER BY expression) ``` + #### Arguments - **expression**: The expression to operate on. Can be a constant, column, or function, and any combination of operators. @@ -1089,5 +1125,3 @@ An alternative syntax is also supported: | 78.5 | +--------------------------------------------------+ ``` - - diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md index 3ccc3cec3982..9bb1a4bce255 100644 --- a/docs/source/user-guide/sql/scalar_functions.md +++ b/docs/source/user-guide/sql/scalar_functions.md @@ -199,7 +199,7 @@ atan(numeric_expression) #### Example ```sql -> SELECT atan(1); + > SELECT atan(1); +-----------+ | atan(1) | +-----------+ @@ -248,7 +248,7 @@ atanh(numeric_expression) #### Example ```sql -> SELECT atanh(0.5); + > SELECT atanh(0.5); +-------------+ | atanh(0.5) | +-------------+ @@ -294,7 +294,7 @@ ceil(numeric_expression) #### Example ```sql -> SELECT ceil(3.14); + > SELECT ceil(3.14); +------------+ | ceil(3.14) | +------------+ @@ -318,11 +318,11 @@ cos(numeric_expression) ```sql > SELECT cos(0); -+---------+ -| cos(0) | -+---------+ -| 1.0 | -+---------+ ++--------+ +| cos(0) | ++--------+ +| 1.0 | ++--------+ ``` ### `cosh` @@ -386,7 +386,7 @@ degrees(numeric_expression) #### Example ```sql -> SELECT degrees(PI()); + > SELECT degrees(pi()); +------------+ | degrees(0) | +------------+ @@ -621,11 +621,11 @@ log10(numeric_expression) ```sql > SELECT log10(100); -+--------------+ -| log10(100) | -+--------------+ -| 2.0 | -+--------------+ ++-------------+ +| log10(100) | ++-------------+ +| 2.0 | ++-------------+ ``` ### `log2` @@ -732,11 +732,11 @@ radians(numeric_expression) ```sql > SELECT radians(180); -+-----------------+ -| radians(180) | -+-----------------+ -| 3.1415 | -+-----------------+ ++----------------+ +| radians(180) | ++----------------+ +| 3.14159265359 | ++----------------+ ``` ### `random` @@ -748,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. @@ -816,7 +827,7 @@ sin(numeric_expression) +----------+ | sin(0) | +----------+ -| 1.0 | +| 1.0 | +----------+ ``` @@ -855,17 +866,6 @@ sqrt(numeric_expression) - **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. -#### Example - -```sql -> SELECT sqrt(16); -+----------+ -| sqrt(16) | -+----------+ -| 4.0 | -+----------+ -``` - ### `tan` Returns the tangent of a number. @@ -904,12 +904,12 @@ tanh(numeric_expression) #### Example ```sql -> SELECT tanh(1); -+-----------+ -| tanh(1) | -+-----------+ -| 0.7615941 | -+-----------+ +> SELECT trunc(42.738); ++----------------+ +| trunc(42.738) | ++----------------+ +| 42 | ++----------------+ ``` ### `trunc` @@ -929,16 +929,16 @@ 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 +#### Example - ```sql - > SELECT trunc(42.738); - +----------------+ - | trunc(42.738) | - +----------------+ - | 42 | - +----------------+ - ``` +```sql +> SELECT trunc(42.738); ++----------------+ +| trunc(42.738) | ++----------------+ +| 42 | ++----------------+ +``` ## Conditional Functions @@ -2444,6 +2444,7 @@ date_bin(interval, expression, origin-timestamp) - **interval**: Bin interval. - **expression**: Time expression to operate on. Can be a constant, column, or function. - **origin-timestamp**: Optional. Starting point used to determine bin boundaries. If not specified defaults 1970-01-01T00:00:00Z (the UNIX epoch in UTC). The following intervals are supported: + - nanoseconds - microseconds - milliseconds @@ -2497,6 +2498,7 @@ date_part(part, expression) #### Arguments - **part**: Part of the date to return. The following date parts are supported: + - year - quarter (emits value in inclusive range [1, 4] based on which quartile of the year the date is in) - month @@ -2536,6 +2538,7 @@ date_trunc(precision, expression) #### Arguments - **precision**: Time precision to truncate to. The following precisions are supported: + - year / YEAR - quarter / QUARTER - month / MONTH From 77e4a541a6c41cab16ae055911cd8ae5e7313e39 Mon Sep 17 00:00:00 2001 From: aditya singh rathore <142787780+Adez017@users.noreply.github.com> Date: Mon, 15 Sep 2025 08:26:32 +0530 Subject: [PATCH 5/9] Update datafusion/functions/src/math/log.rs Co-authored-by: Jeffrey Vo --- datafusion/functions/src/math/log.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/datafusion/functions/src/math/log.rs b/datafusion/functions/src/math/log.rs index 0400615e101f..71d44d339d8c 100644 --- a/datafusion/functions/src/math/log.rs +++ b/datafusion/functions/src/math/log.rs @@ -43,12 +43,12 @@ use datafusion_macros::user_doc; syntax_example = r#"log(base, numeric_expression) log(numeric_expression)"#, sql_example = r#"```sql -> SELECT log(2.71828); -+--------------+ -| log(2.71828) | -+--------------+ -| 1.0 | -+--------------+ +> SELECT log(10); ++---------+ +| log(10) | ++---------+ +| 1.0 | ++---------+ ```"#, standard_argument(name = "base", prefix = "Base numeric"), standard_argument(name = "numeric_expression", prefix = "Numeric") From 475ce2131641d1af7331c746b6eeadc1ac437cc1 Mon Sep 17 00:00:00 2001 From: aditya singh rathore <142787780+Adez017@users.noreply.github.com> Date: Mon, 15 Sep 2025 08:26:45 +0530 Subject: [PATCH 6/9] Update datafusion/functions/src/math/monotonicity.rs Co-authored-by: Jeffrey Vo --- datafusion/functions/src/math/monotonicity.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/datafusion/functions/src/math/monotonicity.rs b/datafusion/functions/src/math/monotonicity.rs index cedba74df663..f7c257324911 100644 --- a/datafusion/functions/src/math/monotonicity.rs +++ b/datafusion/functions/src/math/monotonicity.rs @@ -422,7 +422,7 @@ static DOCUMENTATION_DEGREES: LazyLock = LazyLock::new(|| { +------------+ | degrees(0) | +------------+ -| 0.0 | +| 180.0 | +------------+ ```"#, ) From a3f3d0bf051f7e27dfd959f4c533f3ddc69f44a1 Mon Sep 17 00:00:00 2001 From: aditya singh rathore <142787780+Adez017@users.noreply.github.com> Date: Mon, 15 Sep 2025 08:26:56 +0530 Subject: [PATCH 7/9] Update datafusion/functions/src/math/monotonicity.rs Co-authored-by: Jeffrey Vo --- datafusion/functions/src/math/monotonicity.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/datafusion/functions/src/math/monotonicity.rs b/datafusion/functions/src/math/monotonicity.rs index f7c257324911..dd0969a3622f 100644 --- a/datafusion/functions/src/math/monotonicity.rs +++ b/datafusion/functions/src/math/monotonicity.rs @@ -654,7 +654,7 @@ static DOCUMENTATION_SIN: LazyLock = LazyLock::new(|| { +----------+ | sin(0) | +----------+ -| 1.0 | +| 0.0 | +----------+ ```"#, ) From e5aa4b5035577c7c8949b5d1736eda3de1862d53 Mon Sep 17 00:00:00 2001 From: aditya singh rathore <142787780+Adez017@users.noreply.github.com> Date: Mon, 15 Sep 2025 08:28:48 +0530 Subject: [PATCH 8/9] Update datafusion/functions/src/math/nans.rs Co-authored-by: Jeffrey Vo --- datafusion/functions/src/math/nans.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/datafusion/functions/src/math/nans.rs b/datafusion/functions/src/math/nans.rs index 65f01fc02fee..759b0f5fd50a 100644 --- a/datafusion/functions/src/math/nans.rs +++ b/datafusion/functions/src/math/nans.rs @@ -36,7 +36,7 @@ use std::sync::Arc; +----------+ | isnan(1) | +----------+ -| true | +| false | +----------+ ```"#, standard_argument(name = "numeric_expression", prefix = "Numeric") From 232297071be2ad84037b0a6a0ae17248584f6602 Mon Sep 17 00:00:00 2001 From: aditya singh rathore <142787780+Adez017@users.noreply.github.com> Date: Mon, 15 Sep 2025 08:29:00 +0530 Subject: [PATCH 9/9] Update datafusion/functions/src/math/nanvl.rs Co-authored-by: Jeffrey Vo --- datafusion/functions/src/math/nanvl.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/datafusion/functions/src/math/nanvl.rs b/datafusion/functions/src/math/nanvl.rs index 4a6b1b88612b..f0835b4d48a0 100644 --- a/datafusion/functions/src/math/nanvl.rs +++ b/datafusion/functions/src/math/nanvl.rs @@ -37,11 +37,11 @@ use datafusion_macros::user_doc; Returns the second argument otherwise."#, syntax_example = "nanvl(expression_x, expression_y)", sql_example = r#"```sql -> SELECT nanvl( 0, 5); +> SELECT nanvl(0, 5); +------------+ | nanvl(0,5) | +------------+ -| 5 | +| 0 | +------------+ ```"#, argument(