字段配置

这是 GraphQL Library 7 版本的文档。对于长期支持 (LTS) 版本 5，请参考 GraphQL Library 5 LTS 版本。

如果您需要从 GraphQL 对象类型或 GraphQL 输入对象类型中移除字段，请参考以下类型定义

type Movie @node {
    title: String!
    description: String
}

type Actor @node {
    name: String!
    age: Int
    actedIn: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT)
}

它生成了 Actor 类型

type Actor {
  name: String!
  age: Int
  actedIn(where: MovieWhere, sort: [MovieSort!]!, limit: Int, offset: Int, directed: Boolean = true): [Movie!]!
  actedInConnection(where: ActorActedInConnectionWhere, first: Int, after: String, directed: Boolean = true, sort: [ActorActedInConnectionSort!]): ActorActedInConnection!
}

通过使用 @selectable、@settable、@filterable 和 @relationship 指令，可以控制这些字段的暴露方式。例如，要隐藏选择集（Selection Set）中的 age 字段，可以使用 @selectable 指令

type Movie @node {
    title: String!
    description: String
}

type Actor @node {
    name: String!
    age: Int @selectable(onRead: false, onAggregate: false)
    actedIn: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT)
}

现在 Actor 类型如下所示

type Actor {
  name: String!
  actedIn(where: MovieWhere, sort: [MovieSort!]!, limit: Int, offset: Int, directed: Boolean = true): [Movie!]!
  actedInConnection(where: ActorActedInConnectionWhere, first: Int, after: String, directed: Boolean = true, sort: [ActorActedInConnectionSort!]): ActorActedInConnection!
}

`@relationship`

对于每个使用 @relationship 指令创建的字段，都有若干可用的嵌套操作。它们分别是 create、connect、disconnect 和 delete。

然而，这些操作并非总是必需的。@relationship 指令允许您通过使用 nestedOperations 参数来定义关系中应该启用哪些操作。

此外，@relationship 指令还会导致系统为嵌套聚合添加字段。这些字段可以通过 aggregate 参数禁用。

定义

enum NestedOperations {
    CREATE
    UPDATE
    DELETE
    CONNECT
    DISCONNECT
}

directive @relationship(
    type: String!
    queryDirection: RelationshipQueryDirection! = DEFAULT_DIRECTED
    direction: RelationshipDirection!
    properties: String
    nestedOperations: [NestedOperations!]! = [CREATE, UPDATE, DELETE, CONNECT, DISCONNECT]
    aggregate: Boolean! = true
) on FIELD_DEFINITION

使用

配置聚合

根据之前的类型定义，生成的与 Actor 相关的类型为

type Actor {
  name: String!
  actedIn(where: MovieWhere, sort: [MovieSort!]!, limit: Int, offset: Int, directed: Boolean = true): [Movie!]!
  actedInConnection(where: ActorActedInConnectionWhere, first: Int, after: String, directed: Boolean = true, sort: [ActorActedInConnectionSort!]): ActorActedInConnection!
}

type ActorActedInConnection {
  edges: [ActorActedInRelationship!]!
  totalCount: Int!
  pageInfo: PageInfo!
  aggregate: ActorMovieActedInAggregateSelection!
}

请注意，关系字段 actedIn 在 ActorActedInConnection 类型中生成了操作字段 aggregate，这允许对该关系进行聚合。可以通过在 @relationship 指令上传递 aggregate 参数来配置此行为

type Movie @node {
    title: String!
    description: String
}

type Actor @node {
    name: String!
    age: Int
    actedIn: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT, aggregate: false)
}

在这种情况下，由于 aggregate 参数被设为 false，生成的 ActorActedInConnection 类型为

type ActorActedInConnection {
  edges: [ActorActedInRelationship!]!
  totalCount: Int!
  pageInfo: PageInfo!
}

配置嵌套操作

该库生成的大部分模式（Schema）都是为了支持嵌套操作。有关使用嵌套操作的示例，请参阅 Relationships → Inserting data。

可用的嵌套操作有

enum NestedOperations {
    CREATE
    UPDATE
    DELETE
    CONNECT
    DISCONNECT
}

