Navigation

GraphQL Types, Resolvers, and Operators

Overview

Realm automatically generates a GraphQL schema for any collection that has a defined collection schema. For each collection, Realm generates the following:

  • A document type that represents a single document in the collection
  • A set of queries and mutations that allow you to access and manipulate documents in the collection.
  • A set of input types that allow you to filter queries, modify specific fields, and sort results.

Example Collection Schema

This page includes examples that demonstrate generated values based on the following schema for a movies collection:

{
  "title": "Movie",
  "required": ["title"],
  "properties": {
    "_id": { "bsonType": "objectId" },
    "title": { "bsonType": "string" },
    "year": { "bsonType": "int" },
    "rated": { "bsonType": "string" },
    "runtime": { "bsonType": "int" },
    "director": { "bsonType": "string" },
    "reviews": {
      "bsonType": "array",
      "items": { "bsonType": "objectId" }
    },
    "cast": {
      "bsonType": "array",
      "items": { "bsonType": "string" }
    }
  }
}

Document Types

Realm generates a single GraphQL type for the documents in a collection based on the collection schema. The type uses the name set in the title field of the schema or the collection name if no title is specified.

type Movie {
  _id: ObjectId
  title: String!
  year: Int
  rated: String
  runtime: Int
  director: String
  cast: [String!]
}

Field Mapping

Realm attempts to map fields in your collection schema directly to fields in your GraphQL types. The definition of valid names described in the GraphQL spec does not support all possible valid document field names, so Realm applies the following transformation rules to determine field names in generated GraphQL types:

  • strip unsupported characters
  • strip leading numbers
  • convert to camel case
  • omit fields that begin with a double underscore (e.g. __myField)

BSON Type Mapping

The GraphQL type system is similar but not identical to the BSON types that you can use in a document schema. Realm automatically attempts to map between the BSON types in your schema and supported GraphQL types. If a field type does not have a GraphQL equivalent, Realm does not include the field in the generated GraphQL document type.

The following table lists BSON types that you can use in a schema and the GraphQL types that they map to:

JSON/BSON Type GraphQL Type
objectId ObjectId
int Int
long Int
double Float
decimal Float
date DateTime
timestamp DateTime

Input Types

GraphQL uses input types to represent parameters that you pass to queries and mutations. This is a standard approach used by all GraphQL APIs to define unambiguous, type-safe user inputs.

QueryInput

A QueryInput object defines a set of one or more conditions that a document must meet in order to be included in a query. The object may include fields from the document type as well as any of the operator fields that Realm automatically generates based on each field’s type.

  • Document Fields: If a QueryInput field has the same name as a field in the document type, then Realm matches a document if the value specified in the input field and the value of the field in the document are the same.

    Example

    The following query includes a QueryInput with two fields, rated and year. Both of these field names are defined in the Movie document type, so Realm performs an equality match for both.

    The query returns the title of all movies released in the year 2000 that are rated R.

    movies(query: { rated: "R", year: 2000 }) {
      title
    }
    
  • Operator Fields: If a QueryInput field is a valid operator field for the queried type, then Realm matches a document if the operator evaluates to true.

    Example

    The following query includes a QueryInput with two fields, rated_in and year_gt. Both of these are operator fields, so Realm evaluates each operator to determine if a document matches.

    The query returns the title of all movies released after the year 2000 that are rated either G or PG-13.

    movies(query: { rated_in: ["G", "PG-13"], year_gt: 2000 }) {
      title
    }
    

Comparison Operator Fields

A comparison operator field allows you to define a condition that is more complex than exact equality, such as a range query. Realm generates a set of comparison operator fields for every field in the document type based on the field type. Each comparison operator typically applies to only a subset of all field types, so Realm only generates operator fields for valid combinations.

A comparison operator field evaluates to true for a given document if the value of the field in the document satisfies the operator condition relative to the specified value.

Comparison operator fields have the following form:

<Field Name>_<Operator>: <Operator Value>
Operator Supported Field Types Operator Value Type Description
gt
Int
Float
String
ObjectId
DateTime
<Field Type>

Finds documents where the field is greater than the specified value.

Example

This query finds all movies that were released after the year 2000:

movies(query: { year_gt: 2000 }) {
  title
  year
}
gte
Int
Float
String
ObjectId
DateTime
<Field Type>

Finds documents where the field is greater than or equal to the specified value.

Example

This query finds all movies that were released in or after the year 2000:

movies(query: { year_gte: 2000 }) {
  title
  year
}
lt
Int
Float
String
ObjectId
DateTime
<Field Type>

Finds documents where the field is less than the specified value.

