initial

Author: JPryce-Aklundh

modules/ROOT/content-nav.adoc

@@ -15,6 +15,7 @@
 ** xref:clauses/call.adoc[]
 ** xref:clauses/create.adoc[]
 ** xref:clauses/delete.adoc[]
+** xref:clauses/filter.adoc[]
 ** xref:clauses/finish.adoc[]
 ** xref:clauses/foreach.adoc[]
 ** xref:clauses/limit.adoc[]

modules/ROOT/images/filter_clause.svg

@@ -173,6 +173,11 @@ For example, GQL’s graph reference values `CURRENT_GRAPH` and `CURRENT_PROPERT
 | xref:queries/composed-queries/combined-queries.adoc[`UNION`]
 |
 
+| GQ08
+| `FILTER` statement
+| xref:clauses/filter.adoc[`FILTER`]
+|
+
 | GQ13
 | `ORDER BY` and page statement: `LIMIT`
 | xref:clauses/limit.adoc[`LIMIT`], xref:clauses/order-by.adoc[`ORDER BY`]

modules/ROOT/pages/appendix/gql-conformance/supported-optional.adoc

@@ -0,0 +1,113 @@
+= FILTER
+:description: 
+
+[[example-graph]]
+== Example graph
+
+The following graph is used for the examples below:
+
+image::filter_clause.svg[width="700",role="middle"]
+
+To recreate the graph, run the following query in an empty Neo4j database:
+
+[source, cypher, role=test-setup]
+----
+CREATE (andy:Swedish:Person {name: 'Andy', age: 36}),
+       (timothy:Person {name: 'Timothy', age: 38}),
+       (peter:Person {name: 'Peter', age: 35}),
+       (lisa:Person {name: 'Lisa', age: 48}),
+       (john:Person {name: 'John', age: 40}),
+       (susan:Person {name: 'Susan', age: 32}),
+       (andy)-[:KNOWS {since: 2012}]->(timothy),
+       (andy)-[:KNOWS {since: 1999}]->(peter),
+       (peter)-[:KNOWS {since: 2005}]->(lisa),
+       (lisa)-[:KNOWS {since: 2010}]->(john),
+       (john)-[:KNOWS {since: 2021}]->(susan)
+----
+
+
+== Basic filtering
+
+MATCH (n)
+FILTER n:Swedish
+RETURN n.name AS name
+
+MATCH (n:Person)
+FILTER n.age < 35
+RETURN n.name AS name, n.age AS age
+
+MATCH (p:Person)-[r:KNOWS]->(n:Person)
+FILTER r.since > 2000
+RETURN p.name, n.name
+
+== Filter on dynamic properties
+
+MATCH (n:Person)
+FILTER n[$propname] > 40
+RETURN n.name AS name, n.age AS age
+
+== `WITH`, `WHERE`, and `FILTER`
+
+=== FILTER as a substitute for `WITH * WHERE`
+* Filter makes WITH * WHERE ... redundant
+
+UNWIND [1, 2, 3, 4, 5, 6] AS x
+WITH x
+WHERE x > 2
+RETURN x
+
+same as 
+
+UNWIND [1, 2, 3, 4, 5, 6] AS x
+FILTER > 2
+RETURN x
+
+load csv
+
+.companies.csv
+[source, csv, filename="companies.csv"]
+----
+Id,Name,Location,Email,BusinessType
+1,Neo4j,San Mateo,[email protected],P
+2,AAA,,[email protected],
+3,BBB,Chicago, ,G
+,CCC,Michigan,[email protected],G
+----
+
+[source, cypher]
+----
+LOAD CSV WITH HEADERS FROM 'file:///companies.csv' AS row
+WITH row
+WHERE row.Id IS NOT NULL
+MERGE (c:Company {id: row.Id})
+----
+
+[source, cypher]
+----
+LOAD CSV WITH HEADERS FROM 'file:///companies.csv' AS row
+FILTER row.Id IS NOT NULL
+MERGE (c:Company {id: row.Id})
+----
+
+
+* Variable scope
+
+
+* Filter cannot exist in patterns
+
+
+
+
+
+
+
+
+
+
+
+
+== Differences between `FILTER` and `WHERE`
+
+
+
+

modules/ROOT/pages/clauses/filter.adoc

@@ -565,26 +565,23 @@ Id,Name,Location,Email,BusinessType
 [source, cypher]
 ----
 LOAD CSV WITH HEADERS FROM 'file:///companies.csv' AS row
-WITH row
-WHERE row.Id IS NOT NULL
+FILTER row.Id IS NOT NULL
 MERGE (c:Company {id: row.Id})
 ----
 
 .Provide a default for `null` values
 [source, cypher]
 ----
 LOAD CSV WITH HEADERS FROM 'file:///companies.csv' AS row
-WITH row
-WHERE row.Id IS NOT NULL
+FILTER row.Id IS NOT NULL
 MERGE (c:Company {id: row.Id, hqLocation: coalesce(row.Location, "Unknown")})
 ----
 
 .Change empty `STRING` values to `null` values (not stored)
 [source, cypher]
 ----
 LOAD CSV WITH HEADERS FROM 'file:///companies.csv' AS row
-WITH row
-WHERE row.Id IS NOT NULL
+FILTER row.Id IS NOT NULL
 MERGE (c:Company {id: row.Id})
 SET c.email = nullIf(trim(row.Email), "")
 ----

modules/ROOT/pages/clauses/load-csv.adoc

@@ -209,6 +209,17 @@ a|
 label:functionality[]
 label:new[]
 
+[source, cypher, role="noheader"]
+----
+
+----
+
+| New xref:clauses/filter.adoc[`FILTER`] clause.
+
+a|
+label:functionality[]
+label:new[]
+
 [source, cypher, role="noheader"]
 ----
 WHEN false THEN RETURN 1 AS x

modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

@@ -164,6 +164,7 @@ Note that with future functionality, Cypher may be extended with additional keyw
 * `FALSE`
 * `FIELDTERMINATOR`
 * `FINISH`
+* `FILTER`
 * `FLOAT`
 * `FOR`
 * `FOREACH`