From b6b0d0294a0791689c6a2485d9ad4595a1756eaf Mon Sep 17 00:00:00 2001 From: Bas de Bakker Date: Tue, 16 Dec 2025 11:28:00 +0100 Subject: [PATCH 1/2] Add documentation on OQL INSERT statement --- .../domain-model/oql/oql-statements.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/content/en/docs/refguide/modeling/domain-model/oql/oql-statements.md b/content/en/docs/refguide/modeling/domain-model/oql/oql-statements.md index 776eab10e09..936b7c7c89b 100644 --- a/content/en/docs/refguide/modeling/domain-model/oql/oql-statements.md +++ b/content/en/docs/refguide/modeling/domain-model/oql/oql-statements.md @@ -23,6 +23,8 @@ From Mendix version 11.3, you can also update object attributes in bulk using OQ From Mendix version 11.4, you can update object associations as well as attributes in bulk using OQL `UPDATE` statements. +From Mendix version 11.6, you can insert new objects with attributes in bulk using OQL `INSERT` statements. + {{% /alert %}} ## Java API for OQL updates @@ -160,6 +162,36 @@ WHERE ID IN ( WHERE Module.Customer/Name = 'Mary' ) ``` +## `INSERT` Statement {#oql-insert} + +The syntax of `INSERT` statements is: + +```sql +INSERT INTO ( [ ,...n ] ) +``` + +`entity` is the entity for which new objects will be created. + +`attribute` is an attribute of the entity that will be inserted. + +`oql-query` is any OQL query that returns same number of columns as the number of attributes that will be inserted. +This query can select data from persistable entities and/or [view entities](/refguide/view-entities/). + +Example: + +```sql +INSERT INTO Module.Order ( OrderNumber, CustomerNumber ) +SELECT NewOrderNumber, Loader.TemporaryData_Customer/Loader.Customer/Number FROM Loader.TemporaryData +``` + +### OQL `INSERT` Limitations + +* It is not yet possible to insert associations. As a workaround, they can be added after the `INSERT` using an OQL `UPDATE` statement. +* Attributes of type "Date and time" with a default value of `'[%CurrentDateTime%]'` will not have their default values set when the `INSERT` statement does not specify them. + As a workaround, explicitly insert the attribute with a value of `'[%CurrentDatetime%]'` in the `SELECT` part. +* When using Oracle, due to database limitations, inserting attributes of type unlimited string or binary is not supported. +* The general limitations for OQL statements also apply. See [General Limitations for OQL Statements](#oql-limitations), below. + ## General Limitations for OQL Statements {#oql-limitations} * OQL statements can be used only with persistable entities. From b95cdd692e7ccd8f44b2b22763d70059a812e391 Mon Sep 17 00:00:00 2001 From: MarkvanMents Date: Fri, 19 Dec 2025 11:48:05 +0100 Subject: [PATCH 2/2] Proofread and clarify versions --- .../domain-model/oql/oql-statements.md | 91 ++++++++++++------- 1 file changed, 60 insertions(+), 31 deletions(-) diff --git a/content/en/docs/refguide/modeling/domain-model/oql/oql-statements.md b/content/en/docs/refguide/modeling/domain-model/oql/oql-statements.md index 936b7c7c89b..ffa89aeaed7 100644 --- a/content/en/docs/refguide/modeling/domain-model/oql/oql-statements.md +++ b/content/en/docs/refguide/modeling/domain-model/oql/oql-statements.md @@ -47,13 +47,18 @@ The `execute()` method returns the number of objects that were affected by the s ## `DELETE` Statement {#oql-delete} +{{% alert color="info" %}} +Available from Mendix version 11.1.0 +{{% /alert %}} + The syntax of `DELETE` statements is: ```sql DELETE FROM WHERE ``` -`condition` can be anything that can appear in an OQL [WHERE clause](/refguide/oql-clauses/#where). +* `entity` is the entity whose objects are being deleted. +* `condition` can be anything that can appear in an OQL [WHERE clause](/refguide/oql-clauses/#where). ### OQL `DELETE` Limitations @@ -63,21 +68,39 @@ DELETE FROM WHERE ## `UPDATE` Statement {#oql-update} +{{% alert color="info" %}} +Available from Mendix version 11.3.0 +{{% /alert %}} + The syntax of `UPDATE` statements is: ```sql UPDATE -SET { { | } = } [ ,...n ] +SET { { | } = } [ , …n ] WHERE ``` -`entity` is the entity whose objects are being updated. +* `entity` is the entity whose objects are being updated. + +* `attribute` is an attribute of the entity that is being updated. -`attribute` is an attribute of the entity that is being updated. `association` is an association that is being updated. Multiple attributes and associations can be updated in the same statement. An attribute of type `autonumber` can not be updated. The `ID` field of an entity cannot be updated. + An attribute of type `autonumber` can not be updated. The `ID` attribute of an entity cannot be updated. -`expression` is a new value of an attribute or association. Any [OQL expression](/refguide/oql-expressions/) is allowed. When updating attributes, the value type of the expression should match the attribute type according to [type coercion precedence](/refguide/oql-expression-syntax/#type-coercion). When updating an enumeration attribute using a literal, the literal must be a valid value for the enumeration. When updating an enumeration attribute using another enumeration, the expression enumeration must be a subset of the attribute enumeration. When updating a string attribute using a string literal, the literal length must be equal to or less than the length of the attribute. In the case of associations, association and entity expressions must match the target association type. Values of type LONG can also be used as association values, but they must be valid ids of associations which are of the target association type. +* `association` is an association that is being updated. Associations can be updated in Mendix version 11.4.0 and above. -`condition` can be anything that can appear in an OQL [WHERE clause](/refguide/oql-clauses/#where). + Multiple attributes and associations can be updated in the same statement. + +* `expression` is a new value of an attribute or association. Any [OQL expression](/refguide/oql-expressions/) is allowed. + + * When updating attributes, the value type of the expression should match the attribute type according to [type coercion precedence](/refguide/oql-expression-syntax/#type-coercion). + * When updating an enumeration attribute using a literal, the literal must be a valid value for the enumeration. + * When updating an enumeration attribute using another enumeration, the expression enumeration must be a subset of the attribute enumeration. + * When updating a string attribute using a string literal, the literal length must be equal to or less than the length of the attribute. + * In the case of associations, association and entity expressions must match the target association type. + + Values of type LONG can also be used as association values, but they must be valid ids of associations which are of the target association type. + +* `condition` can be anything that can appear in an OQL [WHERE clause](/refguide/oql-clauses/#where). Example: @@ -141,40 +164,23 @@ SET SpecializationAttribute = 1 ``` -## Joins - -You cannot directly join other entities in the `FROM` clause of OQL `DELETE` or in the `UPDATE` clause of OQL `UPDATE`. However, you can achieve the same result using long paths or subqueries. For example: - -```sql -DELETE FROM Module.Order -WHERE Module.Order_Customer/Module.Customer/Name = 'Mary' -``` - -or - -```sql -UPDATE Module.Order -SET CustomerName = 'Mary' -WHERE ID IN ( - SELECT ID - FROM Module.Order - INNER JOIN Module.Customer ON Module.Customer/CustomerID = Module.Order/CustomerID - WHERE Module.Customer/Name = 'Mary' ) -``` - ## `INSERT` Statement {#oql-insert} +{{% alert color="info" %}} +Available from Mendix version 11.6.0 +{{% /alert %}} + The syntax of `INSERT` statements is: ```sql -INSERT INTO ( [ ,...n ] ) +INSERT INTO ( [ , …n ] ) ``` -`entity` is the entity for which new objects will be created. +* `entity` is the entity for which new objects will be created. -`attribute` is an attribute of the entity that will be inserted. +* `attribute` is an attribute of the entity that will be inserted. -`oql-query` is any OQL query that returns same number of columns as the number of attributes that will be inserted. +* `oql-query` is any OQL query that returns same number of columns as the number of attributes that will be inserted. This query can select data from persistable entities and/or [view entities](/refguide/view-entities/). Example: @@ -198,3 +204,26 @@ SELECT NewOrderNumber, Loader.TemporaryData_Customer/Loader.Customer/Number FROM * Entity access rules are not applied to any OQL statements. * No event handlers will be executed. * Runtime and client state will not be updated with the changes. + +### Joins + +You cannot directly join other entities in the `FROM` clause of OQL `DELETE` or in the `UPDATE` clause of OQL `UPDATE`. However, you can achieve the same result using long paths or subqueries. For example: + +```sql +DELETE FROM Module.Order +WHERE Module.Order_Customer/Module.Customer/Name = 'Mary' +``` + +or + +```sql +UPDATE Module.Order +SET CustomerName = 'Mary' +WHERE ID IN ( + SELECT ID + FROM Module.Order + INNER JOIN Module.Customer ON Module.Customer/CustomerID = Module.Order/CustomerID + WHERE Module.Customer/Name = 'Mary' ) +``` + +