Added section on by-table semantics

[JoelBergstrand]

Adding section on by-table semantics for NEXT, removing the section on known limitations.

[rsill-neo4j]

Suggested change

	=== Leveraging by-table semantics using `UNION` after `NEXT`
	=== Leveraging by-table semantics using `UNION` after `NEXT`

(spacing only)

[hvub]

This heading is the first mention of "by-table semantics". It falls out of the sky. I think, the much earlier section "Passing values to subsequent queries", which current is without change, should make clear that NEXT passes the whole table of intermediate results to the subsequent query. Maybe even show a second example with aggregation.

On the more general level, the page currently reflects the journey we as implementor went through. But it should not — users do not care about our troubles, which meaningless to them.

The page should be present NEXT as the feature that allows to pass the whole table of intermediate result to a subsequent query.

So the effects and benefits of that should come first — instead of in the last section.

So, consider to adjust the order of the section to this:

1. Passing values to subsequent queries
2. Interactions with UNION queries
3. Interactions with CALL subqueries
4. Interactions with conditional queries

In the latter two section, it should be explicitly pointed out respectively that CALL and conditionals only pass individual rows.

The text in "Interactions with CALL subqueries" also need some adjustment. For instance "NEXT can serve as a more readable alternative to CALL subqueries." Not sure we need to hang it this high now. Maybe it is better to show example where CALL nests NEXT and vice verse to illustrate the combined effect of their by-row and by-table semantics.

[hvub]

This heading is the first mention of "by-table semantics". It falls out of the sky. I think, the much earlier section "Passing values to subsequent queries", which current is without change, should make clear that NEXT passes the whole table of intermediate results to the subsequent query. Maybe even show a second example with aggregation.

On the more general level, the page currently reflects the journey we as implementor went through. But it should not — users do not care about our troubles, which meaningless to them.

The page should be present NEXT as the feature that allows to pass the whole table of intermediate result to a subsequent query.

So the effects and benefits of that should come first — instead of in the last section.

So, consider to adjust the order of the section to this:

1. Passing values to subsequent queries
2. Interactions with UNION queries
3. Interactions with CALL subqueries
4. Interactions with conditional queries

In the latter two section, it should be explicitly pointed out respectively that CALL and conditionals only pass individual rows.

The text in "Interactions with CALL subqueries" also need some adjustment. For instance "NEXT can serve as a more readable alternative to CALL subqueries." Not sure we need to hang it this high now. Maybe it is better to show example where CALL nests NEXT and vice verse to illustrate the combined effect of their by-row and by-table semantics.

[JoelBergstrand]

@hvub @rsill-neo4j, I've done a substantial rewrite and reorganization now, trying to put by-table semantics front and center. I find it quite difficult to construct interesting examples, and should we introduce the concept of by-table, by-row semantics at all or just refer to it in more general terms?

[hvub]

@rsill-neo4j I have updated the page a bit more to address my own comments on top of what @JoelBergstrand already did. @JoelBergstrand is out for vacation. I am taking over the PR, so that we can make whatever deadline for the next release is. I am done editing, so please have a look and feel free to fix any editorial sins I may have committed. 😄

[rsill-neo4j]

editorial suggestions

[rsill-neo4j]

these should probably stay (used for cypher cheat sheet includes)

[hvub]

Ah.. okay. I didn't know that.

[hvub]

I have add tags again, but on a newly made selection of three queries.

[hvub]

@rsill-neo4j What is the state of this PR from your point of view? Do you need any more input to take it over the finish line?

[rsill-neo4j]

updated include tags

[rsill-neo4j]

@rsill-neo4j What is the state of this PR from your point of view? Do you need any more input to take it over the finish line?

added a few suggestions for the tags -
restored two that were deleted, but where the queries weren't changed.
the PR moves one, deletes one, adds two, correct?

i'll create a PR for the cheat sheet to account for this.

[JoelBergstrand]

@rsill-neo4j, @hvub, I've rereviewed the PR, looks great!

[rsill-neo4j]

while not technically wrong, i think the discount is calculated incorrectly on a conceptual level -
shouldn't it be (1 - c.discount) ? for example, hannah's laptop is at a discounted price of 37.5 (down from 250)

stumbled upon this just now while trying to understand the testing error

[hvub]

I think you are right.

[hvub]

Should be fixed.

[rsill-neo4j]

4 suggestions to make it clear that changes were introduced with 2025.08, and an entry in the additions page as a direct commit

[rsill-neo4j]

Suggested change

	* `NEXT` allows for passing the full table of intermediate results into the arms of xref:queries/composed-queries/combined-queries.adoc[].
	* `NEXT` allows for passing the full table of intermediate results to a xref:queries/composed-queries/combined-queries.adoc[`UNION`] clause.

[JPryce-Aklundh]

Maybe just: "...results to a xref:queries/composed-queries/combined-queries.adoc[UNION`] clause". (i.e. get rid of the poetic "into the arms" 😄 )

[JPryce-Aklundh]

If I understand it correctly, the below sections marked as new in 2025.08 are not new to this release (e.g. you could have NEXT interact with CALL in 2025.07), and I am not understanding from this update how it impacts users? If it is just an under-the-hood update, then I think it is fine to only make a small mention of it. E.g.
"As of Neo4j 2025.08,... Previously, ...."

If this makes a meaningful change to how NEXT queries work in 2025.06 and 2025.07, then we should have an example to the effect of "NEXT used to work like this: Now it works like that:..."

[rsill-neo4j]

double-checking the queries in the old version, at least this one (NEXT inside CALL) behaves differently (yielding 100% for all products):

MATCH (p:Product) WHERE p.name <> "Coffee"
CALL (p) {
    MATCH (p)<-[:BUYS]-(c:Customer)-[:BUYS]->(otherProduct)
    RETURN c, otherProduct
    NEXT
    RETURN count(DISTINCT c) AS customers, 0 AS customersAlsoBuyingCoffee
    UNION
    FILTER otherProduct.name = "Coffee"
    RETURN 0 as customers, count(DISTINCT c) AS customersAlsoBuyingCoffee
    NEXT
    RETURN max(customers) AS customers, max(customersAlsoBuyingCoffee) AS customersAlsoBuyingCoffee
}
RETURN p.name AS product,
       round(toFloat(customersAlsoBuyingCoffee) * 100 / customers, 1) AS percentageOfCustomersAlsoBuyingCoffee
  ORDER BY product

[hvub]

If there is aggregation in CALL the previous implementation was wrong, so they errored in the last release. Now they are implemented correctly. In that sense it is new.

[hvub]

The same for aggregation in a UNION.

[JPryce-Aklundh]

This entry should be for allReduce

[rsill-neo4j]

copy-paste error! should be fixed

[JPryce-Aklundh]

Maybe just: "...results to a xref:queries/composed-queries/combined-queries.adoc[UNION`] clause". (i.e. get rid of the poetic "into the arms" 😄 )

[JPryce-Aklundh]

If I understand it correctly, the below sections marked as new in 2025.08 are not new to this release (e.g. you could have NEXT interact with CALL in 2025.07), and I am not understanding from this update how it impacts users? If it is just an under-the-hood update, then I think it is fine to only make a small mention of it. E.g.
"As of Neo4j 2025.08,... Previously, ...."

If this makes a meaningful change to how NEXT queries work in 2025.06 and 2025.07, then we should have an example to the effect of "NEXT used to work like this: Now it works like that:..."

[neo4j-docops-agent]

Thanks for the documentation updates.

The preview documentation has now been torn down - reopening this PR will republish it.