You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -37,10 +37,11 @@ label:functionality[]
37
37
label:new[]
38
38
[source, cypher, role="noheader"]
39
39
----
40
-
format()
40
+
WITH datetime('2024-06-27T14:30:45.123456789+02:00[Europe/Paris]') AS dt
41
+
RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x
41
42
----
42
43
43
-
| Format function xref:functions/temporal/format.adoc[].
44
+
| Cypher's new xref:functions/temporal/format.adoc[format function] can create dynamically formatted string representations of temporal instance and duration types.
For instance types, the characters in table <<#character-table>> can be used to create a string pattern.
27
-
n be repeated to change their output.
26
+
Cypher's instance types are `DATE`, `LOCAL TIME`, `ZONED TIME`, `LOCAL DATETIME` and `ZONED DATETIME`, refer to xref:/values-and-types/temporal.adoc#cypher-temporal-instants[temporal instants].
27
+
28
+
Use the characters in table <<#instance-character-table>> to create a string pattern for instance types.
29
+
Most characters change yield a different output when they are repeated.
28
30
29
-
[#character-table]
31
+
[#instance-character-table]
30
32
.Allowed characters for an instance type string pattern
31
33
[options="header"]
32
34
|===
@@ -94,9 +96,13 @@ Up to three letters of 'D' can be specified.
94
96
95
97
| A "fraction" outputs the nano-of-second field as a fraction-of-second. The nano-of-second value has nine digits, thus the number of characters can be between 1 and 9 and is truncated if it is less than 9.
96
98
97
-
| The "year" style is determined the minimum field width below which padding is used. If the count of letters is two, then a reduced two digit form is used. For printing, this outputs the rightmost two digits. For parsing, this will parse using the base value of 2000, resulting in a year within the range 2000 to 2099 inclusive. If the count of letters is less than four (but not two), then the sign is only output for negative years as per SignStyle.NORMAL. Otherwise, the sign is output if the pad width is exceeded, as per SignStyle.EXCEEDS_PAD.
99
+
| The "year" characters determine the minimum field width below which padding is used.
100
+
101
+
With two characters, the reduced two digit form is used. For printing, this outputs the rightmost two digits. For parsing, this will use the base value of 2000, resulting in a year within the range of 2000 and 2099.
98
102
99
-
| A "zone-id" outputs the time-zone ID, such as 'Europe/Paris'. If the count of letters is two, then the time-zone ID is output. Any other count of letters throws IllegalArgumentException.
103
+
With one or three characters, the minus-sign is only output for negative years. Otherwise, the minus-sign is output if the pad width is exceeded.
104
+
105
+
| A "zone-id" outputs the timezone ID. Two characters output the timezone ID, other amounts result in an error.
100
106
101
107
| A "zone-name" outputs the display name of the timezone ID.
102
108
@@ -105,19 +111,48 @@ If the pattern character is 'z', the output is the daylight saving time (DST) zo
105
111
If the character is 'v', the output provides the zone name ignoring daylight saving time.
106
112
One 'v' outputs the short name, two three and five result in an error, and four 'v's output the full name.
107
113
108
-
| Offset X and x: This formats the offset based on the number of pattern letters. One letter outputs just the hour, such as '+01', unless the minute is non-zero in which case the minute is also output, such as '+0130'. Two letters outputs the hour and minute, without a colon, such as '+0130'. Three letters outputs the hour and minute, with a colon, such as '+01:30'. Four letters outputs the hour and minute and optional second, without a colon, such as '+013015'. Five letters outputs the hour and minute and optional second, with a colon, such as '+01:30:15'. Six or more letters throws IllegalArgumentException. Pattern letter 'X' (upper case) will output 'Z' when the offset to be output would be zero, whereas pattern letter 'x' (lower case) will output '+00', '+0000', or '+00:00'.
114
+
| "offset-X" and "offset-x" format the offset based on the number of pattern characters.
115
+
One character outputs just the hour, such as '+01', unless the minute is non-zero. In that case, the minute is also output, such as '+0130'.
116
+
117
+
Two characters output the hour and minute, without a colon, such as '+0130'.
118
+
119
+
Three characters output the hour and minute, with a colon, such as '+01:30'.
120
+
121
+
Four letters outputs the hour and minute and optional second, without a colon, such as '+013015'.
122
+
123
+
Five letters outputs the hour and minute and optional second, with a colon, such as '+01:30:15'.
124
+
125
+
Six or more letters result in an error.
126
+
127
+
An upper case 'X' outputs 'Z' if the offset would be zero, whereas a lowwer case 'x' outputs '+00', '+0000', or '+00:00'.
128
+
129
+
| With a non-zero offset, "offset-O" formats the localized offset based on the number of characters.
130
+
131
+
One character outputs the short form of the localized offset, which is the localized offset text, such as 'GMT', followed by the hour without leading zero, optional 2-digit minute and second if they are non-zero, and a colon, for example 'GMT+8'.
109
132
110
-
| Offset O: With a non-zero offset, this formats the localized offset based on the number of pattern letters. One letter outputs the short form of the localized offset, which is localized offset text, such as 'GMT', with hour without leading zero, optional 2-digit minute and second if non-zero, and colon, for example 'GMT+8'. Four letters outputs the full form, which is localized offset text, such as 'GMT, with 2-digit hour and minute field, optional second field if non-zero, and colon, for example 'GMT+08:00'. If the offset is zero, only localized text is output. Any other count of letters throws IllegalArgumentException.
133
+
Four characters output the full form, which is a localized offset text, such as 'GMT, with a 2-digit hour and minute field, optional second field if non-zero, and colon, for example 'GMT+08:00'.
111
134
112
-
| Offset Z: This formats the offset based on the number of pattern letters. One, two or three letters outputs the hour and minute, without a colon, such as '+0130'. The output will be '+0000' when the offset is zero. Four letters outputs the full form of localized offset, equivalent to four letters of Offset-O. The output will be the corresponding localized offset text if the offset is zero. Five letters outputs the hour, minute, with optional second if non-zero, with colon. It outputs 'Z' if the offset is zero. Six or more letters throws IllegalArgumentException.
135
+
If the offset is zero, only localized text is output.
136
+
137
+
Other character amounts result in an error.
138
+
139
+
| "offset-Z" formats the offset based on the number of characters.
140
+
141
+
One, two or three characters output the hour and minute, without a colon, such as '+0130'. If the offset is zero, the output will be '+0000'.
142
+
143
+
Four characters outputs the full form of the localized offset, equivalent to four characters of "offset-O". If the offset is zero, the output will be the corresponding localized offset text.
144
+
145
+
Five characters output the hour, minute, with optional second if non-zero, with colon. If the offset is zero, the output is 'Z'.
146
+
147
+
More characters will result in an error.
113
148
114
149
| The "pad modifier" modifies the pattern that immediately follows to be padded with spaces. The pad width is determined by the number of pattern characters.
115
150
116
-
| Any unrecognized letter results in an error. Any non-letter character, other than '[', ']', '{', '}', '#' and the single quote are output directly. Yet, it is recommended to wrap all characters that you want to output directly with single quotes to ensure compatibility in the future.
151
+
| Any character that is not reserved, other than '[', ']', '{', '}', '#', and the single quote are output directly. To ensure future compatibility it is recommended to wrap all characters that you want to output directly with single quotes.
117
152
118
153
|===
119
154
120
-
.+duration()+ using duration components
155
+
.awesome example
121
156
======
122
157
123
158
.Query
@@ -139,4 +174,53 @@ RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x
Cypher's duration type `DURATION` has components and component groups, see xref:values-and-types/temporal.adoc#cypher-temporal-accessing-components-durations[components of durations].
181
+
182
+
When constructing a string representation of a duration type with `format()`, components can only be converted within the component groups, for example, weeks to days since they are both in the component group "Days".
183
+
This is because without a reference point, there is no way of determining the specifics of a duration.
184
+
For example, not all months have the same number of days, and switches to or from daylight saving time means that a day has 23 or 25 hours rather than 24.
185
+
186
+
Use the characters in table <<duration-character-table>> to create a string pattern for duration types.
187
+
188
+
[#duration-character-table]
189
+
.Allowed characters for a duration type string pattern
190
+
[options="header"]
191
+
|===
192
+
| Component Group | Characters | Field
193
+
| Months | y/Y/u | Years
194
+
| | q/Q | Quarters
195
+
| | M/L | Months
196
+
| Days | w/W | Weeks
197
+
| | d/D | Days
198
+
| Seconds | h/H/k/K | Hours
199
+
| | m | Minutes
200
+
| | s | Seconds
201
+
| | n/S | Fraction of Second
202
+
| | A | Milliseconds
203
+
| | N | Nanoseconds
204
+
|===
205
+
206
+
.awesome example
207
+
======
208
+
209
+
.Query
210
+
[source, cypher, indent=0]
211
+
----
212
+
WITH datetime('2024-06-27T14:30:45.123456789+02:00[Europe/Paris]') AS dt
213
+
RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x
All temporal types can be indexed, and thereby support exact lookups for equality predicates.
1749
1749
Indexes for temporal instant types additionally support range lookups.
1750
1750
1751
+
1751
1752
[[cypher-temporal-format]]
1752
1753
== Formatting temporal values
1753
1754
1754
-
Lorem ipsum.
1755
+
Using Cypher's xref:/functions/temporal/format.adoc#_instance_types[`format()` function], you can create dynamically formatted string representations of temporal instance and duration types.
1755
1756
1756
-
// A - Excerpt from DateTimeFormatter documentation
1757
+
.A string representation of an instance type
1758
+
======
1759
+
1760
+
.Query
1761
+
[source, cypher, indent=0]
1762
+
----
1763
+
WITH datetime('2024-06-27T14:30:45.123456789+02:00[Europe/Paris]') AS dt
1764
+
RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x
| Z | zone-offset | offset-Z | +0000; -0800; -08:00
1794
-
| p | pad next | pad modifier | 1
1795
-
| | escape for text | delimiter |
1796
-
| ' | single quote | literal |
1797
-
| [ | optional section start | |
1798
-
| ] | optional section end | |
1799
-
|===
1798
+
1799
+
======
1800
+
1801
+
For more examples and details on how to construct string patterns, see xref:/functions/temporal/format.adoc#query-functions-temporal-format-instance-types[instance types] and xref:/functions/temporal/format.adoc#query-functions-temporal-format-duration-types[duration types].
0 commit comments