Example

This query finds all movies that were released before the year 2000:

movies(query: { year_lt: 2000 }) {
  title
  year
}
lte
Int
Float
String
ObjectId
DateTime
<Field Type>

Finds documents where the field is less than or equal to the specified value.

Example

This query finds all movies that were released in or before the year 2000:

movies(query: { year_lte: 2000 }) {
  title
  year
}
ne
Int
Float
String
Boolean
ObjectId
DateTime
<Field Type>

Finds documents where the field is not equal to the specified value.

Example

This query finds all movies that were released in any year other than 2000:

movies(query: { year_ne: 2000 }) {
  title
  year
}
in
Int
Float
String
Boolean
ObjectId
DateTime
Array
[<Field Type>!]

Finds documents where the field is equal to any value in the specified array. If the field is an Array, this finds all documents where any value in the field array is also included in the specified array.

Example

This query finds all movies that feature either or both of Emma Stone and Ryan Gosling:

movies(query: { cast_in: ["Emma Stone", "Ryan Gosling"] }) {
  title
  year
}
nin
Int
Float
String
Boolean
ObjectId
DateTime
Array
[<Field Type>!]

Finds documents where the field is not equal to any value in the specified array. If the field is an Array, this finds all documents where any value in the field array is also in the specified array.

Example

This query finds all movies that are not rated either G or PG-13:

movies(query: { rated_nin: ["G", "PG-13"] }) {
  title
  year
}

Logical Operator Fields

A logical operator field allows you to define logical combinations of independent QueryInput objects. Realm generates root-level logical operator fields for all QueryInput types.

A logical operator field evaluates to true for a given document if the evaluated result of all specified QueryInput objects satisfy the operator condition.

Logical operator fields have the following form:

<Operator>: [<QueryInput>, ...]
Operator Operator Value Type Description
AND [QueryInput!]

Finds documents that match all of the provided QueryInput objects.

Example

This query finds all movies that are rated PG-13 and have a runtime of less than 120 minutes:

query {
  movies(query: { AND: [{ rated: "PG-13" }, { runtime_lt: 120 }] }) {
    title
    year
  }
}
OR [QueryInput!]

Finds documents that match any of the provided QueryInput objects.

Example

This query finds all movies that are rated either G or PG-13:

query {
  movies(query: { OR: [{ rated: "G" }, { rated: "PG-13" }] }) {
    title
    year
  }
}

Element Operator Fields

An element operator field allows you to define a boolean condition that describes a field in the document. Realm generates a set of element operator fields for every field in the document type.

An element operator field evaluates to true for a given document if the result of evaluating the operator condition on the field in the document matches the specified boolean value.

Element operator fields have the following form:

<Field Name>_<Operator>: <Operator Value>
Operator Supported Types Operator Value Type Description
exists Available for all types Boolean

Finds documents where the field is not null.

Example

This query finds all movies that do not have a value defined for the year field:

query {
  movies(query: { year_exists: false }) {
    _id
    title
  }
}

InsertInput

An InsertInput object defines a document to insert into a collection. The document must conform to the GraphQL document type and include all required fields.

Example

The following mutation includes an InsertInput with several fields that are all defined in the Movie document type. The Movie type requires all documents to have a title field, so the InsertInput must include one.

The mutation inserts a new movie named “My Fake Film”.

insertOneMovie(input: {
  title: "My Fake Film",
  rated: "UNRATED",
  year: 2020
}) {
  title
}

UpdateInput

An UpdateInput object defines a new value for one or more fields in a document. The updated document includes the new field values. Any fields that you do not specify remain unchanged. The updated values must conform to the GraphQL document type.

Example

The following mutation includes an UpdateInput that sets the title field to “My Super Real Film”.

updateOneMovie(
  query: { title: "My Fake Film" }
  set: { title: "My Super Real Film" }
) {
  title
}

RelationInput

A RelationInput defines a new set of related documents for a relationship field in the mutated document. You can reference documents that already exist in the related collection with the link field and insert new documents into the related collection with the create field.

type RelationInput {
  link: [ObjectId]
  create: [InsertInput]
}

Example

The following mutation includes an UpdateInput that modifies the reviews field. The field contains an array of _id values for documents in a separate reviews collection for to the field has a defined relationship.

The mutation sets the relationship to point to one newly created document and two existing documents in the reviews collection.

updateOneMovie(
  query: { title: "My Fake Film" }
  set: {
    reviews: {
      link: ["", ""]
      create: []
    }
  }
) {
  title
}

SortByInput

