From 8e222c143578dabd1f257df4ab629404200488bc Mon Sep 17 00:00:00 2001 From: Pavel Antoshin Date: Tue, 26 May 2026 14:16:43 +0200 Subject: [PATCH 1/3] 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. From 9f573e32a0c88b0737f7774fb158b81188be1975 Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Thu, 4 Jun 2026 15:48:59 +0200 Subject: [PATCH 2/3] Note that there are differences --- .../en/docs/refguide/modeling/domain-model/oql/_index.md | 2 +- .../modeling/domain-model/oql/oql-expression-syntax.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 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 62c8219020b..e84167c366f 100644 --- a/content/en/docs/refguide/modeling/domain-model/oql/_index.md +++ b/content/en/docs/refguide/modeling/domain-model/oql/_index.md @@ -66,7 +66,7 @@ The following are bulk update features. | OQL `INSERT` associations *beta* | 11.7.0 | | OQL bulk update *GA* | 11.8.0 | -## Syntax basics +## Syntax Basics An OQL statement consists of [keywords](#reserved-oql-words), identifiers, [value literals](/refguide/oql-expression-syntax/#oql-literals) and [operators](/refguide/oql-expression-syntax/#oql-operators). 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 1ec24027f32..89a8c4a87a3 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 @@ -1045,7 +1045,7 @@ DATEFORMAT ( expression , pattern ) #### 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/). +The `DATEFORMAT` OQL function uses the same pattern syntax, with the differences noted below, as date parsing functions in Studio Pro. See [Parse and Format Date Function Calls](/refguide/parse-and-format-date-function-calls/) for more information. #### Limitations and Database-Specific Differences @@ -1062,8 +1062,8 @@ When an OQL query is executed, `DATEFORMAT` is converted to the corresponding da 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). + 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. @@ -1099,7 +1099,7 @@ DATEPARSE ( expression , pattern ) #### Pattern Syntax -The `DATEPARSE` 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/). +The `DATEPARSE` OQL function uses the same pattern syntax, with the differences noted below, as date parsing functions in Studio Pro. See [Parse and Format Date Function Calls](/refguide/parse-and-format-date-function-calls/) for more information. #### Limitations and Database-Specific Differences From 95fd1c2a4b7a76d98e11290347ede755a5600e87 Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Thu, 4 Jun 2026 15:58:39 +0200 Subject: [PATCH 3/3] Correct list numbering and other markdown issues. --- .../domain-model/oql/oql-expression-syntax.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) 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 89a8c4a87a3..d4d25d7f714 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 @@ -1107,16 +1107,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: +3. SAP HANA does not support format letters `Y` and `w`. +4. 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. +5. 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. 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). +6. The date format should contain enough information to derive the date. For example, `dd/yyyy` is not allowed, but `dd/MM/yyyy` is allowed. +7. 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. +8. 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.