| alias | ol0yuoz6go |
|---|---|
| description | A GraphQL mutation is used to modify data in a GraphQL API. |
A GraphQL mutation is used to modify data. This is an example mutation:
---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
createPost(
title: "My great Vacation"
slug: "my-great-vacation"
published: true
text: "Read about my great vacation."
) {
id
slug
}
}
---
{
"data": {
"createPost": {
"id": "cixneo7zp3cda0134h7t4klep",
"slug": "my-great-vacation"
}
}
}Here's a list of available mutations. To explore them, use the playground for your service.
- Based on the model types and relations in your data model, type mutations and relation mutations will be generated to modify nodes and edges.
- Additionally, custom mutations can be added to your API using Resolvers that are implemented as serverless functions.
For every available model type in your data model, certain mutations are automatically generated.
For example, if your schema contains a Post type:
type Post @model {
id: ID! @isUnique
title: String!
description: String
}the following type mutations will be available:
- the
createPostmutation creates a new node. - the
updatePostmutation updates an existing node. - the
deletePostmutation deletes an existing node.
Creates a new node for a specific type that gets assigned a new id.
All required fields of the type without a default value have to be specified, the other fields are optional arguments.
The query response can contain all fields of the newly created node, including the id field.
Create a new Post node and query its id and slug:
---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
createPost(
title: "My great Vacation"
slug: "my-great-vacation"
published: true
text: "Read about my great vacation."
) {
id
slug
}
}
---
{
"data": {
"createPost": {
"id": "cixneo7zp3cda0134h7t4klep",
"slug": "my-great-vacation"
}
}
}Updates fields of an existing node of a certain model type specified by the id field. The node's fields will be updated according to the additionally provided values.
The query response can contain all fields of the updated node.
Update the text and published fields for an existing Post node and query its id:
---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
updatePost(
id: "cixnen24p33lo0143bexvr52n"
text: "This is the start of my biggest adventure!"
published: true
) {
id
}
}
---
{
"data": {
"updatePost": {
"id": "cixnen24p33lo0143bexvr52n",
"text": "This is the start of my biggest adventure!",
"published": true
}
}
}Deletes a node specified by the id field.
The query response can contain all fields of the deleted node.
Delete an existing Post node and query its (then deleted) id and title:
---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
deletePost(id: "cixneo7zp3cda0134h7t4klep") {
id
title
}
}
---
{
"data": {
"id": "cixneo7zp3cda0134h7t4klep",
"title": "My great Vacation"
}
}For every available relation in your data model, certain mutations are automatically generated.
The names and arguments of the generated mutations depend on the relation name and its cardinalities. For example, with the following schema:
type Post @model {
id: ID! @isUnique
title: String!
author: User @relation(name: "WrittenPosts")
likedBy: [User!]! @relation(name: "LikedPosts")
}
type User @model {
id: ID! @isUnique
name : String!
address: Address @relation(name: "UserAddress")
writtenPosts: [Post!]! @relation(name: "WrittenPosts")
likedPosts: [Post!]! @relation(name: "LikedPosts")
}
type Address @model {
id: ID! @isUnique
city: String!
user: User @relation(name: "UserAddress")
}the following relation mutations will be available:
- the
setUserAddressandunsetUserAddressmutations connect and disconnect two nodes in the one-to-one relationUserAddress. - the
addToWrittenPostsandremoveFromWrittenPostsmutations connect and disconnect two nodes in the one-to-many relationWrittenPosts. - the
addToLikedPostsandremoveFromLikedPostsmutations connect and disconnect two nodes in the a many-to-many relationLikedPosts.
A node in a one-to-one relation can at most be connected to one node.
Creates a new edge between two nodes specified by their id. The according types have to be in the same relation.
The query response can contain both nodes of the new edge. The names of query arguments and node names depend on the field names of the relation.
Consider a blog where every Post node is assigned to additional MetaInformation. Add a new edge to the relation called PostMetaInformation and query the tags stored in the metaInformation node as well as the title:
---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
setPostMetaInformation(
metaInformationMetaInformationId: "cixnjj4l90ipl0106vp6u7a2f"
postPostId: "cixnen24p33lo0143bexvr52n"
) {
metaInformationMetaInformation {
tags
}
postPost {
title
}
}
}
---
{
"data": {
"setPostMetaInformation": {
"metaInformationMetaInformation": {
"tags": [
"GENERAL"
]
},
"postPost": {
"title": "My biggest Adventure"
}
}
}
}Note: First removes existing connections containing one of the specified nodes, then adds the edge connecting both nodes.
You can also use the updatePost or updateMetaInformation mutations to connect a Post node with a metaInformation node:
---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
updatePost(
id: "cixnen24p33lo0143bexvr52n"
metaInformationId: "cixnjj4l90ipl0106vp6u7a2f"
) {
metaInformation {
tags
}
}
}
---
{
"data": {
"updatePost": {
"metaInformation": {
"tags": [
"GENERAL"
]
}
}
}
}---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
updateMetaInformation(
id: "cixnjj4l90ipl0106vp6u7a2f",
postId: "cixnen24p33lo0143bexvr52n"
) {
post {
title
}
}
}
---
{
"data": {
"updateMetaInformation": {
"post": {
"title": "My biggest Adventure"
}
}
}
}Removes an edge between two nodes speficied by their id.
The query response can contain both nodes of the former edge. The names of query arguments and node names depend on the field names of the relation.
Remove an edge from the relation called PostMetaInformation and query the tags stored in the metaInformationnode and the title:
---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
unsetPostMetaInformation(
metaInformationMetaInformationId: "cixnjj4l90ipl0106vp6u7a2f"
postPostId: "cixnen24p33lo0143bexvr52n"
) {
metaInformationMetaInformation {
tags
}
postPost {
title
}
}
}
---
{
"data": {
"unsetPostMetaInformation": {
"metaInformationMetaInformation": {
"tags": [
"GENERAL"
]
},
"postPost": {
"title": "My biggest Adventure"
}
}
}
}One-to-many relations relate two types to each other.
A node of the one side of a one-to-many relation can be connected to multiple nodes. A node of the many side of a one-to-many relation can at most be connected to one node.
Creates a new edge between two nodes specified by their id. The according model type have to be in the same relations.
The query response can contain both nodes of the new edge. The names of query arguments and node names depend on the field names of the relation.
Adds a new edge to the relation called UserPosts and query the name of the User node as well as the title of the Post node:
---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
addToAuthorPosts(
authorUserId: "cixnekqnu2ify0134ekw4pox8"
postsPostId: "cixnen24p33lo0143bexvr52n"
) {
authorUser {
name
}
postsPost {
title
}
}
}
---
{
"data": {
"addToAuthorPosts": {
"authorUser": {
"name": "John Doe"
},
"postsPost": {
"title": "My biggest Adventure"
}
}
}
}Note: Adds the edge only if this node pair is not connected yet by this relation. Does not remove any edges.
Removes one edge between two nodes specified by id
The query response can contain both nodes of the former edge. The names of query arguments and node names depend on the field names of the relation.
Removes an edge for the relation called UserPosts and query the id of the User node as well as the slug of the Post node:
---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
removeFromAuthorPosts(
authorUserId: "cixnekqnu2ify0134ekw4pox8"
postsPostId: "cixnen24p33lo0143bexvr52n"
) {
authorUser {
name
}
postsPost {
slug
}
}
}
---
{
"data": {
"removeFromAuthorPosts": {
"authorUser": {
"name": "John Doe"
},
"postsPost": {
"title": "My biggest Adventure"
}
}
}
}Nodes in a many-to-many relations can be connected to many nodes.
Creates a new edge between two nodes specified by their id. The according model types have to be in the same relations.
The query response can contain both nodes of the new edge. The names of query arguments and node names depend on the field names of the relation.
Add a new edge to the relation called MovieActors and query the title of the Movie node as well as the name of the Actor node:
---
endpoint: https://api.graph.cool/simple/v1/cixos23120m0n0173veiiwrjr
disabled: true
---
mutation {
addToMovieActors(
moviesMovieId: "cixos5gtq0ogi0126tvekxo27"
actorsActorId: "cixxibjo1c1go0131ea1t4yor"
) {
moviesMovie {
title
}
actorsActor {
name
}
}
}
---
{
"data": {
"addToMovieActors": {
"moviesMovie": {
"title": "Inception"
},
"actorsActor": {
"name": "Leonardo DiCaprio"
}
}
}
}Note: Adds the edge only if this node pair is not connected yet by this relation. Does not remove any edges.
Removes one edge between two nodes specified by id.
The query response can contain both nodes of the former edge. The names of query arguments and node names depend on the field names of the relation.
Removes an edge for the relation called MovieActors and query the title of the Movie node as well as the name of the Actor node:
---
endpoint: https://api.graph.cool/simple/v1/cixne4sn40c7m0122h8fabni1
disabled: true
---
mutation {
removeFromMovieActors(
moviesMovieId: "cixos5gtq0ogi0126tvekxo27"
actorsActorId: "cixxibjo1c1go0131ea1t4yor"
) {
moviesMovie {
title
}
actorsActor {
name
}
}
}
---
{
"data": {
"removeFromAuthorPosts": {
"authorUser": {
"name": "John Doe"
},
"postsPost": {
"title": "My biggest Adventure"
}
}
}
}When creating or updating nodes, you can execute nested mutations to interact with connected parts of your type schema.
- to create and connect to a new node on the other side of a relation, you can use nested create mutations.
- to connect to an existing node on the other side of a relation, you can use nested connect mutations.
Nested create mutations connect the created node to a new node in the related type.
Consider the following data model:
type Author @model {
id: ID! @isUnique
contactDetails: ContactDetails @relation(name: "AuthorContactDetails")
posts: [Post!]! @relation(name: "AuthorPosts")
description: String!
}
type ContactDetails @model {
id: ID! @isUnique
author: Author @relation(name: "AuthorContactDetails")
email: String!
}
type Post @model {
id: ID! @isUnique
text: String!
author: Author @relation(name: "AuthorPosts")
}We're considering the createAuthor and updateAuthor mutation to see how to create nested nodes for the to-one relation AuthorContactDetails and the to-many relation AuthorPosts.
Let's explore the available nested create mutations for the one-to-one relation AuthorContactDetails.
---
endpoint: https://api.graph.cool/simple/v1/ciz751zxu2nnd01494hr653xl
disabled: true
---
mutation createAuthorAndContactDetails {
createAuthor(
description: "I am a good author!"
contactDetails: {
email: "nilan@graph.cool"
}
) {
id
contactDetails {
id
}
}
}
---
{
"data": {
"createAuthor": {
"id": "ciz7573ffx1w70112hwj04hqv",
"contactDetails": {
"id": "ciz7573ffx1w80112cjwjduxn"
}
}
}
}
Notice that the nested contactDetails object that takes the same input arguments as the createContactDetails mutation. After running this mutation, a new Author and ContactDetail node have been created that are connected via the AuthorContactDetails relation.
Here's the same mutation using GraphQL variables:
---
endpoint: https://api.graph.cool/simple/v1/ciz751zxu2nnd01494hr653xl
disabled: true
---
mutation createAuthorAndContactDetails($contactDetails: AuthorcontactDetailsContactDetails) {
createAuthor(
description: "I am a good author!"
contactDetails: $contactDetails
) {
id
contactDetails {
id
}
}
}
---
{
"contactDetails": {
"email": "nilan@graph.cool"
}
}
---
{
"data": {
"createAuthor": {
"id": "ciz7573ffx1w70112hwj04hqv",
"contactDetails": {
"id": "ciz7573ffx1w80112cjwjduxn"
}
}
}
}
Notice the variable type AuthorcontactDetailsContactDetails that follows a consistent naming schema:
- The original type name
Author - The related field name
contactDetails - The related type name
ContactDetails
You can also find the type name in the documentation in the Playground:
Similarly, we can update an Author node and simultaneously create new ContactDetails for it:
---
endpoint: https://api.graph.cool/simple/v1/ciz751zxu2nnd01494hr653xl
disabled: true
---
mutation updateAuthorAndCreateContactDetails($contactDetails: AuthorcontactDetailsContactDetails) {
updateAuthor(
id: "ciz7573ffx1w70112hwj04hqv"
description: "I write posts"
contactDetails: $contactDetails
) {
id
contactDetails {
email
}
}
}
---
{
"contactDetails": {
"email": "johannes@graph.cool"
}
}
---
{
"data": {
"updateAuthor": {
"id": "ciz7573ffx1w70112hwj04hqv",
"description": "I write posts"
"contactDetails": {
"email": "johannes@graph.cool"
}
}
}
}Let's explore the available nested create mutations for the one-to-many relation AuthorPosts.
---
endpoint: https://api.graph.cool/simple/v1/ciz751zxu2nnd01494hr653xl
disabled: true
---
mutation createAuthorAndPosts {
createAuthor(
description: "I am a good author!"
posts: [{
text: "A post of mine"
}, {
text: "Another post"
}]
) {
description
posts {
text
}
}
}
---
{
"data": {
"createAuthor": {
"description": "I am a good author!",
"posts": [
{
"text": "A post of mine"
},
{
"text": "Another post"
}
]
}
}
}Note that the nested posts object that takes a list of arguments needed for the createPost mutation. After running this mutation, a new Author and two Post nodes have been created that are now connected via the AuthorPosts relation.
Here's the same mutation using GraphQL variables:
---
endpoint: https://api.graph.cool/simple/v1/ciz751zxu2nnd01494hr653xl
disabled: true
---
mutation createAuthorAndPosts($posts: [AuthorpostsPost!]) {
createAuthor(
description: "I am a good author!"
posts: $posts
) {
description
posts {
text
}
}
}
---
{
"posts": [{
"text": "A post of mine"
}, {
"text": "Another post"
}]
}
---
{
"data": {
"createAuthor": {
"description": "I am a good author!",
"posts": [
{
"text": "A post of mine"
},
{
"text": "Another post"
}
]
}
}
}Note the variable type [AuthorpostsPost!] that follows a consistent naming schema:
- The original type name
Author - The related field name
posts - The related type name
Post
You can also find the type name in the documentation in the Playground:
Similarly, we can update an author and simultaneously assign it to a new list of new posts:
---
endpoint: https://api.graph.cool/simple/v1/ciz751zxu2nnd01494hr653xl
disabled: true
---
mutation updateAuthorAndConnectToPosts($posts: [AuthorpostsPost!]) {
updateAuthor(
id: "ciz7573ffx1w70112hwj04hqv"
description: "I write posts"
posts: $posts
) {
id
posts {
text
}
}
}
---
{
"posts": [{
"text": "A post of mine"
}, {
"text": "Another post"
}]
}
---
{
"data": {
"createAuthor": {
"description": "I am a good author!",
"posts": [
{
"text": "A post of mine"
},
{
"text": "Another post"
}
]
}
}
}Note: This mutation will replace the existing list of posts assigned to the author. If instead you want to append more posts to the list, you can modify the edge directly instead.
Nested connect mutations connect the original node to an existing node in the related type.
Consider the following data model:
type Author @model {
id: ID! @isUnique
contactDetails: ContactDetails @relation(name: "AuthorContactDetails")
posts: [Post!]! @relation(name: "AuthorPosts")
description: String!
}
type ContactDetails @model {
id: ID! @isUnique
author: Author @relation(name: "AuthorContactDetails")
email: String!
}
type Post @model {
id: ID! @isUnique
text: String!
author: Author @relation(name: "AuthorPosts")
}We're considering the createAuthor and updateAuthor mutation to see how to connect nested nodes for the to-one relation AuthorContactDetails and the to-many relation AuthorPosts.
Let's explore the available nested connect mutations for the one-to-one relation AuthorContactDetails.
---
endpoint: https://api.graph.cool/simple/v1/ciz751zxu2nnd01494hr653xl
disabled: true
---
mutation createAuthorAndConnectContactDetails {
createAuthor(
description: "I am a good author!"
contactDetailsId: "ciz7573ffx1w80112cjwjduxn"
) {
id
contactDetails {
id
}
}
}
---
{
"data": {
"createAuthor": {
"id": "ciz7573ffx1w70112hwj04hqv",
"contactDetails": {
"id": "ciz7573ffx1w80112cjwjduxn"
}
}
}
}Notice the nested contactDetailsId argument that gets passed the id of an existing ContactDetails node. After running this mutation, the new Author node and the existing ContactDetails node are connected via the AuthorContactDetails relation.
Similarly, we can update an Author node and simultaneously connect it to an existing ContactDetails node:
---
endpoint: https://api.graph.cool/simple/v1/ciz751zxu2nnd01494hr653xl
disabled: true
---
mutation updateAuthorAndConnectContactDetails {
updateAuthor(
id: "ciz7573ffx1w70112hwj04hqv"
description: "I write posts"
contactDetailsId: "ciz7573ffx1w80112cjwjduxn"
) {
id
contactDetails {
email
}
}
}
---
{
"data": {
"updateAuthor": {
"id": "ciz7573ffx1w70112hwj04hqv",
"description": "I write posts"
"contactDetails": {
"email": "nilan@graph.cool"
}
}
}
}Let's explore the available nested connect mutations for the one-to-many relation AuthorPosts.
---
endpoint: https://api.graph.cool/simple/v1/ciz751zxu2nnd01494hr653xl
disabled: true
---
mutation createAuthorAndConnectPosts($postsIds: [ID!]) {
createAuthor(
description: "I am a good author!"
postsIds: $postsIds
) {
description
posts {
text
}
}
}
---
{
"postsIds": ["ciz787j6eqmf5014929vvo2hp", "ciz787j6eqmf60149lg3jvi4r"]
}
---
{
"data": {
"createAuthor": {
"description": "I am a good author!",
"posts": [
{
"text": "A post of mine"
},
{
"text": "Another post"
}
]
}
}
}Notice the nested postsIds list of Post ids. After running this mutation, the new Author node and the existing Post nodes are now connected via the AuthorPosts relation.
Similarly, we can update an Author node and simultaneously assign it to a new list of existing Post nodes:
---
endpoint: https://api.graph.cool/simple/v1/ciz751zxu2nnd01494hr653xl
disabled: true
---
mutation updateAuthorAndConnectPosts($postsIds: [ID!]) {
updateAuthor(
id: "ciz7573ffx1w70112hwj04hqv"
description: "I write posts"
postsIds: $postsIds
) {
id
posts {
text
}
}
}
---
{
"postsIds": ["ciz787j6eqmf5014929vvo2hp", "ciz787j6eqmf60149lg3jvi4r"]
}
---
{
"data": {
"createAuthor": {
"description": "I write posts",
"posts": [
{
"text": "A post of mine"
},
{
"text": "Another post"
}
]
}
}
}Note: This mutation will replace the existing list of
Postnodes assigned to theAuthornode. If instead you want to append more posts to the list, you can modify the edge directly.
Custom mutations can be added to your GraphQL API using Resolver functions.
You can define the name, input arguments and payload of the mutation and resolve it with a Graphcool Function.
Schema Extension SDL document:
type RandomNumberPayload {
number: Float!
}
extend type Mutation {
randomNumber(min: Int!, max: Int!): RandomNumberPayload
}Graphcool Function:
module.exports = function randomNumber(event) {
const min = event.data.min
const max = event.data.max
if (min > max) {
return {
error: "Invalid input"
}
}
const number = Math.random() * (max - min) + min
return {
data: {
number
}
}
}Then the mutation can be called like this using the Simple API:
mutation {
randomNumber(min: 1, max: 10) {
number # number between 1 and 10
}
}Note that the returned object contains a data key, which in turn contains the number field that was specified in the RandomNumberPayload in the SDL document. Error handling works similarly to other Graphcool Functions, if an object containing the error key is returned.
Working with files (only for legacy Console projects)
To interact with the File API of the platform, you can create, rename or delete files through queries and mutations that are exposed in the Simple API.
Uploading files with a GraphQL mutation is not supported yet. For now, use the File API directly to upload files.
To query the meta information stored for a file, use the allFiles or File queries.
To query a specific file use one of the unique fields id, secret or url fields to specify the file node:
query {
File(id: "my-file-id") {
id
name
}
}Similarly, the allFiles query can be used to query for multiple file nodes.
To rename a file, use the updateFile mutation and choose a new value for the name field:
mutation {
updateFile(
id: "my-file-id"
name: "new-comment-name.png"
) {
file {
id
name
}
}
}To delete a file, use the deleteFile mutation as you would use any other delete mutation:
mutation {
deleteFile(id: "my-file-id") {
file {
id
}
}
}
