@loradb/lora-node 0.35.1 → 0.36.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +5 -0
  2. package/dist/types.d.ts +2 -1
  3. package/dist/types.d.ts.map +1 -1
  4. package/dist/types.js +1 -0
  5. package/dist/types.js.map +1 -1
  6. package/docs/README.md +86 -0
  7. package/docs/concepts/graph-model.md +270 -0
  8. package/docs/concepts/nodes.md +285 -0
  9. package/docs/concepts/properties.md +348 -0
  10. package/docs/concepts/relationships.md +325 -0
  11. package/docs/concepts/result-formats.md +183 -0
  12. package/docs/concepts/schema-free.md +183 -0
  13. package/docs/cookbook.md +1081 -0
  14. package/docs/data-types/lists-and-maps.md +406 -0
  15. package/docs/data-types/overview.md +210 -0
  16. package/docs/data-types/scalars.md +376 -0
  17. package/docs/data-types/spatial.md +291 -0
  18. package/docs/data-types/temporal.md +349 -0
  19. package/docs/data-types/vectors.md +563 -0
  20. package/docs/errors.md +183 -0
  21. package/docs/functions/aggregation.md +372 -0
  22. package/docs/functions/list.md +522 -0
  23. package/docs/functions/map.md +207 -0
  24. package/docs/functions/math.md +421 -0
  25. package/docs/functions/number.md +197 -0
  26. package/docs/functions/overview.md +545 -0
  27. package/docs/functions/spatial.md +384 -0
  28. package/docs/functions/string.md +502 -0
  29. package/docs/functions/temporal.md +590 -0
  30. package/docs/functions/utility.md +137 -0
  31. package/docs/functions/vectors.md +772 -0
  32. package/docs/getting-started/installation.md +204 -0
  33. package/docs/getting-started/node.md +582 -0
  34. package/docs/getting-started/tutorial.md +334 -0
  35. package/docs/index.md +203 -0
  36. package/docs/limitations.md +291 -0
  37. package/docs/performance.md +219 -0
  38. package/docs/queries/aggregation.md +520 -0
  39. package/docs/queries/cheat-sheet.md +302 -0
  40. package/docs/queries/constraints.md +239 -0
  41. package/docs/queries/create.md +331 -0
  42. package/docs/queries/examples.md +453 -0
  43. package/docs/queries/index.md +169 -0
  44. package/docs/queries/indexes.md +538 -0
  45. package/docs/queries/match.md +429 -0
  46. package/docs/queries/ordering.md +359 -0
  47. package/docs/queries/parameters.md +328 -0
  48. package/docs/queries/paths.md +462 -0
  49. package/docs/queries/return-with.md +500 -0
  50. package/docs/queries/set-delete.md +369 -0
  51. package/docs/queries/unwind-merge.md +358 -0
  52. package/docs/queries/where.md +416 -0
  53. package/docs/snapshot.md +545 -0
  54. package/docs/troubleshooting.md +1158 -0
  55. package/docs/wal.md +570 -0
  56. package/docs/why.md +273 -0
  57. package/package.json +13 -14
