From 3fe4001f3890a750d073b7bd5b5f87793b1a05b2 Mon Sep 17 00:00:00 2001
From: Augusto Passalacqua <Augusto.Passalacqua@mendix.com>
Date: Wed, 15 Jul 2026 15:33:05 +0200
Subject: [PATCH 1/2] Document new OQL feature: INSERT ... `VALUES`

---
 .../domain-model/oql/oql-statements.md        | 33 +++++++++++++++++--
 1 file changed, 30 insertions(+), 3 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 f35d0ddb5c8..25869a3e76f 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
@@ -157,13 +157,16 @@ SET
 ## `INSERT` Statement {#oql-insert}
 
 {{% alert color="info" %}}
-Available from Mendix version 11.6.0
+Available from Mendix version 11.6.0 when sourcing data from an oql query.
+Available from Mendix version 11.13.0 when using `VALUES` to specify rows directly.
 {{% /alert %}}
 
-The syntax of `INSERT` statements is:
+`INSERT` statements can be written with values or queries.
+
+### `INSERT` with query
 
 ```sql
-INSERT INTO <entity> ( <attribute | <association> [ , …n ] ) <oql-query>
+INSERT INTO <entity> ( <attribute> | <association> [ , …n ] ) <oql-query>
 ```
 
 * `entity` is the entity for which new objects will be created.
@@ -182,6 +185,30 @@ INSERT INTO Module.Order ( OrderNumber, CustomerNumber, Module.Order_Customer )
 SELECT NewOrderNumber, Loader.TemporaryData_Customer/Loader.Customer/Number, Loader.TemporaryData_Customer FROM Loader.TemporaryData
 ```
 
+### `INSERT` with `VALUES`
+
+```sql
+INSERT INTO <entity> ( <attribute> [ , …n ] ) VALUES (<expression 1> [, …<expression n>]) [ …, (<expression 1> [, …<expression n>])]
+```
+
+* `entity` is the entity for which new objects will be created.
+
+* `attribute` is an attribute of the entity that will be inserted.
+
+* `expression n` is any valid OQL expression with literals or OQL parameters.
+Every row must contain the same number of values of compatible types.
+This query can *not* select data from any entities.
+
+Example:
+
+```sql
+INSERT INTO Module.Person ( Name, BirthDate )
+VALUES
+    ( 'Person A', DATEPARSE('01 Jan 1970', 'dd MMM yyyy') ),
+    ( 'Person B', DATEPARSE('20 Mar 1990', 'dd MMM yyyy') ),
+    ( 'Person C', DATEPARSE('14 Jul 1988', 'dd MMM yyyy') )
+```
+
 ### OQL `INSERT` Limitations
 
 * Only a single value can be specified per association.

From ced3bb17a0e438e01bf8608ed14d71ef0bed0b35 Mon Sep 17 00:00:00 2001
From: Augusto Passalacqua <Augusto.Passalacqua@mendix.com>
Date: Thu, 16 Jul 2026 11:13:39 +0200
Subject: [PATCH 2/2] Applying review changes to the documentation of OQL
 INSERT

---
 .../domain-model/oql/oql-statements.md        | 26 +++++++++++++------
 1 file changed, 18 insertions(+), 8 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 25869a3e76f..8f88c9c6786 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
@@ -156,14 +156,20 @@ SET
 
 ## `INSERT` Statement {#oql-insert}
 
+You can use the `INSERT` statement to insert new entity objects into your data. You can do this in two ways:
+
+* using an OQL query – extracting data and use it to insert one or more new objects
+* using values – specifying explicit values and use these to insert one or more new objects
+
 {{% alert color="info" %}}
-Available from Mendix version 11.6.0 when sourcing data from an oql query.
-Available from Mendix version 11.13.0 when using `VALUES` to specify rows directly.
+Available from Mendix version 11.6.0.
+You can use an OQL query from Mendix version 11.6.0.
+You can use values from Mendix version 11.13.0.
 {{% /alert %}}
 
-`INSERT` statements can be written with values or queries.
+### `INSERT` with OQL Query
 
-### `INSERT` with query
+Insert with OQL query allows you to extract data using an OQL query and insert those values as one or more entity objects.
 
 ```sql
 INSERT INTO <entity> ( <attribute> | <association> [ , …n ] ) <oql-query>
@@ -185,7 +191,9 @@ INSERT INTO Module.Order ( OrderNumber, CustomerNumber, Module.Order_Customer )
 SELECT NewOrderNumber, Loader.TemporaryData_Customer/Loader.Customer/Number, Loader.TemporaryData_Customer FROM Loader.TemporaryData
 ```
 
-### `INSERT` with `VALUES`
+### `INSERT` with Values
+
+Insert with values allows you to insert a list of literals, OQL parameters, and OQL expressions as one or more entity objects.
 
 ```sql
 INSERT INTO <entity> ( <attribute> [ , …n ] ) VALUES (<expression 1> [, …<expression n>]) [ …, (<expression 1> [, …<expression n>])]
@@ -195,9 +203,11 @@ INSERT INTO <entity> ( <attribute> [ , …n ] ) VALUES (<expression 1> [, …<ex
 
 * `attribute` is an attribute of the entity that will be inserted.
 
-* `expression n` is any valid OQL expression with literals or OQL parameters.
-Every row must contain the same number of values of compatible types.
-This query can *not* select data from any entities.
+{{% alert color="info" %}}You cannot insert associations when inserting with values.{{% /alert %}}
+
+* `expression x` is any valid expression consisting solely of literals or OQL expressions. Every row must contain the same number of values of compatible types as the list of attributes you are inserting for each entity object.
+
+{{% alert color="info" %}}This expression cannot use OQL clauses to select data from any entities.{{% /alert %}}
 
 Example: