# Source: https://docs.hypermode.com/dgraph/guides/message-board-app/graphql/react-graphql-mutations.md

# GraphQL Mutations

> Before you can query, you need to add data. Use GraphQL Mutations to add a user, category, posts, and sample data.

<Info>
  We're overhauling Dgraph's docs to make them clearer and more approachable. If
  you notice any issues during this transition or have suggestions, please
  [let us know](https://github.com/hypermodeinc/docs/issues).
</Info>

It'd be great to start by writing some queries to explore the graph of the app,
like you did in the sketches exploring graph ideas, but there's no data yet, so
queries won't be much use. So instead, you'll start by adding data.

## Add a User

GraphQL mutations have the useful property of returning a result. That result
can help your UI, for example, to re-render a page without further queries.
Dgraph Cloud lets the result returned from a mutation be as expressive as any
graph traversal.

Let's start by adding a single test user. The user type has the following
fields: `username`, `displayName`, `avatarImg`, `posts` and `comments`, as shown
below:

```graphql
type User {
  username: String! @id
  displayName: String
  avatarImg: String
  posts: [Post!]
  comments: [Comment!]
}
```

In this example, the only required field (marked with `!`) is the username. So,
to generate a new user node in the graph, we only need to supply a username.

The sample app's GraphQL API includes an `addUser` mutation, which can be used
to add multiple users and their data in a single operation. You can add one user
and their `username` with the following mutation:

```graphql
mutation {
  addUser(input: [{ username: "User1" }]) {
    user {
      username
      displayName
    }
  }
}
```

The `mutation` keyword tells a GraphQL server that it's running a mutation. The
mutation (in this case, `addUser`) takes the provided arguments and adds that
data to the graph.

The mutation shown above adds a single user, `User1`, and returns the newly
created user's `username` and `displayName`. The `displayName` will be `null`
because you didn't provide that data. This user also has no `posts` or
`avatarImg`, but we aren't asking for those in the result. Here's how it looks
when run in the Dgraph Cloud API Explorer.

<img src="https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-user.png?fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=49064b8bf24c500e7b4460116a6c18d8" alt="run a mutation in Dgraph Cloud" width="3584" height="2240" data-path="images/dgraph/guides/message-board-app/dgraph-cloud-add-a-user.png" srcset="https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-user.png?w=280&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=3a5888f42c75197971f3a8969d4c2bdc 280w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-user.png?w=560&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=bf4992deaa4ccbf554ac749b226e5de6 560w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-user.png?w=840&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=806b5e824a17234d86545c4d37121c18 840w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-user.png?w=1100&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=1998d9db85888c7a5c9a41fd9c23d201 1100w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-user.png?w=1650&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=180c55edffda2385a9ef1b79723fbae0 1650w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-user.png?w=2500&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=1089bd4213d7982400d83a8c7e3df4a4 2500w" data-optimize="true" data-opv="2" />

## Add a category

The graph now has a single node. Next, you'll add a category using the
`addCategory` mutation. Categories are a little different than users because the
id is auto-generated by Dgraph Cloud. The following mutation creates the
category and returns its `name` and the `id` Dgraph Cloud gave it.

```graphql
mutation {
  addCategory(input: [{ name: "Category1" }]) {
    category {
      id
      name
    }
  }
}
```

When run in Dgraph Cloud's API Explorer, the mutation looks as shown below. Note
that the category's `id` is auto generated and will be different on any
execution of the mutation.

<img src="https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-category.png?fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=3316a9cbd9886086f01ff53fde5a1cc3" alt="run a mutation with auto generated id in Dgraph Cloud" width="3584" height="2240" data-path="images/dgraph/guides/message-board-app/dgraph-cloud-add-a-category.png" srcset="https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-category.png?w=280&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=59c24508a86ab0729a8e987f540f3579 280w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-category.png?w=560&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=8d995c8fe7cf8c0c717b780ac7249e3a 560w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-category.png?w=840&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=dcad2bb678e663a12bf4a979f1773438 840w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-category.png?w=1100&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=951d22997aa47cb6c009175008448972 1100w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-category.png?w=1650&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=d7535059f34b73cb536219d8d7d68172 1650w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-add-a-category.png?w=2500&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=892243900e1198f341c38f86777907ac 2500w" data-optimize="true" data-opv="2" />

## Add Some Posts

Dgraph Cloud can do more than add single graph nodes at a time. The mutations
can add whole subgraphs and link into the existing graph. To show this, let's do
a few things at once. Remember our first sketch of some graph data?

<img src="https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/first-posts-in-graph.png?fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=2b37c80b26395d3b7047f9d469c56044" alt="sub graph with first posts" width="3200" height="1800" data-path="images/dgraph/guides/message-board-app/first-posts-in-graph.png" srcset="https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/first-posts-in-graph.png?w=280&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=586224b10698e860ceab47e932b65ae9 280w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/first-posts-in-graph.png?w=560&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=fd3bf29b0ffbb5e3fe5109b3321714d5 560w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/first-posts-in-graph.png?w=840&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=786327f2ee124c2d28acbfc7ef58146e 840w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/first-posts-in-graph.png?w=1100&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=a253775412422b423f0cf60c77efd04d 1100w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/first-posts-in-graph.png?w=1650&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=6246ba9a945294458bfe5bc49e7e47bd 1650w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/first-posts-in-graph.png?w=2500&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=9e55377d129f69e2400a0995a9391cce 2500w" data-optimize="true" data-opv="2" />

At the moment we only have the `User1` and `Category1` nodes. It is not much of
a graph, so let's flesh out the rest of the graph in a single mutation. We'll
use the `addPost` mutation to add the three posts, link all the posts to
`User1`, link posts 2 and 3 to the existing category, and then create
`Category2`. And, you'll do all of this in a single operation using the
following mutation:

```graphql
mutation {
  addPost(
    input: [
      {
        title: "Post1"
        text: "Post1"
        author: { username: "User1" }
        category: { name: "Category2" }
      }
      {
        title: "Post2"
        text: "Post2"
        author: { username: "User1" }
        category: { id: "0xfffd8d6ab6e7890a" }
      }
      {
        title: "Post3"
        text: "Post3"
        author: { username: "User1" }
        category: { id: "0xfffd8d6ab6e7890a" }
      }
    ]
  ) {
    post {
      id
      title
      author {
        username
      }
      category {
        name
      }
    }
  }
}
```

Because categories are referenced by an auto-generated `ID`, when you run such a
mutation, you'll need to make sure that you use the right id value for
`Category1` --- in my run that was `0xfffd8d6ab6e7890a`, but yours might differ.
In the Dgraph Cloud API explorer, that mutation looked like this:

<img src="https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-deep-mutations.png?fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=5b0a42b73dbb39695821951275bbcb7d" alt="dgraph-cloud-deep-mutations" width="3584" height="2240" data-path="images/dgraph/guides/message-board-app/dgraph-cloud-deep-mutations.png" srcset="https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-deep-mutations.png?w=280&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=39a69ad0f83fa5b31d7e2bb5d1fbcb73 280w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-deep-mutations.png?w=560&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=ae9fdfdd6002c40df785249a60ce4cf9 560w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-deep-mutations.png?w=840&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=b90d839c1d289098ce528dd7f2620566 840w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-deep-mutations.png?w=1100&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=441f2b272a5e43d29b8751ad97e3ae82 1100w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-deep-mutations.png?w=1650&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=1eb829ae271c091c680871c37d4256d2 1650w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/dgraph-cloud-deep-mutations.png?w=2500&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=c73e62e9e0d66fb388c3dd33484bfbfb 2500w" data-optimize="true" data-opv="2" />

A real app probably wouldn't add multiple posts in that way, but this example
shows the what you can do with mutations in Dgraph Cloud. For example, you could
create a shopping cart and add the first items to that cart in a single
mutation.

The input format to Dgraph Cloud also shows you another important property that
helps you when you are building an app: serialization of data. In general, you
can serialize your data structures, send them to Dgraph Cloud and it mutates the
graph. So, you don't need to programmatically add single objects from the client
or work out which bits are in the graph and which aren't --- just serialize the
data and Dgraph Cloud works it out. Dgraph Cloud uses the id's in the data to
work out how to connect the new data into the existing graph.

## Add sample data

You can run some more mutations, add more users or posts, or add comments to the
posts. To get you started, here's a mutation that adds some more data that we
can use to explore GraphQL queries in the following section.

```graphql
mutation {
  addPost(
    input: [
      {
        title: "A Post about Dgraph Cloud"
        text: "Develop a GraphQL app"
        author: { username: "User1" }
        category: { id: "0xfffd8d6ab6e7890a" }
      }
      {
        title: "A Post about Dgraph"
        text: "It is a GraphQL database"
        author: { username: "User1" }
        category: { id: "0xfffd8d6ab6e7890a" }
      }
      {
        title: "A Post about GraphQL"
        text: "Nice technology for an app"
        author: { username: "User1" }
        category: { id: "0xfffd8d6ab6e7890a" }
      }
    ]
  ) {
    post {
      id
      title
    }
  }
}
```

## GraphQL Variables

A mutation that takes data in its arguments is great to try out in a UI tool,
but an app needs to connect the data in its internal data structures to the API
without building complex query strings. GraphQL *Query Variables* let a query or
mutation depend on input values that are resolved at run-time.

For example, the following `addOnePost` mutation requires an input `$post` (of
type `post`) that it then passes as the `input` argument to the `addPost`
mutation:

```graphql
mutation addOnePost($post: AddPostInput!) {
  addPost(input: [$post]) {
    post {
      id
      title
      text
    }
  }
}
```

Running this mutation requires a packet of JSON that supplies a value for the
needed variable, as follows:

```json
{
  "post": {
    "title": "GraphQL Variables",
    "text": "This post uses variables to input data",
    "author": { "username": "User1" },
    "category": { "id": "0xfffd8d6ab6e7890a" }
  }
}
```

In Dgraph Cloud's UI, there's a **Query Variables** tab that you can use to
enter the variables.

<img src="https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/graphql-variables.png?fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=35fdb18f8d581367c0faf52ae424c3f8" alt="Mutation with GraphQL Variables" width="3584" height="2240" data-path="images/dgraph/guides/message-board-app/graphql-variables.png" srcset="https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/graphql-variables.png?w=280&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=a0fafea7ae50bc22c46dc033e0afd250 280w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/graphql-variables.png?w=560&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=0cd42f13be8907b7a9f1dfa906718594 560w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/graphql-variables.png?w=840&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=79919040ebcd43943055c69c51e50aac 840w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/graphql-variables.png?w=1100&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=ed1e901b7505bf20e058f927e3a270bb 1100w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/graphql-variables.png?w=1650&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=2f8f81055d9513f60d6417caf8e67f8d 1650w, https://mintcdn.com/hypermode/UzHAxAOBRpNLwtpT/images/dgraph/guides/message-board-app/graphql-variables.png?w=2500&fit=max&auto=format&n=UzHAxAOBRpNLwtpT&q=85&s=221259d0eabb2c2337ad793f4127c95f 2500w" data-optimize="true" data-opv="2" />

GraphQL variables let an app depend on a fixed mutation string and simply inject
the actual data into the mutation when it's executed, meaning same mutation can
be used over and over with different data.

## Mutations used in the App

The app always uses GraphQL variables so that there's a small set of mutations
and the data can be supplied by serializing client-side data structures.

The app will need a mutation to add users:

```graphql
mutation ($username: String!) {
  addUser(input: [{ username: $username }]) {
    user {
      username
    }
  }
}
```

It will also need a mutation to add posts:

```graphql
mutation addPost($post: AddPostInput!) {
  addPost(input: [$post]) {
    post {
      id
      # ... and other post data
    }
  }
}
```

It will need a mutation to add comments:

```graphql
mutation addComment($comment: AddCommentInput!) {
  addComment(input: [$comment]) {
    comment {
      id
      # ... and other comment data
    }
  }
}
```

And finally, it will need a mutation to update posts:

```graphql
mutation updatePost($id: ID!, $post: PostPatch) {
  updatePost(input: { filter: { id: [$id] }, set: $post }) {
    post {
      id
      # ... and other post data
    }
  }
}
```

The `updatePost` mutation combines a search and mutation into one. The mutation
first finds the posts to update (the `filter`) and then sets new values for the
post's fields with the `set` argument. To learn how the `filter` works, let's
[look at how Dgraph Cloud handles queries](./react-graphql-queries).