From e373b39749d6c3415ffbdf78283e7fba1e46a524 Mon Sep 17 00:00:00 2001 From: MacondoExpress Date: Mon, 21 Oct 2024 10:44:15 +0100 Subject: [PATCH 1/7] add breaking changes/additions/deprecations on migration guide --- modules/ROOT/pages/migration/index.adoc | 284 ++++++++++++++++++++++++ 1 file changed, 284 insertions(+) diff --git a/modules/ROOT/pages/migration/index.adoc b/modules/ROOT/pages/migration/index.adoc index e88eec49..60f278b6 100644 --- a/modules/ROOT/pages/migration/index.adoc +++ b/modules/ROOT/pages/migration/index.adoc @@ -20,6 +20,128 @@ npm update @neo4j/graphql Here is a list of all the breaking changes from version 5.0.0 to 6.0.0. +=== Changed minimum Node.js version to 20.0.0 + +The minimum Node.js version required to run the Neo4j GraphQL Library is now 20.0.0. + +=== Changed minimum Noo4j version to 5.0.0 + +The minimum Neo4j version required to run the Neo4j GraphQL Library is now 5.0.0. + +=== Invalid filters in Aggregation filter inputs are being removed + +GraphQL input types used for aggregation filters contained some filters that did not rely on aggregating functions. +These filters were deprecated and are now removed from the generated schema. + +To see the aggregating functions supported on filtering refer to xref:/queries-aggregations/filtering.adoc#_aggregation_filtering[Aggregation filtering], + + +=== String aggregation filters that are not using _LENGTH are removed + +String aggregations are computed using lengths, and the `_LENGTH` suffix is now required for all string aggregation filters. + +[cols="1,1"] +|=== +|Before | Now + +a| +[source, graphql, indent=0] +---- +{ + movies( + where: { actorsAggregate: { node: { name_AVERAGE_EQUAL: 1.5 } } } + ) { + title + } +} + +---- +a| +[source, graphql, indent=0] +---- +{ + movies( + where: { actorsAggregate: { node: { name_AVERAGE_LENGTH_EQUAL: 1.5 } } } + ) { + title + } +} + +---- +|=== + + + +=== Removed the deprecated `options` argument from `assertIndexesAndConstraints` + +The deprecated `options` argument from the `assertIndexesAndConstraints` utility has been removed. +Database migrations are outside of the scope of the Neo4j GraphQL Library, and all indexes and constraints will have to be managed manually. + + +=== Removed top-level argument that are not `update` from the top-level update + +The top-level `update` mutation now only accepts the `update` argument. + +The nested operation: + + - create + - create + - delete + - connect + - disconnect + - connectOrCreate + +Are now moved into the `update` argument. + +[cols="1,1"] +|=== +|Before | Now + +a| +[source, graphql, indent=0] +---- +mutation UpdatePeople { + updatePeople(create: { movies: { node: { title: "The Good" } } }) { + people { + name + } + } +} +---- +a| +[source, graphql, indent=0] +---- +mutation UpdatePeople { + updatePeople(create: { movies: { node: { title: "The Good" } } }) { + people { + name + } + } +} +---- +|=== + + +=== Changed the sort argument for interfaces Connection fields + +The sort argument for interfaces Connection fields is now a list of non nullable element. + +[cols="1,1"] +|=== +|Before | Now + +a| +[source, graphql, indent=0] +---- +productionsConnection(after: String, first: Int, sort: [ProductionSort], where: ProductionWhere): ProductionsConnection! +---- +a| +[source, graphql, indent=0] +---- +productionsConnection(after: String, first: Int, sort: [ProductionSort!], where: ProductionWhere): ProductionsConnection! +---- +|=== + === The deprecated `_NOT` filters are no longer supported The following deprecated `NOT` filters are removed from the schema since they are no longer supported: @@ -94,6 +216,88 @@ query { ---- |=== + +=== The `excludeDeprecatedFields` setting in the Neo4jFeaturesSettings has been changed + +As in version 6.x many of the deprecated fields have been removed, the `excludeDeprecatedFields` setting has been modified to reflect these changes. + +The following fields have been removed: + + + - `bookmark` + - `negationFilters` + - `arrayFilters` + - `stringAggregation` + - `aggregationFilters` + - `nestedUpdateOperationsFields` + +The following fields have been added: + + + - `implicitEqualFilters` + - `deprecatedOptionsArgument` + - `directedArgument` + + +== Additions + +=== Added count_EQ as alternative to the deprecated count + +The `count_EQ` filter is now available as an alternative to the deprecated `count` filter. + +[cols="1,1"] +|=== +|Before | Now + +a| +[source, graphql, indent=0] +---- +{ + movies(where: { actorsAggregate: { count: 10 } }) { + title + } +} +---- +a| +[source, graphql, indent=0] +---- +{ + movies(where: { actorsAggregate: { count_EQ: 10 } }) { + title + } +} +---- +|=== + +=== Added the _EQ filter as alternative of the deprecated implicit equal filters + +The `_EQ` filter is now available as an alternative to the deprecated implicit equal filters. + +[cols="1,1"] +|=== +|Before | Now + +a| +[source, graphql, indent=0] +---- +{ + movies(where: { title: "The Matrix" }) { + title + } +} + +---- +a| +[source, graphql, indent=0] +---- +{ + movies(where: { title_EQ: "The Matrix" }) { + title + } +} +---- +|=== + == Deprecations and warnings === `@node` will have to be explicitly defined @@ -132,3 +336,83 @@ type Person @node { ---- |=== +=== Deprecated the implicit equality filters + +Previously when a field in a filter was present in filter without specifying the operator, it was treated as an equality filter. + +This behavior is now deprecated and will be removed in the future. Please, use the `_EQ` filter. + +[cols="1,1"] +|=== +|Before | Now + +a| +[source, graphql, indent=0] +---- +{ + movies(where: { title: "The Matrix" }) { + title + } +} +---- +a| +[source, graphql, indent=0] +---- +{ + movies(where: { title_EQ: "The Matrix" }) { + title + } +} +---- +|=== + +=== Deprecated pagination `options`` argument + +The `options` argument in query and `@relationship` fields is deprecated and will be removed in the future. Use the `limit`, `offset` and `sort` arguments instead. + +[cols="1,1"] +|=== +|Before | Now + +a| +[source, graphql, indent=0] +---- +{ + movies(options: { limit: 10, offset: 10, sort: { title: ASC } }) { + title + } +} +---- +a| +[source, graphql, indent=0] +---- +{ + movies(limit: 10, offset: 10, sort: { title: ASC }) { + title + } +} +---- +|=== + + +=== Deprecated `directed` argument in `@relationship` fields + +The `directed` argument was used to change the query direction of the relationship field at the query time, for instance: + + +[source, graphql, indent=0] +---- +{ + movies { + title + actors(directed: false) { + name + } + } +} +---- + +The `directed` argument in `@relationship` fields is deprecated and will be removed in the future. +Please configure this using `queryDirection` and `direction` arguments of the `@relationship` directive. + + From cdf0f7c8deb575bdec45a429cc903f8ed4b899da Mon Sep 17 00:00:00 2001 From: MacondoExpress Date: Mon, 21 Oct 2024 15:25:00 +0100 Subject: [PATCH 2/7] add improvements to migration guide --- modules/ROOT/pages/migration/index.adoc | 52 ++++++++++++++++++------- 1 file changed, 37 insertions(+), 15 deletions(-) diff --git a/modules/ROOT/pages/migration/index.adoc b/modules/ROOT/pages/migration/index.adoc index f8b1a2c4..9b73baf5 100644 --- a/modules/ROOT/pages/migration/index.adoc +++ b/modules/ROOT/pages/migration/index.adoc @@ -24,19 +24,45 @@ Here is a list of all the breaking changes from version 5.0.0 to 6.0.0. The minimum Node.js version required to run the Neo4j GraphQL Library is now 20.0.0. -=== Changed minimum Noo4j version to 5.0.0 +=== Changed minimum Neo4j version to 5.0.0 The minimum Neo4j version required to run the Neo4j GraphQL Library is now 5.0.0. +=== Removed the deprecated `@relationship` implicit `_SOME` filters + +The deprecated `@relationship` filter without the operator suffix has been removed in favor of the `_SOME` filter. + +[cols="1,1"] +|=== +|Before | Now + +a| +[source, graphql, indent=0] +---- +{ + movies(where: { actors: { name: "Keanu" } }) { + title + } +} +---- +a| +[source, graphql, indent=0] +---- +{ + movies(where: { actors_SOME: { name: "Keanu" } }) { + title + } +} +---- +|=== + === Invalid filters in Aggregation filter inputs are being removed -GraphQL input types used for aggregation filters contained some filters that did not rely on aggregating functions. -These filters were deprecated and are now removed from the generated schema. +In previous versions of the Library, the input used for aggregation filters contained filters that did not rely on aggregating functions. Those filters were deprecated in previous Library versions and removed from the schema. To see the aggregating functions supported on filtering refer to xref:/queries-aggregations/filtering.adoc#_aggregation_filtering[Aggregation filtering], - -=== String aggregation filters that are not using _LENGTH are removed +=== String aggregation filters that are not using `_LENGTH` are removed String aggregations are computed using lengths, and the `_LENGTH` suffix is now required for all string aggregation filters. @@ -70,8 +96,6 @@ a| ---- |=== - - === Removed the deprecated `options` argument from `assertIndexesAndConstraints` The deprecated `options` argument from the `assertIndexesAndConstraints` utility has been removed. @@ -121,7 +145,6 @@ mutation UpdatePeople { ---- |=== - === Changed the sort argument for interfaces Connection fields The sort argument for interfaces Connection fields is now a list of non nullable element. @@ -155,7 +178,6 @@ The following deprecated `NOT` filters are removed from the schema since they ar - `node_NOT` - `edge_NOT` - To achieve the same in version 6.x of the GraphQL library, use the xref:/queries-aggregations/filtering.adoc#_boolean_operators[boolean `NOT` operator] instead. [cols="1,1"] @@ -216,6 +238,10 @@ query { ---- |=== +=== The bookmark field has been removed from the schema + +The bookmark field has been removed from the Mutation info response as it is no longer required. + === The `excludeDeprecatedFields` setting in the Neo4jFeaturesSettings has been changed @@ -238,10 +264,9 @@ The following fields have been added: - `deprecatedOptionsArgument` - `directedArgument` - == Additions -=== Added count_EQ as alternative to the deprecated count +=== Added `count_EQ` as alternative to the deprecated count The `count_EQ` filter is now available as an alternative to the deprecated `count` filter. @@ -336,7 +361,6 @@ query { ---- |=== - === `@node` will have to be explicitly defined In the future, types without the `@node` directive will no longer be treated as Neo4j nodes. @@ -403,7 +427,7 @@ a| ---- |=== -=== Deprecated pagination `options`` argument +=== Deprecated pagination `options` argument The `options` argument in query and `@relationship` fields is deprecated and will be removed in the future. Use the `limit`, `offset` and `sort` arguments instead. @@ -451,5 +475,3 @@ The `directed` argument was used to change the query direction of the relationsh The `directed` argument in `@relationship` fields is deprecated and will be removed in the future. Please configure this using `queryDirection` and `direction` arguments of the `@relationship` directive. - - From ca848436bdeba2fa2ff76a50b28f9def5eff16d2 Mon Sep 17 00:00:00 2001 From: MacondoExpress Date: Tue, 22 Oct 2024 11:35:01 +0100 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com> Co-authored-by: Michael Webb <28074382+mjfwebb@users.noreply.github.com> --- modules/ROOT/pages/migration/index.adoc | 30 ++++++++++++------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/modules/ROOT/pages/migration/index.adoc b/modules/ROOT/pages/migration/index.adoc index 9b73baf5..3ed1f98e 100644 --- a/modules/ROOT/pages/migration/index.adoc +++ b/modules/ROOT/pages/migration/index.adoc @@ -145,9 +145,9 @@ mutation UpdatePeople { ---- |=== -=== Changed the sort argument for interfaces Connection fields +=== Changed the sort argument for interfaces connection fields -The sort argument for interfaces Connection fields is now a list of non nullable element. +The sort argument for interfaces connection fields is now a list of non-nullable elements. [cols="1,1"] |=== @@ -238,18 +238,17 @@ query { ---- |=== -=== The bookmark field has been removed from the schema +=== Removed the bookmark field from the schema -The bookmark field has been removed from the Mutation info response as it is no longer required. +The bookmark field has been removed from the mutation information responses (CreateInfo, UpdateInfo, DeleteInfo) as it is no longer required. -=== The `excludeDeprecatedFields` setting in the Neo4jFeaturesSettings has been changed +=== Changed the `excludeDeprecatedFields` setting in the Neo4jFeaturesSettings As in version 6.x many of the deprecated fields have been removed, the `excludeDeprecatedFields` setting has been modified to reflect these changes. The following fields have been removed: - - `bookmark` - `negationFilters` - `arrayFilters` @@ -266,7 +265,7 @@ The following fields have been added: == Additions -=== Added `count_EQ` as alternative to the deprecated count +=== Added `count_EQ` as an alternative to the deprecated `count` filter The `count_EQ` filter is now available as an alternative to the deprecated `count` filter. @@ -294,9 +293,9 @@ a| ---- |=== -=== Added the _EQ filter as alternative of the deprecated implicit equal filters +=== Added the `_EQ` filter as an alternative to the deprecated implicit "equal" filter -The `_EQ` filter is now available as an alternative to the deprecated implicit equal filters. +The `_EQ` filter is now available as an alternative to the deprecated implicit "equal" filter. [cols="1,1"] |=== @@ -399,9 +398,9 @@ type Person @node { === Deprecated the implicit equality filters -Previously when a field in a filter was present in filter without specifying the operator, it was treated as an equality filter. - -This behavior is now deprecated and will be removed in the future. Please, use the `_EQ` filter. +Previously, if a field was present in a filter without specifying the operator, it was treated as an equality filter. +This behavior is now deprecated and will be removed in the future. +Use the `_EQ` filter instead. [cols="1,1"] |=== @@ -429,7 +428,8 @@ a| === Deprecated pagination `options` argument -The `options` argument in query and `@relationship` fields is deprecated and will be removed in the future. Use the `limit`, `offset` and `sort` arguments instead. +The `options` argument in query and `@relationship` fields is deprecated and will be removed in the future. +Use the `limit`, `offset` and `sort` arguments instead. [cols="1,1"] |=== @@ -458,7 +458,7 @@ a| === Deprecated `directed` argument in `@relationship` fields -The `directed` argument was used to change the query direction of the relationship field at the query time, for instance: +The `directed` argument was used to change the query direction of the relationship field at query time, for instance: [source, graphql, indent=0] @@ -474,4 +474,4 @@ The `directed` argument was used to change the query direction of the relationsh ---- The `directed` argument in `@relationship` fields is deprecated and will be removed in the future. -Please configure this using `queryDirection` and `direction` arguments of the `@relationship` directive. +Configure the query direction via the `queryDirection` and `direction` arguments of the `@relationship` directive instead. From 2404cfde2dcad129fc8d30baf88cee2046dc346e Mon Sep 17 00:00:00 2001 From: MacondoExpress Date: Tue, 22 Oct 2024 11:36:03 +0100 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com> Co-authored-by: Michael Webb <28074382+mjfwebb@users.noreply.github.com> --- modules/ROOT/pages/migration/index.adoc | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/migration/index.adoc b/modules/ROOT/pages/migration/index.adoc index 3ed1f98e..bd212d4a 100644 --- a/modules/ROOT/pages/migration/index.adoc +++ b/modules/ROOT/pages/migration/index.adoc @@ -28,9 +28,9 @@ The minimum Node.js version required to run the Neo4j GraphQL Library is now 20. The minimum Neo4j version required to run the Neo4j GraphQL Library is now 5.0.0. -=== Removed the deprecated `@relationship` implicit `_SOME` filters +=== Removed the deprecated implicit "some" filter from `@relationship` -The deprecated `@relationship` filter without the operator suffix has been removed in favor of the `_SOME` filter. +The deprecated "some" filter without operator suffix has been removed from `@relationship` in favor of the explicit `_SOME` filter. [cols="1,1"] |=== @@ -56,15 +56,16 @@ a| ---- |=== -=== Invalid filters in Aggregation filter inputs are being removed +=== Removed invalid filters in aggregation filter inputs -In previous versions of the Library, the input used for aggregation filters contained filters that did not rely on aggregating functions. Those filters were deprecated in previous Library versions and removed from the schema. +In previous versions of the library, the input used for aggregation filters contained filters that did not rely on aggregating functions. +These filters were deprecated in previous library versions and are removed from the schema. To see the aggregating functions supported on filtering refer to xref:/queries-aggregations/filtering.adoc#_aggregation_filtering[Aggregation filtering], -=== String aggregation filters that are not using `_LENGTH` are removed +=== Removed string aggregation filters not using `_LENGTH` -String aggregations are computed using lengths, and the `_LENGTH` suffix is now required for all string aggregation filters. +Since string aggregations are computed using length, they now require the `_LENGTH` suffix for all string aggregation filters. [cols="1,1"] |=== @@ -102,7 +103,7 @@ The deprecated `options` argument from the `assertIndexesAndConstraints` utility Database migrations are outside of the scope of the Neo4j GraphQL Library, and all indexes and constraints will have to be managed manually. -=== Removed top-level argument that are not `update` from the top-level update +=== Removed top-level arguments that are not `update` from the top-level update The top-level `update` mutation now only accepts the `update` argument. From 141bfc19007a736b5761c20f21307321bc8ce385 Mon Sep 17 00:00:00 2001 From: MacondoExpress Date: Tue, 22 Oct 2024 11:36:37 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Michael Webb <28074382+mjfwebb@users.noreply.github.com> --- modules/ROOT/pages/migration/index.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/modules/ROOT/pages/migration/index.adoc b/modules/ROOT/pages/migration/index.adoc index bd212d4a..4a596aa1 100644 --- a/modules/ROOT/pages/migration/index.adoc +++ b/modules/ROOT/pages/migration/index.adoc @@ -107,7 +107,7 @@ Database migrations are outside of the scope of the Neo4j GraphQL Library, and a The top-level `update` mutation now only accepts the `update` argument. -The nested operation: +The following nested operations have been moved into the `update` argument: - create - create @@ -116,8 +116,6 @@ The nested operation: - disconnect - connectOrCreate -Are now moved into the `update` argument. - [cols="1,1"] |=== |Before | Now From dc86c3aef8bd24b83ebb99b47459d1e2968f8950 Mon Sep 17 00:00:00 2001 From: MacondoExpress Date: Tue, 22 Oct 2024 11:53:38 +0100 Subject: [PATCH 6/7] corrected duplicated example on update-create --- modules/ROOT/pages/migration/index.adoc | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/modules/ROOT/pages/migration/index.adoc b/modules/ROOT/pages/migration/index.adoc index 4a596aa1..a16a6368 100644 --- a/modules/ROOT/pages/migration/index.adoc +++ b/modules/ROOT/pages/migration/index.adoc @@ -123,23 +123,25 @@ The following nested operations have been moved into the `update` argument: a| [source, graphql, indent=0] ---- -mutation UpdatePeople { - updatePeople(create: { movies: { node: { title: "The Good" } } }) { - people { - name - } +mutation UpdateActors { + updateActors(create: { movies: { node: { title: "The Good" } } }) { + actors { + name } + } } ---- a| [source, graphql, indent=0] ---- -mutation UpdatePeople { - updatePeople(create: { movies: { node: { title: "The Good" } } }) { - people { - name - } +mutation UpdateActors { + updateActors( + update: { movies: { create: { node: { title: "The Good" } } } } + ) { + actors { + name } + } } ---- |=== From afcaee5af94a915dcd053a67062cae793c8b8c7c Mon Sep 17 00:00:00 2001 From: MacondoExpress Date: Tue, 22 Oct 2024 14:19:45 +0100 Subject: [PATCH 7/7] apply suggestion from PR review on migration guide --- modules/ROOT/pages/migration/index.adoc | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/modules/ROOT/pages/migration/index.adoc b/modules/ROOT/pages/migration/index.adoc index a16a6368..de9eba25 100644 --- a/modules/ROOT/pages/migration/index.adoc +++ b/modules/ROOT/pages/migration/index.adoc @@ -30,7 +30,7 @@ The minimum Neo4j version required to run the Neo4j GraphQL Library is now 5.0.0 === Removed the deprecated implicit "some" filter from `@relationship` -The deprecated "some" filter without operator suffix has been removed from `@relationship` in favor of the explicit `_SOME` filter. +The deprecated implicit "some" filter without operator suffix has been removed from `@relationship` in favor of the explicit `_SOME` filter. [cols="1,1"] |=== @@ -109,12 +109,11 @@ The top-level `update` mutation now only accepts the `update` argument. The following nested operations have been moved into the `update` argument: - - create - - create - - delete - - connect - - disconnect - - connectOrCreate + - `create` + - `delete` + - `connect` + - `disconnect` + - `connectOrCreate` [cols="1,1"] |=== @@ -241,7 +240,7 @@ query { === Removed the bookmark field from the schema -The bookmark field has been removed from the mutation information responses (CreateInfo, UpdateInfo, DeleteInfo) as it is no longer required. +The bookmark field has been removed from the mutation `info` responses (`CreateInfo`, `UpdateInfo`, `DeleteInfo`) as it is no longer required. === Changed the `excludeDeprecatedFields` setting in the Neo4jFeaturesSettings @@ -266,7 +265,7 @@ The following fields have been added: == Additions -=== Added `count_EQ` as an alternative to the deprecated `count` filter +=== Added the `_EQ` filter as an alternative to the deprecated implicit equal filters The `count_EQ` filter is now available as an alternative to the deprecated `count` filter. @@ -459,7 +458,7 @@ a| === Deprecated `directed` argument in `@relationship` fields -The `directed` argument was used to change the query direction of the relationship field at query time, for instance: +The `directed` argument was used to change the query direction of the relationship field at the query time, for instance: [source, graphql, indent=0]