WHERE

Generic Description

Predicate filter clause applied to current rows or pattern candidates.

Simple example:

MATCH (p:Person) WHERE p.age > 30 RETURN p

Consumer-Level Explanation

Use WHERE when the query must predicate filter clause applied to current rows or pattern candidates and the planner needs to see that operation as part of the Cypher row pipeline. Keep the clause explicit because it controls row grain, variable scope, and what later clauses are allowed to reference.

More Detailed Explanation

WHERE is far more than a simple boolean afterthought. In Nexyron it can combine graph element checks, string functions, list predicates, temporal filters, document-style map/list processing, and vector similarity expressions. Good WHERE usage is often the difference between a focused query and a row-explosion query.

What this clause is really for:

• it defines one concrete stage in the Cypher row pipeline, so variables available before and after WHERE must be clear
• it should make graph structure, temporal filters, document payload shaping, or procedure output explicit instead of relying on client-side interpretation
• planner tooling depends on this clause boundary to know row grain, variable scope, and whether later expressions are reads, writes, schema operations, or projections

Useful current forms include:

• membership checks with IN and NOT IN
• boolean composition with AND, OR, NOT, NOR, and XOR
• null checks with IS NULL and IS NOT NULL
• string predicates such as STARTS WITH, ENDS WITH, CONTAINS, and regex =~

Advanced Example

This example keeps WHERE inside a complete query pipeline so the clause boundary, visible variables, and returned row shape are clear to planner tooling.

MATCH (u:User)-[e:VIEWED]->(d:Document)
TIME e.ts BETWEEN datetime('2025-01-01T00:00:00Z') AND datetime('2025-02-01T00:00:00Z')
WITH u, e, d,
     date_trunc('day', e.ts) AS day_bucket,
     properties(d) AS doc_map,
     unpivot(properties(d.metadata)) AS metadata_rows,
     cosine_similarity(vector(properties(d).embedding), vector([0.22, 0.18, 0.44])) AS score
RETURN u.user_id, d.title, day_bucket, keys(doc_map) AS doc_keys, metadata_rows, score
ORDER BY score DESC
LIMIT 15

Real Use Cases

• filtering candidate neighborhoods before expensive downstream operations
• combining symbolic graph constraints with semantic or temporal thresholds
• removing incomplete or malformed semi-structured payload rows
• excluding status or category sets with NOT IN
• expressing “none of these conditions may match” more directly with NOR

Real Limitations And Tradeoffs

• filters after expansion can still be costly if the match is too broad
• NULL and three-valued abstractions matter
• predicate readability can collapse if too many unrelated concerns are crammed into one WHERE