Navigation

Execute a GraphQL Operation

Overview

You can access data that you’ve exposed from a collection through the GraphQL API. Realm enforces collection rules for all GraphQL operations, so you need to authenticate each request.

Set Up

You can use Apollo’s React hooks to execute GraphQL operations. The hooks are available in the @apollo/react-hooks package and all require the graphql-tag package to define operations.

Important

To execute a GraphQL operation with Apollo, you first need to connect your client application.

To install the required packages, run the following:

npm install graphql-tag @apollo/react-hooks

You can use the graphqurl CLI to execute GraphQL operations from a command line. You must authenticate all requests, so make sure to get a valid access token.

To install the graphqurl CLI, run the following:

npm install -g graphqurl

Run a Query

GraphQL Queries

The GraphQL API supports several different types of queries. For detailed information on all supported query types, including examples, see query resolvers.

Define the query with the qgl tag and then use the useQuery() hook to run the query whenever the component mounts.

import React from "react";
import { useQuery } from "@apollo/react-hooks";
import gql from "graphql-tag";

const allMoviesFrom200Query = gql`
  query AllMoviesFrom2000 {
    movies(query: { year: 2000 }) {
      title
      year
      runtime
    }
  }
`

export default function App() {
  // Must be rendered inside of an ApolloProvider
  const { loading, error, data } = useQuery(allMoviesFrom200Query);
  return (
    <div>
      {loading && <div>loading</div>}
      {error && <div>{`encountered an error: ${error}`}</div>}
      {data && <div>{`successfully queried ${data.length} movies from the year 2000.`}</div>}
    </div>
  );
}
gq https://realm.mongodb.com/api/client/v2.0/app/<Your App ID>/graphql \
    -H 'Authorization: Bearer <Valid Access Token>' \
    -q 'query AllMoviesFrom2000 {  movies(query: { year: 2000 }) { title year runtime }}'

Run a Mutation

GraphQL Mutations

The GraphQL API supports several different types of mutations. For detailed information on all supported mutation types, including examples, see mutation resolvers.

Define the mutation with the qgl tag and then use the useMutation() hook to get a function that executes the mutation.

import React from "react";
import { useQuery, useMutation } from "@apollo/react-hooks";
import gql from "graphql-tag";

const moviesQuery = gql`
  query AllMovies {
    movies {
      title
      year
    }
  }
`
const updateMovieTitleMutation = gql`
  mutation UpdateMovieTitle($oldTitle: String!, $newTitle: String!) {
    updateOneMovie(
      query: { title: $oldTitle }
      set: { title: $newTitle }
    ) {
      title
      year
    }
  }
`

export default function App() {
  // Must be rendered inside of an ApolloProvider
  const { loading, error, data } = useQuery(moviesQuery);
  const [updateMovieTitle] = useMutation(updateMovieTitleMutation);
  const handleUpdateMovieTitle = () => updateMovieTitle({
    variables: { oldTitle: "The Matrix 2", newTitle: "The Matrix Reloaded" }
  })
  return (
    <div>
      {loading && <div>loading</div>}
      {error && <div>{`encountered an error: ${error}`}</div>}
      {data && <div>{`successfully queried ${data.length} movies from the year 2000.`}</div>}
      <button onClick={handleUpdateMovieTitle}>Update Movie Title</button>
    </div>
  );
}
gq https://realm.mongodb.com/api/client/v2.0/app/<Your App ID>/graphql \
    -H 'Authorization: Bearer <Valid Access Token>' \
    -q 'mutation UpdateMovieTitle($oldTitle: String!, $newTitle: String!) { updateOneMovie(query: { title: $oldTitle } set: { title: $newTitle }) { title year } }'
    -v 'oldTitle=The Matrix Reloaded'
    -v 'newTitle=The Matrix 2'