Merge pull request #199 from neo4j/cherry-pick-mutation-pages-PR-to-6.x

Apply mutation pages PR to 6.x

Author: rsill-neo4j

modules/ROOT/pages/deprecations.adoc

@@ -9,11 +9,11 @@ The following products and applications are deprecated:
 
 == GRANDstack starter app
 
-The main purpose of the GRANDstack starter app was to demonstrate how the Neo4j Labs GraphQL library could be used in the context of a full-stack application using React and Apollo client.
+The main purpose of the GRANDstack starter app was to demonstrate how the Neo4j Labs GraphQL Library could be used in the context of a full-stack application using React and Apollo client.
 It allowed developers to build applications more quickly and with a bigger focus on functionality, while also helping users who already had an existing frontend and needed a new back end.
 
 Over time, the GRANDstack starter app grew to support other frameworks such as Flutter and Angular, thus the need to revisit its scope.
-The intention is to replace this project with a new starter application product, which will focus on the back end and the configuration of the GraphQL library, as well as help developers with their frontend.
+The intention is to replace this project with a new starter application product, which will focus on the back end and the configuration of the GraphQL Library, as well as help developers with their frontend.
 
 In the meantime, the `create-grandstack-app` npm package has been marked as deprecated.
 It can still be used to skeleton a GRANDstack app, but the user will be warned that the package is deprecated.

modules/ROOT/pages/migration/index.adoc

@@ -34,7 +34,7 @@ The following deprecated `NOT` filters are removed from the schema since they ar
   - `edge_NOT`
 
 
-To achieve the same in version 6.x of the GraphQL library, use the xref:/queries-aggregations/filtering.adoc#_boolean_operators[boolean `NOT` operator] instead.
+To achieve the same in version 6.x of the GraphQL Library, use the xref:/queries-aggregations/filtering.adoc#_boolean_operators[boolean `NOT` operator] instead.
 
 [cols="1,1"]
 |===
@@ -68,7 +68,7 @@ The following deprecated `_NOT` filters on `@relationship` are removed and no lo
   - `actors_NOT`
   - `actorsConnection_NOT`
 
-To achieve the same in version 6.x of the GraphQL library, use the `NONE` quantifier.
+To achieve the same in version 6.x of the GraphQL Library, use the `NONE` quantifier.
 
 [cols="1,1"]
 |===

modules/ROOT/pages/mutations/create.adoc

@@ -2,7 +2,7 @@
 :description: This page describes how to create nodes through mutations.
 = `create`
 
-Using the following type definitions:
+Consider the following type definitions:
 
 [source, graphql, indent=0]
 ----
@@ -19,7 +19,7 @@ type User @node {
 }
 ----
 
-These `create` mutations and response types should be generated:
+The following `create` mutations and response types are generated:
 
 [source, graphql, indent=0]
 ----
@@ -65,11 +65,12 @@ mutation {
 }
 ----
 
-This should create a `User` with name "John Doe", and that name plus the autogenerated ID should be returned.
+This creates a `User` with the name "John Doe".
+The name and the autogenerated ID are returned.
 
 == Nested `create`
 
-A `User` and an initial `Post` can be created by executing the following:
+You can create a `User` and their initial `Post` at once by executing the following:
 
 [source, graphql, indent=0]
 ----
@@ -101,7 +102,7 @@ mutation {
 ----
 
 This creates a `User` with name "John Doe" and an introductory post.
-Both should be returned with their autogenerated IDs.
+Both are returned with their autogenerated IDs.
 
 [NOTE]
 ====
@@ -111,7 +112,7 @@ Read about xref:mutations/update.adoc#_connectorcreate_relationships[`update`] f
 
 == `connectOrCreate` relationships
 
-If a related node has the `@unique` directive defined, `connectOrCreate` can be used in a nested `create` to perform a `MERGE` operation on the related node.
+If a related node has the `@unique` directive defined, you can use `connectOrCreate` nested in a `create` mutation to perform an operation similar to a link:https://neo4j.com/docs/cypher-manual/current/clauses/merge/[Cypher `MERGE`] operation on the related node.
 This will create a new relationship and the related node if it doesn't exist yet.
 
 Consider the following type definitions:
@@ -130,7 +131,7 @@ type Movie @node {
 }
 ----
 
-Because a movie ID is unique, `connectOrCreate` can be used in an `Actor` mutation to ensure the movie exists in the database before connecting. 
+Since a movie ID is unique, you can use `connectOrCreate` in an `Actor` mutation to ensure the movie exists in the database before connecting them.
 Note that only `@unique` or `@id` fields can be used in `where`:
 
 [source, graphql, indent=0]
@@ -152,15 +153,17 @@ 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.
+This ensures that a movie with ID 1234 exists and is connected to `"Tom Hanks"`.
+If the movie does not exist, it will be created with the title `"Forrest Gump"`.
+If a movie with the given ID already exists, it will also be connected to `"Tom Hanks"`, and keep whatever title it has.
 
-== `CREATE` optimization
+== `create` optimization
 
-With the `create` operations, there is no limit on how many nodes can be created at once.
+With `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. 
 
 The Neo4j GraphQL Library contains an optimization feature designed to mitigate it, but it does not work in the following scenarios:
 
 * A field is populated using the directive `@populated_by`.
-* The `connect` or `connectOrCreate` operation is used.
+* The `connect` or `connectOrCreate` operations are used.
 * Interface and union types are present in the mutation.

modules/ROOT/pages/mutations/delete.adoc

@@ -4,7 +4,7 @@
 
 = `delete`
 
-Using these type definitions:
+Consider these type definitions:
 
 [source, graphql, indent=0]
 ----
@@ -21,7 +21,7 @@ type User @node {
 }
 ----
 
-These `delete` mutations and response types should be generated:
+The following `delete` mutations and response types are generated:
 
 [source, graphql, indent=0]
 ----
@@ -43,7 +43,7 @@ The `DeleteInfo` type is the common return type for all delete mutations.
 
 == Single `delete`
 
-A single post can be deleted by executing the following GraphQL statement:
+You can delete a single post by executing the following GraphQL statement:
 
 [source, graphql, indent=0]
 ----
@@ -57,12 +57,12 @@ mutation {
 }
 ----
 
-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.
+This deletes the post using the autogenerated ID that was returned after the creation of the post.
+Consequently, `nodesDeleted` is equal to `1` (the post) and `relationshipsDeleted` is also equal to `1` as the `HAS_POST` relationship between the `Post` and its author was deleted.
 
 == Nested `delete`
 
-In case you want to delete a `User` *and* all of their posts, you can use a single nested `delete` mutation:
+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]
 ----
@@ -72,42 +72,4 @@ mutation {
     relationshipsDeleted
   }
 }
-----
-
-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]
-----
-mutation {
-    deleteUsers(
-        where: {
-            name_EQ: "Jane Doe"
-        },
-        delete: {
-            posts: [
-                where: {
-                    node: {
-                        creator: {
-                            name_EQ: "Jane Doe"
-                        }
-                    }
-                }
-            ]
-        }
-    ) {
-        nodesDeleted
-        relationshipsDeleted
-    }
-}
-----
-
-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

@@ -3,7 +3,7 @@
 :description: This section describes how to use mutations with the Neo4j GraphQL Library.
 
 
-This section addresses basic examples of the following mutations:
+This page shows 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.
@@ -15,5 +15,5 @@ In order to provide the abstractions available in these mutations, the output Cy
 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.
+If you must perform major data migrations, it may be best to manually write the necessary Cypher and execute this directly in the database.
 ====