GraphQL 类型、解析程序和操作符

字段映射

App Services 会尝试将集合模式中的字段直接映射到 GraphQL 类型中的字段。GraphQL 规范中描述的有效名称定义不支持所有可能的有效文档字段名称，因此 App Services 应用以下转换规则来确定生成的 GraphQL 类型中的字段名称：

• 去掉不支持的字符

• 去掉开头的数字

• 转换为大小写混合名称

• 省略以双下划线开头的字段（例如 __myField）

BSON 类型映射

GraphQL 类型系统与可在模式中使用的 BSON 类型相似，但并不相同。App Services 会自动尝试在模式中的 BSON 类型和支持的 GraphQL 类型之间进行映射。如果字段类型没有对应的 GraphQL，App Services 不会在生成的 GraphQL 文档类型中包含该字段。

下表列出了可在模式中使用的 BSON 类型及其映射到的 GraphQL 类型：

QueryInput

QueryInput 对象定义一个或多个条件，文档必须满足这些条件才能包含在查询中。该对象可能包括文档类型的字段以及 App Services 根据每个字段的类型自动生成的任何操作符字段。

• 文档字段：如果QueryInput字段与文档类型中的字段同名，并且输入字段中指定的值与文档中字段的值相同，则 App Services 将匹配文档。

  例子

  以下查询包含一个 QueryInput 以及两个字段：rated 和 year。Movie 文档类型中定义了这两个字段名称，因此 App Services 会对这两个字段名称执行相等匹配。

  该查询返回 2000 年上映的所有 R 级电影的片名。

  movies(query: { rated: "R", year: 2000 }) {
    title
  }

• 操作符字段：如果 QueryInput 字段是查询类型的有效操作符字段，那么如果操作符的值为 true，App Services 就会匹配文档。

  例子

  以下查询包含一个 QueryInput 以及两个字段：rated_in 和 year_gt。这两个字段均为操作符字段，因此 App Services 会对每个操作符求值以确定某一文档是否匹配。

  该查询返回 2000 年后上映的所有 G 级或 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

InsertInput 对象可定义要插入到集合中的文档。该文档必须符合 GraphQL 文档类型并包含所有必需字段。

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

UpdateInput

UpdateInput 对象为文档中的一个或多个字段定义新值。更新后的文档包含新字段值。未指定的字段保持不变。更新后的值必须符合 GraphQL 文档类型。

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

RelationInput

RelationInput 可为被更改文档中的关系字段定义一组新的相关文档。您可以使用 link 字段引用相关集合中已存在的文档，也可使用 create 字段将新文档插入到相关集合中。

您不能同时使用 link 和 create。如果同时指定了两者，则执行 create 操作并忽略 link。

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

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

SortByInput

SortByInput 枚举值定义了查询返回的文档的排序顺序。您可按其类型不是 object 或 array 的任意根级字段进行升序和降序排序。GraphQL API 不支持嵌套排序。

App Services 为每个字段（Field）生成两个排序枚举值。每个值都是一个完全大写的标识符，结合了字段名称和排序方向（ ASC或DESC 。

movies(sortBy: YEAR_DESC) {
  title
}

查找单个文档

单个文档查询字段使用与集合包含的数据类型相同的名称。其返回所查询类型的单个文档，并接受以下参数：

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

查找多个文档

多文档查询字段使用与集合包含的数据类型相同的名称，但在类型名称后附加了一个 "s"。其返回所查询类型的文档数组，并接受以下参数：

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

插入单一文档

单文档插入 mutation 字段使用 insertOne<Type> 名称，其中 <Type> 是集合包含的数据类型的单数名称。它返回插入的文档并接受以下参数：

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

插入多个文档

多文档插入 mutation 字段使用 insertMany<Type>s 名称，其中 <Type> 是集合包含的数据类型的单数名称。它返回插入的文档并接受以下参数：

mutation {
  insertManyMovies(data: [
    {
      title: "Little Women"
      director: "Greta Gerwig"
      year: 2019
      runtime: 135
    },
    {
      title: "1917"
      director: "Sam Mendes"
      year: 2019
      runtime: 119
    }
  ]) {
    _id
    title
  }
}

更新单份文档

单文档更新更改字段采用 updateOne<Type> 名称，其中 <Type> 为该集合所含数据类型的单数名称。它会返回已更新的文档并接受以下参数：

mutation {
  updateOneMovie(
    query: { title: "The Room" }
    set: { runtime: 99 }
  ) {
    _id
    title
  }
}

更新多个文档

多文档更新变更字段使用名称 updateMany<Type>s，其中 <Type> 是集合包含的数据类型的单数名称。其会返回一个 UpdateManyPayload 文档，说明匹配和修改的字段数量，并接受以下参数：

mutation {
  updateManyMovies(
    query: { director: "Tommy Wiseau" }
    set: { director: "Tom Wiseau" }
  ) {
    matchedCount
    modifiedCount
  }
}

更新或插入单个文档

单文档 upsert 更改字段采用 upsertOne<Type> 名称，其中 <Type> 为该集合所含数据类型的单数名称。该解析程序会更新与查询参数匹配的文档；如果没有与此查询匹配的文档，则会插入新文档。它会返回已 upsert 的文档并接受以下参数：

mutation {
  upsertOneMovie(
    query: { title: "Blacksmith Scene" }
    data: {
      title: "Sandcastles in the Sand",
      director: "Robin Scherbatsky"
      runtime: 90
      year: 2002
    }
  ) {
    _id
    title
  }
}

替换单份文档

单文档替换更改字段使用名称 replaceOne<Type>，其中 <Type> 是集合包含的数据类型的单数名称。它返回替换的文档并接受以下参数：

mutation {
  replaceOneMovie(
    query: { title: "Blacksmith Scene" }
    data: {
      title: "Sandcastles in the Sand",
      director: "Robin Scherbatsky"
      runtime: 90
      year: 2002
    }
  ) {
    _id
    title
  }
}

删除单个文档

单文档删除更改字段采用 deleteOne<Type> 名称，其中 <Type> 为该集合所含数据类型的单数名称。它会返回已删除的文档并接受以下参数：

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

删除多个文档

多文档删除更改字段使用名称deleteMany<Type>s，其中<Type>是集合包含的数据类型的单数名称。它返回一个DeleteManyPayload文档，描述已删除的文档数量并接受以下参数：

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