diff --git a/content/en/docs/refguide/modeling/domain-model/oql/_index.md b/content/en/docs/refguide/modeling/domain-model/oql/_index.md index 15b0cc0336c..e3cd84536cc 100644 --- a/content/en/docs/refguide/modeling/domain-model/oql/_index.md +++ b/content/en/docs/refguide/modeling/domain-model/oql/_index.md @@ -43,6 +43,7 @@ OQL is under constant development so some expressions and features are not avail | Feature | Mendix Version | | --- | --- | | DATEADD | 11.9.0 | +| DATEFORMAT | 11.12.0 | | DATEPARSE | 11.10.0 | | DATETRUNC | 11.9.0 | | LOCATE | 11.9.0 | diff --git a/content/en/docs/refguide/modeling/domain-model/oql/oql-expression-syntax.md b/content/en/docs/refguide/modeling/domain-model/oql/oql-expression-syntax.md index afce4e213a1..ac824565646 100644 --- a/content/en/docs/refguide/modeling/domain-model/oql/oql-expression-syntax.md +++ b/content/en/docs/refguide/modeling/domain-model/oql/oql-expression-syntax.md @@ -1022,6 +1022,57 @@ SELECT Revenue : DATEDIFF(MONTH, End, Start ) as avg_revenue FROM Sales.Period The way the difference is calculated depends on the database. The `YEAR` difference between "2002-01-01" and "2001-12-31" will be `1` with some databases and `0` with others. {{% /alert %}} +### DATEFORMAT {#dateformat-function} + +The `DATEFORMAT` function formats values of type Date and time as strings using a specified pattern. + +This function was introduced in Mendix version 11.12.0. + +#### Syntax + +The syntax is as follows: + +```sql +DATEFORMAT ( expression , pattern ) +``` + +`expression` is a value of type Date and time. + +`pattern` is a pattern used to convert `expression` to a string value. Only string literals are allowed. + +#### Pattern Syntax + +The `DATEFORMAT` OQL function uses the same pattern syntax as date parsing functions in Studio Pro, see [Parse and Format Date Function Calls](/refguide/parse-and-format-date-function-calls/). + +#### Limitations and Database-Specific Differences + +When an OQL query is executed, `DATEFORMAT` is converted to the corresponding database function. Due to implementation specifics of database engines, different limitations apply: + +1. Format letters `u`, `F`, `G`, `k`, `K` are not supported. +2. SQL Server does not support format letters `D`, `Y`, `w`, `W`. +3. MySQL and MariaDB do not support format letters `S` and `W`. +4. SAP HANA does not support format letters `Y` and `w`. +5. Format letter `h` results in different values per database: + + 1. HSQLDB uses zero-based indexing and returns values `0` to `11` + 2. Other databases use one-based indexing and return values `1` to `12` + +6. In addition to listed limitations, there are other implementation differences between database engines. + +{{% alert color="warning" %}} +Always test usages of `DATEFORMAT` with the database engine on which your app runs. OQL queries with `DATEFORMAT` may return different results in HSQLDB and in the production database. +{{% /alert %}} + +#### Examples{#oql-dateformat-example} + +Let's assume that an object has an attribute `StartDate` of type Date and time with value `30 December 2025 13:02:15.300`. + +| Function call | Result | Notes | +|--------------|------|-----| +| `DATEFORMAT(StartDate, 'dd MMM yyyy')` | 30 Dec 2025 | | +| `DATEFORMAT(StartDate, 'yyyy-MM-dd hh:mm:ss a')` | 2025-12-30 01:02:15 PM | | +| `DATEFORMAT(StartDate, 'EEE-ww-YYYY')` | Tue-01-2026 | ISO date format is not supported by SAP HANA and SQL Server. `w` stands for the ISO week number, and `Y` stands for ISO year. | + ### DATEPARSE {#dateparse-function} The `DATEPARSE` function parses string values to Date and time using a specified pattern. @@ -1050,6 +1101,7 @@ When an OQL query is executed, `DATEPARSE` is converted to the corresponding dat 1. Format letters `u`, `F`, `G`, `k`, `K` are not supported. 2. MySQL and MariaDB do not support format letters `S` and `W`. +2. SAP HANA does not support format letters `Y` and `w`. 3. For SQL Server, `DATEPARSE` accepts only patterns that match SQL Server styles 0 to 7, 9 to 13, 100 to 107, 109 to 113, 120 and 121. See [SQL Server documentation](https://learn.microsoft.com/en-us/sql/t-sql/functions/cast-and-convert-transact-sql?view=sql-server-ver17#date-and-time-styles) for the list of supported styles. 4. Format letter `h` accepts different ranges of values per database: