Mutations review (#14)

* Mutations review

* final additions

* removing pages from content nav

* changing formatting

* update

* note on optimization

* fixing conflicts

* fixing conflicts

* update after review

* update after review

Author: lidiazuin

modules/ROOT/pages/mutations/create.adoc

@@ -1,7 +1,8 @@
 [[mutations-create]]
-= Create
+:description: This page describes how to create nodes through mutations.
+= `create`
 
-Using the following type definitions for these examples:
+Using the following type definitions:
 
 [source, graphql, indent=0]
 ----
@@ -18,7 +19,7 @@ type User {
 }
 ----
 
-The following create mutations and response types will be generated for the above type definitions:
+These `create` mutations and response types should be generated:
 
 [source, graphql, indent=0]
 ----
@@ -36,13 +37,17 @@ type Mutation {
 }
 ----
 
-The `CreateInput` types closely mirror the object type definitions, allowing you to create not only the type in question, but to recurse down and perform further operations on related types in the same Mutation.
+Note that the `CreateInput` types closely mirror the object type definitions.
+This allows you to create not only the type in question, but to recurse down and perform further operations on related types in the same mutation.
 
-> The `id` field will be absent from both create input types as the xref::reference/directives/autogeneration.adoc#type-definitions-autogeneration-id[`@id`] directive has been used.
+[NOTE]
+====
+The `id` field is absent from both `create` input types as the xref::reference/directives/autogeneration.adoc#type-definitions-autogeneration-id[`@id`] directive has been used.
+====
 
-== Single create
+== Single `create`
 
-A single user can be created by executing the following GraphQL statement:
+A single `User` can be created by executing the following GraphQL statement:
 
 [source, graphql, indent=0]
 ----
@@ -60,11 +65,11 @@ mutation {
 }
 ----
 
-This will create a User with name "John Doe", and that name plus the autogenerated ID will be returned.
+This should create a `User` with name "John Doe", and that name plus the autogenerated ID should be returned.
 
-== Nested create
+== Nested `create`
 
-A User and an initial Post can be created by executing the following:
+A `User` and an initial `Post` can be created by executing the following:
 
 [source, graphql, indent=0]
 ----
@@ -95,10 +100,19 @@ mutation {
 }
 ----
 
-This will create a User with name "John Doe", an introductory Post, both of which will be returned with their autogenerated IDs.
+This creates a `User` with name "John Doe" and an introductory post.
+Both should be returned with their autogenerated IDs.
+
+[NOTE]
+====
+You can perform similar and complementary actions by using the `update` mutation combined with `create`.
+Read about xref:mutations/update.adoc#_connectorcreate_relationships[`update`] for more information.
+====
 
 == `connectOrCreate` relationships
-If a related node has a `@unique` or `@id` directive defined, `connectOrCreate` can be used in a nested create to perform a `MERGE` operation on the related node, creating a new relationship and the related node if it doesn't exist.
+
+If a related node has a `@unique` or `@id` directive defined, `connectOrCreate` can be used in a nested `create` to perform a `MERGE` operation on the related node.
+This should create a new relationship and the related node if it doesn't exist yet.
 
 Consider the following type definitions:
 
@@ -116,7 +130,8 @@ type Movie {
 }
 ----
 
-Because a movie ID is unique, `connectOrCreate` can be used in an Actor mutation to ensure a movie exists before connecting. Note that only `@unique` or `@id` fields can be used in `where`:
+Because a movie ID is unique, `connectOrCreate` can be used in an `Actor` mutation to ensure the movie exists in the database before connecting. 
+Note that only `@unique` or `@id` fields can be used in `where`:
 
 [source, graphql, indent=0]
 ----
@@ -139,22 +154,13 @@ mutation {
 
 This will ensure that a movie with ID 1234 exists and it is connected to `"Tom Hanks"`. If the movie does not exist, it will be created with the title `"Forrest Gump"`. Note that if the movie with the given ID already exists, it will be connected to it, regardless of the title.
 
-[[optimizing-create-operations]]
-== Optimizing create operations
-
-It's possible to use the Neo4jGraphQL library to create several nodes and relationships in a single mutation, however,
-it's well known that performance issues are present in performing this task.
-A solution has been implemented that doesn't require any changes from the user.
-However, there are still several situations where this kind of optimization is not achievable.
-
-=== Subscriptions enabled
-
-No optimizations are available if a Subscription plugin it's being used.
-
-=== `@populated_by`
+== `CREATE` optimization
 
-No optimizations are available if a Node affected by the mutation has a field with the directive `@populated_by`.
+With the `create` operations, there is no limit on how many nodes can be created at once.
+However, there is a known performance issue for large batch sizes. 
 
-=== `connect` and `connectOrCreate` operations
+The Neo4j GraphQL Library contains an optimization feature designed to mitigate it, but it does not work in the following scenarios:
 
-No optimizations are available if the GraphQL input contains the `connect` or `connectOrCreate` operation.
+* A field is populated using the directive `@populated_by`.
+* The `connect` or `connectOrCreate` operation is used.
+* Interface and union types are present in the mutation.

modules/ROOT/pages/mutations/delete.adoc

@@ -1,7 +1,8 @@
 [[mutations-delete]]
-= Delete
+:description: This page describes how to delete nodes using mutations.
+= `delete`
 
-Using the following type definitions for these examples:
+Using these type definitions:
 
 [source, graphql, indent=0]
 ----
@@ -18,7 +19,7 @@ type User {
 }
 ----
 
-The following delete mutations and response type will be generated for the above type definitions:
+These `delete` mutations and response types should be generated:
 
 [source, graphql, indent=0]
 ----
@@ -33,9 +34,12 @@ type Mutation {
 }
 ----
 
-Note that the `DeleteInfo` type is the common return type for all delete mutations.
+[NOTE]
+====
+The `DeleteInfo` type is the common return type for all delete mutations.
+====
 
-== Single Delete
+== Single `delete`
 
 A single post can be deleted by executing the following GraphQL statement:
 
@@ -51,34 +55,25 @@ mutation {
 }
 ----
 
-This will delete the post using the autogenerated ID that would have been returned after that post's creation.
+This should delete the post using the autogenerated ID that was returned after that post's creation.
+Consequently, `nodesDeleted` should be equal `1` (the post) and `relationshipsDeleted` should also equal `1` as the `HAS_POST` relationship between the `Post` and its author was deleted.
 
-`nodesDeleted` would equal 1 (the post) and `relationshipsDeleted` would also equal equal 1 (the `HAS_POST` relationship between the Post and its author).
+== Nested `delete`
 
-== Nested Delete
-
-Say that if when you delete a User, you want to delete _all_ of their Posts as well. This can be achieved using a single nested delete operations:
+In case you want to delete a `User` *and* all of their posts, you can use a single nested `delete` mutation:
 
 [source, graphql, indent=0]
 ----
 mutation {
-    deleteUsers(
-        where: {
-            name: "Jane Doe"
-        },
-        delete: {
-            posts: [
-                where: { }
-            ]
-        }
-    ) {
-        nodesDeleted
-        relationshipsDeleted
-    }
+  deleteUsers(where: { name: "Jane Doe" }, delete: { posts: {} }) {
+    nodesDeleted
+    relationshipsDeleted
+  }
 }
 ----
 
-You may look at that empty `where` argument and wonder what that's doing. By the time the traversal has reached that argument, it has the context of only posts that were created by Jane Doe, as the traversals to those Post nodes were from her User node. Essentially, the above query is equivalent to:
+By the time the traversal has reached it, that empty `where` argument has the context of only refer to posts that were created by Jane Doe, as the traversals to those `Post` nodes were from her `User` node. 
+Essentially, the above query is equivalent to:
 
 [source, graphql, indent=0]
 ----
@@ -105,4 +100,12 @@ mutation {
 }
 ----
 
-Slightly easier to reason with, but the output Cypher statement will have a redundant `WHERE` clause!
+Note that the output Cypher statement should also have a redundant `WHERE` clause:
+
+//Please add the cypher statement:
+
+//[source, cypher, indent=0]
+//----
+//DELETE User (name:"Jane Doe") 
+//WHERE Posts -
+//----

modules/ROOT/pages/mutations/index.adoc

@@ -1,18 +1,18 @@
 [[mutations]]
+:description: This section describes how to use mutations with the Neo4j GraphQL Library.
 = Mutations
 
-Several mutations are automatically generated for each type defined in type definitions, which are covered in the following chapters:
+This section addresses basic examples of the following mutations:
 
-- xref::mutations/create.adoc[Create] - create nodes, and recursively create or connect further nodes in the graph
-- xref::mutations/update.adoc[Update] - update nodes, and recursively perform any operations from there
-- xref::mutations/delete.adoc[Delete] - delete nodes, and recursively delete or disconnect further nodes in the graph
+- xref::mutations/create.adoc[`create`] - create nodes, and recursively create or connect further nodes in the graph.
+- xref::mutations/update.adoc[`update`] - update nodes, and recursively perform any operations from there.
+- xref::mutations/delete.adoc[`delete`] - delete nodes, and recursively delete or disconnect further nodes in the graph.
 
-== A note on nested mutations
-
-You will see some basic examples of nested mutations in this chapter, which barely scratch the surface of what can be achieved with them. It's encouraged to explore the power of what you can do with them!
-
-However, it has to be noted that in order to provide the abstractions available in these mutations, the output Cypher can end up being extremely complex, which can result in your database throwing out-of-memory errors depending on its configuration.
-
-If out-of-memory errors are a regular occurrence, you can adjust the `dbms.memory.heap.max_size` parameter in the DBMS settings.
+[NOTE]
+====
+In order to provide the abstractions available in these mutations, the output Cypher can end up being complex.
+This can result in your database throwing out-of-memory errors depending on its configuration.
 
+If this becomes a regular occurrence, you can adjust the link:https://neo4j.com/docs/operations-manual/current/configuration/configuration-settings/#config_server.memory.heap.max_size[`server.memory.heap.max_size`] parameter in the DBMS settings.
 If you need to perform major data migrations, it may be best to manually write the necessary Cypher and execute this directly in the database.
+====