@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.
- 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 +349 -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 +538 -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,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.
|