@loradb/lora-node 0.36.0 → 0.36.2
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.
- package/README.md +5 -0
- package/docs/README.md +86 -0
- package/docs/concepts/graph-model.md +270 -0
- package/docs/concepts/nodes.md +285 -0
- package/docs/concepts/properties.md +348 -0
- package/docs/concepts/relationships.md +325 -0
- package/docs/concepts/result-formats.md +183 -0
- package/docs/concepts/schema-free.md +183 -0
- package/docs/cookbook.md +1081 -0
- package/docs/data-types/lists-and-maps.md +406 -0
- package/docs/data-types/overview.md +210 -0
- package/docs/data-types/scalars.md +376 -0
- package/docs/data-types/spatial.md +291 -0
- package/docs/data-types/temporal.md +355 -0
- package/docs/data-types/vectors.md +563 -0
- package/docs/errors.md +183 -0
- package/docs/functions/aggregation.md +372 -0
- package/docs/functions/list.md +522 -0
- package/docs/functions/map.md +207 -0
- package/docs/functions/math.md +421 -0
- package/docs/functions/number.md +197 -0
- package/docs/functions/overview.md +545 -0
- package/docs/functions/spatial.md +384 -0
- package/docs/functions/string.md +502 -0
- package/docs/functions/temporal.md +590 -0
- package/docs/functions/utility.md +137 -0
- package/docs/functions/vectors.md +772 -0
- package/docs/getting-started/installation.md +204 -0
- package/docs/getting-started/node.md +582 -0
- package/docs/getting-started/tutorial.md +334 -0
- package/docs/index.md +203 -0
- package/docs/limitations.md +291 -0
- package/docs/performance.md +219 -0
- package/docs/queries/aggregation.md +520 -0
- package/docs/queries/cheat-sheet.md +302 -0
- package/docs/queries/constraints.md +239 -0
- package/docs/queries/create.md +331 -0
- package/docs/queries/examples.md +453 -0
- package/docs/queries/index.md +169 -0
- package/docs/queries/indexes.md +546 -0
- package/docs/queries/match.md +429 -0
- package/docs/queries/ordering.md +359 -0
- package/docs/queries/parameters.md +328 -0
- package/docs/queries/paths.md +462 -0
- package/docs/queries/return-with.md +500 -0
- package/docs/queries/set-delete.md +369 -0
- package/docs/queries/unwind-merge.md +358 -0
- package/docs/queries/where.md +416 -0
- package/docs/snapshot.md +545 -0
- package/docs/troubleshooting.md +1158 -0
- package/docs/wal.md +570 -0
- package/docs/why.md +273 -0
- 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.2"
|
|
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.2"
|
|
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.
|