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