Update CREATE statement documentation (#392)

Co-authored-by: Alexander <[email protected]>

versioned_docs/version-1.2.x/surrealql/statements/create.mdx

@@ -6,7 +6,7 @@ sidebar_position: 6
 
 # `CREATE` statement
 
-The CREATE statement can be used to add records to the database, if those records do not already exist.
+The `CREATE` statement can be used to add a record to the database. If the record already exists, the statement will give an error.
 
 :::note
 __Note:__ This statement can not be used to create graph relationships. For that, use the [`RELATE`](/docs/surrealdb/surrealql/statements/relate) statement.
@@ -25,58 +25,144 @@ CREATE [ ONLY ] @targets
 ;
 ```
 
-## Example usage
+## Creating a Table Record
 
-The following query shows example usage of this statement.
+When using the create statement the first word after `CREATE` is the table name. You also specify a record identifier using the `:` followed by a value. Ex. `CREATE Table:this`. The two together form the full [record ID](/docs/surrealdb/surrealql/datamodel/ids) which can be used to query the created data or by using the [`SELECT`](/docs/surrealdb/surrealql/statements/select) statement. See the [record ID](/docs/surrealdb/surrealql/datamodel/ids) page to learn more about what counts as a valid record identifier.  If no record identifier is specified, a random identifier will be generated.
+
+:::note
+__Note:__ You can also assign the recordID to be [randomly generated](/docs/surrealdb/surrealql/datamodel/ids#generating-record-ids) 
+:::
+
+The query below will create a new person table and also create a new record with a random ID.
 
 ```surql
--- Create a new record with a random id
-CREATE person SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];
+-- Create a new table
+CREATE person
+```
+
+```bash title="Response"
+[
+    {
+        "id": "person:2vvgzt6m24s952yiy7x8"
+    }
+]
+```
 
+Alternatively, you can specify the record identifier of the record you want to create.
+
+```surql
 -- Create a new record with a specific numeric id
-CREATE person:100 SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];
+CREATE person:100
+```
 
--- Create a new record with a specific string id
-CREATE person:tobie SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];
+The above will create a new record with the ID `person:100`.
 
--- Create just a single record
--- Using the ONLY keyword, just an object for the record in question will be returned.
--- This, instead of an array with a single object.
-CREATE ONLY person:tobie SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];
+```bash title="Response"
+[
+	{
+		"id": "person:100"
+	}
+]
 ```
 
-Instead of specifying record data using the `SET` clause, it is also possible to use the `CONTENT` keyword to specify the record data using a SurrealQL object.
+It is also possible to specify the ID of the record you want to create using a string or any of the supported formats for [record IDs](/docs/surrealdb/surrealql/datamodel/ids).
+
+
+
+## Adding Record Data
+
+When creating a record, you can specify the record data using the `SET` clause, or the `CONTENT` clause. The `SET` clause is used to specify the record data using a list of key-value pairs, while the `CONTENT` clause is used to specify the record data using a SurrealQL object. The `CONTENT` clause is useful when the record data is already in the form of a SurrealQL or JSON object.
 
 ```surql
 -- Create a new record with a random id
-CREATE person CONTENT {
-	name: 'Tobie',
-	company: 'SurrealDB',
-	skills: ['Rust', 'Go', 'JavaScript'],
-};
+CREATE person:100 SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];
+```
+
+The above will create a new record with the ID `person:100` and the specified data.
+
+```bash title="Response"
+[
+	{
+		"id": "person:100",
+		"name": "Tobie",
+		"company": "SurrealDB",
+		"skills": ["Rust", "Go", "JavaScript"]
+	}
+]
+```
 
--- Create a new record with a specific id
-CREATE person:tobie CONTENT {
+Alternatively, you can specify the record data using the `CONTENT` keyword.
+
+```surql
+-- Create a new record with a numeric id
+CREATE person:100 CONTENT {
 	name: 'Tobie',
 	company: 'SurrealDB',
 	skills: ['Rust', 'Go', 'JavaScript'],
 };
 ```
-By default, the create statement returns the record value once the changes have been made. To change the return value of each record, specify a `RETURN` clause, specifying either `NONE`, `BEFORE`, `AFTER`, `DIFF`, or a comma-separated list of specific fields to return.
+
+## Clasues and Options
+
+Using the `ONLY` clause after `CREATE` will return just the record object instead of the default, which returns the object inside of an array.
+
+```surql
+-- Create just a single record
+CREATE ONLY person:tobie SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];
+```
+### Return Values
+
+By default, the create statement returns the record once the changes have been made. To change what is returned, we can use the `RETURN` clause, specifying either `NONE`, `BEFORE`, `AFTER`, `DIFF`, or a comma-separated list of specific fields to return.
 
 ```surql
--- Don't return any result
 CREATE person SET age = 46, username = "john-smith" RETURN NONE;
+```
 
+```surql
 -- Return the changeset diff
 CREATE person SET age = 46, username = "john-smith" RETURN DIFF;
+```
 
+```surql
 -- Return the record before changes were applied
 CREATE person SET age = 46, username = "john-smith" RETURN BEFORE;
+```
 
--- Return the record after changes were applied (the default)
+```surql
+-- Return the record after changes were applied (the default) if any.
 CREATE person SET age = 46, username = "john-smith" RETURN AFTER;
+```
 
+```surql
 -- Return a specific field only from the updated records
 CREATE person SET age = 46, username = "john-smith", interests = ['skiing', 'music'] RETURN interests;
 ```
+
+### Timeout
+
+The `TIMEOUT` clause can be used to specify the maximum time the statement should take to execute. This is useful when you want more control. Such as controlling compute costs or making sure queries succeed or fail within tight latency boundaries to not have a big query queue forming.
+
+The value for `TIMEOUT` is specified in Second or milliseconds.
+
+```surql
+CREATE person:25 SET age = 46, username = "john-smith" TIMEOUT 1000ms;
+```
+
+### Parallel
+
+The `PARALLEL` keyword can be used to specify that the statement should be executed in parallel. Similar to the `TIMEOUT` clause this is useful for more control over how your queries should behave, if that is needed.
+
+```surql
+CREATE person:26, CREATE person:27 PARALLEL; 
+```
+
+## Learn more 
+
+To learn more about SurrealDB, check out the following resources: 
+- [Getting started guide](/docs/surrealdb/introduction/start)
+- [Select statement](/docs/surrealdb/surrealql/statements/select)
+- [Update statement](/docs/surrealdb/surrealql/statements/update)
+- [Insert statement](/docs/surrealdb/surrealql/statements/insert)
+- [Delete statement](/docs/surrealdb/surrealql/statements/delete)
+- [Relate statement](/docs/surrealdb/surrealql/statements/relate)
+