@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.
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 +355 -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 +546 -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,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.2"
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.2"
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.