Mutations: Creating Links

There are two top-level operation types in GraphQL: queries and mutations.

Queries are used when we want to read data.

Mutations are used when we want to change data. We use mutations when we want to create, update, or delete records.

In this section, we’ll learn how to send mutations with Apollo. Doing so is actually not that much different than sending queries and follows similar steps.

  1. Write the mutation as a JavaScript constant using the gql parser function
  2. Use the useMutation hook provided by Apollo Client to send mutations to our GraphQL server
  3. Read the result of the mutation

Preparing the React components

Like before, let’s start by writing the React component where users will be able to add new links.

This is a standard setup for a React component with two input fields where users can provide the url and description of the Link they want to create. The data that’s typed into these fields is held in the component’s local state by way of the useState hook.

Writing the mutation

Our job now is to take the user input and send it as arguments in a GraphQL mutation.

First, we need to define the mutation in our JavaScript code and use the useMutation hook to fire the mutation.

When we use the useMutation hook, we need to destructure out a function that can be used to call the mutaton. That’s what createLink is in the code block above. We’re now free to call the function whenever we need to when the component renders.

Make a call to createLink in the onSubmit event on the form tag.

.../hackernews-react-apollo/src/components/CreateLink.js
return (
  <div>
    <form
      onSubmit={(e) => {
        e.preventDefault();
        createLink();
      }}
    >
      ...
    </form>
  </div>
);

Now, when we run yarn start, we should see the following:

Running yarn start

Two input fields and a Submit button - not very pretty but functional.

Enter some data into the fields, e.g.:

  • Description: The best learning resource for GraphQL
  • URL: howtographql.com

Then click the Submit button. You won’t get any visual feedback in the UI, but let’s see if the query actually worked by checking the current list of links in a Playground.

You can open a Playground again by navigating to http://localhost:4000 in your browser. Then send the following query:

# Try to write the query here
{
  feed {
    links {
      description
      url
    }
  }
}

You’ll see the following server response:

{
  "data": {
    "feed": {
      "links": [
        // ...
        {
          "description": "The best learning resource for GraphQL",
          "url": "howtographql.com"
        }
      ]
    }
  }
}

Awesome! The mutation works, great job! 💪

Unlock the next chapter
Which of the following statements is true?
Only queries can be wrapped with the 'graphql' higher-order component
'<Mutation />' component allow variables, optimisticResponse, refetchQueries, and update as props
When wrapping a component with a mutation using 'graphql', Apollo only injects the mutation function into the render prop function
GraphQL mutations never take any arguments