Skip to content

Mutation pages updates #185

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 21, 2024
Merged

Mutation pages updates #185

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7f92ef6
some nit to pick
rsill-neo4j Oct 10, 2024
d82ed18
updates for the update mutation page
rsill-neo4j Oct 10, 2024
a6b4730
updates to mutation pages
rsill-neo4j Oct 10, 2024
e1ad19f
Apply suggestions from code review
rsill-neo4j Oct 11, 2024
a54e2f5
Apply suggestions from code review
rsill-neo4j Oct 14, 2024
2050e5d
review suggestions
rsill-neo4j Oct 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions modules/ROOT/pages/mutations/create.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand All @@ -19,7 +19,7 @@ type User {
}
----

These `create` mutations and response types should be generated:
The following `create` mutations and response types are generated:

[source, graphql, indent=0]
----
Expand Down Expand Up @@ -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]
----
Expand Down Expand Up @@ -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]
====
Expand All @@ -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` to perform an operation similar to a xref: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:
Expand All @@ -130,7 +131,7 @@ type Movie {
}
----

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]
Expand All @@ -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

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.
17 changes: 9 additions & 8 deletions modules/ROOT/pages/mutations/delete.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

= `delete`

Using these type definitions:
Consider these type definitions:

[source, graphql, indent=0]
----
Expand All @@ -21,7 +21,7 @@ type User {
}
----

These `delete` mutations and response types should be generated:
The following `delete` mutations and response types are generated:
Copy link
Contributor

@lidiazuin lidiazuin Oct 14, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason why the mutation is here written in lowercase? It could be helpful to find a rule for that, but I think generally we write clauses/operations in uppercase.

Copy link
Contributor Author

@rsill-neo4j rsill-neo4j Oct 14, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hm... on second thought, not so sure actually
in code listings, it's a prefix and then it's used as lower case (deletePosts for Post objects)

for mutations, it's used consistently as lower case actually (create, delete and update are all written like this)

Copy link
Contributor

@lidiazuin lidiazuin Oct 15, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, whatever works best! I was just wondering because there are some cases where they are written in uppercase.


[source, graphql, indent=0]
----
Expand All @@ -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]
----
Expand All @@ -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]
----
Expand All @@ -74,8 +74,7 @@ mutation {
}
----

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:
This query is equivalent to:

[source, graphql, indent=0]
----
Expand Down Expand Up @@ -104,10 +103,12 @@ mutation {

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 -
//----
// !
4 changes: 2 additions & 2 deletions modules/ROOT/pages/mutations/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 section 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.
Expand All @@ -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.
====
Loading