A SortByInput enum defines a sort order for documents returned by a query. You can sort in ascending and descending order by any root-level field that does not have a type of object or array. The GraphQL API does not support nested sorts.

Realm generates two sort enum values for each field. Each value is a fully-capitalized identifier that combines the field name and the sort direction, either ASC or DESC.

Example

The following query returns movies sorted by the year they were released with the most recent movies listed first.

movies(sortBy: YEAR_DESC) {
  title
}

Custom Resolver Default Payload

If a custom query or mutation does not define a Payload Type, Realm returns a DefaultPayload that has the following signature:

type DefaultPayload {
  status: String!
}

The status field will always resolve to "complete" regardless of the resolver function’s return value.

{
  status: "complete"
}

Query Resolvers

Realm generates two GraphQL queries for each collection:

  • A singular query that finds a specific document in the collection.
  • A plural query that finds all documents in the collection. You can filter a plural query to include only the subset of documents in a collection that match a QueryInput.

Find a Single Document

The single document query field uses the same name as the data type that the collection contains. It returns a single document of the queried type and accepts the following parameters:

Parameter Type Description
query QueryInput

Optional. An object that defines a filter for documents in the collection. The object may specify one or more fields from the data type and must include a value for each field. The query matches all documents that include the specified field values.

If you do not specify a query parameter then the query operation matches all documents.

query {
  movie(query: { title: "The Matrix" }) {
    title
    year
    runtime
    director
  }
}

Find Multiple Documents

The multiple document query field uses the same name as the data type that the collection contains but has an additional "s" appended to the type name. It returns an array of documents of the queried type and accepts the following parameters:

Parameter GraphQL Type Description
query QueryInput

Optional. An object that defines a filter for documents in the collection. The object may specify one or more fields from the data type and must include a value for each field. The query matches all documents that include the specified field values.

If you do not specify a query argument then the query operation matches all documents.

limit Int

Optional. The maximum number of documents to include in the query result set. If the query matches more than the set limit then it only returns a subset of matched documents.

If you do not specify a limit argument then the query operation returns all matching documents.

sortBy SortByInput

Optional. A value that defines a sort order for documents in the query result set. You can sort in ascending and descending order by any root-level field that does not have a type of object or array.

The sortBy value is a fully-capitalized identifier that combines the field name and the sort direction. For example:

  • to sort by title from A to Z you would use TITLE_ASC
  • to sory by rating from highest to lowest you would use RATING_DESC

If you do not specify a sortBy argument then the query operation does not guarantee the order of documents in the result set.

query {
  movies(
    query: { year: 2000 }
    limit: 100
    sortBy: TITLE_ASC
  ) {
    title
    year
    runtime
    director
  }
}

Mutation Resolvers

Realm generates a set of mutations for the documents in each collection. These allow you insert, modify, and delete one or more documents.

Insert a Single Document

The single document insert mutation field uses the name insertOne<Type> where <Type> is the singular name of the data type that the collection contains. It returns the inserted document and accepts the following parameters:

Parameter Type Description
data InsertInput! Required. A document to insert into the collection. If the collection schema marks a field as required then this document must include a valid value for that field. Realm automatically converts GraphQL types in the InsertInput object into their respective BSON type.
mutation {
  insertOneMovie(data: {
    title: "Little Women"
    director: "Greta Gerwig"
    year: 2019
    runtime: 135
  }) {
    _id
    title
  }
}

Insert Multiple Documents

The multiple document insert mutation field uses the name insertMany<Type>s where <Type> is the singular name of the data type that the collection contains. It returns the inserted document and accepts the following parameters:

Parameter Type Description
data [InsertInput!]! Required. An array of documents to insert into the collection. The array must contain at least one document. If the collection schema marks a field as required then each document must include a valid value for that field. Realm automatically converts GraphQL types in the InsertInput object into their respective BSON type as defined in the collection schema.
mutation {
  insertManyMovies(data: [
    {
      title: "Little Women"
      director: "Greta Gerwig"
      year: 2019
      runtime: 135
    },
    {
      title: "1917"
      director: "Sam Mendes"
      year: 2019
      runtime: 119
    }
  ]) {
    _id
    title
  }
}

Update a Single Document

The single document update mutation field uses the name updateOne<Type> where <Type> is the singular name of the data type that the collection contains. It returns the updated document and accepts the following parameters:

Parameter Type Description
query QueryInput

Optional. An object that configures which documents in the collection to update. The object may specify one or more fields from the data type and must include a value for each field. The query matches all documents that include the specified field values.

If you do not specify a query argument then the mutation updates the first document in the result set, which is likely but not guaranteed to be the most recently inserted document.

