字段配置

这是 GraphQL 库版本 7 的文档。有关长期支持 (LTS) 版本 5，请参阅 GraphQL 库版本 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，可以控制这些字段的暴露方式。例如，要在选择集中隐藏字段 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!
}

配置嵌套操作

库生成的大部分模式都需要支持嵌套操作。如 @relationship → 插入数据中所述，这些操作由 @relationship 指令启用。

可用的嵌套操作有

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!
}

这意味着描述无法被查询，无论是在顶级还是嵌套级别。然而，聚合在这两种情况下都可用

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 字段可以从同名生成的 actedIn 字段和 actedInConnection 字段中查询。为了避免这种情况，需要使用 @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`

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

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 操作中不再可用。

`@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 字段在值过滤器和聚合过滤器中都不可用于筛选。