Merge pull request #11543 from passalaqua/dat/feature/insert-values

Document new OQL feature: INSERT ... `VALUES`

Author: ConnorLand

content/en/docs/refguide/modeling/domain-model/oql/oql-statements.md

@@ -156,14 +156,23 @@ 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
+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 %}}
 
-The syntax of `INSERT` statements is:
+### `INSERT` with OQL 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>
+INSERT INTO <entity> ( <attribute> | <association> [ , …n ] ) <oql-query>
 ```
 
 * `entity` is the entity for which new objects will be created.
@@ -182,6 +191,34 @@ 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 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>])]
+```
+
+* `entity` is the entity for which new objects will be created.
+
+* `attribute` is an attribute of the entity that will be inserted.
+
+{{% 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:
+
+```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.