@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,355 @@
1
+ ---
2
+ title: "Temporal Data Types"
3
+ description: "LoraDB's six temporal types — Date, Time, LocalTime, DateTime, LocalDateTime, and Duration — with component access, arithmetic, truncation, and ordering semantics."
4
+ online: "https://loradb.com/docs/data-types/temporal"
5
+ package: "@loradb/lora-node@0.36.2"
6
+ ---
7
+
8
+ # Temporal Data Types
9
+
10
+ LoraDB has six first-class temporal types. Each can be stored as a
11
+ [node](../concepts/nodes.md) or [relationship](../concepts/relationships.md)
12
+ [property](../concepts/properties.md), compared,
13
+ [ordered](../queries/ordering.md), and used in arithmetic with `Duration`.
14
+
15
+ | Type | Components | Timezone |
16
+ |---|---|---|
17
+ | `Date` | year, month, day | — |
18
+ | `Time` | hour, minute, second, nanosecond | UTC offset |
19
+ | `LocalTime` | hour, minute, second, nanosecond | — |
20
+ | `DateTime` | Date + Time fields | UTC offset, and optionally a named zone (`Europe/Amsterdam`) |
21
+ | `LocalDateTime` | Date + LocalTime fields | — |
22
+ | `Duration` | months, days, seconds, nanoseconds | — |
23
+
24
+ See [Temporal Functions](../functions/temporal.md) for the full
25
+ construction, [truncation](../functions/temporal.md#truncation), and
26
+ [arithmetic](../functions/temporal.md#arithmetic) reference. This page
27
+ focuses on the *types*.
28
+
29
+ ## Which one do I use?
30
+
31
+ | Situation | Type |
32
+ |---|---|
33
+ | A calendar day (invoice date, birthday) | `Date` |
34
+ | An instant with offset (event timestamp, audit log) | `DateTime` |
35
+ | A wall-clock time with offset | `Time` |
36
+ | A naive local wall-clock time | `LocalTime` |
37
+ | A naive local moment (meeting at 10:00 "Amsterdam time") | `LocalDateTime` |
38
+ | A span (90 minutes, 30 days, 2 weeks) | `Duration` |
39
+
40
+ When in doubt, use `DateTime` for instants and `Date` for calendar days
41
+ — they cover most real-world needs.
42
+
43
+ Store instants as temporals, not as ISO strings: they compare, sort and
44
+ index correctly, and they are smaller. In memory a `DateTime` property
45
+ takes about 13 bytes (11 for its value), a `Date` about 6, against 26 for
46
+ `'2026-11-18T12:00:00.123Z'` as a string. On a log of append-only events
47
+ with two timestamps each, that is about 26 bytes less per event.
48
+
49
+ ## Writing temporals
50
+
51
+ ### Literals via casts
52
+
53
+ There are no bare temporal literals — cast a string or component map
54
+ to the target temporal type:
55
+
56
+ ```cypher
57
+ CREATE (e:Event {
58
+ title: 'Launch',
59
+ at: '2026-05-01T09:00:00Z'::DATETIME,
60
+ day: '2026-05-01'::DATE,
61
+ clock: '09:00:00'::LOCAL_TIME,
62
+ runs_for: 'PT90M'::DURATION
63
+ })
64
+ ```
65
+
66
+ ### Component maps
67
+
68
+ ```cypher
69
+ CREATE (d:Day {
70
+ on: {year: 2024, month: 1, day: 15}::DATE
71
+ })
72
+ ```
73
+
74
+ A map can also give an ISO week date (`{year, week, dayOfWeek}`), an
75
+ ordinal date (`{year, ordinalDay}`) or a quarter date (`{year, quarter,
76
+ dayOfQuarter}`), start from another temporal (`{date: d, day: 1}`), or
77
+ count from the Unix epoch (`{epochSeconds}`, `{epochMillis}`, `DATETIME`
78
+ only). A key the type has no use for, or a smaller component without
79
+ the larger ones (`day` without `month`), is an error that names it.
80
+
81
+ ```cypher
82
+ RETURN date({year: 2026, week: 1, dayOfWeek: 1}) AS first_monday, // 2025-12-29
83
+ date({year: 2026, ordinalDay: 100}) AS day_100, // 2026-04-10
84
+ duration({hours: 1.5}) AS ninety_minutes // PT1H30M
85
+ ```
86
+
87
+ See more in [Temporal Functions → Construction and current time](../functions/temporal.md#construction-and-current-time).
88
+
89
+ ### ISO strings
90
+
91
+ Strings take every ISO 8601 form, in the extended or the basic format:
92
+ calendar dates (`2026-05-01`, `20260501`, `2026-05`, `2026`), week dates
93
+ (`2026-W18-5`), ordinal dates (`2026-121`), quarter dates (`2026-Q2-31`)
94
+ and times with an optional offset (`09:00:00.5+02:00`, `090000+0200`).
95
+ Fields are fixed width, so `2026-5-1` and `9:00` are refused, and the
96
+ local types refuse an offset instead of dropping it:
97
+ `'09:00+02:00'::LOCAL_TIME` is an error.
98
+
99
+ ### Time zones
100
+
101
+ A `DateTime` can carry a named IANA zone as well as its offset. It
102
+ prints as `2026-07-01T12:00:00+02:00[Europe/Amsterdam]`, parses back
103
+ from that form, and follows the zone's daylight saving rules through
104
+ arithmetic and truncation. See
105
+ [Temporal Functions → Time zones](../functions/temporal.md#time-zones).
106
+
107
+ ```cypher
108
+ RETURN datetime({year: 2026, month: 1, day: 15, hour: 9, timezone: 'Europe/Amsterdam'}) AS winter,
109
+ // 2026-01-15T09:00:00+01:00[Europe/Amsterdam]
110
+ datetime({year: 2026, month: 7, day: 15, hour: 9, timezone: 'Europe/Amsterdam'}) AS summer
111
+ // 2026-07-15T09:00:00+02:00[Europe/Amsterdam]
112
+ ```
113
+
114
+ A `DateTime` stored with a named zone uses a storage encoding that
115
+ LoraDB versions before 0.19.0 cannot read, in snapshots and in the WAL.
116
+ Values without a zone are stored exactly as before.
117
+
118
+ ### From host language
119
+
120
+ Every binding ships a helper so you can pass typed values as
121
+ parameters without writing query casts manually:
122
+
123
+ - Node/WASM — [typed helpers](../getting-started/node.md#typed-helpers)
124
+ - Python — [parameters](https://loradb.com/docs/getting-started/python#parameterised-query)
125
+
126
+ ## Comparison and ordering
127
+
128
+ Values of the **same** temporal type are totally ordered.
129
+
130
+ ```cypher
131
+ MATCH (e:Event)
132
+ WHERE e.at >= temporal.now() AND e.at < temporal.now() + 'P7D'::DURATION
133
+ RETURN e
134
+ ORDER BY e.at
135
+ ```
136
+
137
+ Different temporal types are **not** cross-comparable. Ordering a
138
+ `Date` against a `DateTime` (`<`, `<=`, `>`, `>=`) is an error rather
139
+ than a silent `null`, so a `WHERE` never drops rows because of it.
140
+ Convert first, for example with `date(x)` or `datetime(x)`.
141
+
142
+ ## Arithmetic
143
+
144
+ - `Date + Duration` → `Date`
145
+ - `DateTime + Duration` → `DateTime`
146
+ - `DateTime - DateTime` → `Duration`
147
+
148
+ ```cypher
149
+ RETURN '2024-01-15'::DATE + 'P30D'::DURATION
150
+ ;// 2024-02-14
151
+
152
+ RETURN '2025-01-01T00:00:00Z'::DATETIME - '2024-01-01T00:00:00Z'::DATETIME
153
+ // P366D (a Duration — 2024 is a leap year)
154
+ ```
155
+
156
+ `Duration` is **calendar-aware**: `'P1M'::DURATION` is "one month"
157
+ (variable length in days), not exactly 30 days. Use `'P30D'::DURATION`
158
+ for a fixed 30-day window.
159
+
160
+ ## Component access
161
+
162
+ ```cypher
163
+ WITH '2024-01-15T10:30:45Z'::DATETIME AS dt
164
+ RETURN dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second
165
+ ```
166
+
167
+ For the full list see
168
+ [Temporal Functions → component access](../functions/temporal.md#component-access).
169
+
170
+ ## Serialisation
171
+
172
+ Across host-language bindings, temporals are tagged:
173
+
174
+ | Type | Shape |
175
+ |---|---|
176
+ | `Date` | `{kind: "date", iso: "YYYY-MM-DD"}` |
177
+ | `Time` | `{kind: "time", iso: "HH:MM:SS.nnnnn+ZZ:ZZ"}` |
178
+ | `LocalTime` | `{kind: "localtime", iso: "HH:MM:SS.nnnnn"}` |
179
+ | `DateTime` | `{kind: "datetime", iso: "YYYY-MM-DDTHH:MM:SS.nnnnn+ZZ:ZZ"}`, with `[Region/City]` appended for a named zone |
180
+ | `LocalDateTime` | `{kind: "localdatetime", iso: "YYYY-MM-DDTHH:MM:SS.nnnnn"}` |
181
+ | `Duration` | `{kind: "duration", iso: "P…"}` |
182
+
183
+ Use the host-language helpers (`date()`, `datetime()`, `duration()` in
184
+ each binding — see [Node](../getting-started/node.md#typed-helpers),
185
+ [Python](https://loradb.com/docs/getting-started/python#parameterised-query)) to build these values
186
+ without touching the tagged shape manually.
187
+
188
+ ## Examples
189
+
190
+ ### Events in the next week
191
+
192
+ ```cypher
193
+ MATCH (e:Event)
194
+ WHERE e.at >= temporal.now() AND e.at < temporal.now() + 'P7D'::DURATION
195
+ RETURN e.title, e.at
196
+ ORDER BY e.at
197
+ ```
198
+
199
+ ### Bucketed by month
200
+
201
+ ```cypher
202
+ MATCH (e:Event)
203
+ RETURN temporal.truncate('month', e.on) AS month, count(*) AS events
204
+ ORDER BY month
205
+ ```
206
+
207
+ ### Age from birthday
208
+
209
+ ```cypher
210
+ MATCH (p:Person)
211
+ RETURN p.name,
212
+ temporal.in_days(p.born, temporal.today()) / 365 AS approx_age_years
213
+ ```
214
+
215
+ ### Duration arithmetic
216
+
217
+ ```cypher
218
+ CREATE (m:Meeting {
219
+ start: '2026-05-01T09:00:00Z'::DATETIME,
220
+ len: 'PT1H30M'::DURATION
221
+ });
222
+
223
+ MATCH (m:Meeting)
224
+ RETURN m.start, m.start + m.len AS end
225
+ ```
226
+
227
+ ### Active in last 30 days
228
+
229
+ ```cypher
230
+ MATCH (u:User)
231
+ WHERE u.last_seen >= temporal.now() - 'P30D'::DURATION
232
+ RETURN count(*) AS active_30d
233
+ ```
234
+
235
+ ### Group by year of birth
236
+
237
+ ```cypher
238
+ MATCH (p:Person) WHERE p.born IS NOT NULL
239
+ RETURN p.born.year AS year, count(*) AS people
240
+ ORDER BY year
241
+ ```
242
+
243
+ ### Window query — past N days
244
+
245
+ ```cypher
246
+ MATCH (e:Event)
247
+ WHERE e.at >= temporal.now() - {days: $days}::DURATION
248
+ RETURN e
249
+ ORDER BY e.at DESC
250
+ ```
251
+
252
+ Bind `$days` as an integer from the host — the `{days: …}::DURATION`
253
+ map cast accepts a variable, unlike the ISO string form
254
+ `'P7D'::DURATION` which must be a literal.
255
+
256
+ ### Age-bracket bucketing
257
+
258
+ ```cypher
259
+ MATCH (p:Person)
260
+ WITH p, temporal.in_days(p.born, temporal.today()) / 365 AS age_years
261
+ RETURN CASE
262
+ WHEN age_years < 18 THEN 'minor'
263
+ WHEN age_years < 65 THEN 'adult'
264
+ ELSE 'senior'
265
+ END AS bracket,
266
+ count(*) AS people
267
+ ORDER BY people DESC
268
+ ```
269
+
270
+ Uses [`CASE`](../queries/return-with.md#case-expressions) to bucket a
271
+ numeric age.
272
+
273
+ ### Retention cohort
274
+
275
+ ```cypher
276
+ MATCH (u:User)-[:SIGNED_UP_ON]->(d:Day)
277
+ WITH temporal.truncate('month', d.on) AS cohort, u
278
+ OPTIONAL MATCH (u)-[:LOGGED_IN]->(l:Login)
279
+ WHERE l.at >= temporal.now() - 'P30D'::DURATION
280
+ RETURN cohort,
281
+ count(DISTINCT u) AS total,
282
+ count(DISTINCT CASE WHEN l IS NOT NULL THEN u END) AS active_30d
283
+ ORDER BY cohort
284
+ ```
285
+
286
+ ## Edge cases
287
+
288
+ ### Date arithmetic on month-ends
289
+
290
+ `Duration` calendar-aware arithmetic handles month-end clamping:
291
+
292
+ ```cypher
293
+ RETURN '2024-01-31'::DATE + 'P1M'::DURATION; // 2024-02-29
294
+ RETURN '2024-03-31'::DATE + 'P1M'::DURATION // 2024-04-30
295
+ ```
296
+
297
+ ### Timezone-aware comparison
298
+
299
+ `DateTime` values in different offsets or zones order by their UTC
300
+ instant, so ordering is timezone-safe. Equality also compares the offset
301
+ and zone: the same instant written at `Z` and at `+01:00` orders equal
302
+ but is not `=`.
303
+
304
+ ```cypher
305
+ RETURN '2024-01-01T12:00:00Z'::DATETIME < '2024-01-01T13:30:00+01:00'::DATETIME, // true
306
+ '2024-01-01T12:00:00Z'::DATETIME <= '2024-01-01T13:00:00+01:00'::DATETIME, // true
307
+ '2024-01-01T12:00:00Z'::DATETIME = '2024-01-01T13:00:00+01:00'::DATETIME // false
308
+ ```
309
+
310
+ ### Cross-type comparison
311
+
312
+ `Date` and `DateTime` aren't directly comparable: ordering one against
313
+ the other is an error. Convert one side, `date(dt)` takes the date of a
314
+ `DateTime` in its own offset:
315
+
316
+ ```cypher
317
+ MATCH (e:Event)
318
+ WHERE date(e.at) >= date()
319
+ RETURN e
320
+ ```
321
+
322
+ ### `'P1M'::DURATION` vs `'P30D'::DURATION`
323
+
324
+ Calendar-aware vs fixed:
325
+
326
+ ```cypher
327
+ RETURN '2024-02-15'::DATE + 'P1M'::DURATION; // 2024-03-15
328
+ RETURN '2024-02-15'::DATE + 'P30D'::DURATION // 2024-03-16
329
+ ```
330
+
331
+ ### Storing as string
332
+
333
+ If you only want ISO string storage, use `String` — but then sorting
334
+ by date requires parsing on every comparison. Prefer the typed form.
335
+
336
+ ## Limitations
337
+
338
+ - Truncation takes every Cypher unit, from `"millennium"` down to
339
+ `"microsecond"` (case-insensitive). `temporal.truncate(unit, value)`
340
+ returns `null` for a unit the value's type does not have, while
341
+ `date.truncate(…)` and the other `<type>.truncate` forms fail.
342
+ - Parsing is strict ISO 8601. Non-ISO shapes (`MM/DD/YYYY`, RFC-2822)
343
+ and fields that are not fixed width are rejected.
344
+ - A `Time` has no date to resolve daylight saving against, so a named
345
+ zone gives it the zone's current offset.
346
+ - Arithmetic between different temporal types (e.g. `Date - Time`) is
347
+ not supported.
348
+
349
+ ## See also
350
+
351
+ - [**Temporal Functions**](../functions/temporal.md) — construction, current time, truncation, arithmetic.
352
+ - [**WHERE**](../queries/where.md) — temporal predicates and ranges.
353
+ - [**Ordering**](../queries/ordering.md) — chronological sort.
354
+ - [**Aggregation**](../queries/aggregation.md) — date-bucketed group-bys.
355
+ - [**Scalars → Integer/Float**](./scalars.md) — underlying component types.