GraphQL Types, Resolvers, and Operators

Field Mapping

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

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 App Services 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 App Services 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 App Services 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 App Services 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 App Services 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
  }

<Field Name>_<Operator>: <Operator Value>

movies(query: { year_gt: 2000 }) {
  title
  year
}

movies(query: { year_gte: 2000 }) {
  title
  year
}

movies(query: { year_lt: 2000 }) {
  title
  year
}

movies(query: { year_lte: 2000 }) {
  title
  year
}

movies(query: { year_ne: 2000 }) {
  title
  year
}

movies(query: { cast_in: ["Emma Stone", "Ryan Gosling"] }) {
  title
  year
}

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

<Operator>: [<QueryInput>, ...]

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

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

<Field Name>_<Operator>: <Operator Value>

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.

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.

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 or insert new documents into the related collection with the create field.

You cannot use both link and create at the same time. If both are specified, the create operation takes precedence and the link is ignored.

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

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.

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

movies(sortBy: YEAR_DESC) {
  title
}

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:

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:

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

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:

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:

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:

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:

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:

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:

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:

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:

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