Add docs for new COLLECT subqueries #398

gem-neo4j · 2023-02-08T13:23:09Z

Docs for Collect Subqueries: https://github.com/neo-technology/neo4j/pull/19242

gem-neo4j · 2023-02-08T13:23:51Z

Collect Subqueries

neo-technology-commit-status-publisher · 2023-02-08T13:24:54Z

Looks like you've updated the documentation!

Check out your changes at https://neo4j-docs-cypher-398.surge.sh

ncordon · 2023-02-16T16:28:49Z

modules/ROOT/pages/syntax/expressions.adoc

We could avoid using what we want to explain (collect) in the definition if possible?

Suggested change

A `COLLECT` subquery expression can be used to collect the rows returned by the subquery into a list.

A `COLLECT` subquery expression can be used to create a list with the rows returned by a given subquery.

ncordon · 2023-02-16T16:35:41Z

modules/ROOT/pages/syntax/expressions.adoc

Maybe give an example where we have shadowing and the query would fail?

ncordon

Could we add an example with several pattern expressions in the query?

JPryce-Aklundh

Looks very good - just a few suggestions 👍
And the test has picked up one failed query

JPryce-Aklundh · 2023-02-23T11:55:05Z

modules/ROOT/pages/syntax/expressions.adoc

Suggested change

Any non-writing query is allowed. `COLLECT` subqueries differ from `COUNT` and `EXISTS` subqueries in that the final `RETURN` clause is mandatory.

Any non-writing query is allowed.

`COLLECT` subqueries differ from `COUNT` and `EXISTS` subqueries in that the final `RETURN` clause is mandatory.

JPryce-Aklundh · 2023-02-23T12:03:16Z

modules/ROOT/pages/syntax/expressions.adoc

Looking at the query, my first thought was why does this show me who has more than one dog? Taking a look at the graph, I understand what you mean, but would it not be more clear to write "outputs the owners of the dog named Ozzy"?

JPryce-Aklundh · 2023-02-23T12:05:50Z

modules/ROOT/pages/syntax/expressions.adoc

Could the second "scope" be modified accordingly? (or in some other way to clarify further what "this" scope means?)

Suggested change

Variables introduced by the `MATCH` clause and the outside scope can be used in this scope.

Variables introduced by the `MATCH` clause and the outside scope can be used in the inner scope.

JPryce-Aklundh · 2023-02-23T12:07:52Z

modules/ROOT/pages/syntax/expressions.adoc

Suggested change

In the below example, the outer variable `name` is being shadowed and will result in an error.

In the below example, the outer variable `name` is shadowed and will therefore throw an error.

JPryce-Aklundh · 2023-02-23T12:11:15Z

modules/ROOT/pages/syntax/expressions.adoc

What is restricted? The use of COLLECT altogether when using admin commands, or its location when using admin commands? I am using the former, so maybe this could work:

Suggested change

`COLLECT` can be used in any position in a query, with the exception of administration commands, where it is restricted.

`COLLECT` can be used in any position in a query, with the exception of administration commands, where the `COLLECT` expression is restricted.

JPryce-Aklundh · 2023-02-23T12:12:10Z

modules/ROOT/pages/syntax/expressions.adoc

Suggested change

See a few examples below:

See a few examples below of how `COLLECT` can be used in different positions within a query:

JPryce-Aklundh · 2023-02-23T12:14:34Z

modules/ROOT/pages/syntax/expressions.adoc

Is the blank line at the end of the query intentional? I notice it below as well.

Suggested change

----

MATCH (person:Person) WHERE person.name = "Peter"

SET person.dogNames = COLLECT { MATCH (person)-[:HAS_DOG]->(d:Dog) RETURN d.name }

RETURN person.dogNames as dogNames

----

----

MATCH (person:Person) WHERE person.name = "Peter"

SET person.dogNames = COLLECT { MATCH (person)-[:HAS_DOG]->(d:Dog) RETURN d.name }

RETURN person.dogNames as dogNames

----

JPryce-Aklundh

Looks good! Just a few suggestions from me 👍

JPryce-Aklundh · 2023-02-28T13:03:11Z

modules/ROOT/pages/syntax/expressions.adoc

Suggested change

The following query collects all persons by their dog's names,

The following query collects all persons by their dogs' names,

JPryce-Aklundh · 2023-02-28T13:05:45Z

modules/ROOT/pages/syntax/expressions.adoc

Suggested change

When using `COLLECT` over the function `collect()` it is important to note that they have different behavior surrounding `null` values.

`COLLECT` does not handle `null` values in the same way that function `collect()` does.

JPryce-Aklundh · 2023-02-28T13:06:04Z

modules/ROOT/pages/syntax/expressions.adoc

Suggested change

The `collect()` function automatically removes null values.

The `collect()` function automatically removes `null` values.

JPryce-Aklundh · 2023-02-28T13:06:52Z

modules/ROOT/pages/syntax/expressions.adoc

Suggested change

