@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,376 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Scalar Types — Null, Boolean, Integer, Float, String"
|
|
3
|
+
description: "The five scalar types in LoraDB — Null, Boolean, Integer, Float, String — their literals, comparison rules, three-valued logic, and how each round-trips to host languages."
|
|
4
|
+
online: "https://loradb.com/docs/data-types/scalars"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Scalar Types
|
|
9
|
+
|
|
10
|
+
The five scalar types — `Null`, `Boolean`, `Integer`, `Float`,
|
|
11
|
+
`String` — are the atoms of every value in LoraDB. Lists, maps,
|
|
12
|
+
temporal values, spatial points, and graph types are compositions
|
|
13
|
+
over these.
|
|
14
|
+
|
|
15
|
+
## Null
|
|
16
|
+
|
|
17
|
+
Represents the absence of a value. LoraDB uses **three-valued logic**
|
|
18
|
+
for comparisons involving `null`.
|
|
19
|
+
|
|
20
|
+
```cypher
|
|
21
|
+
RETURN null, null = null, null <> null, 1 = null
|
|
22
|
+
// null, null, null, null
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Boolean operators propagate `null` carefully:
|
|
26
|
+
|
|
27
|
+
| Expression | Result |
|
|
28
|
+
|---|---|
|
|
29
|
+
| `null AND true` | `null` |
|
|
30
|
+
| `null AND false` | `false` |
|
|
31
|
+
| `null OR true` | `true` |
|
|
32
|
+
| `null OR false` | `null` |
|
|
33
|
+
| `NOT null` | `null` |
|
|
34
|
+
|
|
35
|
+
### Null tests
|
|
36
|
+
|
|
37
|
+
Use [`IS NULL` / `IS NOT NULL`](../queries/where.md#null-checks) — **not**
|
|
38
|
+
`= null`:
|
|
39
|
+
|
|
40
|
+
```cypher
|
|
41
|
+
MATCH (n) WHERE n.optional IS NULL RETURN n;
|
|
42
|
+
MATCH (n) WHERE n.optional IS NOT NULL RETURN n
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Null in aggregates
|
|
46
|
+
|
|
47
|
+
| Aggregate | Behaviour |
|
|
48
|
+
|---|---|
|
|
49
|
+
| `count(*)` | Counts rows; `null` bindings still count |
|
|
50
|
+
| `count(expr)` | Skips `null` |
|
|
51
|
+
| `sum`, `avg`, `min`, `max` | Skip `null` |
|
|
52
|
+
| `collect(expr)` | Keeps `null` |
|
|
53
|
+
|
|
54
|
+
See [Aggregation Functions](../functions/aggregation.md) for the full
|
|
55
|
+
table.
|
|
56
|
+
|
|
57
|
+
### Null in ordering
|
|
58
|
+
|
|
59
|
+
`null` sorts **last** in ascending order and **first** in descending
|
|
60
|
+
order. Guard with [`coalesce`](../functions/overview.md#type-conversion-and-checking)
|
|
61
|
+
to change placement — see [Ordering](../queries/ordering.md#nulls-in-ordering).
|
|
62
|
+
|
|
63
|
+
## Boolean
|
|
64
|
+
|
|
65
|
+
`true` or `false`. Bools are **not** integers in LoraDB — `true = 1`
|
|
66
|
+
evaluates to `false`. Use `toInteger(b)` to convert.
|
|
67
|
+
|
|
68
|
+
```cypher
|
|
69
|
+
RETURN true AND false; // false
|
|
70
|
+
RETURN true OR false; // true
|
|
71
|
+
RETURN NOT true; // false
|
|
72
|
+
RETURN true XOR false; // true
|
|
73
|
+
RETURN toInteger(true), // 1
|
|
74
|
+
toInteger(false) // 0
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Parameters
|
|
78
|
+
|
|
79
|
+
Bools bind transparently:
|
|
80
|
+
|
|
81
|
+
```cypher
|
|
82
|
+
MATCH (u:User) WHERE u.active = $active RETURN u
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Use as a flag property
|
|
86
|
+
|
|
87
|
+
```cypher
|
|
88
|
+
MATCH (p:Product) WHERE p.in_stock RETURN p;
|
|
89
|
+
MATCH (p:Product) WHERE NOT p.in_stock RETURN p
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Note the short form: `WHERE p.in_stock` is equivalent to
|
|
93
|
+
`WHERE p.in_stock = true`, but will also match only `true` — it drops
|
|
94
|
+
rows where `p.in_stock` is `false` or `null`.
|
|
95
|
+
|
|
96
|
+
## Integer
|
|
97
|
+
|
|
98
|
+
64-bit signed (`i64`). Literals can be decimal, hex, or octal.
|
|
99
|
+
|
|
100
|
+
```cypher
|
|
101
|
+
RETURN 42, -1, 0, 0xFF, 0o17
|
|
102
|
+
// 42, -1, 0, 255, 15
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### Arithmetic
|
|
106
|
+
|
|
107
|
+
| Op | Example | Notes |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| `+`, `-`, `*` | `1 + 2` | Integer if both operands are integers |
|
|
110
|
+
| `/` | `10 / 3` → `3` | Integer division (truncates toward zero) when both operands are integers; `Float` if either is |
|
|
111
|
+
| `%` | `10 % 3` → `1` | Remainder, signed like the dividend; `Float` if either operand is |
|
|
112
|
+
| `^` | `2 ^ 10` → `1024` | Exponent |
|
|
113
|
+
| unary `-`, `+` | `-x` | |
|
|
114
|
+
|
|
115
|
+
Integer divide or modulo by zero fails the query; with a `Float`
|
|
116
|
+
operand it returns `null`.
|
|
117
|
+
|
|
118
|
+
```cypher
|
|
119
|
+
RETURN 1 / 0; // error: integer division by zero
|
|
120
|
+
RETURN 1.0 / 0 // null
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
See [Math Functions → Arithmetic operators](../functions/math.md#arithmetic-operators)
|
|
124
|
+
for the full details, including mixed-type arithmetic.
|
|
125
|
+
|
|
126
|
+
### Conversion
|
|
127
|
+
|
|
128
|
+
```cypher
|
|
129
|
+
RETURN toInteger('42'), // 42
|
|
130
|
+
toInteger(3.9), // 3 (truncates)
|
|
131
|
+
toInteger('abc'), // null
|
|
132
|
+
toFloat(42) // 42.0
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Use as an id
|
|
136
|
+
|
|
137
|
+
Integers are the most common id type:
|
|
138
|
+
|
|
139
|
+
```cypher
|
|
140
|
+
MATCH (u:User {id: $id}) RETURN u
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
For very large ids, note [integer precision in JS](../getting-started/node.md#performance--best-practices)
|
|
144
|
+
— values above `2^53` lose precision when crossing the JS boundary.
|
|
145
|
+
|
|
146
|
+
### Limitations
|
|
147
|
+
|
|
148
|
+
Integer `+`, `-`, `*`, `/`, `%` and unary `-` are overflow-checked: a result
|
|
149
|
+
outside the `i64` range fails the query with a `LORA_VALIDATION` error
|
|
150
|
+
(`integer addition overflowed`, …) instead of wrapping. For extreme
|
|
151
|
+
inputs, convert to `Float` first.
|
|
152
|
+
|
|
153
|
+
## Float
|
|
154
|
+
|
|
155
|
+
64-bit floating point (`f64`, IEEE 754).
|
|
156
|
+
|
|
157
|
+
```cypher
|
|
158
|
+
RETURN 3.14, 1.0e10, -0.5
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Mixed-type arithmetic promotes to `Float`:
|
|
162
|
+
|
|
163
|
+
```cypher
|
|
164
|
+
RETURN 1 + 2.5; // 3.5 (Float)
|
|
165
|
+
RETURN 10 / 3.0 // 3.333…
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### IEEE 754 quirks
|
|
169
|
+
|
|
170
|
+
- `NaN == NaN` → `false`
|
|
171
|
+
- `NaN` comparisons → `false`
|
|
172
|
+
- Float division by zero returns `null` — `1.0 / 0.0` and
|
|
173
|
+
`0.0 / 0.0` never produce `Infinity` or `NaN`
|
|
174
|
+
|
|
175
|
+
```cypher
|
|
176
|
+
RETURN 1.0 / 0.0; // null
|
|
177
|
+
RETURN 0.0 / 0.0 // null
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Rounding
|
|
181
|
+
|
|
182
|
+
See [Math → Rounding](../functions/math.md#rounding-and-absolute-value):
|
|
183
|
+
|
|
184
|
+
```cypher
|
|
185
|
+
RETURN math.round(3.5); // 4
|
|
186
|
+
RETURN math.round(2.5); // 3 (default half-up rounding)
|
|
187
|
+
RETURN math.ceil(0.1); // 1
|
|
188
|
+
RETURN math.floor(-0.1) // -1
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Use as a ratio / rate
|
|
192
|
+
|
|
193
|
+
```cypher
|
|
194
|
+
MATCH (r:Review)
|
|
195
|
+
RETURN r.stars / 5.0 AS normalised // 0.0 .. 1.0
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## String
|
|
199
|
+
|
|
200
|
+
UTF-8 text. Either quote style works.
|
|
201
|
+
|
|
202
|
+
```cypher
|
|
203
|
+
RETURN 'hello', "world"
|
|
204
|
+
RETURN 'it''s fine' // 'it's fine' (double the quote to escape)
|
|
205
|
+
RETURN "with \n newline" // string with a literal newline
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Concatenation
|
|
209
|
+
|
|
210
|
+
```cypher
|
|
211
|
+
RETURN 'Hello, ' + 'Ada'; // 'Hello, Ada'
|
|
212
|
+
RETURN 'id=' + 42; // 'id=42'
|
|
213
|
+
RETURN 'id=' + toString(42) // 'id=42'
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
A string and a number concatenate, in either order, with the number
|
|
217
|
+
printed as [`toString`](../functions/string.md#type-conversion) prints it.
|
|
218
|
+
Other types (booleans, maps, temporals) must be converted first: `+`
|
|
219
|
+
between a string and one of them is an error, not a silent `null`. A
|
|
220
|
+
`null` operand still gives `null`.
|
|
221
|
+
|
|
222
|
+
### Useful functions
|
|
223
|
+
|
|
224
|
+
See [String Functions](../functions/string.md) for the full reference.
|
|
225
|
+
Highlights:
|
|
226
|
+
|
|
227
|
+
```cypher
|
|
228
|
+
RETURN string.lower('LoraDB'), // 'loradb'
|
|
229
|
+
string.split('a,b,c', ','), // ['a', 'b', 'c']
|
|
230
|
+
string.slice('LoraDB', 0, 4), // 'Lora'
|
|
231
|
+
string.replace('aba', 'a', 'x') // 'xbx'
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
### Comparison
|
|
235
|
+
|
|
236
|
+
Strings sort byte-lexicographically. Case-sensitive comparisons are
|
|
237
|
+
the default; normalise with `string.lower` / `string.upper` for case-insensitive
|
|
238
|
+
matching — see [WHERE → string matching](../queries/where.md#string-matching).
|
|
239
|
+
|
|
240
|
+
```cypher
|
|
241
|
+
MATCH (u:User)
|
|
242
|
+
WHERE string.lower(u.name) = string.lower($search)
|
|
243
|
+
RETURN u
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### Lengths: bytes vs code points
|
|
247
|
+
|
|
248
|
+
```cypher
|
|
249
|
+
RETURN value.size('café'), // string size
|
|
250
|
+
string.length('café') // 4 (code points)
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
For display-length, prefer `string.length`. For general polymorphic
|
|
254
|
+
size checks, use `value.size`.
|
|
255
|
+
|
|
256
|
+
## Parameters
|
|
257
|
+
|
|
258
|
+
Scalar [parameters](../queries/parameters.md) bind transparently from
|
|
259
|
+
host-language values — Rust primitives, JS numbers / strings /
|
|
260
|
+
booleans, Python `int` / `float` / `str` / `None`. See the per-platform
|
|
261
|
+
[Getting Started](../getting-started/installation.md) guide for your
|
|
262
|
+
language.
|
|
263
|
+
|
|
264
|
+
```cypher
|
|
265
|
+
MATCH (u:User)
|
|
266
|
+
WHERE u.id = $id AND u.active = $active
|
|
267
|
+
RETURN u
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
## Comparison matrix
|
|
271
|
+
|
|
272
|
+
| | Scalar equality | Ordering |
|
|
273
|
+
|---|---|---|
|
|
274
|
+
| `Boolean` | `true = true` → `true` | `false < true` |
|
|
275
|
+
| `Integer` | numeric | numeric |
|
|
276
|
+
| `Float` | numeric (IEEE 754) | numeric; `NaN` incomparable |
|
|
277
|
+
| `String` | case-sensitive | byte-lex |
|
|
278
|
+
| `Null` | null-propagating | null-propagating (last asc, first desc) |
|
|
279
|
+
|
|
280
|
+
Cross-type comparisons return `null` (type mismatch detection is not
|
|
281
|
+
yet implemented — see [Limitations](../limitations.md)).
|
|
282
|
+
|
|
283
|
+
## Common patterns
|
|
284
|
+
|
|
285
|
+
### Default a missing scalar
|
|
286
|
+
|
|
287
|
+
```cypher
|
|
288
|
+
MATCH (p:Person)
|
|
289
|
+
RETURN p.name, coalesce(p.nickname, p.name) AS display
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
### Safe equality
|
|
293
|
+
|
|
294
|
+
```cypher
|
|
295
|
+
MATCH (a), (b)
|
|
296
|
+
WHERE coalesce(a.key, '') = coalesce(b.key, '')
|
|
297
|
+
RETURN a, b
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
### Case-insensitive search
|
|
301
|
+
|
|
302
|
+
```cypher
|
|
303
|
+
MATCH (u:User)
|
|
304
|
+
WHERE string.lower(u.email) CONTAINS string.lower($q)
|
|
305
|
+
RETURN u
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### Boolean flag pattern
|
|
309
|
+
|
|
310
|
+
```cypher
|
|
311
|
+
MATCH (p:Product) WHERE p.in_stock RETURN p
|
|
312
|
+
|
|
313
|
+
;// Equivalent, explicit:
|
|
314
|
+
MATCH (p:Product) WHERE p.in_stock = true RETURN p
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
The bare form *drops* rows where `p.in_stock` is `null` — common
|
|
318
|
+
source of surprise when a property is missing rather than `false`.
|
|
319
|
+
Guard with `coalesce`:
|
|
320
|
+
|
|
321
|
+
```cypher
|
|
322
|
+
MATCH (p:Product)
|
|
323
|
+
WHERE coalesce(p.in_stock, false)
|
|
324
|
+
RETURN p
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
### Branch on a scalar with CASE
|
|
328
|
+
|
|
329
|
+
```cypher
|
|
330
|
+
MATCH (u:User)
|
|
331
|
+
RETURN u.handle,
|
|
332
|
+
CASE u.tier
|
|
333
|
+
WHEN 'pro' THEN 'paying'
|
|
334
|
+
WHEN 'free' THEN 'trial'
|
|
335
|
+
ELSE 'unknown'
|
|
336
|
+
END AS segment
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
See [`CASE`](../queries/return-with.md#case-expressions) — LoraDB's
|
|
340
|
+
conditional expression, supporting both "match a value" and "generic
|
|
341
|
+
boolean per branch" forms.
|
|
342
|
+
|
|
343
|
+
## Edge cases
|
|
344
|
+
|
|
345
|
+
### Nulls in arithmetic
|
|
346
|
+
|
|
347
|
+
`1 + null` is `null`. Any arithmetic involving `null` propagates.
|
|
348
|
+
|
|
349
|
+
```cypher
|
|
350
|
+
MATCH (p:Person)
|
|
351
|
+
RETURN p.name, p.age + 1 AS next_age
|
|
352
|
+
// \`null\` if p.age is null
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
### Booleans and truthiness
|
|
356
|
+
|
|
357
|
+
`WHERE x` drops a row only when `x` is `false` or `null`. Any other
|
|
358
|
+
value keeps it — including `0`, `''`, and `[]`, so `WHERE 0` filters
|
|
359
|
+
nothing. Write the comparison you mean (`WHERE x <> 0`,
|
|
360
|
+
`WHERE x IS NOT NULL`) rather than relying on a bare value.
|
|
361
|
+
|
|
362
|
+
### Very small numbers
|
|
363
|
+
|
|
364
|
+
Sub-nanosecond precision is lost on `Float`. For exact arithmetic on
|
|
365
|
+
small quantities (money, percentages), use scaled integers (cents,
|
|
366
|
+
basis points).
|
|
367
|
+
|
|
368
|
+
## See also
|
|
369
|
+
|
|
370
|
+
- [**Lists & Maps**](./lists-and-maps.md) — collections.
|
|
371
|
+
- [**Temporal**](./temporal.md) / [**Spatial**](./spatial.md) — typed domains.
|
|
372
|
+
- [**Math Functions**](../functions/math.md),
|
|
373
|
+
[**String Functions**](../functions/string.md) — operators and helpers.
|
|
374
|
+
- [**WHERE**](../queries/where.md) — null-safe filtering and comparison.
|
|
375
|
+
- [**Ordering → nulls**](../queries/ordering.md#nulls-in-ordering).
|
|
376
|
+
- [**Limitations**](../limitations.md) — overflow, type-mismatch behavior.
|
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Spatial Data Types (Points)"
|
|
3
|
+
description: "The Point type in LoraDB — 2D and 3D, Cartesian and WGS-84 — its SRIDs, equality rules, property storage behaviour, and links to the spatial function library."
|
|
4
|
+
online: "https://loradb.com/docs/data-types/spatial"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Spatial Data Types
|
|
9
|
+
|
|
10
|
+
LoraDB has a `Point` type in four shapes: 2D and 3D, Cartesian and
|
|
11
|
+
WGS-84 (geographic). For
|
|
12
|
+
[cast-based construction](../functions/spatial.md#construction) and the
|
|
13
|
+
[`geo.distance`](../functions/spatial.md#geodistance) function, see
|
|
14
|
+
[Spatial Functions](../functions/spatial.md). This page covers the type
|
|
15
|
+
itself.
|
|
16
|
+
|
|
17
|
+
## SRIDs
|
|
18
|
+
|
|
19
|
+
| SRID | Name | Components |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| `7203` | Cartesian 2D | `x`, `y` |
|
|
22
|
+
| `9157` | Cartesian 3D | `x`, `y`, `z` |
|
|
23
|
+
| `4326` | WGS-84 geographic 2D | `longitude`, `latitude` |
|
|
24
|
+
| `4979` | WGS-84 geographic 3D | `longitude`, `latitude`, `height` |
|
|
25
|
+
|
|
26
|
+
## Which one do I use?
|
|
27
|
+
|
|
28
|
+
| Domain | Type |
|
|
29
|
+
|---|---|
|
|
30
|
+
| Latitude/longitude (places on Earth) | WGS-84 2D (`4326`) |
|
|
31
|
+
| + elevation (flights, altitudes) | WGS-84 3D (`4979`) |
|
|
32
|
+
| Abstract 2D plane (games, canvas) | Cartesian 2D (`7203`) |
|
|
33
|
+
| 3D position (physics, CAD) | Cartesian 3D (`9157`) |
|
|
34
|
+
|
|
35
|
+
## Writing points
|
|
36
|
+
|
|
37
|
+
```cypher
|
|
38
|
+
CREATE (c:City {
|
|
39
|
+
name: 'Amsterdam',
|
|
40
|
+
location: {latitude: 52.37, longitude: 4.89}::POINT
|
|
41
|
+
})
|
|
42
|
+
|
|
43
|
+
CREATE (w:Waypoint {
|
|
44
|
+
mark: {x: 1.0, y: 2.0, z: 3.0}::POINT
|
|
45
|
+
})
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Reading points
|
|
49
|
+
|
|
50
|
+
Component access is well-defined across all four SRIDs — see the table
|
|
51
|
+
in [Spatial Functions](../functions/spatial.md#component-access). In brief:
|
|
52
|
+
|
|
53
|
+
```cypher
|
|
54
|
+
WITH {latitude: 52.37, longitude: 4.89}::POINT AS p
|
|
55
|
+
RETURN p.x, // 4.89 (same as longitude on geographic)
|
|
56
|
+
p.y, // 52.37 (same as latitude on geographic)
|
|
57
|
+
p.latitude, // 52.37
|
|
58
|
+
p.longitude, // 4.89
|
|
59
|
+
p.srid, // 4326
|
|
60
|
+
p.crs // 'WGS-84-2D'
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Geographic accessors return `null` on Cartesian points and vice-versa —
|
|
64
|
+
they have no meaningful projection.
|
|
65
|
+
|
|
66
|
+
## Comparison
|
|
67
|
+
|
|
68
|
+
Points are **not ordered** — they have no total order. They compare for
|
|
69
|
+
equality only, by all components including SRID.
|
|
70
|
+
|
|
71
|
+
```cypher
|
|
72
|
+
RETURN {x: 1, y: 2}::POINT = {x: 1, y: 2}::POINT; // true
|
|
73
|
+
RETURN {x: 1, y: 2}::POINT = {x: 1, y: 2, z: 0}::POINT; // false (different SRID)
|
|
74
|
+
RETURN {latitude: 0, longitude: 0}::POINT = {x: 0, y: 0}::POINT
|
|
75
|
+
// false (different CRS)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
For "within distance" filtering, use `geo.distance`:
|
|
79
|
+
|
|
80
|
+
```cypher
|
|
81
|
+
MATCH (c:City)
|
|
82
|
+
WHERE geo.distance(c.location, $here) < 10000
|
|
83
|
+
RETURN c
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Serialisation
|
|
87
|
+
|
|
88
|
+
Points serialise as tagged maps. In JS / TS / Python bindings, prefer
|
|
89
|
+
the built-in helpers (`cartesian`, `wgs84`, `cartesian3d`, `wgs84_3d`)
|
|
90
|
+
over writing the tagged shape by hand.
|
|
91
|
+
|
|
92
|
+
| Variant | Tagged shape |
|
|
93
|
+
|---|---|
|
|
94
|
+
| Cartesian 2D | `{kind: "point", srid: 7203, crs: "cartesian", x, y}` |
|
|
95
|
+
| Cartesian 3D | `{kind: "point", srid: 9157, crs: "cartesian-3D", x, y, z}` |
|
|
96
|
+
| WGS-84 2D | `{kind: "point", srid: 4326, crs: "WGS-84-2D", x, y, longitude, latitude}` |
|
|
97
|
+
| WGS-84 3D | `{kind: "point", srid: 4979, crs: "WGS-84-3D", x, y, z, longitude, latitude, height}` |
|
|
98
|
+
|
|
99
|
+
HTTP-server responses use a compact property-style form
|
|
100
|
+
(`{srid, x, y[, z]}`); the JS / Python bindings apply the tagged
|
|
101
|
+
`kind:"point"` wrapper on the way out.
|
|
102
|
+
|
|
103
|
+
## Examples
|
|
104
|
+
|
|
105
|
+
### Five nearest cities
|
|
106
|
+
|
|
107
|
+
```cypher
|
|
108
|
+
MATCH (c:City {name: 'Amsterdam'})
|
|
109
|
+
MATCH (other:City) WHERE other.name <> 'Amsterdam'
|
|
110
|
+
RETURN other.name,
|
|
111
|
+
geo.distance(c.location, other.location) AS metres
|
|
112
|
+
ORDER BY metres ASC
|
|
113
|
+
LIMIT 5
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### Filter by bounding box
|
|
117
|
+
|
|
118
|
+
```cypher
|
|
119
|
+
MATCH (c:City)
|
|
120
|
+
WHERE geo.within_bbox(
|
|
121
|
+
c.location,
|
|
122
|
+
{longitude: 3, latitude: 50}::POINT,
|
|
123
|
+
{longitude: 7, latitude: 55}::POINT
|
|
124
|
+
)
|
|
125
|
+
RETURN c
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
On WGS-84, a lower-left longitude greater than the upper-right
|
|
129
|
+
longitude describes a box that crosses the antimeridian, for example
|
|
130
|
+
from 170° to -170° around the Pacific:
|
|
131
|
+
|
|
132
|
+
```cypher
|
|
133
|
+
MATCH (c:City)
|
|
134
|
+
WHERE geo.within_bbox(
|
|
135
|
+
c.location,
|
|
136
|
+
{longitude: 170, latitude: -60}::POINT,
|
|
137
|
+
{longitude: -170, latitude: 60}::POINT
|
|
138
|
+
)
|
|
139
|
+
RETURN c
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Cartesian corners are normalised to min/max, so their order does not
|
|
143
|
+
matter. See [`geo.within_bbox`](../functions/spatial.md#geowithin_bbox).
|
|
144
|
+
|
|
145
|
+
### 3D Cartesian distance
|
|
146
|
+
|
|
147
|
+
```cypher
|
|
148
|
+
CREATE (p:Anchor {pos: {x: 0, y: 0, z: 0}::POINT})
|
|
149
|
+
CREATE (q:Anchor {pos: {x: 3, y: 4, z: 12}::POINT});
|
|
150
|
+
|
|
151
|
+
MATCH (a:Anchor), (b:Anchor) WHERE id(a) < id(b)
|
|
152
|
+
RETURN geo.distance(a.pos, b.pos)
|
|
153
|
+
// 13.0 (math.sqrt(9 + 16 + 144))
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Group venues by kilometre ring
|
|
157
|
+
|
|
158
|
+
```cypher
|
|
159
|
+
MATCH (v:Venue)
|
|
160
|
+
WITH v, toInteger(geo.distance(v.location, $centre) / 1000) AS km
|
|
161
|
+
RETURN km, count(*) AS venues
|
|
162
|
+
ORDER BY km
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Join on proximity
|
|
166
|
+
|
|
167
|
+
```cypher
|
|
168
|
+
MATCH (a:Spot), (b:Spot)
|
|
169
|
+
WHERE id(a) < id(b)
|
|
170
|
+
AND geo.distance(a.location, b.location) < 500
|
|
171
|
+
RETURN a.name, b.name
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Store a home location and match nearby
|
|
175
|
+
|
|
176
|
+
```cypher
|
|
177
|
+
// Home stored as WGS-84 2D
|
|
178
|
+
MATCH (me:User {id: $id})
|
|
179
|
+
MATCH (p:Place)
|
|
180
|
+
WHERE geo.distance(p.location, me.home) < 5000
|
|
181
|
+
RETURN p
|
|
182
|
+
ORDER BY geo.distance(p.location, me.home)
|
|
183
|
+
LIMIT 10
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Bounding-box over a set of points
|
|
187
|
+
|
|
188
|
+
No `envelope` helper — aggregate the components directly:
|
|
189
|
+
|
|
190
|
+
```cypher
|
|
191
|
+
MATCH (c:City)
|
|
192
|
+
RETURN min(c.location.longitude) AS w,
|
|
193
|
+
max(c.location.longitude) AS e,
|
|
194
|
+
min(c.location.latitude) AS s,
|
|
195
|
+
max(c.location.latitude) AS n
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### Cluster by rounded coordinates
|
|
199
|
+
|
|
200
|
+
A poor man's grid clustering, useful for quick heatmaps:
|
|
201
|
+
|
|
202
|
+
```cypher
|
|
203
|
+
MATCH (s:Sensor)
|
|
204
|
+
WITH math.round(s.location.latitude * 10) / 10 AS lat,
|
|
205
|
+
math.round(s.location.longitude * 10) / 10 AS lon,
|
|
206
|
+
count(*) AS n
|
|
207
|
+
WHERE n > 5
|
|
208
|
+
RETURN lat, lon, n
|
|
209
|
+
ORDER BY n DESC
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
0.1° grid ≈ 11 km at the equator. Adjust the multiplier for the grid
|
|
213
|
+
you want.
|
|
214
|
+
|
|
215
|
+
### Two-step filter — cheap first, distance second
|
|
216
|
+
|
|
217
|
+
Property filters with a label scope run fast (see
|
|
218
|
+
[Limitations](../limitations.md#storage)). Narrow with predicates first,
|
|
219
|
+
compute `geo.distance` after:
|
|
220
|
+
|
|
221
|
+
```cypher
|
|
222
|
+
MATCH (c:City)
|
|
223
|
+
WHERE c.country = $country // cheap label + prop filter
|
|
224
|
+
AND c.location.latitude >= $s AND c.location.latitude <= $n
|
|
225
|
+
AND c.location.longitude >= $w AND c.location.longitude <= $e
|
|
226
|
+
WITH c, geo.distance(c.location, $centre) AS metres
|
|
227
|
+
WHERE metres < $radius
|
|
228
|
+
RETURN c
|
|
229
|
+
ORDER BY metres
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
For hot spatial predicates, add a POINT index on the top-level point
|
|
233
|
+
property. See [Queries → Indexes](../queries/indexes.md).
|
|
234
|
+
|
|
235
|
+
## Edge cases
|
|
236
|
+
|
|
237
|
+
### Null coordinate
|
|
238
|
+
|
|
239
|
+
Any `null` coordinate makes the `POINT` cast return `null`:
|
|
240
|
+
|
|
241
|
+
```cypher
|
|
242
|
+
RETURN {latitude: null, longitude: 4.89}::POINT // null
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
### Cross-SRID operations
|
|
246
|
+
|
|
247
|
+
`geo.distance` with mismatched SRIDs fails the query with a
|
|
248
|
+
`LORA_VALIDATION` error:
|
|
249
|
+
|
|
250
|
+
```cypher
|
|
251
|
+
RETURN geo.distance({x: 0, y: 0}::POINT, {latitude: 0, longitude: 0}::POINT)
|
|
252
|
+
// error: Cannot compute distance between points with different SRIDs
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Guard at filter time when a scope may mix SRIDs:
|
|
256
|
+
|
|
257
|
+
```cypher
|
|
258
|
+
MATCH (a:Loc), (b:Loc)
|
|
259
|
+
WHERE a.loc.srid = b.loc.srid
|
|
260
|
+
RETURN geo.distance(a.loc, b.loc)
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### Component access on wrong SRID
|
|
264
|
+
|
|
265
|
+
Returns `null` — never raises.
|
|
266
|
+
|
|
267
|
+
```cypher
|
|
268
|
+
WITH {x: 1, y: 2}::POINT AS p
|
|
269
|
+
RETURN p.latitude // null (Cartesian has no latitude)
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
### Float precision
|
|
273
|
+
|
|
274
|
+
WGS-84 coordinates are `Float` (IEEE 754). Don't rely on exact equality
|
|
275
|
+
between computed points — use `geo.distance(a, b) < epsilon` instead.
|
|
276
|
+
|
|
277
|
+
## Limitations
|
|
278
|
+
|
|
279
|
+
- **WGS-84 3D `geo.distance` ignores `height`** — surface great-circle only.
|
|
280
|
+
- **Cross-SRID `geo.distance`** fails the query (no CRS transforms).
|
|
281
|
+
- **No WKT I/O** — parse WKT host-side. Use `geo.within_bbox` for
|
|
282
|
+
same-SRID bounding-box predicates.
|
|
283
|
+
- **No custom SRIDs** — only the four listed above.
|
|
284
|
+
- **`BETWEEN`** keyword is not supported — use `>=` / `<=`.
|
|
285
|
+
|
|
286
|
+
## See also
|
|
287
|
+
|
|
288
|
+
- [**Spatial Functions**](../functions/spatial.md) — point construction and `geo.distance`.
|
|
289
|
+
- [**Math**](../functions/math.md) — Cartesian trig/arithmetic building blocks.
|
|
290
|
+
- [**WHERE**](../queries/where.md) — radius / bbox filters.
|
|
291
|
+
- [**Ordering**](../queries/ordering.md) — nearest-first sort.
|