FILTER documentation

[JPryce-Aklundh]

No description provided.

[hvub]

Thank you. LGTM. Two remarks inline.

[hvub]

Hmm.... I not sure I would say that. Yes there are way to use WHERE which do not work with FILTER. However, this comes from 1) where being a subclause 2) the context in which it is allowed. So, it is a bit of an apple and oranges comparison.

I guess you basically trying to say that they are different in some respects and the user should not think that every WHERE is 1-to-1 replaceable by a FILTER. That is certainly true. But may we can find a way to say that in a neutral way without adding a quality to it.

The main cause of the difference is exactly that FILTER is a clause while WHERE is a subclause (of multiple different clauses).

So, may be like something like this:

Suggested change

	Unlike `WHERE`, `FILTER` is not a subclause, which means it can be used independently of the xref:clauses/match.adoc[`MATCH`], xref:clauses/optional-match.adoc[`OPTIONAL MATCH`], and xref:clauses/with.adoc[`WITH`] clauses.
	It is not, however, as versatile as `WHERE`.
	Unlike `WHERE`, `FILTER` is not a subclause, which means it can be used independently of the xref:clauses/match.adoc[`MATCH`], xref:clauses/optional-match.adoc[`OPTIONAL MATCH`], and xref:clauses/with.adoc[`WITH`] clauses.
	Conversely, `FILTER` cannot be used within these clauses like `WHERE` but only next to them.

While this somewhat fulfils to aim I laid out the top, I am not sure I like for the flow. Anyway. May you have a better idea.

Alternatively, we can also consider dropping the second sentence altogether.

Or turn it into a forward reference to section "FILTER as a substitute for WITH * WHERE", like: "For more details on this difference see ..."

[hvub]

One item you could add is relative to the point the docs makes somewhere that

When used with MATCH and OPTIONAL MATCH, WHERE adds constraints to the patterns described. It should not be seen as a filter after the matching is finished.

This make a different particularly with OPTIONAL MATCH.

UNWIND [32,37,40] AS age
OPTIONAL MATCH (p:Person) 
  WHERE p.age = age
RETURN p.name

returns

╒═══════╕
│p.name │
╞═══════╡
│"Susan"│
├───────┤
│null   │
├───────┤
│"John" │
└───────┘

while

UNWIND [32,37,40] AS age
OPTIONAL MATCH (p:Person) 
FILTER p.age = age
RETURN p.name

returns

╒═══════╕
│p.name │
╞═══════╡
│"Susan"│
├───────┤
│"John" │
└───────┘

[neo-technology-commit-status-publisher]

Thanks for the documentation updates.

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