@loradb/lora-node 0.36.0 → 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 (53) hide show
  1. package/README.md +5 -0
  2. package/docs/README.md +86 -0
  3. package/docs/concepts/graph-model.md +270 -0
  4. package/docs/concepts/nodes.md +285 -0
  5. package/docs/concepts/properties.md +348 -0
  6. package/docs/concepts/relationships.md +325 -0
  7. package/docs/concepts/result-formats.md +183 -0
  8. package/docs/concepts/schema-free.md +183 -0
  9. package/docs/cookbook.md +1081 -0
  10. package/docs/data-types/lists-and-maps.md +406 -0
  11. package/docs/data-types/overview.md +210 -0
  12. package/docs/data-types/scalars.md +376 -0
  13. package/docs/data-types/spatial.md +291 -0
  14. package/docs/data-types/temporal.md +349 -0
  15. package/docs/data-types/vectors.md +563 -0
  16. package/docs/errors.md +183 -0
  17. package/docs/functions/aggregation.md +372 -0
  18. package/docs/functions/list.md +522 -0
  19. package/docs/functions/map.md +207 -0
  20. package/docs/functions/math.md +421 -0
  21. package/docs/functions/number.md +197 -0
  22. package/docs/functions/overview.md +545 -0
  23. package/docs/functions/spatial.md +384 -0
  24. package/docs/functions/string.md +502 -0
  25. package/docs/functions/temporal.md +590 -0
  26. package/docs/functions/utility.md +137 -0
  27. package/docs/functions/vectors.md +772 -0
  28. package/docs/getting-started/installation.md +204 -0
  29. package/docs/getting-started/node.md +582 -0
  30. package/docs/getting-started/tutorial.md +334 -0
  31. package/docs/index.md +203 -0
  32. package/docs/limitations.md +291 -0
  33. package/docs/performance.md +219 -0
  34. package/docs/queries/aggregation.md +520 -0
  35. package/docs/queries/cheat-sheet.md +302 -0
  36. package/docs/queries/constraints.md +239 -0
  37. package/docs/queries/create.md +331 -0
  38. package/docs/queries/examples.md +453 -0
  39. package/docs/queries/index.md +169 -0
  40. package/docs/queries/indexes.md +538 -0
  41. package/docs/queries/match.md +429 -0
  42. package/docs/queries/ordering.md +359 -0
  43. package/docs/queries/parameters.md +328 -0
  44. package/docs/queries/paths.md +462 -0
  45. package/docs/queries/return-with.md +500 -0
  46. package/docs/queries/set-delete.md +369 -0
  47. package/docs/queries/unwind-merge.md +358 -0
  48. package/docs/queries/where.md +416 -0
  49. package/docs/snapshot.md +545 -0
  50. package/docs/troubleshooting.md +1158 -0
  51. package/docs/wal.md +570 -0
  52. package/docs/why.md +273 -0
  53. package/package.json +13 -14
