From 1a3fffe654dd5234ed761b49d903c8247963c9ba Mon Sep 17 00:00:00 2001 From: MacondoExpress Date: Wed, 16 Aug 2023 12:11:42 +0100 Subject: [PATCH 1/3] add documentation of the filterable directive --- .../pages/reference/directives/index.adoc | 6 + .../field-configuration.adoc | 146 +++++++++++++++++- 2 files changed, 151 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/reference/directives/index.adoc b/modules/ROOT/pages/reference/directives/index.adoc index 716cc95e..6cd68052 100644 --- a/modules/ROOT/pages/reference/directives/index.adoc +++ b/modules/ROOT/pages/reference/directives/index.adoc @@ -48,6 +48,12 @@ The `@exclude` directive is used on object types to instruct them to be skipped Reference: xref::reference/directives/schema-configuration/type-configuration.adoc#_exclude_deprecated[`@exclude`] +== `@filterable` + +The `@filterable` directive defines the filters generated for a field. + +Reference: xref:reference/directives/schema-configuration/field-configuration.adoc#_filterable[`@filterable`] + == `@fulltext` The `@fulltext` directive indicates that there should be a Fulltext index inserted into the database for the specified Node and its properties. diff --git a/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc b/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc index 7e7c0b05..bcb59570 100644 --- a/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc +++ b/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc @@ -30,7 +30,7 @@ type Actor { } ---- -By using the directives `@selectable`, `@settable`, and `@relationship` it is possible to control how these fields are exposed. +By using the directives `@selectable`, `@settable`, `@filterable` and `@relationship` it is possible to control how these fields are exposed. For instance, to hide the field `age` in the Selection Set, you can use the `@selectable` directive: [source, graphql, indent=0] @@ -395,6 +395,150 @@ input ActorUpdateInput { This means the `actedIn` can be updated on an update, but it will not be available on create operations. +== `@filterable` + +This directive defines the filters generated for the field where this directive is applied. +It has two arguments: + +* **byValue**: If disabled, this field will not generates value filters. +* **byAggregate**: If disabled, this field will not generates aggregation filters. + +=== Definition + +[source, graphql, indent=0] +---- +"""Instructs @neo4j/graphql to generate filters for this field.""" +directive @filterable(byValue: Boolean! = true, byAggregate: Boolean! = true) on FIELD_DEFINITION +---- + +==== Usage + +With this definition: + +[source, graphql, indent=0] +---- +type Movie { + title: String! + description: String @filterable(byValue: false, byAggregate: false) + actors: [Actor!]! @relationship(type: "ACTED_IN", direction: IN) +} + +type Actor { + name: String! + actedIn: [Movie!]! + @relationship(type: "ACTED_IN", direction: OUT) +} +---- + +The following input fields will be generated: + +[source, graphql, indent=0] +---- +input MovieWhere { + OR: [MovieWhere!] + AND: [MovieWhere!] + NOT: MovieWhere + title: String + title_IN: [String!] + title_CONTAINS: String + title_STARTS_WITH: String + title_ENDS_WITH: String + actorsAggregate: MovieActorsAggregateInput + actors_ALL: ActorWhere + actors_NONE: ActorWhere + actors_SINGLE: ActorWhere + actors_SOME: ActorWhere + actorsConnection_ALL: MovieActorsConnectionWhere + actorsConnection_NONE: MovieActorsConnectionWhere + actorsConnection_SINGLE: MovieActorsConnectionWhere + actorsConnection_SOME: MovieActorsConnectionWhere +} + +input ActorActedInNodeAggregationWhereInput { + AND: [ActorActedInNodeAggregationWhereInput!] + OR: [ActorActedInNodeAggregationWhereInput!] + NOT: ActorActedInNodeAggregationWhereInput + title_AVERAGE_LENGTH_EQUAL: Float + title_LONGEST_LENGTH_EQUAL: Int + title_SHORTEST_LENGTH_EQUAL: Int + title_AVERAGE_LENGTH_GT: Float + title_LONGEST_LENGTH_GT: Int + title_SHORTEST_LENGTH_GT: Int + title_AVERAGE_LENGTH_GTE: Float + title_LONGEST_LENGTH_GTE: Int + title_SHORTEST_LENGTH_GTE: Int + title_AVERAGE_LENGTH_LT: Float + title_LONGEST_LENGTH_LT: Int + title_SHORTEST_LENGTH_LT: Int + title_AVERAGE_LENGTH_LTE: Float + title_LONGEST_LENGTH_LTE: Int + title_SHORTEST_LENGTH_LTE: Int +} +---- + +As shown by the generated input fields, the `description` field is not available for filtering on both value and aggregation filters. + +=== `@filterable` with Relationships + +This directive can be used along with relationship fields. +When an operation on a field is disabled this way, that relationship will not be available on top-level operations. +For example: + +[source, graphql, indent=0] +---- +type Movie { + title: String! + description: String @filterable(byValue: false, byAggregate: false) + actors: [Actor!]! @relationship(type: "ACTED_IN", direction: IN) @filterable(byValue: false, byAggregate: false) +} + +type Actor { + name: String! + actedIn: [Movie!]! + @relationship(type: "ACTED_IN", direction: OUT) + +} +---- + +The following input fields will be generated: + +[source, graphql, indent=0] +---- +input MovieWhere { + OR: [MovieWhere!] + AND: [MovieWhere!] + NOT: MovieWhere + title: String + title_IN: [String!] + title_CONTAINS: String + title_STARTS_WITH: String + title_ENDS_WITH: String +} + +input ActorActedInNodeAggregationWhereInput { + AND: [ActorActedInNodeAggregationWhereInput!] + OR: [ActorActedInNodeAggregationWhereInput!] + NOT: ActorActedInNodeAggregationWhereInput + title_AVERAGE_LENGTH_EQUAL: Float + title_LONGEST_LENGTH_EQUAL: Int + title_SHORTEST_LENGTH_EQUAL: Int + title_AVERAGE_LENGTH_GT: Float + title_LONGEST_LENGTH_GT: Int + title_SHORTEST_LENGTH_GT: Int + title_AVERAGE_LENGTH_GTE: Float + title_LONGEST_LENGTH_GTE: Int + title_SHORTEST_LENGTH_GTE: Int + title_AVERAGE_LENGTH_LT: Float + title_LONGEST_LENGTH_LT: Int + title_SHORTEST_LENGTH_LT: Int + title_AVERAGE_LENGTH_LTE: Float + title_LONGEST_LENGTH_LTE: Int + title_SHORTEST_LENGTH_LTE: Int +} +---- + +As shown by the above inputs fields, the `actors` field is not available for filtering on both value and aggregation filters. + == `@readonly` label:deprecated[] With this directive, fields will only be featured in mutations for creating and in object types for querying. From 85f6da926ed48ca890adc824e2e489b5c03b5629 Mon Sep 17 00:00:00 2001 From: MacondoExpress Date: Wed, 16 Aug 2023 17:46:27 +0100 Subject: [PATCH 2/3] Update modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc Co-authored-by: Liam-Doodson <114480811+Liam-Doodson@users.noreply.github.com> --- .../directives/schema-configuration/field-configuration.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc b/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc index bcb59570..c30f7c25 100644 --- a/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc +++ b/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc @@ -397,7 +397,7 @@ This means the `actedIn` can be updated on an update, but it will not be availab == `@filterable` -This directive defines the filters generated for the field where this directive is applied. +This directive defines the filters generated for the field to which this directive is applied. It has two arguments: * **byValue**: If disabled, this field will not generates value filters. From 162aeae78fe25264144ebfd62d0e4cea04bc11ef Mon Sep 17 00:00:00 2001 From: MacondoExpress Date: Wed, 16 Aug 2023 17:46:34 +0100 Subject: [PATCH 3/3] Update modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc Co-authored-by: Liam-Doodson <114480811+Liam-Doodson@users.noreply.github.com> --- .../directives/schema-configuration/field-configuration.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc b/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc index c30f7c25..ab4f52b7 100644 --- a/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc +++ b/modules/ROOT/pages/reference/directives/schema-configuration/field-configuration.adoc @@ -400,8 +400,8 @@ This means the `actedIn` can be updated on an update, but it will not be availab This directive defines the filters generated for the field to which this directive is applied. It has two arguments: -* **byValue**: If disabled, this field will not generates value filters. -* **byAggregate**: If disabled, this field will not generates aggregation filters. +* **byValue**: If disabled, this field will not generate value filters. +* **byAggregate**: If disabled, this field will not generate aggregation filters. === Definition