From 8e222c143578dabd1f257df4ab629404200488bc Mon Sep 17 00:00:00 2001 From: Pavel Antoshin Date: Tue, 26 May 2026 14:16:43 +0200 Subject: [PATCH] Create documentation for DATEFORMAT --- .../modeling/domain-model/oql/_index.md | 1 + .../domain-model/oql/oql-expression-syntax.md | 61 ++++++++++++++++++- 2 files changed, 60 insertions(+), 2 deletions(-) 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..eb4494cb925 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,60 @@ 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 and parameters 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 minor implementation differences between database engines such as: + + 1. Casing (`SUN 3:12 PM` in PostgreSQL, `Sun 3:12 PM` in SQL Server and `Sun 3:12 pm` in HSQLDB) + 2. Year formatting (`YY` is formatted as `2026` in MySQL, as `26` in HSQLDB and PostgreSQL, and is not supported at all in SQL Server and SAP HANA). + +{{% 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. @@ -1038,7 +1092,7 @@ DATEPARSE ( expression , pattern ) `expression` is a value of type String. -`pattern` is a pattern used to convert `expression` to a Date and time value. Only string literals are allowed. +`pattern` is a pattern used to convert `expression` to a Date and time value. Only string literals and parameters are allowed. #### Pattern Syntax @@ -1050,13 +1104,16 @@ 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: 1. HSQLDB uses zero-based indexing and accepts values `0` to `11` 2. Other databases use one-based indexing and accept values `1` to `12` -5. In addition to listed limitations, there are other implementation differences between database engines. +5. The date format should contain enough information to derive the date. For example, `dd/yyyy` is not allowed, but `dd/MM/yyyy` is allowed. +6. If the format contains a unit of time, all units of time of greater magnitude should also be included. For example, `dd/MM/yyyy mm` is not allowed, but `dd/MM/yyyy HH:mm` is allowed. +6. In addition to listed limitations, there are other implementation differences between database engines related to corner cases such as format strings where the same information is included more than once (for example, if the format string contains both `YYYY` and `yyyy`) or format strings where there is enough information to derive the date, but that information is not of the usual format (`DATEPARSE('365/12/13', 'DD/MM/yy')` would lead to an exception in SAP HANA). {{% alert color="warning" %}} Always test usages of `DATEPARSE` with the database engine on which your app runs. OQL queries with `DATEPARSE` may return different results in HSQLDB and in the production database.