Navigation

GraphQL Types & Resolvers

Overview

Stitch automatically generates GraphQL types & resolvers for any collection that has a defined collection schema. For each collection, Stitch defines a GraphQL document type that represents a single document in the collection as well as a set of queries and mutations to work with that type.

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" },
    "runtime": { "bsonType": "int" },
    "director": { "bsonType": "string" }
  }
}

Data Types

Stitch automatically generates types that you can use in the GraphQL API.

Document Types

Stitch generates a single GraphQL type for 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.

Stitch automatically maps BSON field types defined in the schema to GraphQL types according to the BSON Type Mapping.

type Movie {
  _id: ObjectId
  title: String!
  year: Int
  runtime: Int
  director: String
}

Input Types

GraphQL uses input types to represent parameters that you pass to a mutation. This is a standard approach used by all GraphQL APIs. The GraphQL docs describe why:

Objects can contain fields that express circular references or references to interfaces and unions, neither of which is appropriate for use as an input argument. For this reason, input objects have a separate type in the system.

The Stitch GraphQL API uses the following input types:

Input Type Description
QueryInput 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.
InsertInput 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. Stitch automatically converts GraphQL types in the InsertInput object into their respective BSON type.
UpdateInput 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. Stitch automatically converts GraphQL types in the UpdateInput object into their respective BSON type.
RelationInput

An object that either defines a new related document in a relationship field or sets the relationship to point to an existing document in the related collection.

To create a new document, specify an InsertInput in the create field.

To point to an existing document, specify the document’s foreign key value in the link field.

type RelationInput {
  create: InsertInput
  link: <Foreign Key Type>
}
SortByInput

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

Custom Resolver Default Payload

If a custom query or mutation does not define a Payload Type, Stitch 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"
}

BSON Type Mapping

The GraphQL type system is similar but not identical to the BSON types that you can use in a schema. Stitch automatically maps between BSON types and GraphQL types based on the schema.

The following table lists BSON types that you can use in a collection 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

Query Resolvers

Stitch 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

Stitch 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. Stitch 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. Stitch 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. Stitch 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. Stitch 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. Stitch 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. Stitch 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 replaceOne<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 replaceMany<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
  }
}