set UpdateInput! Required. An object that defines a new value for one or more fields in the document. The updated document will include the new field values. Any fields that you do not specify remain unchanged. Realm automatically converts GraphQL types in the UpdateInput object into their respective BSON type.
mutation {
  updateOneMovie(
    query: { title: "The Room" }
    set: { runtime: 99 }
  ) {
    _id
    title
  }
}

Update Multiple Documents

The multiple document update mutation field uses the name updateMany<Type>s where <Type> is the singular name of the data type that the collection contains. It returns an UpdateManyPayload document that describes the number of fields that were matched and modified and accepts the following parameters:

Parameter Type Description
query QueryInput

Optional. An object that configures which documents in the collection to update. The object may specify one or more fields from the data type and must include a value for each field. The query matches all documents that include the specified field values.

If you do not specify a query argument then the mutation updates the first document in the result set, which is likely but not guaranteed to be the most recently inserted document.

set UpdateInput! Required. An object that defines a new value for one or more fields in the document. The updated document will include the new field values. Any fields that you do not specify remain unchanged. Realm automatically converts GraphQL types in the UpdateInput object into their respective BSON type.
mutation {
  updateManyMovies(
    query: { director: "Tommy Wiseau" }
    set: { director: "Tom Wiseau" }
  ) {
    matchedCount
    modifiedCount
  }
}

Upsert a Single Document

The single document upsert mutation field uses the name upsertOne<Type> where <Type> is the singular name of the data type that the collection contains. This resolver updates a document that matches the query parameter and inserts a new document if none match the query. It returns the upserted document and accepts the following parameters:

Parameter Type Description
query QueryInput

Optional. An object that configures which document to update. The object may specify one or more fields from the data type and must include a value for each field. The query matches all documents that include the specified field values.

If you do not specify a query argument or no documents match, then the mutation inserts the document specified in the data parameter.

data InsertInput! Required. The document to insert if the query does not match any existing documents. If the query does match a document replaces the queried document. If the collection schema marks a field as required then this document must include a valid value for that field. Realm automatically converts GraphQL types in the InsertInput object into their respective BSON type.
mutation {
  upsertOneMovie(
    query: { title: "Blacksmith Scene" }
    data: {
      title: "Sandcastles in the Sand",
      director: "Robin Scherbatsky"
      runtime: 90
      year: 2002
    }
  ) {
    _id
    title
  }
}

Replace a Single Document

The single document replacement mutation field uses the name replaceOne<Type> where <Type> is the singular name of the data type that the collection contains. It returns the replaced document and accepts the following parameters:

Parameter Type Description
query QueryInput

Optional. An object that configures which documents in the collection to replace. The object may specify one or more fields from the data type and must include a value for each field. The query matches all documents that include the specified field values.

If you do not specify a query argument then the mutation replaces the first document in the result set, which is likely but not guaranteed to be the most recently inserted document.

data InsertInput! Required. The document that replaces the queried document. If the collection schema marks a field as required then this document must include a valid value for that field. Realm automatically converts GraphQL types in the InsertInput object into their respective BSON type.
mutation {
  replaceOneMovie(
    query: { title: "Blacksmith Scene" }
    data: {
      title: "Sandcastles in the Sand",
      director: "Robin Scherbatsky"
      runtime: 90
      year: 2002
    }
  ) {
    _id
    title
  }
}

Delete a Single Document

The single document delete mutation field uses the name deleteOne<Type> where <Type> is the singular name of the data type that the collection contains. It returns the deleted document and accepts the following parameters:

Parameter Type Description
query QueryInput

Required. An object that configures which document in the collection to delete. The object may specify one or more fields from the data type and must include a value for each field. The query matches all documents that include the specified field values.

If the query matches multiple documents, the mutation deletes the first document in the result set, which is likely but not guaranteed to be the most recently inserted document.

mutation {
  deleteOneMovie(query: { title: "The Room" }) {
    _id
    title
    year
    runtime
    director
  }
}

Delete Multiple Documents

The multiple document delete mutation field uses the name deleteMany<Type>s where <Type> is the singular name of the data type that the collection contains. It returns a DeleteManyPayload document that describes the number of documents that were deleted and accepts the following parameters:

Parameter Type Description
query QueryInput

Optional. An object that configures which documents in the collection to delete. The object may specify one or more fields from the data type and must include a value for each field. The query matches all documents that include the specified field values.

If you do not specify a query argument then the mutation deletes all documents in the collection.

mutation {
  deleteManyMovies(query: { director: "Tommy Wiseau" }) {
    deletedCount
  }
}