`COLLECT` will not remove them automatically, however, they can be removed by simply adding a filtering step in the subquery.

`COLLECT` will not remove `null values` automatically.

However, they can be removed by adding a filtering step in the subquery.

Should the backticks be around just null here?

Yeah, sorry!

gem-neo4j added team-cypher-surface dev labels Feb 8, 2023

gem-neo4j force-pushed the dev_collect_subqueries branch from b37b5fa to 91f3794 Compare February 10, 2023 13:40

gem-neo4j marked this pull request as ready for review February 10, 2023 15:41

gem-neo4j force-pushed the dev_collect_subqueries branch from 91f3794 to 9f1e870 Compare February 10, 2023 15:48

Lojjs assigned ncordon Feb 13, 2023

ncordon reviewed Feb 16, 2023

View reviewed changes

modules/ROOT/pages/syntax/expressions.adoc Outdated

Copy link

Contributor

ncordon Feb 16, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe give an example where we have shadowing and the query would fail?

ncordon reviewed Feb 16, 2023

View reviewed changes

gem-neo4j force-pushed the dev_collect_subqueries branch from 9f1e870 to 98c8278 Compare February 20, 2023 12:38

JPryce-Aklundh reviewed Feb 23, 2023

View reviewed changes

gem-neo4j force-pushed the dev_collect_subqueries branch from 8f17429 to 3ef52fd Compare February 28, 2023 09:47

JPryce-Aklundh approved these changes Feb 28, 2023

View reviewed changes

ncordon approved these changes Mar 1, 2023

View reviewed changes

gem-neo4j added the 5.6 label Mar 1, 2023

gem-neo4j added 5 commits March 1, 2023 12:55

Add docs for new COLLECT subqueries

cb1749f

PR review updates

5fd551c

PR review updates

7ba4733

Add example to illustrate how COLLECT differs with nulls from collect()

f8efed1

PR review updates

d0d9cd9

gem-neo4j force-pushed the dev_collect_subqueries branch from 349c85e to d0d9cd9 Compare March 1, 2023 11:55

Mark failure example as test-fail

f6801f9

JPryce-Aklundh merged commit 77a7c38 into neo4j:dev Mar 1, 2023

JPryce-Aklundh deleted the dev_collect_subqueries branch March 1, 2023 12:58

	A `COLLECT` subquery expression can be used to collect the rows returned by the subquery into a list.
	A `COLLECT` subquery expression can be used to create a list with the rows returned by a given subquery.

	Any non-writing query is allowed. `COLLECT` subqueries differ from `COUNT` and `EXISTS` subqueries in that the final `RETURN` clause is mandatory.
	Any non-writing query is allowed.
	`COLLECT` subqueries differ from `COUNT` and `EXISTS` subqueries in that the final `RETURN` clause is mandatory.

	Variables introduced by the `MATCH` clause and the outside scope can be used in this scope.
	Variables introduced by the `MATCH` clause and the outside scope can be used in the inner scope.

	In the below example, the outer variable `name` is being shadowed and will result in an error.
	In the below example, the outer variable `name` is shadowed and will therefore throw an error.

	`COLLECT` can be used in any position in a query, with the exception of administration commands, where it is restricted.
	`COLLECT` can be used in any position in a query, with the exception of administration commands, where the `COLLECT` expression is restricted.

	See a few examples below:
	See a few examples below of how `COLLECT` can be used in different positions within a query:

-----
-MATCH (person:Person) WHERE person.name = "Peter"
-SET person.dogNames = COLLECT { MATCH (person)-[:HAS_DOG]->(d:Dog) RETURN d.name }
-RETURN person.dogNames as dogNames
-----
+----
+MATCH (person:Person) WHERE person.name = "Peter"
+SET person.dogNames = COLLECT { MATCH (person)-[:HAS_DOG]->(d:Dog) RETURN d.name }
+RETURN person.dogNames as dogNames
+----

	The following query collects all persons by their dog's names,
	The following query collects all persons by their dogs' names,

	When using `COLLECT` over the function `collect()` it is important to note that they have different behavior surrounding `null` values.
	`COLLECT` does not handle `null` values in the same way that function `collect()` does.

	The `collect()` function automatically removes null values.
	The `collect()` function automatically removes `null` values.

	`COLLECT` will not remove them automatically, however, they can be removed by simply adding a filtering step in the subquery.
	`COLLECT` will not remove `null values` automatically.
	However, they can be removed by adding a filtering step in the subquery.

Add docs for new COLLECT subqueries #398

Add docs for new COLLECT subqueries #398

Uh oh!

Conversation

gem-neo4j commented Feb 8, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gem-neo4j commented Feb 8, 2023

Uh oh!

neo-technology-commit-status-publisher commented Feb 8, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ncordon left a comment

Choose a reason for hiding this comment

Uh oh!

JPryce-Aklundh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JPryce-Aklundh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gem-neo4j commented Feb 8, 2023 •

edited

Loading