@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,384 @@
1
+ ---
2
+ title: "Spatial Functions (Points, Distance)"
3
+ description: "Spatial functions in LoraDB — cast-based POINT construction, 2D/3D Cartesian and WGS-84 distance, bounding boxes, property round-tripping, and parameter binding."
4
+ online: "https://loradb.com/docs/functions/spatial"
5
+ package: "@loradb/lora-node@0.36.2"
6
+ ---
7
+
8
+ # Spatial Functions (Points, Distance)
9
+
10
+ LoraDB has a `Point` [type](../data-types/spatial.md) with 2D and 3D
11
+ variants in both Cartesian and WGS-84 (geographic) coordinate reference
12
+ systems. Points round-trip through [property](../concepts/properties.md)
13
+ storage, [parameters](../queries/parameters.md), and results.
14
+
15
+ ## Overview
16
+
17
+ | Goal | Function |
18
+ |---|---|
19
+ | Construct a point | [`{…}::POINT`](#construction) |
20
+ | Distance between two points | [`geo.distance(a, b)`](#geodistance) |
21
+ | Bounding-box test | [`geo.within_bbox(p, ll, ur)`](#geowithin_bbox) |
22
+ | Access components | `p.x`, `p.y`, `p.z`, `p.latitude`, `p.longitude`, `p.height` |
23
+ | SRID / CRS metadata | `p.srid`, `p.crs` |
24
+ | Filter by radius | [`geo.distance(p, centre) < r`](#storing-points) |
25
+
26
+ ## SRIDs
27
+
28
+ | SRID | System | Components |
29
+ |---|---|---|
30
+ | `7203` | Cartesian 2D | `x`, `y` |
31
+ | `9157` | Cartesian 3D | `x`, `y`, `z` |
32
+ | `4326` | WGS-84 geographic 2D | `longitude`, `latitude` |
33
+ | `4979` | WGS-84 geographic 3D | `longitude`, `latitude`, `height` |
34
+
35
+ CRS names accepted on the `crs` key (case-insensitive): `cartesian`,
36
+ `cartesian-3D`, `WGS-84-2D`, `WGS-84-3D`. `WGS-84` is an alias for
37
+ `WGS-84-2D`. `z` is accepted as an alias for `height` in geographic
38
+ points.
39
+
40
+ ## Construction
41
+
42
+ Construct points by casting a map to `POINT`. `value::POINT` is compact
43
+ for handwritten Cypher, and `CAST(value AS POINT)` is also part of the
44
+ Cypher grammar.
45
+
46
+ ### Cartesian
47
+
48
+ ```cypher
49
+ RETURN {x: 1, y: 2}::POINT; // SRID 7203
50
+ RETURN {x: 1, y: 2, z: 3}::POINT; // SRID 9157
51
+ RETURN {x: 1, y: 2, srid: 7203}::POINT; // explicit SRID
52
+ RETURN {x: 1, y: 2, z: 3, crs: 'cartesian-3D'}::POINT;
53
+ RETURN CAST({x: 1, y: 2} AS POINT) // CAST form
54
+ ```
55
+
56
+ ### Geographic (WGS-84)
57
+
58
+ ```cypher
59
+ RETURN {latitude: 52.37, longitude: 4.89}::POINT; // SRID 4326
60
+ RETURN {longitude: 4.89, latitude: 52.37, height: 20}::POINT; // SRID 4979
61
+ RETURN {longitude: 4.89, latitude: 52.37, z: 20}::POINT; // also 4979 (z = height)
62
+ RETURN {x: 4.89, y: 52.37, crs: 'WGS-84-2D'}::POINT // CRS promotes x/y to lon/lat
63
+ ```
64
+
65
+ ### Rules
66
+
67
+ - `x`/`y` may not be mixed with `longitude`/`latitude` in the same map.
68
+ - `z` and `height` may not both be present — they're aliases.
69
+ - If both `crs` and `srid` are given, they must agree.
70
+ - Any `null` coordinate → `{…}::POINT` returns `null`.
71
+ - Unknown keys (`lon`, `elevation`, …) are rejected — no silent typos.
72
+
73
+ ## geo.distance
74
+
75
+ `geo.distance(a, b)`.
76
+
77
+ | Same-SRID pair | Formula |
78
+ |---|---|
79
+ | Cartesian 2D | `math.sqrt(dx² + dy²)` |
80
+ | Cartesian 3D | `math.sqrt(dx² + dy² + dz²)` |
81
+ | WGS-84 2D | Haversine great-circle, Earth radius 6 371 km |
82
+ | WGS-84 3D | **Haversine surface only — height is ignored** |
83
+
84
+ ```cypher
85
+ // Cartesian 2D
86
+ RETURN geo.distance({x: 0, y: 0}::POINT, {x: 3, y: 4}::POINT)
87
+ // 5.0
88
+
89
+ ;// Cartesian 3D
90
+ RETURN geo.distance({x: 0, y: 0, z: 0}::POINT, {x: 2, y: 3, z: 6}::POINT)
91
+ // 7.0
92
+
93
+ ;// WGS-84 2D (metres)
94
+ RETURN geo.distance(
95
+ {latitude: 52.37, longitude: 4.89}::POINT, // Amsterdam
96
+ {latitude: 51.00, longitude: 4.40}::POINT // Antwerp
97
+ )
98
+ // ≈ 155_000.0
99
+ ```
100
+
101
+ `geo.distance` on points with different SRIDs fails the query with
102
+ `Cannot compute distance between points with different SRIDs`. That
103
+ covers Cartesian-vs-geographic and 2D-vs-3D mismatches. A `null`
104
+ argument returns `null`.
105
+
106
+ ## geo.within_bbox
107
+
108
+ `geo.within_bbox(p, lowerLeft, upperRight)` returns `true` when `p`
109
+ falls inside the closed bounding box formed by the two corner points.
110
+ All three points must share an SRID — a mismatch, including mixed 2D
111
+ and 3D inputs, fails the query.
112
+
113
+ ```cypher
114
+ MATCH (v:Venue)
115
+ WHERE geo.within_bbox(
116
+ v.location,
117
+ {longitude: 4.7, latitude: 52.2}::POINT,
118
+ {longitude: 5.1, latitude: 52.5}::POINT
119
+ )
120
+ RETURN v
121
+ ```
122
+
123
+ ### Boxes across the antimeridian
124
+
125
+ On WGS-84 points, a `lowerLeft.longitude` greater than
126
+ `upperRight.longitude` means the box crosses the antimeridian (the
127
+ 180° meridian). The box then covers longitudes
128
+ `[lowerLeft.longitude, 180]` and `[-180, upperRight.longitude]`, the
129
+ same rule as Neo4j's `point.withinBBox`. Latitude is still an ordinary
130
+ `[lowerLeft.latitude, upperRight.latitude]` range.
131
+
132
+ ```cypher
133
+ // Fiji (178°E) and Samoa (172°W) are inside; Paris is not
134
+ WITH {longitude: 170, latitude: -60}::POINT AS ll,
135
+ {longitude: -170, latitude: 60}::POINT AS ur
136
+ RETURN geo.within_bbox({longitude: 178.0, latitude: -18.0}::POINT, ll, ur) AS fiji,
137
+ geo.within_bbox({longitude: -172.0, latitude: -13.8}::POINT, ll, ur) AS samoa,
138
+ geo.within_bbox({longitude: 2.35, latitude: 48.85}::POINT, ll, ur) AS paris
139
+ ```
140
+
141
+ Cartesian boxes have no wrap-around: their corners are normalised to
142
+ min/max on each axis, so the two corners may be given in either order.
143
+
144
+ POINT indexes can accelerate bounding-box and radius predicates when
145
+ the query is scoped to a matching label or relationship type:
146
+
147
+ ```cypher
148
+ CREATE POINT INDEX venue_location FOR (v:Venue) ON (v.location);
149
+ MATCH (v:Venue)
150
+ WHERE geo.within_bbox(v.location, $southwest, $northeast)
151
+ RETURN v
152
+ ```
153
+
154
+ A box across the antimeridian still uses the index: it runs as two
155
+ seeks, one on each side of the 180° meridian, for node and relationship
156
+ POINT indexes.
157
+
158
+ ## Component access
159
+
160
+ | Accessor | 2D Cart | 3D Cart | WGS-84 2D | WGS-84 3D |
161
+ |---|---|---|---|---|
162
+ | `p.x` / `p.y` | ✓ | ✓ | ✓ (= lon/lat) | ✓ |
163
+ | `p.z` | `null` | ✓ | `null` | ✓ (= height) |
164
+ | `p.longitude` / `p.latitude` | `null` | `null` | ✓ | ✓ |
165
+ | `p.height` | `null` | `null` | `null` | ✓ |
166
+ | `p.srid` | ✓ | ✓ | ✓ | ✓ |
167
+ | `p.crs` | ✓ | ✓ | ✓ | ✓ |
168
+
169
+ Geographic accessors return `null` on Cartesian points by design —
170
+ they have no meaningful projection onto latitude / longitude.
171
+
172
+ ```cypher
173
+ WITH {latitude: 52.37, longitude: 4.89, height: 12}::POINT AS p
174
+ RETURN p.latitude, // 52.37
175
+ p.longitude, // 4.89
176
+ p.height, // 12
177
+ p.srid, // 4979
178
+ p.crs // 'WGS-84-3D'
179
+ ```
180
+
181
+ ## Storing points
182
+
183
+ ```cypher
184
+ CREATE (c:City {
185
+ name: 'Amsterdam',
186
+ location: {latitude: 52.37, longitude: 4.89}::POINT
187
+ })
188
+ ```
189
+
190
+ ### Nearest N cities
191
+
192
+ ```cypher
193
+ MATCH (c:City {name: 'Amsterdam'})
194
+ MATCH (other:City)
195
+ WHERE other.name <> 'Amsterdam'
196
+ RETURN other.name,
197
+ geo.distance(c.location, other.location) AS metres
198
+ ORDER BY metres ASC
199
+ LIMIT 5
200
+ ```
201
+
202
+ ### Radius filter
203
+
204
+ ```cypher
205
+ MATCH (v:Venue)
206
+ WHERE geo.distance(v.location, $centre) < 1000
207
+ RETURN v
208
+ ```
209
+
210
+ ### Bounding-box filter
211
+
212
+ ```cypher
213
+ MATCH (c:City)
214
+ WHERE geo.within_bbox(
215
+ c.location,
216
+ {longitude: 3, latitude: 50}::POINT,
217
+ {longitude: 7, latitude: 55}::POINT
218
+ )
219
+ RETURN c
220
+ ```
221
+
222
+ ## Parameters
223
+
224
+ Pass a literal `{…}::POINT` cast, or bind the tagged point value from your
225
+ host language (see [Node → typed helpers](../getting-started/node.md#typed-helpers),
226
+ [Python → parameters](https://loradb.com/docs/getting-started/python#parameterised-query)).
227
+
228
+ ```cypher
229
+ MATCH (c:City)
230
+ WHERE geo.distance(c.location, $here) < 10000
231
+ RETURN c
232
+ ```
233
+
234
+ From Node/WASM:
235
+
236
+ ```ts
237
+ import { wgs84 } from '@loradb/lora-node';
238
+ await db.execute(query, { here: wgs84(4.89, 52.37) });
239
+ ```
240
+
241
+ ## Common patterns
242
+
243
+ ### Closest-first list
244
+
245
+ ```cypher
246
+ MATCH (shop:Shop)
247
+ RETURN shop,
248
+ geo.distance(shop.location, $me) AS metres
249
+ ORDER BY metres
250
+ LIMIT 20
251
+ ```
252
+
253
+ ### Group by distance bucket
254
+
255
+ ```cypher
256
+ MATCH (s:Station)
257
+ WITH s, toInteger(geo.distance(s.location, $me) / 1000) AS km
258
+ RETURN km AS distance_km, count(*) AS stations
259
+ ORDER BY distance_km
260
+ ```
261
+
262
+ ### Count things within radius
263
+
264
+ ```cypher
265
+ MATCH (b:Business)
266
+ WHERE geo.distance(b.location, $origin) < $radius
267
+ RETURN b.category, count(*) AS n
268
+ ORDER BY n DESC
269
+ ```
270
+
271
+ ### Is any member of a set within range
272
+
273
+ ```cypher
274
+ MATCH (u:User {id: $id})
275
+ RETURN EXISTS { (u)-[:OWNS]->(:Car) } AS owns_car
276
+ ```
277
+
278
+ For pattern-based `any`, prefer
279
+ [`EXISTS { … }`](../queries/where.md#pattern-existence).
280
+
281
+ ### Nearest-per-category
282
+
283
+ ```cypher
284
+ MATCH (v:Venue)
285
+ WITH v.category AS category, v, geo.distance(v.location, $me) AS metres
286
+ ORDER BY metres ASC
287
+ WITH category, collect({v: v, metres: metres})[0] AS nearest
288
+ RETURN category, nearest.v.name AS name, nearest.metres AS metres
289
+ ORDER BY metres
290
+ ```
291
+
292
+ One nearest venue per category. The `collect(…)[0]` after `ORDER BY`
293
+ picks the first (smallest distance) within each group.
294
+
295
+ ### Haversine sanity check
296
+
297
+ LoraDB's `geo.distance` on WGS-84 uses Haversine with Earth radius 6 371
298
+ km. For two closely spaced points, Cartesian distance on
299
+ latitude/longitude is a useful local approximation:
300
+
301
+ ```cypher
302
+ WITH {latitude: 52.37, longitude: 4.89}::POINT AS a,
303
+ {latitude: 52.40, longitude: 4.92}::POINT AS b
304
+ RETURN geo.distance(a, b) AS haversine_metres,
305
+ math.sqrt(math.pow((b.latitude - a.latitude) * 111000, 2) +
306
+ math.pow((b.longitude - a.longitude) * 111000 *
307
+ math.cos(math.radians(a.latitude)), 2)) AS approx_metres
308
+ ```
309
+
310
+ Expect tiny differences within a city. The Cartesian approximation
311
+ diverges quickly over continental scales — stick with `geo.distance` for
312
+ real geodetic work.
313
+
314
+ ### Project onto Cartesian for game coordinates
315
+
316
+ Cartesian 2D is perfect for canvas/game logic. Points can share an
317
+ entity with other properties:
318
+
319
+ ```cypher
320
+ UNWIND list.range(1, 100) AS i
321
+ CREATE (:Spawn {
322
+ id: i,
323
+ position: {x: math.random() * 1000, y: math.random() * 1000}::POINT
324
+ });
325
+
326
+ MATCH (a:Spawn {id: 1}), (b:Spawn)
327
+ WHERE b.id <> 1
328
+ RETURN b.id, geo.distance(a.position, b.position) AS dist
329
+ ORDER BY dist ASC
330
+ LIMIT 5
331
+ ```
332
+
333
+ ## Edge cases
334
+
335
+ ### Cross-SRID distance
336
+
337
+ Fails the query with a `LORA_VALIDATION` error:
338
+
339
+ ```cypher
340
+ RETURN geo.distance({x: 0, y: 0}::POINT, {latitude: 0, longitude: 0}::POINT)
341
+ // error: Cannot compute distance between points with different SRIDs
342
+ ```
343
+
344
+ Filter to matching SRIDs first:
345
+
346
+ ```cypher
347
+ MATCH (a:Spot), (b:Spot)
348
+ WHERE a.location.srid = b.location.srid
349
+ RETURN a, b, geo.distance(a.location, b.location)
350
+ ```
351
+
352
+ ### Null coordinate
353
+
354
+ `{latitude: null, longitude: 4.89}::POINT` returns `null`, not a point
355
+ — any downstream use propagates null.
356
+
357
+ ### 3D geographic height
358
+
359
+ `geo.distance` on WGS-84 3D points is still surface-only. For true
360
+ ellipsoidal/altitude distance, compute host-side.
361
+
362
+ ### Integer vs float coordinates
363
+
364
+ Both are accepted. Integer coordinates are promoted to `Float` when
365
+ used with `geo.distance`.
366
+
367
+ ## Limitations
368
+
369
+ - **WGS-84 3D `geo.distance` ignores `height`** — it computes surface
370
+ great-circle distance only. A true 3D geodesic (ellipsoid + altitude)
371
+ distance is not implemented.
372
+ - **Cross-SRID distance** fails the query. There is no built-in CRS
373
+ transformation.
374
+ - **No WKT I/O or CRS transforms.** Convert WKT host-side and keep all
375
+ compared points in the same SRID.
376
+ - **`point.fromWKT()` / WKT output** is not implemented.
377
+ - No custom SRIDs — only the four listed above.
378
+
379
+ ## See also
380
+
381
+ - [**Spatial Data Types**](../data-types/spatial.md) — type reference.
382
+ - [**Math**](./math.md) — underlying arithmetic for Cartesian distance.
383
+ - [**WHERE**](../queries/where.md) — radius filters.
384
+ - [**Ordering**](../queries/ordering.md) — nearest-first via `ORDER BY geo.distance(…)`.