Navigation

GraphQL API

Overview

Version Requirement

GraphQL requires MongoDB version 4.0 or greater.

The MongoDB Realm GraphQL API allows client applications to access data stored in a linked MongoDB cluster using any standard GraphQL client. Realm automatically creates GraphQL types for every linked collection that has a defined document schema and evaluates role-based permissions for all GraphQL requests.

Create an Atlas Cluster for Free

The GraphQL API lets you access data that you have stored in a MongoDB Atlas cluster. To get started, create a free cluster and link it to your Realm app.

If you don’t have any data yet but you still want to explore the GraphQL API, consider adding a sample data set to your cluster.

To learn how to make data available through the GraphQL API, see Expose Data in a Collection.

To learn how to define custom queries and mutations, see Define a Custom Query or Mutation.

To learn about the types and operations that you can use with the Realm GraphQL API, see GraphQL Types & Resolvers.

Why GraphQL?

GraphQL is a declarative, strongly-typed query language for client applications. Clients define the exact data shape and contents that they need in a single request which eliminates over-fetching problems and circumvents the need for multiple costly round trips to the server.

To learn more about GraphQL, check out the official GraphQL tutorial.

Limitations

  • The GraphQL API can process a maximum of ten resolvers for a given query or mutation. If an operation specifies more than ten resolvers, the entire operation will fail with the error message "max number of queries reached".

GraphQL Operations

Realm automatically generates types and resolvers for data that you expose to the GraphQL API. The generated types and operations are all named after the base type name for each exposed collection. If you don’t define a type name, Realm uses the collection name instead.

For more information on how to expose a collection and name its data type, see Expose Data in a Collection.

Queries

A GraphQL query is a read operation that requests specific fields from one or more types. Realm automatically generates query types for documents in each collection that has a defined schema.

For more information and examples, including a list of all automatically generated query types, see Query Resolvers.

# Find a single movie by name
query {
  movie(query: { title: "The Matrix" }) {
    _id
    title
    year
    runtime
  }
}

# Find all movies from the year 2000
query {
  movies(query: { year: 2000 }) {
    _id
    title
    year
    runtime
  }
}

# Find the ten longest movies from the year 2000
query {
  movies(
    query: { year: 2000 }
    sortBy: RUNTIME_DESC
    limit: 10
  ) {
    _id
    title
    year
    runtime
  }
}

Mutations

A GraphQL mutation is a write operation that creates, modifies, or deletes one or more documents. Realm automatically generates mutation types for documents in each collection that has a defined schema. MongoDB Realm uses transactions to ensure safe writes via mutations.

For more information and examples, including a list of all automatically generated mutation types, see Mutation Resolvers.

For an example of how to run a mutation from a client application, see Run a GraphQL Mutation.

# Insert a new movie
mutation {
  insertOneMovie(data: {
    title: "Little Women"
    director: "Greta Gerwig"
    year: 2019
    runtime: 135
  }) {
    _id
    title
  }
}

# Update the year of a movie
mutation {
  updateOneMovie(
    query: { title: "The Matrix" }
    set: { year: 1999 }
  ) {
    _id
    title
  }
}

# Delete a movie
mutation {
  deleteOneMovie(query: { title: "The Room" }) {
    _id
    title
  }
}

# Delete multiple movies
mutation {
  deleteManyMovies(query: { director: "Tommy Wiseau" }) {
    _id
    title
  }
}