@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.
- package/README.md +5 -0
- package/docs/README.md +86 -0
- package/docs/concepts/graph-model.md +270 -0
- package/docs/concepts/nodes.md +285 -0
- package/docs/concepts/properties.md +348 -0
- package/docs/concepts/relationships.md +325 -0
- package/docs/concepts/result-formats.md +183 -0
- package/docs/concepts/schema-free.md +183 -0
- package/docs/cookbook.md +1081 -0
- package/docs/data-types/lists-and-maps.md +406 -0
- package/docs/data-types/overview.md +210 -0
- package/docs/data-types/scalars.md +376 -0
- package/docs/data-types/spatial.md +291 -0
- package/docs/data-types/temporal.md +355 -0
- package/docs/data-types/vectors.md +563 -0
- package/docs/errors.md +183 -0
- package/docs/functions/aggregation.md +372 -0
- package/docs/functions/list.md +522 -0
- package/docs/functions/map.md +207 -0
- package/docs/functions/math.md +421 -0
- package/docs/functions/number.md +197 -0
- package/docs/functions/overview.md +545 -0
- package/docs/functions/spatial.md +384 -0
- package/docs/functions/string.md +502 -0
- package/docs/functions/temporal.md +590 -0
- package/docs/functions/utility.md +137 -0
- package/docs/functions/vectors.md +772 -0
- package/docs/getting-started/installation.md +204 -0
- package/docs/getting-started/node.md +582 -0
- package/docs/getting-started/tutorial.md +334 -0
- package/docs/index.md +203 -0
- package/docs/limitations.md +291 -0
- package/docs/performance.md +219 -0
- package/docs/queries/aggregation.md +520 -0
- package/docs/queries/cheat-sheet.md +302 -0
- package/docs/queries/constraints.md +239 -0
- package/docs/queries/create.md +331 -0
- package/docs/queries/examples.md +453 -0
- package/docs/queries/index.md +169 -0
- package/docs/queries/indexes.md +546 -0
- package/docs/queries/match.md +429 -0
- package/docs/queries/ordering.md +359 -0
- package/docs/queries/parameters.md +328 -0
- package/docs/queries/paths.md +462 -0
- package/docs/queries/return-with.md +500 -0
- package/docs/queries/set-delete.md +369 -0
- package/docs/queries/unwind-merge.md +358 -0
- package/docs/queries/where.md +416 -0
- package/docs/snapshot.md +545 -0
- package/docs/troubleshooting.md +1158 -0
- package/docs/wal.md +570 -0
- package/docs/why.md +273 -0
- 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.2"
|
|
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`.
|