Skip to content

Commit cb80a93

Browse files
JPryce-AklundhJPryce-Aklundh
authored
Expressions / temporal operators (#1223)
1 parent b0fb7db commit cb80a93

File tree

8 files changed

+188
-171
lines changed

8 files changed

+188
-171
lines changed

‎modules/ROOT/content-nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@
7575
*** xref:expressions/predicates/type-predicate-expressions.adoc[]
7676
** xref:expressions/mathematical-operators.adoc[]
7777
** xref:expressions/string-operators.adoc[]
78+
** xref:expressions/temporal-operators.adoc[]
7879
** xref:expressions/conditional-expressions.adoc[]
7980
8081
* xref:functions/index.adoc[]

‎modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5732,7 +5732,7 @@ Replaced by xref:values-and-types/lists.adoc#cypher-list-comprehension[list comp
57325732
| xref:functions/scalar.adoc#functions-randomuuid[randomUUID()] | Function | Added |
57335733
| xref:values-and-types/temporal.adoc[Temporal types] | Functionality | Added | Supports storing, indexing and working with the following temporal types: Date, Time, LocalTime, DateTime, LocalDateTime and Duration.
57345734
| xref:functions/temporal/index.adoc[Temporal functions] | Functionality | Added | Functions allowing for the creation and manipulation of values for each temporal type -- _Date_, _Time_, _LocalTime_, _DateTime_, _LocalDateTime_ and _Duration_.
5735-
| xref:syntax/operators.adoc#query-operators-temporal[Temporal operators] | Functionality | Added | Operators allowing for the manipulation of values for each temporal type -- _Date_, _Time_, _LocalTime_, _DateTime_, _LocalDateTime_ and _Duration_.
5735+
| xref:expressions/temporal-operators.adoc[Temporal operators] | Functionality | Added | Operators allowing for the manipulation of values for each temporal type -- _Date_, _Time_, _LocalTime_, _DateTime_, _LocalDateTime_ and _Duration_.
57365736
| xref:functions/string.adoc#functions-tostring[toString()] | Function | Extended | Now also allows temporal values as input (i.e. values of type _Date_, _Time_, _LocalTime_, _DateTime_, _LocalDateTime_ or _Duration_).
57375737
|===
57385738

‎modules/ROOT/pages/expressions/index.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,6 @@ For details and examples of specific expressions, see the following sections:
1313
** xref:expressions/predicates/type-predicate-expressions.adoc[]: information about how to verify the value type of a Cypher expression.
1414
* xref:expressions/mathematical-operators.adoc[]: `+`, `-`, `*`, `/`, `%`, `^`.
1515
* xref:expressions/string-operators.adoc[]: `+`, `||`
16+
* xref:expressions/temporal-operators.adoc[]: `+`, `-`, `*`, `/`
1617
* xref:expressions/conditional-expressions.adoc[]
1718

‎modules/ROOT/pages/expressions/temporal-operators.adoc‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
= Temporal operators
2+
:description: Information about Cypher's temporal operators.
3+
:table-caption!:
4+
5+
Cypher contains the following temporal operators:
6+
7+
* Adding a xref::values-and-types/temporal.adoc#cypher-temporal-durations[`DURATION`] to either a xref::values-and-types/temporal.adoc#cypher-temporal-instants[temporal instant value] or another `DURATION`: `+`
8+
* Subtracting a `DURATION` from either a temporal instant value or another `DURATION`: `-`
9+
* Multiplying a `DURATION` with a xref::values-and-types/property-structural-constructed.adoc#property-types[number (`INTEGER` or `FLOAT`)]: `*`
10+
* Dividing a `DURATION` by a number: `/`
11+
12+
For additional expressions that evaluate to a xref:values-and-types/temporal.adoc[temporal value type], see:
13+
14+
* xref:functions/temporal/index.adoc[Temporal functions -- instant types]
15+
* xref:functions/temporal/duration.adoc[Temporal functions -- duration types]
16+
17+
.Value returned from temporal operators
18+
[options="header"]
19+
|===
20+
| Operator | Left-hand operand | Right-hand operand | Result value type
21+
22+
| `+`
23+
| Temporal instant
24+
| `DURATION`
25+
| The type of the temporal instant
26+
27+
| `+`
28+
| `DURATION`
29+
| Temporal instant
30+
| The type of the temporal instant
31+
32+
| `-`
33+
| Temporal instant
34+
| `DURATION`
35+
| The type of the temporal instant
36+
37+
| `+`
38+
| `DURATION`
39+
| `DURATION`
40+
| `DURATION`
41+
42+
| `-`
43+
| `DURATION`
44+
| `DURATION`
45+
| `DURATION`
46+
47+
| `*`
48+
| `DURATION`
49+
| Number
50+
| `DURATION`
51+
52+
| `*`
53+
| Number
54+
| `DURATION`
55+
| `DURATION`
56+
57+
| `/`
58+
| `DURATION`
59+
| Number
60+
| `DURATION`
61+
62+
|===
63+
64+
[[adding-subtracting-durations]]
65+
== Adding and subtracting `DURATION` values
66+
67+
`DURATION` values can be added and subtracted from temporal instant values, such as `LOCAL DATETIME`.
68+
In the below example, the xref:functions/temporal/index.adoc#functions-localdatetime[`localdatetime()`] function is used to create a `LOCAL DATETIME` value, and the xref:functions/temporal/duration.adoc#functions-durations[`duration()`] function is used to create a `DURATION` value.
69+
70+
.Add and subtract a `DURATION` value to/from a `LOCAL DATETIME`
71+
[source, cypher]
72+
----
73+
WITH localdatetime({year:1984, month:10, day:11, hour:12, minute:31, second:14}) AS aDateTime,
74+
duration({years: 12, nanoseconds: 2}) AS aDuration
75+
RETURN aDateTime + aDuration AS addition,
76+
aDateTime - aDuration AS subtraction
77+
----
78+
79+
.Result
80+
[role="queryresult",options="header,footer",cols="2*<m"]
81+
|===
82+
| addition | subtraction
83+
84+
| 1996-10-11T12:31:14.000000002 | 1972-10-11T12:31:13.999999998
85+
86+
2+d|Rows: 1
87+
|===
88+
89+
When adding or subtracting a `DURATION` that results in a non-existing date, Cypher truncates the date to the nearest valid date.
90+
For example, if adding 1 month to January 31st, the result will not be February 31st (an invalid date) but February 28th (or 29th in a leap year).
91+
92+
.Add 1 month to January 31st
93+
[source, cypher]
94+
----
95+
RETURN date("2011-01-31") + duration("P1M") AS truncatedDate
96+
----
97+
98+
.Result
99+
[role="queryresult",options="header,footer",cols="1*<m"]
100+
|===
101+
| truncatedDate
102+
103+
| 2011-02-28
104+
105+
1+d|Rows: 1
106+
|===
107+
108+
When adding two `DURATION` values to a temporal instant value, the order in which the durations are applied affects the result.
109+
110+
.Add two `DURATION` values to a `DATE`
111+
[source, cypher]
112+
----
113+
RETURN (date("2011-01-31") + duration("P1M")) + duration("P12M") AS date1,
114+
date("2011-01-31") + (duration("P1M") + duration("P12M")) AS date2
115+
----
116+
117+
In `date1`, durations are added one after the other, so the date is truncated after adding the first month, resulting in `2012-02-28`.
118+
In `date2`, the durations are combined first, and truncation only happens once, resulting in `2012-02-29`.
119+
120+
.Result
121+
[role="queryresult",options="header,footer",cols="2*<m"]
122+
|===
123+
| date1 | date2
124+
125+
| 2012-02-28 | 2012-02-29
126+
127+
2+d|Rows: 1
128+
|===
129+
130+
[[ignored-components]]
131+
=== Ignored components
132+
133+
When adding or subtracting a `DURATION` value to a temporal instant value, any xref::values-and-types/temporal.adoc#cypher-temporal-duration-component[`DURATION` components] that do not apply to that specific type are ignored.
134+
(For information about what components are supported by temporal instant values, see xref::values-and-types/temporal.adoc#cypher-temporal-accessing-components-temporal-instants[Components of temporal instants]).
135+
For example, when adding a `DURATION` to a `DATE`, only the `year`, `month`, and `day` components of a `DURATION` value are considered, while `hour`, `minute`, `second`, and `nanosecond` are ignored.
136+
This behavior also applies to `LOCAL TIME` and `ZONED TIME`.
137+
138+
.Add and subtract a `DURATION` to/from a `DATE`
139+
[source, cypher]
140+
----
141+
WITH date({year:1984, month:10, day:11}) AS aDate,
142+
duration({years: 12, nanoseconds: 2}) AS aDuration
143+
RETURN aDate + aDuration AS addition,
144+
aDate - aDuration AS subtraction
145+
----
146+
147+
.Result
148+
[role="queryresult",options="header,footer",cols="2*<m"]
149+
|===
150+
| addition | subtraction
151+
152+
| 1996-10-11 | 1972-10-11
153+
154+
2+d|Rows: 1
155+
|===
156+
157+
== Multiplying and dividing `DURATION` values
158+
159+
When multiplying or dividing a `DURATION`, each component is handled separately.
160+
In multiplication, the value of each component is multiplied by the given factor, while in division, each component is divided by the given number.
161+
If the result of the division does not fit into the original components, it overflows into smaller components (e.g. converting days into hours).
162+
This overflow also occurs when multiplying with fractions.
163+
164+
.Multiply and divide a `DURATION` value
165+
[source, cypher]
166+
----
167+
WITH duration({days: 14, minutes: 12, seconds: 70, nanoseconds: 1}) AS aDuration
168+
RETURN aDuration,
169+
aDuration * 2 AS multipliedDuration,
170+
aDuration / 3 AS dividedDuration
171+
----
172+
173+
.Result
174+
[role="queryresult",options="header,footer",cols="3*<m"]
175+
|===
176+
| aDuration | multipliedDuration | dividedDuration
177+
| P14DT13M10.000000001S | P28DT26M20.000000002S | P4DT16H4M23.333333333S
178+
179+
3+d|Rows: 1
180+
|===
181+

‎modules/ROOT/pages/functions/temporal/duration.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Duration functions allow for the creation and manipulation of temporal `DURATION
88

99
[NOTE]
1010
====
11-
See also xref::values-and-types/temporal.adoc[Temporal values] and xref::syntax/operators.adoc#query-operators-temporal[Temporal operators].
11+
See also xref::values-and-types/temporal.adoc[Temporal values] and xref::expressions/temporal-operators.adoc[Temporal operators].
1212
====
1313

1414
[[functions-durations]]

‎modules/ROOT/pages/functions/temporal/index.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ The following functions are included on this page:
5454

5555
[NOTE]
5656
====
57-
See also xref::values-and-types/temporal.adoc[Temporal (Date/Time) values] and xref::syntax/operators.adoc#query-operators-temporal[Temporal operators].
57+
See also xref::values-and-types/temporal.adoc[Temporal (Date/Time) values] and xref::expressions/temporal-operators.adoc[Temporal operators].
5858
====
5959

6060

0 commit comments

Comments
 (0)