@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.
- 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 +349 -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 +538 -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
|
@@ -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.
|