默认情况下，@relationship 在定义时会启用所有这些操作。要仅启用其中一部分，必须通过传递 nestedOperations 参数来指定所需的操作。

禁用嵌套创建

要禁用嵌套的 CREATE 操作，请将初始类型定义更改为

type Movie @node {
    title: String!
    description: String
}

type Actor @node {
    name: String!
    age: Int
    actedIn: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT, nestedOperations: [UPDATE, DELETE, CONNECT, DISCONNECT])
}

由于 CREATE 操作不在 nestedOperations 参数数组中，因此不再可能从 Actor 类型开始创建电影。

禁用所有嵌套操作

如果不需要任何嵌套操作，可以通过传递一个空数组来禁用所有嵌套操作

type Movie @node {
    title: String!
    description: String
}

type Actor @node {
    name: String!
    age: Int
    actedIn: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT, nestedOperations: [])
}

`@selectable`

该指令设置字段在查询和聚合中的可用性。它有两个参数

onRead：如果禁用，该字段在查询和订阅中不可用。
onAggregate：如果禁用，聚合在此字段上不可用。

定义

"""Instructs @neo4j/graphql to generate this field for selectable fields."""
directive @selectable(onRead: Boolean! = true, onAggregate: Boolean! = true) on FIELD_DEFINITION

用法

通过以下定义

type Movie @node {
    title: String!
    description: String @selectable(onRead: false, onAggregate: true)
}

生成的模式中的 Movie 类型如下所示

type Movie {
    title: String!
}

这意味着无法查询描述（description），无论是在顶层还是在嵌套级别。但是，聚合在两者上都是可用的

type MovieAggregateNode {
  title: StringAggregateSelection!
  description: StringAggregateSelection!
}

如果您想从 MovieAggregateNode 中移除 description 字段，需要将 onAggregate 的值更改为 false

type Movie @node {
    title: String!
    description: String @selectable(onRead: false, onAggregate: false)
}

@selectable 与关系

该指令可以与关系字段一起使用。

根据之前的类型定义，生成的 Actor 类型为

type Actor {
  name: String!
  actedIn(where: MovieWhere, sort: [MovieSort!]!, limit: Int, offset: Int, directed: Boolean = true): [Movie!]!
  actedInConnection(where: ActorActedInConnectionWhere, first: Int, after: String, directed: Boolean = true, sort: [ActorActedInConnectionSort!]): ActorActedInConnection!
}

这意味着可以通过同名的生成字段 actedIn 和字段 actedInConnection 查询 actedIn 字段。为了避免这种情况，需要使用 @selectable 指令。例如，这些类型定义

type Movie @node {
    title: String!
    description: String
}

type Actor @node {
    name: String!
    actedIn: [Movie!]!
        @relationship(type: "ACTED_IN", direction: OUT)
        @selectable(onRead: false, onAggregate: false)
}

生成 Actor 类型

type Actor {
  name: String!
  actedInConnection(where: ActorActedInConnectionWhere, first: Int, after: String, directed: Boolean = true, sort: [ActorActedInConnectionSort!]): ActorActedInConnection!
}

type ActorActedInConnection {
  aggregate: ActorMovieActedInAggregateSelection!
}

请注意 aggregate 字段仍然存在于 ActorActedInConnection 类型上，且不受 onAggregate 参数的影响。

要禁用 aggregate 字段的生成，请参阅 @relationship 指令的 aggregate 参数。

`@settable`

该指令设置输入字段在创建和更新变更（mutations）中的可用性。它有两个参数

onCreate：如果禁用，该字段在创建操作中不可用。
onUpdate：如果禁用，该字段在更新操作中不可用。

定义

"""Instructs @neo4j/graphql to generate this input field for mutation."""
directive @settable(onCreate: Boolean! = true, onUpdate: Boolean! = true) on FIELD_DEFINITION

用法

通过此定义

type Movie @node {
    title: String!
    description: String @settable(onCreate: true, onUpdate: false)
}

type Actor @node {
    name: String!
    actedIn: [Movie!]!
        @relationship(type: "ACTED_IN", direction: OUT)
}

生成了以下输入字段

input MovieCreateInput {
    description: String
    title: String!
}

input MovieUpdateInput {
  title: StringScalarMutations
}