@@ -0,0 +1,416 @@
1
+ ---
2
+ title: "WHERE — Filtering Rows"
3
+ description: "The WHERE clause in LoraDB — boolean filters after MATCH, WITH, or OPTIONAL MATCH — including comparisons, regex, list predicates, EXISTS subqueries, and when to filter after aggregation."
4
+ online: "https://loradb.com/docs/queries/where"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # WHERE — Filtering Rows
9
+
10
+ `WHERE` filters rows produced by the preceding [`MATCH`](./match.md),
11
+ [`WITH`](./return-with.md#with), or
12
+ [`OPTIONAL MATCH`](./match.md#optional-match). Any boolean expression
13
+ is valid.
14
+
15
+ > `WHERE` runs **before** [`RETURN`](./return-with.md) and
16
+ > [aggregation](./aggregation.md). For filtering _after_ an aggregate
17
+ > (SQL `HAVING`), pipe through [`WITH`](./return-with.md#with).
18
+
19
+ ## Overview
20
+
21
+ | Goal | Operator / Keyword |
22
+ |---|---|
23
+ | Compare scalars | `=`, `<>`, `<`, `<=`, `>`, `>=` |
24
+ | Boolean combinators | `AND`, `OR`, `NOT`, `XOR` |
25
+ | Match a prefix / suffix / substring | `STARTS WITH`, `ENDS WITH`, `CONTAINS` |
26
+ | Regex | `=~` |
27
+ | Null-safe check | `IS NULL`, `IS NOT NULL` |
28
+ | Membership | `IN [...]` / `IN $param` |
29
+ | List quantifiers | `all`, `any`, `none`, `single` |
30
+ | Pattern existence | `EXISTS { (...)-[...]->(...) }` |
31
+ | Conditional branch | [`CASE WHEN … THEN … END`](./return-with.md#case-expressions) |
32
+
33
+ ## Comparison
34
+
35
+ ```cypher
36
+ MATCH (n:User) WHERE n.age > 18 RETURN n;
37
+ MATCH (n:User) WHERE n.age >= 18 AND n.age <= 65 RETURN n;
38
+ MATCH (n:User) WHERE n.name = 'alice' RETURN n;
39
+ MATCH (n:User) WHERE n.name <> 'bob' RETURN n
40
+ ```
41
+
42
+ RANGE indexes can accelerate equality and range comparisons when the
43
+ predicate is scoped to a matching label or relationship type:
44
+
45
+ ```cypher
46
+ CREATE INDEX user_age FOR (u:User) ON (u.age);
47
+ MATCH (u:User) WHERE u.age >= 18 AND u.age < 65 RETURN u
48
+ ```
49
+
50
+ Comparison returns `null` (not `false`) when either operand is `null` or
51
+ when the types mismatch — see [Scalars → Null](../data-types/scalars.md#null)
52
+ and [Limitations](../limitations.md#operators-and-expressions).
53
+
54
+ No `BETWEEN` keyword — use explicit `>=` / `<=` bounds:
55
+
56
+ ```cypher
57
+ MATCH (p:Product) WHERE p.price >= 10 AND p.price <= 50 RETURN p
58
+ ```
59
+
60
+ ## Boolean operators
61
+
62
+ ```cypher
63
+ MATCH (n) WHERE n.active AND n.age >= 18 RETURN n;
64
+ MATCH (n) WHERE n.active OR n.age < 18 RETURN n;
65
+ MATCH (n) WHERE NOT n.active RETURN n;
66
+ MATCH (n) WHERE n.active XOR n.admin RETURN n
67
+ ```
68
+
69
+ Three-valued logic applies — `null AND false` is `false`, `null AND
70
+ true` is `null`. See the full truth table in
71
+ [Scalars → Null](../data-types/scalars.md#null).
72
+
73
+ `AND` and `OR` evaluate left to right and stop as soon as the left side
74
+ decides: after `false AND` or `true OR` the right side is not evaluated,
75
+ so it cannot fail the query. That makes a guard work:
76
+
77
+ ```cypher
78
+ MATCH (e:Event)
79
+ WHERE type.of(e.at) = 'DATE' AND e.at >= date('2024-01-01')
80
+ RETURN e
81
+ ```
82
+
83
+ Here an `e.at` that holds a `DATETIME` never reaches the comparison,
84
+ which would otherwise be an error (see
85
+ [Temporal types](../data-types/temporal.md#cross-type-comparison)). A
86
+ `null` left side decides nothing, so the right side is evaluated.
87
+
88
+ ### Precedence
89
+
90
+ `NOT` binds tightest, then `AND`, then `XOR`, then `OR`. Parenthesise
91
+ freely when in doubt:
92
+
93
+ ```cypher
94
+ // These are equivalent
95
+ MATCH (n) WHERE n.a OR n.b AND n.c RETURN n;
96
+ MATCH (n) WHERE n.a OR (n.b AND n.c) RETURN n
97
+ ```
98
+
99
+ ## String matching
100
+
101
+ All string operators are **case-sensitive**. For case-insensitive
102
+ matching, normalise with [`string.lower`](../functions/string.md#tolower--toupper)
103
+ or `string.upper` on both sides.
104
+
105
+ ```cypher
106
+ MATCH (n) WHERE n.name STARTS WITH 'a' RETURN n;
107
+ MATCH (n) WHERE n.name ENDS WITH 'z' RETURN n;
108
+ MATCH (n) WHERE n.name CONTAINS 'al' RETURN n
109
+ ```
110
+
111
+ TEXT indexes can accelerate these string predicates:
112
+
113
+ ```cypher
114
+ CREATE TEXT INDEX user_name FOR (u:User) ON (u.name);
115
+ MATCH (u:User) WHERE u.name STARTS WITH 'Al' RETURN u
116
+ ```
117
+
118
+ ```cypher
119
+ MATCH (u:User)
120
+ WHERE string.lower(u.name) STARTS WITH string.lower($query)
121
+ RETURN u
122
+ ```
123
+
124
+ ## Regex
125
+
126
+ ```cypher
127
+ MATCH (u:User) WHERE u.name =~ 'A.*e' RETURN u;
128
+ MATCH (u:User) WHERE u.email =~ '.*@loradb\\.com' RETURN u
129
+ ```
130
+
131
+ Uses the Rust `regex` crate — standard RE2-style syntax, no
132
+ backreferences. Anchors are implicit: `=~ 'foo'` matches only the full
133
+ string `"foo"`, not any string containing `foo`. Use `.*` to allow
134
+ prefixes/suffixes, or `CONTAINS 'foo'` for plain substring.
135
+
136
+ ## Null checks
137
+
138
+ Most expressions involving `null` propagate to `null`, not to `false`.
139
+ Use `IS NULL` / `IS NOT NULL`, **not** `= null`.
140
+
141
+ ```cypher
142
+ MATCH (n) WHERE n.optional IS NULL RETURN n;
143
+ MATCH (n) WHERE n.optional IS NOT NULL RETURN n
144
+
145
+ ;// Wrong — always yields zero rows
146
+ MATCH (n) WHERE n.optional = null RETURN n
147
+ ```
148
+
149
+ Common guard: require a property to exist _and_ be non-empty:
150
+
151
+ ```cypher
152
+ MATCH (u:User)
153
+ WHERE u.email IS NOT NULL AND string.length(u.email) > 0
154
+ RETURN u
155
+ ```
156
+
157
+ ## IN
158
+
159
+ Membership check against a list literal or parameter.
160
+
161
+ ```cypher
162
+ MATCH (n) WHERE n.age IN [18, 21, 25] RETURN n;
163
+ MATCH (n) WHERE NOT n.name IN ['Alice', 'Bob'] RETURN n;
164
+ MATCH (u:User) WHERE u.id IN $ids RETURN u
165
+ ```
166
+
167
+ `$ids` binds to a [list](../data-types/lists-and-maps.md#lists) in the host
168
+ language (`[1, 2, 3]` in JS/Python, `Vec<LoraValue>` in Rust).
169
+
170
+ ### IN with DISTINCT
171
+
172
+ ```cypher
173
+ MATCH (u:User)-[:OWNS]->(p:Project)
174
+ WHERE p.tag IN $tags
175
+ RETURN DISTINCT u
176
+ ```
177
+
178
+ ### `IN` over an empty list
179
+
180
+ `x IN []` is always `false`. Empty-list parameters drop every row —
181
+ validate on the host side if that's a likely accident.
182
+
183
+ ## Arithmetic in WHERE
184
+
185
+ Any expression that produces a boolean is allowed.
186
+
187
+ ```cypher
188
+ MATCH (n) WHERE n.age + 5 > 30 RETURN n;
189
+ MATCH (n) WHERE n.price * n.quantity > 1000 RETURN n;
190
+ MATCH (n) WHERE (n.end - n.start).seconds > 60 RETURN n
191
+ ```
192
+
193
+ ## Cross-variable comparison
194
+
195
+ Predicates can reference multiple bindings from the `MATCH`:
196
+
197
+ ```cypher
198
+ MATCH (a:User)-[:FOLLOWS]->(b:User)
199
+ WHERE a.age > b.age
200
+ RETURN a.name AS older, b.name AS younger
201
+ ```
202
+
203
+ ```cypher
204
+ MATCH (a:User)-[:FOLLOWS]->(b)
205
+ WHERE a.country = b.country
206
+ RETURN a, b
207
+ ```
208
+
209
+ ## Pattern existence
210
+
211
+ Use `EXISTS { pattern }` to filter rows by whether a pattern matches —
212
+ without adding extra rows to the output.
213
+
214
+ ```cypher
215
+ MATCH (u:User)
216
+ WHERE EXISTS { (u)-[:FOLLOWS]->() }
217
+ RETURN u
218
+ ```
219
+
220
+ ```cypher
221
+ // Users who have never posted
222
+ MATCH (u:User)
223
+ WHERE NOT EXISTS { (u)-[:WROTE]->(:Post) }
224
+ RETURN u.name
225
+ ```
226
+
227
+ This is the anti-join pattern — cheaper than
228
+ `OPTIONAL MATCH … WHERE other IS NULL` when you don't need the optional
229
+ result.
230
+
231
+ A `WHERE` inside the braces filters the pattern's matches. `MATCH` is
232
+ optional:
233
+
234
+ ```cypher
235
+ // People active since $since
236
+ MATCH (p:Person)
237
+ WHERE EXISTS { (p)-[:DID]->(a) WHERE a.at >= $since }
238
+ RETURN p.name
239
+ ```
240
+
241
+ A relationship pattern on its own is a predicate too, the short form of
242
+ `EXISTS { }`. It needs at least one relationship, so `(a)` stays a
243
+ parenthesized expression:
244
+
245
+ ```cypher
246
+ MATCH (p:Person), (q:Person)
247
+ WHERE p <> q AND NOT (p)-[:BLOCKS]-(q)
248
+ RETURN p.name, q.name
249
+ ```
250
+
251
+ When the subquery's start node is not bound by the outer row, give it
252
+ an inline property map, for example
253
+ `EXISTS { MATCH (v:Person {subject: $s}) WHERE v.verified }`.
254
+ The same applies to `COUNT { }`. LoraDB seeks that property through an
255
+ index, as `MATCH` does, instead of scanning the label once per outer
256
+ row. See
257
+ [Performance → Query shape notes](../performance.md#unbound-start-nodes-in-pattern-subqueries).
258
+
259
+ ## List predicates
260
+
261
+ Ask a question about the elements of a list. Covered fully in
262
+ [List Functions → Predicates](../functions/list.md#predicates-in-where).
263
+
264
+ ```cypher
265
+ MATCH (n) WHERE all(x IN n.scores WHERE x > 0) RETURN n;
266
+ MATCH (n) WHERE any(x IN n.tags WHERE x = 'VIP') RETURN n;
267
+ MATCH (n) WHERE none(x IN n.scores WHERE x < 0) RETURN n;
268
+ MATCH (n) WHERE single(x IN n.scores WHERE x = 100) RETURN n
269
+ ```
270
+
271
+ ## CASE in predicates
272
+
273
+ [`CASE`](./return-with.md#case-expressions) is an expression, so it
274
+ composes inside `WHERE` wherever you'd write a scalar. Useful when the
275
+ comparison value itself depends on a per-row condition:
276
+
277
+ ```cypher
278
+ MATCH (p:Product)
279
+ WHERE CASE
280
+ WHEN p.on_sale THEN p.sale_price
281
+ ELSE p.price
282
+ END <= $budget
283
+ RETURN p
284
+ ```
285
+
286
+ Equivalent with [`coalesce`](../functions/overview.md#type-conversion-and-checking)
287
+ when you only need a "first non-null" fallback:
288
+
289
+ ```cypher
290
+ MATCH (p:Product)
291
+ WHERE coalesce(p.sale_price, p.price) <= $budget
292
+ RETURN p
293
+ ```
294
+
295
+ See [`RETURN → CASE expressions`](./return-with.md#case-expressions) for
296
+ the full syntax.
297
+
298
+ ## Common patterns
299
+
300
+ ### Safe prefix search
301
+
302
+ ```cypher
303
+ MATCH (u:User)
304
+ WHERE string.lower(u.name) STARTS WITH string.lower($query)
305
+ RETURN u
306
+ ORDER BY u.name
307
+ LIMIT 20
308
+ ```
309
+
310
+ ### Tag filtering
311
+
312
+ ```cypher
313
+ MATCH (p:Product)
314
+ WHERE any(t IN p.tags WHERE t IN $tags)
315
+ RETURN p
316
+ ```
317
+
318
+ ### Date range
319
+
320
+ ```cypher
321
+ MATCH (e:Event)
322
+ WHERE e.at >= '2024-01-01'::DATE AND e.at < '2025-01-01'::DATE
323
+ RETURN e
324
+ ORDER BY e.at
325
+ ```
326
+
327
+ See [Temporal Functions](../functions/temporal.md) for cast-based
328
+ temporal construction and arithmetic.
329
+
330
+ ### "Has at least one of each"
331
+
332
+ ```cypher
333
+ MATCH (u:User)
334
+ WHERE EXISTS { (u)-[:OWNS]->(:Repo) }
335
+ AND EXISTS { (u)-[:WROTE]->(:Post) }
336
+ RETURN u
337
+ ```
338
+
339
+ ### "Has none of these"
340
+
341
+ ```cypher
342
+ MATCH (p:Post)
343
+ WHERE none(t IN ['spam', 'nsfw', 'flagged']
344
+ WHERE EXISTS { (p)-[:TAGGED]->(:Tag {name: t}) })
345
+ RETURN p
346
+ ```
347
+
348
+ ### Chained optional predicates
349
+
350
+ Break a complex predicate into `WITH` stages for readability. Each
351
+ stage only sees what it needs:
352
+
353
+ ```cypher
354
+ MATCH (u:User)
355
+ WITH u, coalesce(u.score, 0) AS s
356
+ WHERE s >= 50
357
+ WITH u, s, (u.last_seen >= temporal.now() - 'P30D'::DURATION) AS recent
358
+ WHERE recent
359
+ RETURN u.handle, s
360
+ ```
361
+
362
+ Same meaning as one giant `WHERE`, but each stage is narrower and
363
+ easier to trace.
364
+
365
+ ### Default a missing value
366
+
367
+ Use [`coalesce`](../functions/overview.md#type-conversion-and-checking) to
368
+ substitute a fallback:
369
+
370
+ ```cypher
371
+ MATCH (p:Person)
372
+ WHERE coalesce(p.score, 0) >= 50
373
+ RETURN p
374
+ ```
375
+
376
+ ## Edge cases
377
+
378
+ ### Aggregates in WHERE
379
+
380
+ Aggregates are **not** allowed in `WHERE`. Attempting `WHERE count(x) > 5`
381
+ is a semantic error — use
382
+ [`WITH … WHERE`](./aggregation.md#5-filter-after-aggregating-having-style)
383
+ instead.
384
+
385
+ ### Missing property vs null property
386
+
387
+ A missing property and a property set to `null` are indistinguishable —
388
+ both return `null` on access. `SET n.prop = null` is the idiomatic way
389
+ to remove a property (see [SET → computed expressions](./set-delete.md#computed-expressions)).
390
+
391
+ ### Comparison across types
392
+
393
+ Cross-type comparisons (e.g. `Int < String`) return `null`, not `false`
394
+ — see [Limitations](../limitations.md#operators-and-expressions). Cast
395
+ explicitly with [`toString`](../functions/string.md#type-conversion) /
396
+ `toInteger` / `toFloat` first.
397
+
398
+ ### `null` propagation in compound predicates
399
+
400
+ ```cypher
401
+ // If n.a is null, the whole expression is null → row dropped
402
+ MATCH (n) WHERE n.a = 1 AND n.b > 2 RETURN n
403
+ ```
404
+
405
+ Guard null-prone properties with `IS NOT NULL` or `coalesce` when you
406
+ need to reason about three-valued logic.
407
+
408
+ ## See also
409
+
410
+ - [**MATCH**](./match.md) — what feeds `WHERE`.
411
+ - [**RETURN / WITH**](./return-with.md) — projection and HAVING-style filtering.
412
+ - [**Aggregation**](./aggregation.md) — group, then filter via `WITH`.
413
+ - [**String Functions**](../functions/string.md) — `toLower`, `replace`, regex.
414
+ - [**List Functions**](../functions/list.md) — `all`, `any`, `none`, `single`.
415
+ - [**Scalars → Null**](../data-types/scalars.md#null) — three-valued logic.
416
+ - [**Temporal Functions**](../functions/temporal.md) — date/time predicates.