@@ -0,0 +1,207 @@
1
+ ---
2
+ title: "Map Functions"
3
+ description: "Map functions in LoraDB — lookup, projection, patching, shallow and deep merge, nested paths, entries, flattening, grouping, and index-building helpers for MAP values."
4
+ online: "https://loradb.com/docs/functions/map"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Map Functions
9
+
10
+ [Maps](../data-types/lists-and-maps.md#maps) are ordered by key when they
11
+ are returned as values, which makes function output deterministic in
12
+ tests and API responses. Map functions return `null` when the input is
13
+ not a map or a required key argument is not a string.
14
+
15
+ ## Overview
16
+
17
+ | Goal | Function |
18
+ |---|---|
19
+ | Lookup | `map.get`, `map.has_key` |
20
+ | Shape projection | `map.pick`, `map.keys`, `map.values`, `map.entries` |
21
+ | Patching | `map.set`, `map.remove`, `map.rename`, `map.merge`, `map.deep_merge`, `map.compact` |
22
+ | Construct maps | `map.from` |
23
+ | Nested map paths | `map.get_path`, `map.set_path`, `map.remove_path`, `map.flatten`, `map.unflatten` |
24
+ | Row-shaped list helpers | `map.group_by`, `map.index_by` |
25
+ | Reverse lookup | `map.invert` |
26
+ | Size | `map.size`, `value.size` |
27
+
28
+ ## Lookup
29
+
30
+ Use `map.get(map, key[, default])` when a missing key should not be
31
+ confused with a stored `null` value. Use `map.has_key` when presence is
32
+ the question.
33
+
34
+ ```cypher
35
+ RETURN map.get({name: 'Ada'}, 'name'); // 'Ada'
36
+ RETURN map.get({name: 'Ada'}, 'missing'); // null
37
+ RETURN map.get({name: 'Ada'}, 'missing', 'n/a'); // 'n/a'
38
+
39
+ RETURN map.has_key({a: 1, b: null}, 'b'); // true
40
+ RETURN map.has_key({a: 1}, 'b') // false
41
+ ```
42
+
43
+ Dot lookup remains the shortest form when a missing key can simply
44
+ become `null`:
45
+
46
+ ```cypher
47
+ WITH {name: 'Ada'} AS person
48
+ RETURN person.name
49
+ ```
50
+
51
+ ## Projection
52
+
53
+ `map.pick(map, keys)` keeps only the requested keys that exist. The
54
+ returned map is still sorted by key in output.
55
+
56
+ ```cypher
57
+ RETURN map.pick({id: 1, name: 'Ada', email: 'ada@example.test'}, ['id', 'name'])
58
+ // {id: 1, name: 'Ada'}
59
+ ```
60
+
61
+ Introspection helpers expose a map as lists:
62
+
63
+ ```cypher
64
+ RETURN map.keys({c: 1, a: 2, b: 3}); // ['a', 'b', 'c']
65
+ RETURN map.values({a: 1, b: 2}); // [1, 2]
66
+ RETURN map.values({a: 1, b: 2}, ['b']); // [2]
67
+ RETURN map.entries({a: 1, b: 2}); // [['a', 1], ['b', 2]]
68
+ RETURN map.size({a: 1, b: 2}) // 2
69
+ ```
70
+
71
+ ## Patching
72
+
73
+ All patching helpers return a new map value; they do not mutate stored
74
+ properties by themselves. To persist a patched map, assign it in `SET`.
75
+
76
+ ```cypher
77
+ RETURN map.set({a: 1}, 'b', 2); // {a: 1, b: 2}
78
+ RETURN map.remove({a: 1, b: 2}, 'a'); // {b: 2}
79
+ RETURN map.rename({first: 'Ada'}, 'first', 'name')
80
+ ;// {name: 'Ada'}
81
+ RETURN map.compact({a: 1, b: null, c: 3}) // {a: 1, c: 3}
82
+ ```
83
+
84
+ `map.remove` also accepts a list of keys:
85
+
86
+ ```cypher
87
+ RETURN map.remove({a: 1, b: 2, c: 3}, ['a', 'c'])
88
+ // {b: 2}
89
+ ```
90
+
91
+ ## Merge
92
+
93
+ `map.merge(left, right[, strategy])` combines two maps.
94
+
95
+ | Strategy | Behaviour |
96
+ |---|---|
97
+ | `'right'` | Default. Values from `right` replace values from `left`. |
98
+ | `'left'` | Existing values from `left` win. |
99
+ | `'error'` | Returns `null` if both maps contain the same key. |
100
+
101
+ ```cypher
102
+ RETURN map.merge({a: 1}, {a: 9, b: 2}); // {a: 9, b: 2}
103
+ RETURN map.merge({a: 1}, {a: 9, b: 2}, 'left'); // {a: 1, b: 2}
104
+ RETURN map.merge({a: 1}, {a: 9}, 'error') // null
105
+ ```
106
+
107
+ `map.deep_merge(left, right[, strategy])` uses the same conflict
108
+ strategies, but when both sides contain a map at the same key it merges
109
+ those nested maps recursively.
110
+
111
+ ```cypher
112
+ RETURN map.deep_merge(
113
+ {user: {name: 'Ada', flags: {admin: false}}},
114
+ {user: {email: 'ada@example.test', flags: {admin: true}}}
115
+ )
116
+ // {user: {email: 'ada@example.test', flags: {admin: true}, name: 'Ada'}}
117
+ ```
118
+
119
+ Use `map.merge` for flat patches where replacement is exactly what you
120
+ want. Use `map.deep_merge` for JSON-like configuration and payload
121
+ maps where nested keys should survive partial updates.
122
+
123
+ ## Constructing Maps
124
+
125
+ `map.from` builds a map from alternating key/value lists, pair lists, or
126
+ parallel key and value lists. Keys must be strings.
127
+
128
+ ```cypher
129
+ RETURN map.from(['a', 1, 'b', 2]); // {a: 1, b: 2}
130
+ RETURN map.from([['a', 1], ['b', 2]]); // {a: 1, b: 2}
131
+ RETURN map.from(['a', 'b'], [1, 2]) // {a: 1, b: 2}
132
+ ```
133
+
134
+ ## Flattening
135
+
136
+ For direct nested lookup and patching, use path helpers. A path can be a
137
+ dotted string or a list of string keys. Missing reads return `null`, or
138
+ the optional default value when one is supplied.
139
+
140
+ ```cypher
141
+ RETURN map.get_path({user: {name: 'Ada'}}, 'user.name')
142
+ ;// 'Ada'
143
+
144
+ RETURN map.get_path({user: {name: 'Ada'}}, ['user', 'email'], 'n/a')
145
+ ;// 'n/a'
146
+
147
+ RETURN map.set_path({user: {name: 'Ada'}}, 'user.email', 'ada@example.test')
148
+ ;// {user: {email: 'ada@example.test', name: 'Ada'}}
149
+
150
+ RETURN map.remove_path({user: {name: 'Ada', email: 'a@x'}}, 'user.email')
151
+ // {user: {name: 'Ada'}}
152
+ ```
153
+
154
+ `map.set_path` creates missing intermediate maps. If an intermediate
155
+ path segment exists but is not a map, it is replaced with a map so the
156
+ requested nested value can be written.
157
+
158
+ For shape conversion, `map.flatten` turns nested maps into dotted keys.
159
+ `map.unflatten` reverses the operation. Pass a separator string when `.`
160
+ is not a good fit for your data.
161
+
162
+ ```cypher
163
+ RETURN map.flatten({user: {name: 'Ada', age: 36}, active: true})
164
+ ;// {active: true, user.age: 36, user.name: 'Ada'}
165
+
166
+ RETURN map.unflatten(map.flatten({user: {name: 'Ada'}}))
167
+ // {user: {name: 'Ada'}}
168
+ ```
169
+
170
+ ## Grouping And Indexing
171
+
172
+ These helpers operate on a list of maps, which is a common shape after
173
+ collecting rows or decoding JSON.
174
+
175
+ ```cypher
176
+ WITH [
177
+ {id: 'u1', team: 'eng', name: 'Ada'},
178
+ {id: 'u2', team: 'eng', name: 'Grace'},
179
+ {id: 'u3', team: 'ops', name: 'Lin'}
180
+ ] AS rows
181
+ RETURN map.group_by(rows, 'team') AS by_team,
182
+ map.index_by(rows, 'id') AS by_id
183
+ ```
184
+
185
+ `map.group_by` returns a map from key value to list of matching maps.
186
+ `map.index_by` returns a map from key value to the last matching map.
187
+ Both stringify the grouping value, so integers, booleans, and strings
188
+ can all be used as group keys.
189
+
190
+ ## Inverting
191
+
192
+ `map.invert(map)` creates a reverse lookup from each value to its key.
193
+ Values are stringified, and duplicate stringified values keep the last
194
+ key in sorted map order.
195
+
196
+ ```cypher
197
+ RETURN map.invert({draft: 0, published: 1})
198
+ // {'0': 'draft', '1': 'published'}
199
+ ```
200
+
201
+ ## See Also
202
+
203
+ - [**Lists and Maps**](../data-types/lists-and-maps.md) — literals,
204
+ property access, and dynamic keys.
205
+ - [**List Functions**](./list.md) — helpers for lists of maps.
206
+ - [**JSON Functions**](./overview.md#categories) — `json.decode` commonly
207
+ returns nested maps.
@@ -0,0 +1,421 @@
1
+ ---
2
+ title: "Math Functions"
3
+ description: "Math functions in LoraDB — math.abs, math.sign, math.sqrt, math.exp, math.log, trigonometry, rounding, and constants — with domain-safe fallbacks to null rather than errors."
4
+ online: "https://loradb.com/docs/functions/math"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Math Functions
9
+
10
+ Every math function returns `null` on `null` input. Functions with
11
+ a restricted domain (e.g. `math.sqrt` of a negative number) return
12
+ `null` rather than raising.
13
+
14
+ ## Overview
15
+
16
+ | Goal | Function |
17
+ |---|---|
18
+ | Absolute value | [`math.abs(n)`](#rounding-and-absolute-value) |
19
+ | Round | [`math.ceil`, `math.floor`, `math.trunc`, `math.round`, `math.sign`](#rounding-and-absolute-value) |
20
+ | Root, power, log | [`math.sqrt`, `math.hypot`, `math.pow`, `math.exp`, `math.log`, `math.ln`, `math.log10`, `math.log_base`](#roots-powers-logs) |
21
+ | Bounds and interpolation | [`math.min`, `math.max`, `math.clamp`, `math.lerp`](#bounds-and-interpolation) |
22
+ | Number formatting and predicates | [`number.format`, `number.to_base`, `number.from_base`, `number.to_roman`, `number.from_roman`, `number.is_integer`, `number.is_even`, `number.is_odd`, `number.is_positive`](#number-formatting-and-predicates) |
23
+ | Trig | [`math.sin`, `math.cos`, `math.tan`, `math.asin`, `math.acos`, `math.atan`, `math.atan2`](#trigonometry) |
24
+ | Unit conversion | [`math.degrees`, `math.radians`](#trigonometry) |
25
+ | Constants | [`math.pi()`, `math.e()`](#constants) |
26
+ | Random | [`math.random()` / `random()`](#random) |
27
+ | Arithmetic | [`+ - * / % ^`](#arithmetic-operators) |
28
+
29
+ ## Rounding and absolute value
30
+
31
+ | Function | Behaviour |
32
+ |---|---|
33
+ | `math.abs(n)` | Absolute value — `Int` stays `Int`, `Float` stays `Float` |
34
+ | `math.ceil(n)` | Round up to the nearest integer |
35
+ | `math.floor(n)` | Round down |
36
+ | `math.trunc(n)` | Drop the fractional part, toward zero |
37
+ | `math.round(n[, digits[, mode]])` | Round to nearest; default mode is `half_up` |
38
+ | `math.sign(n)` | `-1`, `0`, or `1` |
39
+
40
+ ```cypher
41
+ RETURN math.abs(-3.5); // 3.5
42
+ RETURN math.ceil(3.1); // 4
43
+ RETURN math.floor(3.9); // 3
44
+ RETURN math.trunc(-3.9); // -3
45
+ RETURN math.round(3.5); // 4
46
+ RETURN math.round(2.5); // 3 (default half-up rounding)
47
+ RETURN math.sign(-9); // -1
48
+ RETURN math.sign(0); // 0
49
+ RETURN math.sign(9) // 1
50
+ ```
51
+
52
+ ### Rounding modes
53
+
54
+ `math.round(n)` defaults to half-up rounding and returns an integer.
55
+ Pass `digits` to round to a decimal place. Pass a mode string to choose
56
+ another strategy: `'half_up'`, `'half_even'`, `'ceil'`, `'floor'`, or
57
+ `'trunc'`.
58
+
59
+ ```cypher
60
+ RETURN math.round(3.14159, 2); // 3.14
61
+ RETURN math.round(2.5); // 3
62
+ RETURN math.round(2.5, 0, 'half_even') // 2.0
63
+ ```
64
+
65
+ ## Roots, powers, logs
66
+
67
+ | Function | Domain | Returns |
68
+ |---|---|---|
69
+ | `math.sqrt(n)` | `n ≥ 0` | `Float`; `null` on negative input |
70
+ | `math.hypot(a, b)` | numeric inputs | `sqrt(a² + b²)` without intermediate overflow |
71
+ | `math.pow(a, b)` | numeric inputs | `a` raised to `b` |
72
+ | `math.log(n)` / `math.ln(n)` | `n > 0` | Natural log; `null` out of domain |
73
+ | `math.log10(n)` | `n > 0` | Base-10 log; `null` out of domain |
74
+ | `math.log_base(n, base)` | `n > 0`, `base > 0`, `base != 1` | Logarithm in an arbitrary base |
75
+ | `math.exp(n)` | any | `e^n` |
76
+
77
+ ```cypher
78
+ RETURN math.sqrt(16); // 4.0
79
+ RETURN math.hypot(3, 4); // 5.0
80
+ RETURN math.pow(2, 10); // 1024.0
81
+ RETURN math.sqrt(-1); // null
82
+ RETURN math.log(math.e()); // 1.0
83
+ RETURN math.log10(1000); // 3.0
84
+ RETURN math.log_base(8, 2); // 3.0
85
+ RETURN math.exp(1) // 2.7182818…
86
+ ```
87
+
88
+ ### Hypotenuse
89
+
90
+ ```cypher
91
+ WITH 3 AS a, 4 AS b
92
+ RETURN math.hypot(a, b) // 5.0
93
+ ```
94
+
95
+ For 2D Cartesian points, [`geo.distance`](./spatial.md#geodistance) does this.
96
+
97
+ ## Bounds and Interpolation
98
+
99
+ `math.min(a, b, ...)` and `math.max(a, b, ...)` compare numeric
100
+ arguments inside a single row. They are scalar helpers, not aggregate
101
+ functions. Use [`min(expr)` and `max(expr)`](./aggregation.md#min--max)
102
+ when you need the smallest or largest value across rows in a group.
103
+
104
+ All arguments must be finite numbers. A `null`, string, map, list, or
105
+ non-finite float returns `null`.
106
+
107
+ ```cypher
108
+ RETURN math.min(3, 1, 2); // 1
109
+ RETURN math.max(3, 1, 2); // 3
110
+ RETURN math.min(3, 1.5, 2); // 1.5
111
+ RETURN math.max(3, null); // null
112
+ RETURN math.clamp(125, 0, 100); // 100
113
+ RETURN math.lerp(10, 20, 0.25) // 12.5
114
+ ```
115
+
116
+ `math.clamp(x, lo, hi)` constrains a value to an inclusive range.
117
+ `math.lerp(a, b, t)` returns `a + (b - a) * t`, which is useful for
118
+ normalising scores and building weighted formulas.
119
+
120
+ ## Number Formatting And Predicates
121
+
122
+ The `number.*` namespace contains numeric presentation helpers and
123
+ integer predicates. Base conversion supports radices from 2 through 36.
124
+ Invalid digits, unsupported bases, and overflow return `null`.
125
+
126
+ ```cypher
127
+ RETURN number.format(12345.678, 2, ','); // '12,345.68'
128
+ RETURN number.to_base(255, 16); // 'ff'
129
+ RETURN number.from_base('ff', 16); // 255
130
+ RETURN number.to_roman(1994); // 'MCMXCIV'
131
+ RETURN number.from_roman('MCMXCIV') // 1994
132
+ ```
133
+
134
+ Predicates are intentionally type-aware:
135
+
136
+ ```cypher
137
+ RETURN number.is_integer(42); // true
138
+ RETURN number.is_integer(42.5); // false
139
+ RETURN number.is_even(42); // true
140
+ RETURN number.is_odd(42); // false
141
+ RETURN number.is_even(42.0); // null
142
+ RETURN number.is_positive(0.1); // true
143
+ RETURN number.is_negative(-1); // true
144
+ RETURN number.is_zero(0.0); // true
145
+ RETURN number.is_nan(0.0 / 0.0) // true
146
+ ```
147
+
148
+ `number.is_even` and `number.is_odd` accept integer values. Use
149
+ `number.is_integer` first when data may arrive as floats. Sign
150
+ predicates accept both integers and floats.
151
+
152
+ ## Trigonometry
153
+
154
+ All angles are in **radians**. Domain violations (e.g. `math.asin(2)`)
155
+ return `null` rather than raising.
156
+
157
+ | Function | Notes |
158
+ |---|---|
159
+ | `math.sin(x)`, `math.cos(x)`, `math.tan(x)` | Standard trig |
160
+ | `math.asin(x)`, `math.acos(x)`, `math.atan(x)` | Inverse trig; domain `[-1, 1]` for `asin`/`acos` |
161
+ | `math.atan2(y, x)` | Two-argument arctangent — `y` first |
162
+ | `math.degrees(r)` / `math.radians(d)` | Unit conversion |
163
+
164
+ ```cypher
165
+ RETURN math.sin(math.pi() / 2); // 1.0
166
+ RETURN math.cos(0); // 1.0
167
+ RETURN math.tan(math.pi() / 4); // 0.9999… (float rounding)
168
+ RETURN math.asin(1); // 1.5707… (π/2)
169
+ RETURN math.asin(2); // null (out of domain)
170
+ RETURN math.atan2(1, 1); // 0.7853… (π/4)
171
+ RETURN math.degrees(math.pi()); // 180.0
172
+ RETURN math.radians(180) // 3.1415…
173
+ ```
174
+
175
+ ### Work in degrees
176
+
177
+ Most geometry inputs are degrees — wrap every trig call:
178
+
179
+ ```cypher
180
+ WITH 30 AS deg
181
+ RETURN math.sin(math.radians(deg)),
182
+ math.cos(math.radians(deg))
183
+ ```
184
+
185
+ ### Bearing between two points
186
+
187
+ ```cypher
188
+ WITH 4.89 AS lon1, 52.37 AS lat1,
189
+ 4.40 AS lon2, 51.00 AS lat2
190
+ WITH math.radians(lat1) AS phi1, math.radians(lat2) AS phi2,
191
+ math.radians(lon2 - lon1) AS d_lambda
192
+ RETURN (math.degrees(math.atan2(
193
+ math.sin(d_lambda) * math.cos(phi2),
194
+ math.cos(phi1) * math.sin(phi2) - math.sin(phi1) * math.cos(phi2) * math.cos(d_lambda)
195
+ )) + 360) % 360 AS bearing
196
+ ```
197
+
198
+ Approximation — use [`geo.distance`](./spatial.md#geodistance) for real geodesic
199
+ distance between WGS-84 points.
200
+
201
+ ## Constants
202
+
203
+ ```cypher
204
+ RETURN math.pi(); // 3.14159…
205
+ RETURN math.e() // 2.71828…
206
+ ```
207
+
208
+ ## Random
209
+
210
+ `math.random()` returns a `Float` in `[0, 1)`. The bare
211
+ `random()` form is an alias for the same function.
212
+
213
+ ```cypher
214
+ RETURN math.random(); // e.g. 0.42389…
215
+ RETURN math.random() * 100; // a Float in [0, 100)
216
+ RETURN toInteger(math.random() * 100) // an Int in [0, 99]
217
+ ```
218
+
219
+ Not cryptographically secure — seeded from system-time nanoseconds. Do
220
+ **not** use for key generation or sampling that must be unpredictable.
221
+
222
+ ### Random sample
223
+
224
+ Each row gets its own `math.random()` value:
225
+
226
+ ```cypher
227
+ MATCH (u:User)
228
+ RETURN u
229
+ ORDER BY math.random()
230
+ LIMIT 100
231
+ ```
232
+
233
+ ### Weighted pick
234
+
235
+ ```cypher
236
+ MATCH (p:Prize)
237
+ WITH p, math.random() * p.weight AS score
238
+ ORDER BY score DESC
239
+ LIMIT 1
240
+ RETURN p
241
+ ```
242
+
243
+ ## Arithmetic operators
244
+
245
+ | Op | Example | Notes |
246
+ |---|---|---|
247
+ | `+` | `a + b` | Also concatenates strings and lists |
248
+ | `-` | `a - b` | Unary `-x` allowed |
249
+ | `*` | `a * b` | |
250
+ | `/` | `a / b` | Two integers divide as integers, truncating toward zero; a `Float` operand gives a `Float`. Integer divide by zero fails the query; float divide by zero → `null` |
251
+ | `%` | `a % b` | Remainder, signed like the dividend; a `Float` operand gives a `Float`. Integer mod by zero fails the query; float mod by zero → `null` |
252
+ | `^` | `a ^ b` | Exponent; an integral result that fits in `Int` comes back as `Int` |
253
+
254
+ ```cypher
255
+ RETURN 10 / 3; // 3 (integer division)
256
+ RETURN 10 / 4.0; // 2.5
257
+ RETURN 10 % 3; // 1
258
+ RETURN 7.5 % 2; // 1.5
259
+ RETURN 2 ^ 10; // 1024
260
+ RETURN 1 / 0 // error: integer division by zero
261
+ ```
262
+
263
+ `+`, `-`, `*`, `/`, `%` and unary `-` on integers are overflow-checked: a
264
+ result outside the 64-bit range fails the query instead of wrapping.
265
+ See [Integer overflow](#integer-overflow).
266
+
267
+ ### Mixed-type arithmetic
268
+
269
+ ```cypher
270
+ RETURN 1 + 2.5; // 3.5 (Float)
271
+ RETURN 10 / 3.0 // 3.333…
272
+ ```
273
+
274
+ Any `Float` operand promotes the result to `Float`. For an exact
275
+ quotient of two integers, make one of them a float:
276
+
277
+ ```cypher
278
+ RETURN toFloat(10) / 3 // 3.333…
279
+ ```
280
+
281
+ ## Numeric precedence
282
+
283
+ Unary `-`/`+` binds tightest, then `^`, then `*` / `/` / `%`, then
284
+ binary `+` / `-`, then comparisons. Use parentheses freely.
285
+
286
+ ```cypher
287
+ RETURN 1 + 2 * 3; // 7
288
+ RETURN (1 + 2) * 3; // 9
289
+ RETURN -2 ^ 2; // 4 (binds as (-2)^2)
290
+ RETURN -(2 ^ 2) // -4
291
+ ```
292
+
293
+ ## Common patterns
294
+
295
+ ### Clamp a value
296
+
297
+ ```cypher
298
+ WITH $raw AS raw, 0 AS lo, 100 AS hi
299
+ RETURN math.clamp(raw, lo, hi) AS clamped
300
+ ```
301
+
302
+ ### Normalise to 0..1
303
+
304
+ ```cypher
305
+ MATCH (m:Metric)
306
+ WITH min(m.value) AS lo, max(m.value) AS hi
307
+ MATCH (m:Metric)
308
+ RETURN m.id,
309
+ (m.value - lo) / (hi - lo) AS normalised
310
+ ```
311
+
312
+ ### Bucket a number
313
+
314
+ ```cypher
315
+ MATCH (p:Product)
316
+ RETURN (p.price / 10) * 10 AS bucket, count(*) AS n
317
+ ORDER BY bucket
318
+ ```
319
+
320
+ ### Log-scale bucket
321
+
322
+ ```cypher
323
+ MATCH (p:Post)
324
+ WITH p, CASE WHEN p.views > 0 THEN toInteger(math.log10(p.views)) ELSE 0 END AS decade
325
+ RETURN decade, count(*) AS posts
326
+ ORDER BY decade
327
+ ```
328
+
329
+ ### Exponential decay (recency score)
330
+
331
+ ```cypher
332
+ MATCH (p:Post)
333
+ WITH p, temporal.between(p.published_at, temporal.now()).days AS age
334
+ RETURN p.id, p.title,
335
+ p.views * math.exp(-age * 0.05) AS score
336
+ ORDER BY score DESC
337
+ LIMIT 20
338
+ ```
339
+
340
+ Half-life of roughly 14 days at `0.05` — tune the constant to taste.
341
+
342
+ ### Percent change
343
+
344
+ ```cypher
345
+ MATCH (m:Metric)
346
+ RETURN m.id,
347
+ m.current,
348
+ m.previous,
349
+ CASE
350
+ WHEN m.previous = 0 OR m.previous IS NULL THEN null
351
+ ELSE (m.current - m.previous) * 100.0 / m.previous
352
+ END AS pct_change
353
+ ```
354
+
355
+ Guard against zero/null — see
356
+ [`CASE`](../queries/return-with.md#case-expressions).
357
+
358
+ ### Weighted average
359
+
360
+ ```cypher
361
+ MATCH (r:Review)
362
+ RETURN toFloat(sum(r.stars * r.weight)) / sum(r.weight) AS weighted_mean
363
+ ```
364
+
365
+ ## Edge cases
366
+
367
+ ### Integer overflow
368
+
369
+ Integer `+`, `-`, `*`, `/`, `%` and unary `-` are checked, and so are
370
+ `list.sum`, `list.product` and `list.scan`. A result outside
371
+ the `i64` range fails the query with a `LORA_VALIDATION` error such as
372
+ `integer addition overflowed` — it never wraps or panics:
373
+
374
+ ```cypher
375
+ RETURN 9223372036854775807 + 1
376
+ // error: integer addition overflowed
377
+ ```
378
+
379
+ For potentially huge inputs, coerce to `Float` with
380
+ [`toFloat`](./string.md#type-conversion) first.
381
+
382
+ ### NaN / Infinity
383
+
384
+ Float division by zero never produces `Infinity` or `NaN` — it returns
385
+ `null` (integer division by zero fails the query). Math functions guard
386
+ their domains the same way.
387
+
388
+ ```cypher
389
+ RETURN 1.0 / 0.0; // null
390
+ RETURN 0.0 / 0.0; // null
391
+ RETURN math.sqrt(-1) // null (Cypher-level domain guard, not NaN)
392
+ ```
393
+
394
+ If a `NaN` value does reach a query, IEEE 754 applies: `NaN` is neither less than nor greater than any
395
+ value, and `NaN == NaN` is `false`.
396
+
397
+ ### Integer division truncates
398
+
399
+ ```cypher
400
+ RETURN 7 / 2; // 3
401
+ RETURN -7 / 2; // -3
402
+ RETURN 7 / 2.0 // 3.5
403
+ ```
404
+
405
+ Make one operand a float (`toFloat`) when you want the exact quotient.
406
+
407
+ ## Limitations
408
+
409
+ - Integer `+`, `-`, `*`, `%` and unary `-` fail the query on overflow
410
+ instead of wrapping. Coerce to `Float` with `toFloat` on potentially
411
+ huge inputs. `list.sum` over integers is not overflow-checked.
412
+ - `NaN` and `Infinity` follow IEEE 754 — `NaN == NaN` evaluates to
413
+ `false`, and `NaN` is neither less nor greater than any other value.
414
+ - `math.random()` / `random()` is not cryptographically secure.
415
+
416
+ ## See also
417
+
418
+ - [**Scalars → Integer / Float**](../data-types/scalars.md#integer) — numeric types.
419
+ - [**WHERE**](../queries/where.md#arithmetic-in-where) — arithmetic in filters.
420
+ - [**Spatial Functions**](./spatial.md) — `geo.distance` as the geodesic alternative.
421
+ - [**Aggregation Functions**](./aggregation.md) — `sum`, `avg`, percentiles.