diff --git a/web/book/src/SUMMARY.md b/web/book/src/SUMMARY.md index 5781c96c74e4..7b8aa90c36dc 100644 --- a/web/book/src/SUMMARY.md +++ b/web/book/src/SUMMARY.md @@ -33,8 +33,6 @@ - [Ranges](./reference/syntax/ranges.md) - [Comments](./reference/syntax/comments.md) - [Parameters](./reference/syntax/parameters.md) - - [Date & time](./reference/syntax/date-time/index.md) - - [Format specifiers](./reference/syntax/date-time/format-specifiers.md) - [Declarations]() @@ -60,6 +58,9 @@ - [Window](./reference/stdlib/transforms/window.md) - [Aggregation functions]() + - [Date functions](./reference/stdlib/date.md) + - [Mathematical functions](./reference/stdlib/math.md) + - [Text functions](./reference/stdlib/string.md) - [Specification](./reference/spec/README.md) diff --git a/web/book/src/reference/syntax/date-time/format-specifiers.md b/web/book/src/reference/stdlib/date.md similarity index 82% rename from web/book/src/reference/syntax/date-time/format-specifiers.md rename to web/book/src/reference/stdlib/date.md index 0c75036ecba0..055473d8e5c3 100644 --- a/web/book/src/reference/syntax/date-time/format-specifiers.md +++ b/web/book/src/reference/stdlib/date.md @@ -1,4 +1,50 @@ -# Date & time format specifiers +# Date functions + +These are all the functions defined in the `date` module: + +### `to_text` + +Converts a date into a text.\ +Since there are many possible date representations, `to_text` takes a `format` parameter +that describes thanks to [specifiers](#date--time-format-specifiers) how the date +or timestamp should be structured. + +```admonish info +Since all RDBMS have different ways to format dates and times, PRQL **requires an explicit dialect** to be specified +``` + +```admonish info +For now the supported DBs are: Clickhouse, DuckDB, MySQL, MSSQL and Postgres. +``` + +```prql +prql target:sql.duckdb + +from invoices +select { + invoice_date | date.to_text "%d/%m/%Y" +} +``` + +```prql +prql target:sql.postgres + +from invoices +select { + invoice_date | date.to_text "%d/%m/%Y" +} +``` + +```prql +prql target:sql.mysql + +from invoices +select { + invoice_date | date.to_text "%d/%m/%Y" +} +``` + +### Date & time format specifiers PRQL specifiers for date and time formatting is a subset of specifiers used by [`chrono`](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). diff --git a/web/book/src/reference/stdlib/math.md b/web/book/src/reference/stdlib/math.md new file mode 100644 index 000000000000..857dc7afde4a --- /dev/null +++ b/web/book/src/reference/stdlib/math.md @@ -0,0 +1,34 @@ +# Mathematical functions + +These are all the functions defined in the `math` module: + +| function | parameters | description | +| -------- | ---------- | ---------------------------------- | +| abs | `col` | Absolute value of `col` | +| acos | `col` | Arccosine of `col` | +| asin | `col` | Arcsine of `col` | +| atan | `col` | Arctangent of `col` | +| ceil | `col` | Rounds the number up of `col` | +| cos | `col` | Cosine of `col` | +| degrees | `col` | Converts radians to degrees | +| exp | `col` | Exponential of `col` | +| floor | `col` | Rounds the number down | +| ln | `col` | Natural logarithm of `col` | +| log | `b` `col` | `b`-log of `col` | +| log10 | `col` | 10-log of `col` | +| pi | | The constant π | +| pow | `b` `col` | Computes `col` to the power `b` | +| radians | `col` | Converts degrees to radians | +| round | `n` `col` | Rounds `col` to `n` decimal places | +| sin | `col` | Sin of `col` | +| sqrt | `col` | Square root of `col` | +| tan | `col` | Tangent of `col` | + +### Example + +```prql +from employees +select { + age_squared = age | math.pow 2 +} +``` diff --git a/web/book/src/reference/stdlib/string.md b/web/book/src/reference/stdlib/string.md new file mode 100644 index 000000000000..82023bceb8d1 --- /dev/null +++ b/web/book/src/reference/stdlib/string.md @@ -0,0 +1,27 @@ +# Text functions + +These are all the functions defined in the `string` module: + +| function | parameters | description | +| ----------- | ---------------------- | ----------------------------------------------------------------------------- | +| contains | `text` `col` | Returns true if `col` contains `text` | +| ends_with | `text` `col` | Returns true if `col` ends with `text` | +| length | `col` | Returns the number of characters in `col` | +| lower | `col` | Converts `col` to lower case | +| ltrim | `col` | Removes all the whitespaces from the left side of `col` | +| replace | `before` `after` `col` | Replaces any occurrences of `before` with `after` in `col` | +| rtrim | `col` | Removes all the whitespaces from the right side of `col` | +| starts_with | `text` `col` | Returns true if `col` starts with `text` | +| substring | `idx` `len` `col` | Extracts a substring at the index `idx` (starting at 1) with the length `len` | +| trim | `col` | Removes all the whitespaces from both sides of `col` | +| upper | `col` | Converts `col` to upper case | + +### Example + +```prql +from employees +select { + last_name | string.lower | string.starts_with("a"), + title | string.replace "manager" "chief" +} +``` diff --git a/web/book/src/reference/syntax/date-time/index.md b/web/book/src/reference/syntax/date-time/index.md deleted file mode 100644 index ac131645b42f..000000000000 --- a/web/book/src/reference/syntax/date-time/index.md +++ /dev/null @@ -1,46 +0,0 @@ -# Date and time - -We already know that PRQL uses the `@2020-01-01` syntax to declare dates. To -manipulate those dates, PRQL has a `date` module with some useful functions - -### `to_text` - -This function allows to convert a date into a text. Since there are many -possible date representations, `to_text` takes a `format` parameter that -describes thanks to [specifiers](./format-specifiers.md) how the date or -timestamp should be structured. - -```admonish info -Since all RDBMS have different ways to format dates and times, PRQL **requires an explicit dialect** to be specified -``` - -```admonish info -For now the supported DBs are: Clickhouse, DuckDB, MySQL, MSSQL and Postgres. -``` - -```prql -prql target:sql.duckdb - -from invoices -select { - invoice_date | date.to_text "%d/%m/%Y" -} -``` - -```prql -prql target:sql.postgres - -from invoices -select { - invoice_date | date.to_text "%d/%m/%Y" -} -``` - -```prql -prql target:sql.mysql - -from invoices -select { - invoice_date | date.to_text "%d/%m/%Y" -} -``` diff --git a/web/book/tests/documentation/snapshots/documentation__book__reference__syntax__date-time__index__date-and-time__0.snap b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__date__date-functions__0.snap similarity index 100% rename from web/book/tests/documentation/snapshots/documentation__book__reference__syntax__date-time__index__date-and-time__0.snap rename to web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__date__date-functions__0.snap diff --git a/web/book/tests/documentation/snapshots/documentation__book__reference__syntax__date-time__index__date-and-time__1.snap b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__date__date-functions__1.snap similarity index 100% rename from web/book/tests/documentation/snapshots/documentation__book__reference__syntax__date-time__index__date-and-time__1.snap rename to web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__date__date-functions__1.snap diff --git a/web/book/tests/documentation/snapshots/documentation__book__reference__syntax__date-time__index__date-and-time__2.snap b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__date__date-functions__2.snap similarity index 100% rename from web/book/tests/documentation/snapshots/documentation__book__reference__syntax__date-time__index__date-and-time__2.snap rename to web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__date__date-functions__2.snap diff --git a/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__math__example__0.snap b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__math__example__0.snap new file mode 100644 index 000000000000..d0b1753c2a30 --- /dev/null +++ b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__math__example__0.snap @@ -0,0 +1,9 @@ +--- +source: web/book/tests/documentation/book.rs +expression: "from employees\nselect {\n age_squared = age | math.pow 2\n}\n" +--- +SELECT + POW(age, 2) AS age_squared +FROM + employees + diff --git a/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__string__example__0.snap b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__string__example__0.snap new file mode 100644 index 000000000000..cb07fe7eca57 --- /dev/null +++ b/web/book/tests/documentation/snapshots/documentation__book__reference__stdlib__string__example__0.snap @@ -0,0 +1,10 @@ +--- +source: web/book/tests/documentation/book.rs +expression: "from employees\nselect {\n last_name | string.lower | string.starts_with(\"a\"),\n title | string.replace \"manager\" \"chief\"\n}\n" +--- +SELECT + LOWER(last_name) LIKE CONCAT('a', '%'), + REPLACE(title, 'manager', 'chief') +FROM + employees +