@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.
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 +349 -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 +538 -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,590 @@
1
+ ---
2
+ title: "Temporal Functions (Dates, Times, Durations)"
3
+ description: "Temporal functions in LoraDB — current-time helpers, cast-based temporal construction, component accessors, truncation, and Duration arithmetic."
4
+ online: "https://loradb.com/docs/functions/temporal"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Temporal Functions (Dates, Times, Durations)
9
+
10
+ LoraDB supports the Cypher temporal model end-to-end — see
11
+ [Temporal Data Types](../data-types/temporal.md) for the type details.
12
+ Each value is first-class: store it as a
13
+ [property](../concepts/properties.md), compare it, do arithmetic on it.
14
+
15
+ ## Overview
16
+
17
+ | Goal | Function |
18
+ |---|---|
19
+ | Current date/time | `temporal.today()`, `temporal.now('date')`, `temporal.now()` / `now()`, `temporal.now('time')`, `temporal.now('local_time')`, `temporal.now('local_datetime')` |
20
+ | Parse ISO string | `'…'::DATE`, `'…'::DATETIME`, etc. |
21
+ | From components | `{year, month, day}::DATE`, … |
22
+ | Construct duration | `'P…'::DURATION`, `{days, hours, …}::DURATION` |
23
+ | From epoch | `datetime.fromepoch(seconds, nanos)`, `datetime.fromepochmillis(ms)` |
24
+ | Truncate | [`temporal.truncate(unit, value)`, `date.truncate(unit, value, map)`](#truncation) |
25
+ | Difference | [`duration.between(a, b)`, `duration.inDays(a, b)`](#durationbetween), [`temporal.between(a, b)`, `temporal.in_days(a, b)`](#temporalbetween--temporalin_days) |
26
+ | Component access | `dt.year`, `dt.month`, `dt.hour`, `dur.days` … |
27
+ | Add/subtract | `date + duration`, `datetime - datetime` |
28
+
29
+ ## Temporal types at a glance
30
+
31
+ | Type | Components | Timezone |
32
+ |---|---|---|
33
+ | `Date` | year, month, day | — |
34
+ | `Time` | hour, minute, second, nanosecond | UTC offset |
35
+ | `LocalTime` | hour, minute, second, nanosecond | — |
36
+ | `DateTime` | Date + Time fields | UTC offset, and optionally a named zone |
37
+ | `LocalDateTime` | Date + LocalTime fields | — |
38
+ | `Duration` | months, days, seconds, nanoseconds | — |
39
+
40
+ ## Construction And Current Time
41
+
42
+ Construct temporal values with casts. `value::TYPE` is compact for
43
+ handwritten Cypher, while `CAST(value AS TYPE)` is also supported by the
44
+ Cypher grammar. `TRY_CAST(value AS TYPE)` returns `null` instead of
45
+ reporting a conversion error.
46
+
47
+ The Cypher constructors work as well, and build the type they are named
48
+ for. With no argument they return the current value: `date()` is today's
49
+ `DATE`, `datetime()` the current `DATETIME`, and `localdatetime()`,
50
+ `time()` and `localtime()` likewise. With one argument they are the cast:
51
+ `date(x)` is `x::DATE`, `duration(x)` is `x::DURATION`. Another temporal
52
+ keeps the components the target has, so `date(datetime())` is today's
53
+ date and `localtime(dt)` drops the offset. An argument that does not
54
+ convert is an error.
55
+
56
+ ```cypher
57
+ RETURN date() AS today,
58
+ date(datetime('2026-10-01T23:30:00+02:00')) AS day, // 2026-10-01
59
+ datetime('2026-10-01') AS midnight, // 2026-10-01T00:00:00Z
60
+ time({hour: 9, minute: 30, timezone: '+01:00'}) AS t
61
+ ```
62
+
63
+ A map of only a `timezone` is the current value in that zone, for every
64
+ type: `date({timezone: $tz})` is the reader's local day. At 23:30 UTC on
65
+ 2026-10-24 it is `2026-10-25` in `Europe/Amsterdam`.
66
+
67
+ ```cypher
68
+ RETURN date({timezone: 'Europe/Amsterdam'}) AS todayThere,
69
+ localtime({timezone: '+09:00'}) AS clockInTokyo
70
+ ```
71
+
72
+ `date.transaction()`, `date.statement()` and `date.realtime()` (and the
73
+ same on `time`, `localtime`, `datetime` and `localdatetime`) return the
74
+ current value too. LoraDB has one clock, so the three agree.
75
+
76
+ A map gives the components. Besides `year, month, day`, a date can be an
77
+ ISO week date (`{year, week, dayOfWeek}`, where `year` is the week-based
78
+ year), an ordinal date (`{year, ordinalDay}`) or a quarter date
79
+ (`{year, quarter, dayOfQuarter}`). A clock takes `hour, minute, second,
80
+ millisecond, microsecond, nanosecond`, and the zoned types a `timezone`.
81
+ `date`, `time` and `datetime` keys start from another temporal and the
82
+ other keys override its components; a zoned value given a new `timezone`
83
+ keeps its instant. A smaller component needs the larger ones (`day`
84
+ needs `month`, `second` needs `minute`), and a key the type has no use
85
+ for is an error that names it. `datetime({epochSeconds, nanosecond})` and
86
+ `datetime({epochMillis})` build an instant from the Unix epoch.
87
+
88
+ ```cypher
89
+ RETURN date({year: 1984, week: 10, dayOfWeek: 3}) AS week_date, // 1984-03-07
90
+ date({year: 1984, ordinalDay: 202}) AS ordinal, // 1984-07-20
91
+ date({year: 1984, quarter: 3, dayOfQuarter: 45}) AS quarter, // 1984-08-14
92
+ date({date: date('1984-10-11'), day: 28}) AS moved, // 1984-10-28
93
+ datetime.fromepochmillis(1724198400000) AS instant // 2024-08-21T00:00:00Z
94
+ ```
95
+
96
+ Strings take every ISO 8601 form, extended or basic: `2015-07-21` /
97
+ `20150721`, `2015-07`, `2015`, week dates `2015-W30-2` / `2015W302`,
98
+ ordinal dates `2015-202` / `2015202`, quarter dates `2015-Q3-21`, and
99
+ times such as `21:40:32.142+01:00`, `214032.142+0100`, `21:40` or `21`
100
+ with an offset of `Z`, `±HH:MM`, `±HHMM` or `±HH`. Fields are fixed width
101
+ (`2015-7-21` is refused), and the local types refuse an offset rather
102
+ than drop it: `localtime('12:00+01:00')` is an error.
103
+
104
+ ### Time zones
105
+
106
+ A `timezone` can be an offset (`'+02:00'`, `'Z'`) or an IANA zone name
107
+ (`'Europe/Amsterdam'`, matched case-insensitively). A `DATETIME` in a
108
+ named zone keeps the zone, prints it after the offset
109
+ (`2026-07-01T12:00:00+02:00[Europe/Amsterdam]`) and parses back from
110
+ that form; a string with a zone and no offset takes the zone's offset,
111
+ and an offset the zone does not have at that moment is an error. The
112
+ zone database is built into LoraDB, so every platform, including the
113
+ browser, resolves zones the same way.
114
+
115
+ Daylight saving follows the zone's rules, as in Neo4j. A local time
116
+ that does not exist (the spring gap) moves forward by the length of the
117
+ gap, and one that happens twice (the autumn overlap) takes the earlier
118
+ offset. Adding a duration moves the calendar part (months, days) on the
119
+ wall clock and the rest (hours and smaller) on the instant, so `P1D`
120
+ keeps the time of day across a change and `PT24H` is 24 hours. A
121
+ `TIME` has no date to resolve daylight saving against, so a named zone
122
+ gives it the zone's current offset.
123
+
124
+ ```cypher
125
+ RETURN datetime({year: 2026, month: 7, day: 1, hour: 12, timezone: 'Europe/Amsterdam'});
126
+ // 2026-07-01T12:00:00+02:00[Europe/Amsterdam]
127
+ RETURN datetime('2026-03-29T02:30[Europe/Amsterdam]'); // 2026-03-29T03:30:00+02:00[Europe/Amsterdam]
128
+ RETURN datetime('2026-03-28T12:00[Europe/Amsterdam]') + duration('P1D')
129
+ // 2026-03-29T12:00:00+02:00[Europe/Amsterdam]
130
+ ```
131
+
132
+ The zero-argument current-value helpers also have bare aliases:
133
+ `now()` for `temporal.now()`,
134
+ `timestamp()` for
135
+ `temporal.timestamp()`, and
136
+ `timezone()` for
137
+ `temporal.timezone()`.
138
+
139
+ There are two separate jobs here:
140
+
141
+ - **Current-time helpers** create a value from the database clock.
142
+ - **Casts** create or convert a value from query text, maps, parameters,
143
+ or other expressions.
144
+
145
+ Avoid wrapping an already-cast value in an old constructor-shaped helper.
146
+ For example, write `$value::DATETIME`, not `datetime($value::DATETIME)`
147
+ or `temporal.datetime($value::DATETIME)`.
148
+
149
+ ### Current-time helpers
150
+
151
+ | Helper | Returns | Use when |
152
+ |---|---|---|
153
+ | `temporal.today()` | `DATE` | You need the current calendar day. |
154
+ | `temporal.now('date')` | `DATE` | Equivalent current-day form when the kind is parameterized. |
155
+ | `temporal.now()` / `now()` | `DATETIME` | You need the current instant with timezone offset. |
156
+ | `temporal.now('time')` | `TIME` | You need only the current time-of-day with offset. |
157
+ | `temporal.now('local_time')` | `LOCAL_TIME` | You need a wall-clock time without timezone. |
158
+ | `temporal.now('local_datetime')` | `LOCAL_DATETIME` | You need date and wall-clock time without timezone. |
159
+ | `temporal.timestamp()` / `timestamp()` | `INTEGER` | You need Unix epoch milliseconds. |
160
+ | `temporal.timezone()` / `timezone()` | `STRING` | You need the database timezone label, currently `UTC`. |
161
+
162
+ Use `temporal.now()` for stored instants such as `created_at` and
163
+ `updated_at`. Use `temporal.today()` for date-only concepts such as
164
+ birthdays, billing days, and cohort dates. Use local variants only when
165
+ the value is intentionally a wall-clock value rather than an absolute
166
+ instant.
167
+
168
+ ### Date
169
+
170
+ | Form | Example |
171
+ |---|---|
172
+ | Current day | `temporal.today()` |
173
+ | ISO string | `'2024-01-15'::DATE` |
174
+ | Map | `{year: 2024, month: 1, day: 15}::DATE` |
175
+ | CAST form | `CAST('2024-01-15' AS DATE)` |
176
+
177
+ ```cypher
178
+ RETURN temporal.today(); // today
179
+ RETURN '2024-01-15'::DATE; // 2024-01-15
180
+ RETURN {year: 2024, month: 1, day: 15}::DATE; // 2024-01-15
181
+ RETURN TRY_CAST($maybe_date AS DATE) // null on invalid input
182
+ ```
183
+
184
+ ### DateTime
185
+
186
+ | Form | Example |
187
+ |---|---|
188
+ | Current instant | `temporal.now()` / `now()` |
189
+ | ISO string | `'2024-01-15T10:00:00Z'::DATETIME` |
190
+ | Map | `{year, month, day, hour, minute, second, millisecond, timezone}::DATETIME` |
191
+ | Local current instant | `temporal.now('local_datetime')` |
192
+
193
+ ```cypher
194
+ RETURN '2024-01-15T10:00:00Z'::DATETIME;
195
+ RETURN {year: 2024, month: 1, day: 15, hour: 10, minute: 0}::DATETIME;
196
+ RETURN '2024-01-15T10:00:00+02:00'::DATETIME
197
+ ```
198
+
199
+ ### Time / LocalTime / LocalDateTime
200
+
201
+ ```cypher
202
+ RETURN '12:34:56'::TIME; // with UTC offset (default Z)
203
+ RETURN '12:34:56+02:00'::TIME;
204
+ RETURN '12:34:56'::LOCAL_TIME; // no timezone
205
+ RETURN '2024-01-15T10:00:00'::LOCAL_DATETIME;
206
+ RETURN temporal.now('time');
207
+ RETURN temporal.now('local_time');
208
+ RETURN temporal.now('local_datetime')
209
+ ```
210
+
211
+ ### duration
212
+
213
+ ISO 8601 string or a component map.
214
+
215
+ ```cypher
216
+ RETURN 'P30D'::DURATION; // 30 days
217
+ RETURN 'P1Y2M3DT4H5M6S'::DURATION; // full form
218
+ RETURN 'PT90M'::DURATION; // 90 minutes
219
+ RETURN {years: 1, months: 2, days: 3}::DURATION; // equivalent map form
220
+ RETURN CAST('PT90M' AS DURATION) // CAST form
221
+ ```
222
+
223
+ A duration map takes `years, months, weeks, days, hours, minutes,
224
+ seconds, milliseconds, microseconds, nanoseconds`, each an integer or a
225
+ float. A fraction cascades into the smaller units as in Neo4j: a month
226
+ is 30.436875 days on average.
227
+
228
+ ```cypher
229
+ RETURN duration({hours: 1.5}); // PT1H30M
230
+ RETURN duration({weeks: 2.5}); // P17DT12H
231
+ RETURN duration({months: 0.75}); // P22DT19H51M49.5S
232
+ RETURN duration({seconds: 1, milliseconds: 500}) // PT1.5S
233
+ ```
234
+
235
+ ### Query casts vs parameters
236
+
237
+ Every binding ships a helper so you can pass typed values in
238
+ host-language parameter maps without writing query casts:
239
+
240
+ ```ts
241
+ // Node.js / WASM
242
+ import { datetime, duration } from "@loradb/lora-node";
243
+
244
+ await db.execute(
245
+ "CREATE (:Event {at: $at, len: $len})",
246
+ { at: datetime("2026-05-01T09:00:00Z"), len: duration("PT90M") }
247
+ );
248
+ ```
249
+
250
+ See [Node → typed helpers](../getting-started/node.md#typed-helpers) and
251
+ [Python → parameters](https://loradb.com/docs/getting-started/python#parameterised-query).
252
+
253
+ ## Component access
254
+
255
+ Temporal values expose components via property access.
256
+
257
+ ```cypher
258
+ RETURN '2024-01-15'::DATE.year; // 2024
259
+ RETURN '2024-01-15'::DATE.month; // 1
260
+ RETURN '2024-01-15T10:30:00Z'::DATETIME.hour; // 10
261
+ RETURN '2024-01-15T10:30:45Z'::DATETIME.second; // 45
262
+ RETURN 'P30D'::DURATION.days; // 30
263
+ RETURN 'P1Y'::DURATION.months // 12
264
+ ```
265
+
266
+ Available: `.year`, `.month`, `.day`, `.hour`, `.minute`, `.second`,
267
+ `.millisecond`, `.days`, `.months`, `.years`, `.hours`, `.minutes`,
268
+ `.seconds`.
269
+
270
+ A `DATETIME` also has `.timezone` (the zone's name, such as
271
+ `Europe/Amsterdam`, or the offset when it has no named zone), `.offset`
272
+ (`+02:00`, or `Z`), `.offsetMinutes`, `.offsetSeconds`, `.epochSeconds`
273
+ and `.epochMillis`. A `TIME` has `.timezone` (its offset) and the three
274
+ offset fields.
275
+
276
+ ```cypher
277
+ WITH datetime('2026-07-01T12:00:00+02:00[Europe/Amsterdam]') AS dt
278
+ RETURN dt.timezone, // 'Europe/Amsterdam'
279
+ dt.offset, // '+02:00'
280
+ dt.offsetMinutes, // 120
281
+ dt.epochSeconds // 1782900000
282
+ ```
283
+
284
+ ### Build a year-month key
285
+
286
+ ```cypher
287
+ MATCH (e:Event)
288
+ RETURN e.at.year AS year,
289
+ e.at.month AS month,
290
+ count(*) AS events
291
+ ORDER BY year, month
292
+ ```
293
+
294
+ ## Truncation
295
+
296
+ Reduce a temporal value to a coarser unit. The units are
297
+ `"millennium"`, `"century"`, `"decade"`, `"year"`, `"weekYear"` (the
298
+ Monday starting week 1 of the ISO week-based year), `"quarter"`,
299
+ `"month"`, `"week"` (the Monday of the week), `"day"`, `"hour"`,
300
+ `"minute"`, `"second"`, `"millisecond"` and `"microsecond"`. A `DATE`
301
+ takes the units down to `"day"`; a `TIME` or `LOCAL_TIME` the units from
302
+ `"day"` down.
303
+
304
+ `temporal.truncate(unit, value)` keeps the value's type and returns
305
+ `null` for a unit it cannot apply. The Cypher forms
306
+ `date.truncate(unit, value[, map])`, and likewise on `datetime`,
307
+ `localdatetime`, `time` and `localtime`, build the named type, then apply
308
+ the map's components over the result; an unknown unit or a unit the type
309
+ does not have is an error. A `timezone` in the map replaces the zone and
310
+ keeps the local time.
311
+
312
+ ```cypher
313
+ RETURN date.truncate('week', date('2017-11-11')); // 2017-11-06
314
+ RETURN date.truncate('week', date('2017-11-11'), {dayOfWeek: 2}); // 2017-11-07
315
+ RETURN datetime.truncate('minute', datetime('2017-11-11T12:31:14Z'))
316
+ // 2017-11-11T12:31:00Z
317
+ ```
318
+
319
+ ```cypher
320
+ RETURN temporal.truncate('month', '2024-01-15'::DATE); // 2024-01-01
321
+ RETURN temporal.truncate('year', '2024-07-01'::DATE); // 2024-01-01
322
+ RETURN temporal.truncate('hour', '2024-01-15T10:42:00Z'::DATETIME)
323
+ // 2024-01-15T10:00:00Z
324
+ ```
325
+
326
+ ### Bucketing rows
327
+
328
+ ```cypher
329
+ MATCH (e:Event)
330
+ RETURN temporal.truncate('month', e.at) AS month, count(*) AS events
331
+ ORDER BY month
332
+ ```
333
+
334
+ ```cypher
335
+ MATCH (r:Request)
336
+ RETURN temporal.truncate('hour', r.at) AS hour, count(*) AS hits
337
+ ORDER BY hour
338
+ ```
339
+
340
+ ## Arithmetic
341
+
342
+ - `Date + Duration` → `Date`
343
+ - `DateTime + Duration` → `DateTime`
344
+ - `DateTime - DateTime` → `Duration`
345
+
346
+ Duration arithmetic preserves calendar semantics: months and days are
347
+ stored separately from seconds.
348
+
349
+ ```cypher
350
+ RETURN '2024-01-15'::DATE + 'P30D'::DURATION
351
+ ; // 2024-02-14
352
+
353
+ RETURN '2024-01-15T00:00:00Z'::DATETIME + 'PT36H'::DURATION
354
+ ; // 2024-01-16T12:00:00Z
355
+
356
+ RETURN '2024-12-31T00:00:00Z'::DATETIME - '2024-01-01T00:00:00Z'::DATETIME
357
+ // P365D (a Duration)
358
+ ```
359
+
360
+ ### Calendar vs fixed durations
361
+
362
+ `'P1M'::DURATION` is "one month" — a variable number of days. `'P30D'::DURATION`
363
+ is exactly 30 days.
364
+
365
+ ```cypher
366
+ RETURN '2024-01-31'::DATE + 'P1M'::DURATION; // 2024-02-29 (leap year)
367
+ RETURN '2024-01-31'::DATE + 'P30D'::DURATION // 2024-03-01
368
+ ```
369
+
370
+ ### duration.between
371
+
372
+ `duration.between(a, b)` is the duration from `a` to `b` in months, then
373
+ days, then time, as in Neo4j. `duration.inMonths`, `duration.inDays` and
374
+ `duration.inSeconds` measure in one unit only, counting complete units.
375
+ The two values can be of different temporal types: a value without a
376
+ time is at midnight, with only one side zoned the other is read in the
377
+ same zone, and when either lacks a date only the times of day count.
378
+
379
+ ```cypher
380
+ RETURN duration.between(date('1984-10-11'), date('1985-11-25')); // P1Y1M14D
381
+ RETURN duration.inDays(date('1984-10-11'), date('1985-11-25')); // P410D
382
+ RETURN duration.inSeconds(date('1984-10-11'),
383
+ datetime('1984-10-12T01:00:32.142+01:00'))
384
+ // PT25H32.142S
385
+ ```
386
+
387
+ ### temporal.between / temporal.in_days
388
+
389
+ ```cypher
390
+ RETURN temporal.between('2024-01-01'::DATE, '2024-12-31'::DATE)
391
+ ; // P365D (Duration)
392
+
393
+ RETURN temporal.in_days('2024-01-01'::DATE, '2024-04-10'::DATE)
394
+ // 100
395
+ ```
396
+
397
+ `temporal.in_days` is for `DATE` values. For `DATETIME` values, use
398
+ `temporal.between(a, b).days` when you need the day component.
399
+
400
+ ## Comparison
401
+
402
+ Comparable within the same type using `<`, `<=`, `>`, `>=`, `=`, `<>`.
403
+ Cross-type comparisons (e.g. `Date` vs `DateTime`) return `null`.
404
+
405
+ ```cypher
406
+ MATCH (e:Event)
407
+ WHERE e.at >= temporal.now() AND e.at < temporal.now() + 'P7D'::DURATION
408
+ RETURN e
409
+ ORDER BY e.at
410
+ ```
411
+
412
+ ```cypher
413
+ MATCH (p:Person)
414
+ WHERE p.born < '1900-01-01'::DATE
415
+ RETURN p.name, p.born
416
+ ```
417
+
418
+ ## Storing temporal values
419
+
420
+ Temporals serialise tagged: `{"kind": "date", "iso": "2024-01-15"}` etc.
421
+ (see [Temporal Data Types](../data-types/temporal.md#serialisation)). They
422
+ round-trip cleanly through `CREATE` and `MATCH`.
423
+
424
+ ```cypher
425
+ CREATE (e:Event {
426
+ title: 'Launch',
427
+ at: '2026-05-01T09:00:00Z'::DATETIME,
428
+ runs_for: 'PT90M'::DURATION,
429
+ day: '2026-05-01'::DATE
430
+ });
431
+
432
+ MATCH (e:Event)
433
+ RETURN e.title,
434
+ e.at,
435
+ e.at + e.runs_for AS ends_at
436
+ ```
437
+
438
+ ## Common patterns
439
+
440
+ ### Events in the next week
441
+
442
+ ```cypher
443
+ MATCH (e:Event)
444
+ WHERE e.at >= temporal.now()
445
+ AND e.at < temporal.now() + 'P7D'::DURATION
446
+ RETURN e
447
+ ORDER BY e.at
448
+ ```
449
+
450
+ ### Events in a month
451
+
452
+ ```cypher
453
+ MATCH (e:Event)
454
+ WHERE temporal.truncate('month', e.at) = '2026-05-01'::DATE
455
+ RETURN e
456
+ ```
457
+
458
+ ### Age from birthday
459
+
460
+ ```cypher
461
+ MATCH (p:Person)
462
+ RETURN p.name,
463
+ temporal.in_days(p.born, temporal.today()) / 365 AS approx_age_years
464
+ ```
465
+
466
+ ### Rolling 30-day active users
467
+
468
+ ```cypher
469
+ MATCH (u:User)-[:VIEWED]->(:Page)
470
+ WHERE u.last_seen >= temporal.now() - 'P30D'::DURATION
471
+ RETURN count(DISTINCT u) AS active_30d
472
+ ```
473
+
474
+ ### Session length
475
+
476
+ ```cypher
477
+ MATCH (s:Session)
478
+ RETURN s.id, (s.ended - s.started) AS duration
479
+ ORDER BY duration DESC
480
+ ```
481
+
482
+ ### First / last event per user
483
+
484
+ ```cypher
485
+ MATCH (u:User)-[:DID]->(e:Event)
486
+ RETURN u.id,
487
+ min(e.at) AS first_event,
488
+ max(e.at) AS last_event
489
+ ```
490
+
491
+ ### Cohorts by signup month
492
+
493
+ ```cypher
494
+ MATCH (u:User)
495
+ RETURN temporal.truncate('month', u.created) AS cohort,
496
+ count(*) AS signups
497
+ ORDER BY cohort
498
+ ```
499
+
500
+ ### "Since last seen" bucket
501
+
502
+ ```cypher
503
+ MATCH (u:User)
504
+ WITH u,
505
+ temporal.between(u.last_seen, temporal.now()).days AS days_away
506
+ RETURN CASE
507
+ WHEN days_away <= 1 THEN 'today'
508
+ WHEN days_away <= 7 THEN 'week'
509
+ WHEN days_away <= 30 THEN 'month'
510
+ ELSE 'dormant'
511
+ END AS freshness,
512
+ count(*) AS users
513
+ ORDER BY users DESC
514
+ ```
515
+
516
+ Uses [`CASE`](../queries/return-with.md#case-expressions) to bucket a
517
+ continuous duration into named tiers.
518
+
519
+ ### Time-of-day histogram
520
+
521
+ ```cypher
522
+ MATCH (e:Event)
523
+ RETURN e.at.hour AS hour, count(*) AS events
524
+ ORDER BY hour
525
+ ```
526
+
527
+ Component access on a `DateTime` returns integers — no string parsing
528
+ needed.
529
+
530
+ ### Recurring window — "same time next week"
531
+
532
+ ```cypher
533
+ MATCH (m:Meeting {id: $id})
534
+ RETURN m.start,
535
+ m.start + 'P7D'::DURATION AS next_week,
536
+ m.start + 'P14D'::DURATION AS two_weeks
537
+ ```
538
+
539
+ ### Build ISO timestamp for serialisation
540
+
541
+ ```cypher
542
+ MATCH (e:Event)
543
+ RETURN e.id, e.at::STRING AS iso
544
+ ```
545
+
546
+ `CAST(e.at AS STRING)` / `e.at::STRING` on a `DateTime` emits a
547
+ round-trippable ISO 8601 string.
548
+
549
+ ## Edge cases
550
+
551
+ ### Mixing types
552
+
553
+ `Date - DateTime`, `Time + Duration` — not supported. Convert first to
554
+ matching types.
555
+
556
+ ### Timezone handling
557
+
558
+ `DateTime` carries a UTC offset, and a named zone when it was built with
559
+ one (see [Time zones](#time-zones)). Compare `DateTime` values across
560
+ zones freely: they order by instant. Equality also compares the zone, so
561
+ the same instant at `+02:00` and in `Europe/Amsterdam` are not equal. `LocalDateTime` has no
562
+ zone; two `LocalDateTime` values compare by naive wall-clock order.
563
+
564
+ ### Strict ISO parsing
565
+
566
+ Non-ISO shapes (`MM/DD/YYYY`, RFC-2822) are rejected at parse time. Normalise on the host side before passing to
567
+ `'…'::DATE` / `'…'::DATETIME`.
568
+
569
+ ### `temporal.today()` with no args — now vs wall clock
570
+
571
+ In WASM, `temporal.today()` resolves to `Date.now()` at millisecond precision —
572
+ nanosecond fields are zero. In native builds, it reflects the OS clock.
573
+ See [WASM → gotchas](https://loradb.com/docs/getting-started/wasm#performance--best-practices).
574
+
575
+ ## Limitations
576
+
577
+ - Arithmetic between values of **different** temporal types
578
+ (e.g. `Date - Time`) is not supported. Convert first.
579
+ - Parsing is strict ISO 8601 — non-ISO shapes (`MM/DD/YYYY`,
580
+ RFC-2822) are rejected.
581
+ - No component-access shortcuts on `Duration` beyond the listed
582
+ fields.
583
+
584
+ ## See also
585
+
586
+ - [**Temporal Data Types**](../data-types/temporal.md) — type reference.
587
+ - [**Scalars**](../data-types/scalars.md) — underlying numeric components.
588
+ - [**WHERE**](../queries/where.md) — temporal predicates.
589
+ - [**Ordering**](../queries/ordering.md) — chronological sorting.
590
+ - [**Aggregation**](./aggregation.md) — bucketing with `temporal.truncate`.