Docs Menu

Docs HomeAtlas App Services

Atlas GraphQL API [Deprecated]

On this page

  • Overview
  • Why GraphQL?
  • How App Services Creates GraphQL Schemas
  • GraphQL Operations
  • Queries
  • Mutations
  • Limitations

The Atlas GraphQL API allows client applications to access data stored in a linked MongoDB Atlas cluster using any standard GraphQL client.

Atlas App Services automatically creates GraphQL types for every linked collection that has a defined schema and evaluates role-based permissions for all GraphQL requests. To learn how to make data available through the GraphQL API, see Expose Data in a Collection.

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

To extend the generated GraphQL API's functionality with custom queries and mutations, see Define a Custom Resolver.

Note

Create an Atlas Cluster for Free

The GraphQL API lets you access data that you have stored in a MongoDB Atlas cluster or Federated database instance. To get started, create a free cluster and link it to your 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.

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.

Using App Services, you generate the GraphQL schema and resolvers from JSON schemas for MongoDB collections. This differs from the traditional code-first and schema-first approaches to GraphQL schema development.

To define your GraphQL schema with App Services:

  1. Define a JSON schema for a MongoDB collection in your MongoDB Atlas cluster. You can enforce the shape of the collection schema based on custom definitions or use a generated schema based on the documents in the collection.

  2. Generate the GraphQL schema and resolvers based on your collection JSON schema.

  3. Optionally extend the functionality of your generated GraphQL schema with custom resolvers.

App Services 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, App Services 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.

Note

GraphQL mutation and custom resolver requests use MongoDB transactions to ensure correctness across multiple database operations. If any operation in a request fails, then the entire transaction fails and no operations are committed to the database.

A GraphQL query is a read operation that requests specific fields from one or more types. App Services 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
}
}

A GraphQL mutation is a write operation that creates, modifies, or deletes one or more documents. App Services automatically generates mutation types for documents in each collection that has a defined schema. App Services 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.

# 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
}
}
  • 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 fails with the error message "max number of queries reached".

  • The GraphQL API can resolve relationships to a maximum depth of five for a given query or mutation. If an operation specifies a relationship deeper than five resolvers, the entire operation fails with the error message "max relationship depth exceeded".

  • The GraphQL API expects collection schemas to have unique titles and raises a warning if your data model contains duplicate titles.

    You can safely ignore this warning if:

    • The title conflicts only involve embedded objects.

    • Every schema with a given title uses an identical definition, including relationships.

  • The GraphQL API does not currently support relationships for fields inside arrays of embedded objects. You can use a custom resolver to manually look up and resolve embedded object array relationships.

←  Upgrade a Shared Tier ClusterExpose Data in a Collection →