GraphcoolDocs
FAQ

Mutation API

Last updated a day ago Edit this page

A GraphQL mutation is used to modify data at a GraphQL endpoint.

#Overview

A GraphQL mutation is used to modify data. This is an example mutation:

Query Variables
Hit the Play Button to get a response here
Docs

Here's a list of available mutations. To explore them, use the playground for your service.

#Type mutations

For every available model type in your data model, certain mutations are automatically generated.

For example, if your schema contains a Post type:

1
2
3
4
5
type Post @model {
  id: ID! @isUnique
  title: String!
  description: String
}

the following type mutations will be available:

#Creating a 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:

Query Variables
Hit the Play Button to get a response here
Docs

#Updating a node

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:

Query Variables
Hit the Play Button to get a response here
Docs

#Deleting a node

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:

Query Variables
Hit the Play Button to get a response here
Docs

#Relation mutations

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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:

#Modifying edges for one-to-one relations

A node in a one-to-one relation can at most be connected to one node.

Connect two nodes in a one-to-one relation

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:

Query Variables
Hit the Play Button to get a response here
Docs

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:

Query Variables
Hit the Play Button to get a response here
Docs
Query Variables
Hit the Play Button to get a response here
Docs

Disconnect two nodes in a one-to-one relation

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:

Query Variables
Hit the Play Button to get a response here
Docs

#Modifying edges for one-to-many relations

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.

Connect two nodes in a one-to-many relation

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:

Query Variables
Hit the Play Button to get a response here
Docs

Note: Adds the edge only if this node pair is not connected yet by this relation. Does not remove any edges.

Disconnect two nodes in a one-to-many relation

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:

Query Variables
Hit the Play Button to get a response here
Docs

#Modifying edges for many-to-many relations

Nodes in a many-to-many relations can be connected to many nodes.

Connect two nodes in a many-to-many relation

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:

Query Variables
Hit the Play Button to get a response here
Docs

Note: Adds the edge only if this node pair is not connected yet by this relation. Does not remove any edges.

Disconnect two nodes in a many-to-many relation

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:

Query Variables
Hit the Play Button to get a response here
Docs

#Nested mutations

When creating or updating nodes, you can execute nested mutations to interact with connected parts of your type schema.

#Limitations

Different limitations and improvement suggestions are available. Please join the discussion on GitHub!

Many other suggestions and improvements are currently being discussed.

#Nested create mutations

Nested create mutations connect the created node to a new node in the related type.

Consider the following data model:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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.

Nested create mutations for to-one relations

Let's explore the available nested create mutations for the one-to-one relation AuthorContactDetails.

Creating a new Author node and connect it to new ContactDetails
Query Variables
Hit the Play Button to get a response here
Docs

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:

Query Variables
Hit the Play Button to get a response here
Docs

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:

Updating an existing Author node and connect it to new ContactDetails

Similarly, we can update an Author node and simultaneously create new ContactDetails for it:

Query Variables
Hit the Play Button to get a response here
Docs

Nested create mutations for to-many relations

Let's explore the available nested create mutations for the one-to-many relation AuthorPosts.

Creating a new Author node and connect it to multiple new Post nodes
Query Variables
Hit the Play Button to get a response here
Docs

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:

Query Variables
Hit the Play Button to get a response here
Docs

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:

Updating an existing Author node and connecting it to multiple new Post nodes

Similarly, we can update an author and simultaneously assign it to a new list of new posts:

Query Variables
Hit the Play Button to get a response here
Docs

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

Nested connect mutations connect the original node to an existing node in the related type.

Consider the following data model:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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.

Nested connect mutations for to-one relations

Let's explore the available nested connect mutations for the one-to-one relation AuthorContactDetails.

Creating a new Author node and connecting it to an existing ContactDetails node
Query Variables
Hit the Play Button to get a response here
Docs

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.

Updating an existing Author node and connecting it to an existing ContactDetails node

Similarly, we can update an Author node and simultaneously connect it to an existing ContactDetails node:

Query Variables
Hit the Play Button to get a response here
Docs

Nested connect mutations for to-many relations

Let's explore the available nested connect mutations for the one-to-many relation AuthorPosts.

Creating a new Author node and connecting it to multiple existing Post nodes
Query Variables
Hit the Play Button to get a response here
Docs

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.

Updating an existing Author node and connecting it to multiple new Post nodes

Similarly, we can update an Author node and simultaneously assign it to a new list of existing Post nodes:

Query Variables
Hit the Play Button to get a response here
Docs

Note: This mutation will replace the existing list of Post nodes assigned to the Author node. If instead you want to append more posts to the list, you can modify the edge directly.

#Custom mutations

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.

#Example

Return a random number in a specified range

Schema Extension SDL document:

1
2
3
4
5
6
7
type RandomNumberPayload {
  number: Float!
}

extend type Mutation {
  randomNumber(min: Int!, max: Int!): RandomNumberPayload
}

Graphcool Function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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:

1
2
3
4
5
6
mutation {
  isValidAge(age: 12) {
    isValid # false
    age # 12
  }
}

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

Uploading files with a GraphQL mutation is not supported yet. For now, use the File API directly to upload files.

#Reading meta information of 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:

1
2
3
4
5
6
query {
  File(id: "my-file-id") {
    id
    name
  }
}

Similarly, the allFiles query can be used to query for multiple file nodes.

#Renaming files

To rename a file, use the updateFile mutation and choose a new value for the name field:

1
2
3
4
5
6
7
8
9
10
11
mutation {
  updateFile(
    id: "my-file-id"
    name: "new-comment-name.png"
  ) {
    file {
      id
      name
    }
  }
}

#Deleting files

To delete a file, use the deleteFile mutation as you would use any other delete mutation:

1
2
3
4
5
6
7
mutation {
  deleteFile(id: "my-file-id") {
    file {
      id
    }
  }
}

Was this page helpful?