这意味着可以在创建时设置描述，但在更新操作中不可用。

@settable 与关系

该指令可以与关系字段一起使用。当以这种方式禁用字段上的操作时，该关系在顶层操作中将不再可用。例如

type Movie @node {
    title: String!
    description: String
}

type Actor @node {
    name: String!
    actedIn: [Movie!]!
        @relationship(type: "ACTED_IN", direction: OUT)
        @settable(onCreate: false, onUpdate: true)
}

生成了以下输入字段

input ActorCreateInput {
  name: String!
}

input ActorUpdateInput {
  name: StringScalarMutations
  actedIn: [ActorActedInUpdateFieldInput!]
}

这意味着 actedIn 可以在更新时进行更新，但在 create 操作中不再可用。

`@sortable`

该指令设置输入字段的排序可用性。它只有一个参数

byValue：默认为 true。如果禁用，该字段将不可用于排序。

定义

"""Instructs @neo4j/graphql to generate sorting inputs for this field."""
directive @sortable(byValue: Boolean! = true) on FIELD_DEFINITION

用法

通过此定义

type Movie @node {
    title: String!
    description: String! @sortable(byValue: false)
}

为 Movies 生成了以下输入类型

"""
Fields to sort Movies by. The order in which sorts are applied is not guaranteed when specifying many fields in one MovieSort object.
"""
input MovieSort {
  title: SortDirection
}

电影可以按标题排序，但不能按描述排序

这是有效的

query {
  movies(sort: {title: DESC}) {
    title
  }
}

这是无效的

query {
  movies(sort: {description: DESC}) {
    title
  }
}

如果没有字段是可排序的，则不会生成 MovieSort 类型，且 sort 输入将不可用。

`@filterable`

该指令定义了应用此指令的字段所生成的过滤器。它有两个参数

byValue：如果禁用，该字段不会生成值过滤器。
byAggregate：如果禁用，该字段不会生成聚合过滤器。

定义

"""Instructs @neo4j/graphql to generate filters for this field."""
directive @filterable(byValue: Boolean! = true, byAggregate: Boolean! = true) on FIELD_DEFINITION

用法

通过此定义

type Movie @node {
    title: String!
    description: String @filterable(byValue: false, byAggregate: false)
    actors: [Actor!]! @relationship(type: "ACTED_IN", direction: IN)
}

type Actor @node {
    name: String!
    actedIn: [Movie!]!
        @relationship(type: "ACTED_IN", direction: OUT)
}

生成了以下输入字段

input MovieWhere {
  OR: [MovieWhere!]
  AND: [MovieWhere!]
  NOT: MovieWhere
  title: StringScalarFilters
  actors: ActorRelationshipFilters
  actorsConnection: MovieActorsConnectionFilters
}


input ActorActedInNodeAggregationWhereInput {
  AND: [ActorActedInNodeAggregationWhereInput!]
  OR: [ActorActedInNodeAggregationWhereInput!]
  NOT: ActorActedInNodeAggregationWhereInput
  title: StringScalarAggregationFilters
}

如生成的输入字段所示，description 字段在值过滤器和聚合过滤器中均不可用。

@filterable 与关系

该指令可以与关系字段一起使用。当以这种方式禁用字段上的操作时，该关系在顶层操作中将不再可用。例如

type Movie @node {
    title: String!
    description: String @filterable(byValue: false, byAggregate: false)
    actors: [Actor!]! @relationship(type: "ACTED_IN", direction: IN) @filterable(byValue: false, byAggregate: false)
}

type Actor @node {
    name: String!
    actedIn: [Movie!]!
        @relationship(type: "ACTED_IN", direction: OUT)

}

生成了以下输入字段

input MovieWhere {
  OR: [MovieWhere!]
  AND: [MovieWhere!]
  NOT: MovieWhere
  title: StringScalarFilters
}

input ActorActedInNodeAggregationWhereInput {
  AND: [ActorActedInNodeAggregationWhereInput!]
  OR: [ActorActedInNodeAggregationWhereInput!]
  NOT: ActorActedInNodeAggregationWhereInput
  title: StringScalarAggregationFilters
}

如之前的输入字段所示，actors 字段在值过滤器和聚合过滤器中均不可用。