@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
package/docs/errors.md ADDED
@@ -0,0 +1,183 @@
1
+ ---
2
+ title: "Error reference"
3
+ description: "Stable error codes emitted by LoraDB across every binding and the HTTP server. Match on these codes — not on message text — to route failures in your application."
4
+ online: "https://loradb.com/docs/errors"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Error reference
9
+
10
+ Every LoraDB error carries a stable `LORA_*` code drawn from a single
11
+ catalog. The code is part of the public API and never changes between
12
+ releases; the human-readable message is allowed to evolve. Bindings,
13
+ the HTTP server, and integration tests should match on the code, never
14
+ on the message.
15
+
16
+ ## Codes
17
+
18
+ ### Client errors (caller's fault)
19
+
20
+ | Code | When you'll see it |
21
+ |---|---|
22
+ | `LORA_PARSE` | Cypher syntax could not be parsed, or the query is past a [shape limit](./limitations.md#query-limits) (nesting, operator chain, clause count, hop count). |
23
+ | `LORA_SEMANTIC` | Unknown variable or function, wrong arity, or type mismatch. |
24
+ | `LORA_INVALID_PARAMS` | A parameter value couldn't be coerced into a Lora value, or is nested or sized past the [value limits](./limitations.md#query-limits). |
25
+ | `LORA_READ_ONLY` | A mutating statement was issued in a read-only context. |
26
+ | `LORA_NOT_FOUND` | A named entity (database, label, key) does not exist. |
27
+ | `LORA_CONSTRAINT` | A precondition failed (e.g. `DELETE` on a node with relationships — use `DETACH DELETE`). |
28
+ | `LORA_VALIDATION` | A well-formed database operation failed validation, including a value a query builds or stores past the [value limits](./limitations.md#query-limits). |
29
+ | `LORA_UNIQUE_CONSTRAINT` | A uniqueness constraint rejected duplicate data. |
30
+ | `LORA_NOT_NULL_CONSTRAINT` | An existence / NOT NULL constraint rejected missing data. |
31
+ | `LORA_FOREIGN_KEY` | A relationship or dependent record references a missing entity. |
32
+ | `LORA_TRANSACTION` | A transaction lifecycle rule was violated. |
33
+ | `LORA_LOCKED` | The database directory is locked by another process or live handle. |
34
+ | `LORA_CHANGES_TRUNCATED` | A change feed was asked to resume from an LSN the database no longer retains. Start a fresh feed and re-read current state. |
35
+ | `LORA_CHANGES_LAGGED` | A change feed subscriber fell further behind than its buffer allows. Resume with the last LSN it processed. |
36
+ | `LORA_INVALID_VECTOR` | A vector value failed dimension or coordinate-type validation. |
37
+ | `LORA_TIMEOUT` | The query exceeded its cooperative deadline. |
38
+ | `LORA_RESULT_TOO_LARGE` | HTTP server only. The query's result has more rows than `--max-result-rows`, or its response is larger than `--max-response-bytes`. Add a `LIMIT` or page with `SKIP` / `LIMIT`. |
39
+ | `LORA_DATABASE_NAME` | A logical database name violates the portable-path rules. |
40
+ | `LORA_CONFIG` | A CLI flag or configuration value is invalid. |
41
+
42
+ ### Server errors (engine's fault)
43
+
44
+ | Code | When you'll see it |
45
+ |---|---|
46
+ | `LORA_IO` | An I/O failure outside the WAL / snapshot subsystems. |
47
+ | `LORA_STORAGE_PERMISSION` | The database directory cannot be written: permission denied, or a read-only file system. Opening a database writes its lock file and WAL, so this is what opening a read-only directory returns. |
48
+ | `LORA_CONNECTION` | The database backing connection or handle failed. |
49
+ | `LORA_WAL_CORRUPTION` | A WAL record was truncated, mis-CRC'd, or otherwise unreadable. |
50
+ | `LORA_WAL_POISONED` | The WAL is poisoned and no longer accepts durable writes. |
51
+ | `LORA_SNAPSHOT_CODEC` | Snapshot bad magic, version, or checksum. |
52
+ | `LORA_SNAPSHOT_CRYPTO` | Snapshot encryption / decryption / KDF failure. |
53
+ | `LORA_INTERNAL` | The engine could not classify the failure. |
54
+
55
+ ### Binding-side codes
56
+
57
+ | Code | When you'll see it |
58
+ |---|---|
59
+ | `LORA_PANIC` | A Rust panic was caught at a binding boundary. The process keeps running; the call returns this code instead. |
60
+ | `LORA_TOO_MANY_OPEN` | Node only. The database already has `maxOpenTransactions` interactive transactions and write streams open (1024 by default). Finish or close one, or raise the limit. Read-write `transaction()` batches queue instead. |
61
+
62
+ ## HTTP transport
63
+
64
+ The Axum server returns errors as JSON:
65
+
66
+ ```json
67
+ {
68
+ "error": {
69
+ "code": "LORA_PARSE",
70
+ "message": "parse error at 0..10: expected statement",
71
+ "category": "client"
72
+ }
73
+ }
74
+ ```
75
+
76
+ `category` is `"client"` (4xx) or `"server"` (5xx). The HTTP status
77
+ code follows the category, with these refinements:
78
+
79
+ | Status | Codes |
80
+ |---|---|
81
+ | `400 Bad Request` | `LORA_PARSE`, `LORA_SEMANTIC`, `LORA_READ_ONLY`, `LORA_DATABASE_NAME`, `LORA_CONFIG` |
82
+ | `404 Not Found` | `LORA_NOT_FOUND` |
83
+ | `408 Request Timeout` | `LORA_TIMEOUT` |
84
+ | `409 Conflict` | `LORA_CONSTRAINT`, `LORA_UNIQUE_CONSTRAINT`, `LORA_NOT_NULL_CONSTRAINT`, `LORA_FOREIGN_KEY`, `LORA_TRANSACTION` |
85
+ | `422 Unprocessable Entity` | `LORA_INVALID_PARAMS`, `LORA_INVALID_VECTOR`, `LORA_VALIDATION`, `LORA_RESULT_TOO_LARGE` |
86
+ | `500 Internal Server Error` | `LORA_IO`, `LORA_STORAGE_PERMISSION`, `LORA_WAL_CORRUPTION`, `LORA_SNAPSHOT_CODEC`, `LORA_SNAPSHOT_CRYPTO`, `LORA_INTERNAL` |
87
+ | `503 Service Unavailable` | `LORA_CONNECTION`, `LORA_WAL_POISONED` |
88
+
89
+ ## Examples per language
90
+
91
+ ### Rust
92
+
93
+ ```rust
94
+ use lora_database::{Database, LoraError, LoraErrorCode};
95
+
96
+ let db = Database::in_memory();
97
+ match db.execute("NOT CYPHER", None) {
98
+ Ok(_) => {}
99
+ Err(e) => {
100
+ let lora = LoraError::from_anyhow(e);
101
+ if lora.code() == LoraErrorCode::Parse {
102
+ eprintln!("syntax: {}", lora.message());
103
+ }
104
+ }
105
+ }
106
+ ```
107
+
108
+ ### Node.js / TypeScript
109
+
110
+ ```ts
111
+ import { LoraError } from "@loradb/lora-node";
112
+
113
+ try {
114
+ await db.execute("NOT CYPHER");
115
+ } catch (err) {
116
+ if (err instanceof LoraError) {
117
+ if (err.code === "LORA_PARSE") console.error("syntax:", err.message);
118
+ }
119
+ }
120
+ ```
121
+
122
+ `err.code` is the precise wire string from the catalog above, for
123
+ example `"LORA_PARSE"` or `"LORA_INVALID_PARAMS"`.
124
+
125
+ ### Python
126
+
127
+ ```python
128
+ from lora_python import LoraQueryError
129
+
130
+ try:
131
+ db.execute("NOT CYPHER")
132
+ except LoraQueryError as e:
133
+ code, _, message = str(e).partition(": ")
134
+ if code == "LORA_PARSE":
135
+ print(f"syntax: {message}")
136
+ ```
137
+
138
+ ### Go
139
+
140
+ ```go
141
+ import (
142
+ "errors"
143
+ "fmt"
144
+
145
+ lora "github.com/lora-db/lora/crates/bindings/lora-go"
146
+ )
147
+
148
+ if _, err := db.Execute("NOT CYPHER", nil); err != nil {
149
+ var le *lora.LoraError
150
+ if errors.As(err, &le) && le.Code == lora.CodeParse {
151
+ fmt.Println("syntax:", le.Message)
152
+ }
153
+ }
154
+ ```
155
+
156
+ ### Ruby
157
+
158
+ ```ruby
159
+ begin
160
+ db.execute("NOT CYPHER")
161
+ rescue LoraRuby::QueryError => e
162
+ code, _, message = e.message.partition(": ")
163
+ warn "syntax: #{message}" if code == "LORA_PARSE"
164
+ end
165
+ ```
166
+
167
+ ### WASM / browsers
168
+
169
+ ```js
170
+ try {
171
+ await db.execute("NOT CYPHER", null);
172
+ } catch (err) {
173
+ if (err.code === "LORA_PARSE") console.warn("syntax", err.message);
174
+ }
175
+ ```
176
+
177
+ ## Why match on codes, not messages
178
+
179
+ Codes are the contract. Messages are advisory: between minor releases
180
+ we rewrite individual `#[error("...")]` strings to make them clearer or
181
+ include more context. Anything matching message text — `if
182
+ err.message.contains("not found")` — will silently break. Match on
183
+ `LORA_NOT_FOUND` instead.
@@ -0,0 +1,372 @@
1
+ ---
2
+ title: "Aggregation Functions"
3
+ description: "Aggregation functions in LoraDB — count, sum, avg, min, max, collect, stdev, and percentile family — including null handling, empty-input semantics, and implicit grouping rules."
4
+ online: "https://loradb.com/docs/functions/aggregation"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Aggregation Functions
9
+
10
+ Aggregation collapses a group of input rows into a single value per
11
+ group. For clause-level semantics (implicit `GROUP BY`,
12
+ `HAVING`-style filtering via [`WITH`](../queries/return-with.md#with),
13
+ where aggregates are legal) see the
14
+ [Aggregation query page](../queries/aggregation.md).
15
+
16
+ > All aggregates **skip `null` inputs** except `count(*)`, which counts
17
+ > rows. Empty-input semantics
18
+ > vary per function — see the [summary table](#summary-table).
19
+
20
+ ## Summary table
21
+
22
+ | Function | `DISTINCT` | Empty input | Null input | Returns |
23
+ |---|---|---|---|---|
24
+ | `count(*)` | — | `0` | counted as 1 per row | `Int` |
25
+ | `count(expr)` | yes | `0` | skipped | `Int` |
26
+ | `collect(expr)` | yes | `[]` | skipped | `List` |
27
+ | `sum(expr)` | yes | `0` | skipped | `Int` if all-int, else `Float` |
28
+ | `avg(expr)` | yes | `null` | skipped | `Float` |
29
+ | `min(expr)` / `max(expr)` | yes | `null` | skipped | same type as element |
30
+ | `stdev(expr)` | — | `0.0` | skipped | `Float`, sample (n − 1) |
31
+ | `stdevp(expr)` | — | `0.0` | skipped | `Float`, population (n) |
32
+ | `percentileCont(expr, p)` | — | `null` | skipped | `Float`, linear interpolation |
33
+ | `percentileDisc(expr, p)` | — | `null` | skipped | `Float`, nearest rank |
34
+
35
+ ## count
36
+
37
+ ### Row count
38
+
39
+ ```cypher
40
+ MATCH (n:User)
41
+ RETURN count(*) AS users
42
+ ```
43
+
44
+ ### Non-null count
45
+
46
+ ```cypher
47
+ UNWIND [1, 2, null, 4] AS x
48
+ RETURN count(*), count(x)
49
+ // 4, 3
50
+ ```
51
+
52
+ `count(*)` counts every input row, including rows where bound variables
53
+ are `null`; `count(expr)` skips null `expr`.
54
+
55
+ ### Distinct count
56
+
57
+ ```cypher
58
+ UNWIND ['a', 'a', 'b', 'c'] AS x
59
+ RETURN count(x), count(DISTINCT x)
60
+ // 4, 3
61
+ ```
62
+
63
+ ### count with OPTIONAL MATCH
64
+
65
+ This is the subtlety that trips up new Cypher users:
66
+
67
+ ```cypher
68
+ MATCH (u:User)
69
+ OPTIONAL MATCH (u)-[:WROTE]->(p:Post)
70
+ RETURN u.name,
71
+ count(*) AS rows, // 1 per user, even if no posts
72
+ count(p) AS posts // 0 if no posts
73
+ ```
74
+
75
+ Always prefer `count(expr)` when you want zeros for optional matches.
76
+
77
+ ### Empty graph
78
+
79
+ ```cypher
80
+ MATCH (:NoSuchLabel)
81
+ RETURN count(*) // 0
82
+ ```
83
+
84
+ One row out, with value `0` — `count(*)` never returns `null`.
85
+
86
+ ## collect
87
+
88
+ ### Basic collect
89
+
90
+ ```cypher
91
+ MATCH (p:Person)-[:KNOWS]->(f:Person)
92
+ RETURN p.name, collect(f.name) AS friends
93
+ ```
94
+
95
+ ### Distinct values
96
+
97
+ ```cypher
98
+ UNWIND [1, 2, null, 2, 3] AS x
99
+ RETURN collect(x), // [1, 2, 2, 3]
100
+ collect(DISTINCT x) // [1, 2, 3]
101
+ ```
102
+
103
+ ### Collect skips nulls
104
+
105
+ `collect` **skips** top-level `null` values, so an unmatched
106
+ `OPTIONAL MATCH` collects to `[]`. A list or map that merely contains
107
+ `null` is a value and is kept:
108
+
109
+ ```cypher
110
+ UNWIND [[1, null], null, {a: null}] AS x
111
+ RETURN collect(x) // [[1, null], {a: null}]
112
+ ```
113
+
114
+ ### Collect + slice for top-N
115
+
116
+ ```cypher
117
+ MATCH (u:User)-[:WROTE]->(p:Post)
118
+ WITH u, p ORDER BY p.published_at DESC
119
+ WITH u, collect(p.title)[..5] AS last_five
120
+ RETURN u.name, last_five
121
+ ```
122
+
123
+ Use any [list operation](./list.md) on the resulting list.
124
+
125
+ ### Collect of maps
126
+
127
+ ```cypher
128
+ MATCH (p:Project)-[:HAS_TASK]->(t:Task)
129
+ RETURN p.name,
130
+ collect({id: t.id, name: t.name, done: t.done}) AS tasks
131
+ ```
132
+
133
+ One row per project, with an array of task summaries.
134
+
135
+ ## sum
136
+
137
+ ```cypher
138
+ UNWIND [1, 2, null, 4] AS x
139
+ RETURN sum(x); // 7
140
+
141
+ UNWIND [1.0, 2.5, 3.5] AS x
142
+ RETURN sum(x); // 7.0
143
+
144
+ MATCH (:Never)
145
+ RETURN sum(1) // 0 (empty input)
146
+ ```
147
+
148
+ Return type: `Int` when every contributing element is an `Int`; `Float`
149
+ if any contributor is a `Float`.
150
+
151
+ ### Distinct sum
152
+
153
+ ```cypher
154
+ UNWIND [1, 1, 2, 2, 3] AS x
155
+ RETURN sum(x), sum(DISTINCT x) // 9, 6
156
+ ```
157
+
158
+ ## avg
159
+
160
+ ```cypher
161
+ UNWIND [1, 2, 3, 4] AS x
162
+ RETURN avg(x); // 2.5
163
+
164
+ UNWIND [1, null, 3] AS x
165
+ RETURN avg(x); // 2.0
166
+
167
+ MATCH (:Never)
168
+ RETURN avg(1) // null
169
+ ```
170
+
171
+ Always returns `Float` (or `null` on empty input).
172
+
173
+ ## min / max
174
+
175
+ Works on numbers, strings, and temporal values under their natural total
176
+ order.
177
+
178
+ ```cypher
179
+ UNWIND ['banana', 'apple', 'cherry'] AS s
180
+ RETURN min(s), max(s); // 'apple', 'cherry'
181
+
182
+ UNWIND ['2024-01-01'::DATE, '2024-06-30'::DATE, '2024-12-15'::DATE] AS d
183
+ RETURN min(d), max(d)
184
+ ;// 2024-01-01, 2024-12-15
185
+
186
+ MATCH (:Never)
187
+ RETURN min(1) // null
188
+ ```
189
+
190
+ ### Min/max with tiebreaker
191
+
192
+ `min()` / `max()` only return the value, not the node owning it. For
193
+ "the node with the maximum", sort and take one:
194
+
195
+ ```cypher
196
+ MATCH (u:User)-[:WROTE]->(p:Post)
197
+ WITH u, count(p) AS posts
198
+ ORDER BY posts DESC
199
+ LIMIT 1
200
+ RETURN u.name, posts
201
+ ```
202
+
203
+ ## stdev / stdevp
204
+
205
+ Sample vs population standard deviation.
206
+
207
+ ```cypher
208
+ UNWIND [2, 4, 4, 4, 5, 5, 7, 9] AS x
209
+ RETURN stdev(x), // 2.1380… (n − 1)
210
+ stdevp(x) // 2.0 (n)
211
+ ```
212
+
213
+ - `stdev` returns `0.0` when fewer than two non-null values are aggregated.
214
+ - `stdevp` returns `0.0` on an empty input.
215
+
216
+ ```cypher
217
+ MATCH (r:Review)
218
+ WITH r.product AS product, avg(r.stars) AS mean, stdev(r.stars) AS sd
219
+ WHERE sd > 1.0
220
+ RETURN product, mean, sd
221
+ ```
222
+
223
+ ## percentileCont / percentileDisc
224
+
225
+ Both take the column and a percentile `p ∈ [0, 1]`.
226
+
227
+ ```cypher
228
+ UNWIND [1, 2, 3, 4, 5] AS x
229
+ RETURN percentileCont(x, 0.5), // 3.0 (exact median for odd count)
230
+ percentileDisc(x, 0.5); // 3
231
+
232
+ UNWIND [1, 2, 3, 4] AS x
233
+ RETURN percentileCont(x, 0.5), // 2.5 (linear interpolation)
234
+ percentileDisc(x, 0.5); // 2 (nearest rank)
235
+
236
+ UNWIND [10, 20, 30, 40, 50, 60, 70, 80, 90, 100] AS x
237
+ RETURN percentileCont(x, 0.9), // 91.0
238
+ percentileDisc(x, 0.9) // 90
239
+ ```
240
+
241
+ - `percentileCont` interpolates between values.
242
+ - `percentileDisc` picks an actual input value.
243
+
244
+ Use `percentileCont` when the "true" percentile matters (latency
245
+ histograms); `percentileDisc` when you need a real observation (the
246
+ actual data point at P50).
247
+
248
+ ## Typical patterns
249
+
250
+ ### Group + aggregate
251
+
252
+ ```cypher
253
+ MATCH (o:Order)-[:CONTAINS]->(i:Item)
254
+ RETURN o.region AS region,
255
+ count(i) AS items,
256
+ sum(i.price) AS revenue
257
+ ORDER BY revenue DESC
258
+ ```
259
+
260
+ ### Aggregate + filter (HAVING)
261
+
262
+ ```cypher
263
+ MATCH (p:Person)-[:WORKS_AT]->(c:Company)
264
+ WITH c.name AS company, count(p) AS employees
265
+ WHERE employees > 5
266
+ RETURN company, employees
267
+ ```
268
+
269
+ ### Multiple aggregates in one RETURN
270
+
271
+ ```cypher
272
+ MATCH (r:Review)
273
+ RETURN count(*) AS n,
274
+ avg(r.stars) AS mean,
275
+ stdev(r.stars) AS sd,
276
+ percentileCont(r.stars, 0.5) AS median,
277
+ percentileCont(r.stars, 0.95) AS p95
278
+ ```
279
+
280
+ ### Re-aggregate after first aggregate
281
+
282
+ ```cypher
283
+ MATCH (o:Order)
284
+ WITH o.region AS region, sum(o.amount) AS revenue
285
+ RETURN count(region) AS regions,
286
+ avg(revenue) AS mean_regional_revenue
287
+ ```
288
+
289
+ ### Rolling count by date bucket
290
+
291
+ ```cypher
292
+ MATCH (e:Event)
293
+ RETURN temporal.truncate('month', e.at) AS month,
294
+ count(*) AS events
295
+ ORDER BY month
296
+ ```
297
+
298
+ Uses [`temporal.truncate`](./temporal.md#truncation).
299
+
300
+ ### Percentile per group
301
+
302
+ ```cypher
303
+ MATCH (r:Review)
304
+ RETURN r.product AS product,
305
+ percentileCont(r.stars, 0.5) AS p50,
306
+ percentileCont(r.stars, 0.95) AS p95
307
+ ORDER BY p95 DESC
308
+ ```
309
+
310
+ ### Count-if via CASE
311
+
312
+ `count(expr)` skips `null`. A `CASE` with an omitted `ELSE` returns
313
+ `null`, so the pattern cleanly expresses "count rows where condition
314
+ holds":
315
+
316
+ ```cypher
317
+ MATCH (o:Order)
318
+ RETURN o.region,
319
+ count(CASE WHEN o.status = 'paid' THEN 1 END) AS paid,
320
+ count(CASE WHEN o.status = 'cancelled' THEN 1 END) AS cancelled
321
+ ```
322
+
323
+ See [`CASE`](../queries/return-with.md#case-expressions).
324
+
325
+ ### Sum with a filter on the aggregated value
326
+
327
+ `WHERE` runs before aggregation. To filter aggregated values, pipe
328
+ through [`WITH`](../queries/return-with.md#with):
329
+
330
+ ```cypher
331
+ MATCH (o:Order)
332
+ WITH o.customer AS customer, sum(o.amount) AS lifetime
333
+ WHERE lifetime > 1000
334
+ RETURN customer, lifetime
335
+ ORDER BY lifetime DESC
336
+ ```
337
+
338
+ ### Aggregation with ORDER BY inside collect
339
+
340
+ `collect` preserves input order. Sort the rows before the aggregate
341
+ to produce an ordered list:
342
+
343
+ ```cypher
344
+ MATCH (u:User)-[:WROTE]->(p:Post)
345
+ WITH u, p ORDER BY p.published_at DESC
346
+ RETURN u.handle, collect(p.title)[..3] AS latest_three
347
+ ```
348
+
349
+ ## Limitations
350
+
351
+ - **Aggregates are rejected inside [`WHERE`](../queries/where.md).** Use
352
+ [`WITH … WHERE`](../queries/return-with.md#having-style-filtering-with)
353
+ instead.
354
+ - **`stdev`, `stdevp`, `percentileCont`, `percentileDisc` don't
355
+ support `DISTINCT`.** For a percentile of distinct values, first
356
+ `collect(DISTINCT x)`, then [`UNWIND`](../queries/unwind-merge.md#unwind)
357
+ and aggregate.
358
+ - **`count(*)` counts rows, not non-null values.** Use `count(expr)`
359
+ when you want nulls skipped.
360
+ - **No `GROUP BY` keyword** — non-aggregated columns in the same
361
+ projection stage form the group key implicitly.
362
+
363
+ See [Limitations](../limitations.md#aggregates) for the full list.
364
+
365
+ ## See also
366
+
367
+ - [**Aggregation query page**](../queries/aggregation.md) — clause semantics and grouping.
368
+ - [**RETURN / WITH**](../queries/return-with.md) — HAVING-style filtering.
369
+ - [**WHERE**](../queries/where.md) — filter before aggregation.
370
+ - [**UNWIND**](../queries/unwind-merge.md#unwind) — expand a collected list back into rows.
371
+ - [**List Functions**](./list.md) — post-process `collect()` output.
372
+ - [**Temporal Functions**](./temporal.md) — date buckets for grouping.