diff --git a/crates/polars-sql/src/functions.rs b/crates/polars-sql/src/functions.rs index 5822aa8086bf..c605271b9f4e 100644 --- a/crates/polars-sql/src/functions.rs +++ b/crates/polars-sql/src/functions.rs @@ -23,186 +23,236 @@ pub(crate) enum PolarsSqlFunctions { // Math functions // ---- /// SQL 'abs' function + /// Returns the absolute value of the input column /// ```sql /// SELECT ABS(column_1) from df; /// ``` Abs, /// SQL 'cos' function + /// Compute the cosine sine of the input column (in radians) /// ```sql /// SELECT COS(column_1) from df; /// ``` Cos, /// SQL 'cot' function + /// Compute the cotangent of the input column (in radians) /// ```sql /// SELECT COT(column_1) from df; /// ``` Cot, /// SQL 'sin' function + /// Compute the sine of the input column (in radians) /// ```sql /// SELECT SIN(column_1) from df; /// ``` Sin, /// SQL 'tan' function + /// Compute the tangent of the input column (in radians) /// ```sql /// SELECT TAN(column_1) from df; /// ``` Tan, /// SQL 'cosd' function + /// Compute the cosine sine of the input column (in degrees) /// ```sql /// SELECT COSD(column_1) from df; /// ``` CosD, /// SQL 'cotd' function + /// Compute cotangent of the input column (in degrees) /// ```sql /// SELECT COTD(column_1) from df; /// ``` CotD, /// SQL 'sind' function + /// Compute the sine of the input column (in degrees) /// ```sql /// SELECT SIND(column_1) from df; /// ``` SinD, /// SQL 'tand' function + /// Compute the tangent of the input column (in degrees) /// ```sql /// SELECT TAND(column_1) from df; /// ``` TanD, /// SQL 'acos' function + /// Compute inverse cosinus of the input column (in radians) /// ```sql /// SELECT ACOS(column_1) from df; /// ``` Acos, /// SQL 'asin' function + /// Compute inverse sine of the input column (in radians) /// ```sql /// SELECT ASIN(column_1) from df; /// ``` Asin, /// SQL 'atan' function + /// Compute inverse tangent of the input column (in radians) /// ```sql /// SELECT ATAN(column_1) from df; /// ``` Atan, /// SQL 'atan2' function + /// Compute the inverse tangent of column_2/column_1 (in radians). /// ```sql - /// SELECT ATAN2(column_1) from df; + /// SELECT ATAN2(column_1, column_2) from df; /// ``` Atan2, /// SQL 'acosd' function + /// Compute inverse cosinus of the input column (in degrees) /// ```sql /// SELECT ACOSD(column_1) from df; /// ``` AcosD, /// SQL 'asind' function + /// Compute inverse sine of the input column (in degrees) /// ```sql /// SELECT ASIND(column_1) from df; /// ``` AsinD, /// SQL 'atand' function + /// Compute inverse tangent of the input column (in degrees) /// ```sql /// SELECT ATAND(column_1) from df; /// ``` AtanD, /// SQL 'atan2d' function + /// Compute the inverse tangent of column_2/column_1 (in degrees). /// ```sql /// SELECT ATAN2D(column_1) from df; /// ``` Atan2D, /// SQL 'ceil' function + /// Returns the nearest integer closest from zero. /// ```sql /// SELECT CEIL(column_1) from df; /// ``` Ceil, /// SQL 'exp' function + /// Computes the exponential of the given value. /// ```sql /// SELECT EXP(column_1) from df; /// ``` Exp, /// SQL 'floor' function + /// Returns the nearest integer away from zero. + /// 0.5 will be rounded /// ```sql /// SELECT FLOOR(column_1) from df; /// ``` Floor, /// SQL 'pi' function + /// Returns a (very good) approximation of 𝜋 /// ```sql /// SELECT PI() from df; /// ``` Pi, /// SQL 'ln' function + /// Computes the natural logarithm of the given value /// ```sql /// SELECT LN(column_1) from df; /// ``` Ln, /// SQL 'log2' function + /// Computes the logarithm of the given value in base 2 /// ```sql /// SELECT LOG2(column_1) from df; /// ``` Log2, /// SQL 'log10' function + /// Computes the logarithm of the given value in base 10 /// ```sql /// SELECT LOG10(column_1) from df; /// ``` Log10, /// SQL 'log' function + /// Computes the `base` logarithm of the given value /// ```sql /// SELECT LOG(column_1, 10) from df; /// ``` Log, /// SQL 'log1p' function + /// Computes the natural logarithm of the “given value plus one” /// ```sql /// SELECT LOG1P(column_1) from df; /// ``` Log1p, /// SQL 'pow' function + /// Returns the value to the power of `exponent` /// ```sql /// SELECT POW(column_1, 2) from df; /// ``` Pow, /// SQL 'sqrt' function + /// Returns the square root (√) of a number /// ```sql /// SELECT SQRT(column_1) from df; /// ``` Sqrt, /// SQL 'cbrt' function + /// Returns the cube root (∛) of a number /// ```sql /// SELECT CBRT(column_1) from df; /// ``` Cbrt, /// SQL 'round' function + /// Round a number to `x` decimals (default: 0) away from zero. + /// .5 is rounded away from zero. /// ```sql /// SELECT ROUND(column_1, 3) from df; /// ``` Round, + /// SQL 'degrees' function + /// Convert between radians and degrees + /// ```sql + /// SELECT DEGREES(column_1) from df; + /// ``` + Degrees, + /// SQL 'RADIANS' function + /// Convert between degrees and radians + /// ```sql + /// SELECT radians(column_1) from df; + /// ``` + Radians, // ---- // String functions // ---- /// SQL 'ends_with' function + /// Returns True if the value ends with the second argument. /// ```sql /// SELECT ENDS_WITH(column_1, 'a') from df; /// SELECT column_2 from df WHERE ENDS_WITH(column_1, 'a'); /// ``` EndsWith, /// SQL 'initcap' function + /// Returns the value with the first letter capitalized /// ```sql /// SELECT INITCAP(column_1) from df; /// ``` InitCap, /// SQL 'left' function + /// Returns the `length` first characters /// ```sql /// SELECT LEFT(column_1, 3) from df; /// ``` Left, /// SQL 'length' function (characters) + /// Returns the character length of the string /// ```sql /// SELECT LENGTH(column_1) from df; /// ``` Length, /// SQL 'lower' function + /// Returns an lowercased column /// ```sql /// SELECT LOWER(column_1) from df; /// ``` Lower, /// SQL 'ltrim' function + /// Strip whitespaces from the left /// ```sql /// SELECT LTRIM(column_1) from df; /// ``` @@ -213,37 +263,45 @@ pub(crate) enum PolarsSqlFunctions { /// ``` OctetLength, /// SQL 'regexp_like' function + /// True if `pattern` matches the value (optional: `flags`). /// ```sql - /// SELECT REGEXP_LIKE(column_1,'xyz', 'i') from df; + /// SELECT REGEXP_LIKE(column_1, 'xyz', 'i') from df; /// ``` RegexpLike, /// SQL 'rtrim' function + /// Strip whitespaces from the right /// ```sql /// SELECT RTRIM(column_1) from df; /// ``` RTrim, /// SQL 'starts_with' function + /// Returns True if the value starts with the second argument. /// ```sql /// SELECT STARTS_WITH(column_1, 'a') from df; /// SELECT column_2 from df WHERE STARTS_WITH(column_1, 'a'); /// ``` StartsWith, /// SQL 'substr' function + /// Returns a portion of the data (first character = 0) in the range + /// \[start, start + length] /// ```sql /// SELECT SUBSTR(column_1, 3, 5) from df; /// ``` Substring, /// SQL 'upper' function + /// Returns an uppercased column /// ```sql /// SELECT UPPER(column_1) from df; /// ``` Upper, /// SQL 'nullif' function + /// Returns NULL if two expressions are equal, otherwise returns the first /// ```sql /// SELECT NULLIF(column_1, column_2) from df; /// ``` NullIf, /// SQL 'coalesce' function + /// Returns the first non-null value in the provided values/columns /// ```sql /// SELECT COALESCE(column_1, ...) from df; /// ``` @@ -253,6 +311,7 @@ pub(crate) enum PolarsSqlFunctions { // Aggregate functions // ---- /// SQL 'count' function + /// Returns the amount of elements in the grouping /// ```sql /// SELECT COUNT(column_1) from df; /// SELECT COUNT(*) from df; @@ -261,41 +320,49 @@ pub(crate) enum PolarsSqlFunctions { /// ``` Count, /// SQL 'sum' function + /// Returns the sum of all the elements in the grouping /// ```sql /// SELECT SUM(column_1) from df; /// ``` Sum, /// SQL 'min' function + /// Returns the smallest (minimum) of all the elements in the grouping /// ```sql /// SELECT MIN(column_1) from df; /// ``` Min, /// SQL 'max' function + /// Returns the greatest (maximum) of all the elements in the grouping /// ```sql /// SELECT MAX(column_1) from df; /// ``` Max, /// SQL 'avg' function + /// Returns the average (mean) of all the elements in the grouping /// ```sql /// SELECT AVG(column_1) from df; /// ``` Avg, /// SQL 'stddev' function + /// Returns the standard deviation of all the elements in the grouping /// ```sql /// SELECT STDDEV(column_1) from df; /// ``` StdDev, /// SQL 'variance' function + /// Returns the variance of all the elements in the grouping /// ```sql /// SELECT VARIANCE(column_1) from df; /// ``` Variance, /// SQL 'first' function + /// Returns the first element of the grouping /// ```sql /// SELECT FIRST(column_1) from df; /// ``` First, /// SQL 'last' function + /// Returns the last element of the grouping /// ```sql /// SELECT LAST(column_1) from df; /// ``` @@ -305,20 +372,11 @@ pub(crate) enum PolarsSqlFunctions { // Array functions // ---- /// SQL 'array_length' function + /// Returns the length of the array /// ```sql /// SELECT ARRAY_LENGTH(column_1) from df; /// ``` ArrayLength, - /// SQL 'degrees' function - /// ```sql - /// SELECT DEGREES(column_1) from df; - /// ``` - Degrees, - /// SQL 'RADIANS' function - /// ```sql - /// SELECT radians(column_1) from df; - /// ``` - Radians, /// SQL 'array_lower' function /// Returns the minimum value in an array; equivalent to `array_min` /// ```sql @@ -356,12 +414,13 @@ pub(crate) enum PolarsSqlFunctions { /// ``` ArrayUnique, /// SQL 'unnest' function - /// unnest/explods an array column into multiple rows + /// Unnest/explodes an array column into multiple rows /// ```sql /// SELECT unnest(column_1) from df; /// ``` Explode, /// SQL 'array_to_string' function + /// Takes all elements of the array and joins them into one string /// ```sql /// SELECT ARRAY_TO_STRING(column_1, ', ') from df; /// ```