Document temporal parsing (#1392)

Co-authored-by: Louise Berglund <[email protected]>

Author: rsill-neo4j

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

@@ -22,6 +22,31 @@ Cypher 25 was introduced in Neo4j 2025.06 and can only be used on Neo4j 2025.06+
 Features removed in Cypher 25 are still available on Neo4j 2025.06+ databases either by prepending a query with `CYPHER 5` or by having Cypher 5 as the default language for the database.
 For more information, see xref:queries/select-version.adoc[].
 
+
+[[cypher-deprecations-additions-removals-2025.10]]
+== Neo4j 2025.10
+
+=== Updated in Cypher 25
+
+[cols="2", options="header"]
+|===
+| Feature
+| Details
+
+a|
+label:functionality[]
+label:updated[]
+[source, cypher, role="noheader"]
+----
+RETURN datetime('11/18/1986', "MM/dd/yyyy") AS dt
+----
+
+| The following constructors of temporal types have been extended with the optional argument `pattern`:
+xref:functions/temporal/index.adoc#functions-date[date()], xref:functions/temporal/index.adoc#functions-datetime[datetime()], xref:functions/temporal/index.adoc#functions-localdatetime[localdatetime()], xref:functions/temporal/index.adoc#functions-localtime[localtime()], xref:functions/temporal/index.adoc#functions-time[time()] and xref:functions/temporal/duration.adoc#query-functions-temporal-duration[duration()].
+These patterns are the same as those used to create temporal strings with the xref:functions/temporal/format.adoc[`format()`] function introduced in 2025.09 and thus allow for the parsing of temporal strings into temporal values.
+|===
+
+
 [[cypher-deprecations-additions-removals-2025.09]]
 == Neo4j 2025.09
 

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

@@ -16,23 +16,25 @@ See also xref::values-and-types/temporal.adoc[Temporal values] and xref::express
 
 .Details
 |===
-| *Syntax* 3+| `duration(input)`
+| *Syntax* 3+| `duration(input[, pattern])`
 | *Description* 3+| Creates a `DURATION` value.
-.2+| *Arguments* | *Name* | *Type* | *Description*
-| `input` | `ANY` | A map optionally containing the following keys: 'years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds', or 'nanoseconds'.
+.3+| *Arguments* | *Name* | *Type* | *Description*
+| `input` | `ANY` | Either a string representation of a duration value or a map optionally containing the following keys: 'years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds', 'milliseconds', 'microseconds', or 'nanoseconds'.
+| `pattern` | `STRING` | A pattern used to parse the input. If a pattern is provided, `input` must be `STRING`.
 | *Returns* 3+| `DURATION`
 |===
 
 .Considerations
 |===
 
-| At least one parameter must be provided (`duration()` and `+duration({})+` are invalid).
-| There is no constraint on how many of the parameters are provided.
+| If `input` is not a string, at least one component must be provided (`duration()` and `+duration({})+` are invalid).
+| There is no constraint on how many components are provided.
 | It is possible to have a `DURATION` where the amount of a smaller unit (e.g. `seconds`) exceeds the threshold of a larger unit (e.g. `days`).
-| The values of the parameters may be expressed as decimal fractions.
-| The values of the parameters may be arbitrarily large.
-| The values of the parameters may be negative.
+| The values of the components may be expressed as decimal fractions.
+| The values of components may be arbitrarily large.
+| The values of components may be negative.
 | The xref:values-and-types/temporal.adoc#cypher-temporal-accessing-components-durations[components of `DURATION` objects] are individually accessible.
+| The `pattern` argument is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-duration-types-characters[Allowed characters for duration types].
 
 |===
 
@@ -85,7 +87,8 @@ duration("P14DT16H12M"),
 duration("P5M1.5D"),
 duration("P0.75M"),
 duration("PT0.75M"),
-duration("P2012-02-02T14:37:21.545")
+duration("P2012-02-02T14:37:21.545"),
+duration("5 hours 6 minutes", "h 'hours' m 'minutes'")
 ] AS aDuration
 RETURN aDuration
 ----
@@ -101,7 +104,8 @@ RETURN aDuration
 | P22DT19H51M49.5S
 | PT45S
 | P2012Y2M2DT14H37M21.545S
-1+d|Rows: 5
+| PT5H6M
+1+d|Rows: 6
 
 |===
 

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

@@ -332,13 +332,15 @@ The following table lists the supported truncation units and the corresponding s
 
 .Details
 |===
-| *Syntax* 3+| `date( [input] )`
+| *Syntax* 3+| `date([ input, pattern] )`
 | *Description* 3+| Creates a `DATE` instant.
-.2+| *Arguments* | *Name* | *Type* | *Description*
+.3+| *Arguments* | *Name* | *Type* | *Description*
 | `input` | `ANY` | Either a string representation of a temporal value, a map containing the single key 'timezone', or a map containing temporal values ('date', 'year', 'month', 'day', 'week', 'dayOfWeek', 'quarter', 'dayOfQuarter', 'ordinalDay') as components.
+| `pattern` | `STRING` | A pattern used to parse the input. If a pattern is provided, `input` must be `STRING`.
 | *Returns* 3+| `DATE`
 |===
 
+
 .Temporal components
 [options="header"]
 |===
@@ -393,6 +395,7 @@ The following table lists the supported truncation units and the corresponding s
 | `date(null)` returns `null`.
 | If any of the optional parameters are provided, these will override the corresponding components of `date`.
 | `date(dd)` may be written instead of `+date({date: dd})+`.
+| The `pattern` argument is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-instance-types-characters[Allowed characters for instance types].
 
 |===
 
@@ -604,7 +607,8 @@ date('2015-07'),
 date('201507'),
 date('2015-W30-2'),
 date('2015202'),
-date('2015')
+date('2015'),
+date('11/18/1986', "MM/dd/yyyy")
 ] AS theDate
 RETURN theDate
 ----
@@ -620,7 +624,8 @@ RETURN theDate
 | 2015-07-21
 | 2015-07-21
 | 2015-01-01
-1+d|Rows: 6
+| 1986-11-18
+1+d|Rows: 7
 
 |===
 
@@ -841,10 +846,11 @@ RETURN
 
 .Details
 |===
-| *Syntax* 3+| `datetime([ input ])`
+| *Syntax* 3+| `datetime([ input, pattern ])`
 | *Description* 3+| Creates a `ZONED DATETIME` instant.
-.2+| *Arguments* | *Name* | *Type* | *Description*
+.3+| *Arguments* | *Name* | *Type* | *Description*
 | `input` | `ANY` | Either a string representation of a temporal value, a map containing the single key 'timezone', or a map containing temporal values ('year', 'month', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond', 'timezone') as components.
+| `pattern` | `STRING` | A pattern used to parse the input. If a pattern is provided, `input` must be `STRING`.
 | *Returns* 3+| `ZONED DATETIME`
 |===
 
@@ -914,6 +920,7 @@ RETURN
 | Selecting a `ZONED DATETIME` or `ZONED TIME` as the `time` component and overwriting the timezone will adjust the local time to keep the same point in time.
 | `epochSeconds`/`epochMillis` may be used in conjunction with `nanosecond`.
 | `datetime(null)` returns null.
+| The `pattern` argument is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-instance-types-characters[Allowed characters for instance types].
 
 |===
 
@@ -1118,7 +1125,8 @@ datetime('20150721T21:40-01:30'),
 datetime('2015-W30T2140-02'),
 datetime('2015202T21+18:00'),
 datetime('2015-07-21T21:40:32.142[Europe/London]'),
-datetime('2015-07-21T21:40:32.142-04[America/New_York]')
+datetime('2015-07-21T21:40:32.142-04[America/New_York]'),
+datetime('Tuesday, November 18, AD 1986', 'EEEE, MMMM d, G uuuu')
 ] AS theDate
 RETURN theDate
 ----
@@ -1136,7 +1144,8 @@ RETURN theDate
 | 2015-07-21T21:00+18:00
 | 2015-07-21T21:40:32.142+01:00[Europe/London]
 | 2015-07-21T21:40:32.142-04:00[America/New_York]
-1+d|Rows: 8
+| 1986-11-18T00:00Z
+1+d|Rows: 9
 
 |===
 
@@ -1599,10 +1608,11 @@ RETURN
 
 .Details
 |===
-| *Syntax* 3+| `localdatetime([ input ])`
+| *Syntax* 3+| `localdatetime([ input, pattern ])`
 | *Description* 3+| Creates a `LOCAL DATETIME` instant.
-.2+| *Arguments* | *Name* | *Type* | *Description*
+.3+| *Arguments* | *Name* | *Type* | *Description*
 | `input` | `ANY` | Either a string representation of a temporal value, a map containing the single key 'timezone', or a map containing temporal values ('year', 'month', 'day', 'hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond') as components.
+| `pattern` | `STRING` | A pattern used to parse the input. If a pattern is provided, `input` must be `STRING`.
 | *Returns* 3+| `LOCAL DATETIME`
 |===
 
@@ -1661,6 +1671,7 @@ RETURN
 | `localdatetime(null)` returns null.
 | If any of the optional parameters are provided, these will override the corresponding components of `datetime`, `date` and/or `time`.
 | `localdatetime(dd)` may be written instead of `+localdatetime({datetime: dd})+`.
+| The `pattern` argument is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-instance-types-characters[Allowed characters for instance types].
 
 |===
 
@@ -1829,7 +1840,8 @@ UNWIND [
 localdatetime('2015-07-21T21:40:32.142'),
 localdatetime('2015-W30-2T214032.142'),
 localdatetime('2015-202T21:40:32'),
-localdatetime('2015202T21')
+localdatetime('2015202T21'),
+localdatetime('Tuesday, November 18, AD 1986', 'EEEE, MMMM d, G uuuu')
 ] AS theDate
 RETURN theDate
 ----
@@ -1843,7 +1855,8 @@ RETURN theDate
 | 2015-07-21T21:40:32.142
 | 2015-07-21T21:40:32
 | 2015-07-21T21:00
-1+d|Rows: 4
+| 1986-11-18T00:00Z
+1+d|Rows: 5
 
 |===
 
@@ -2179,10 +2192,11 @@ RETURN
 
 .Details
 |===
-| *Syntax* 3+| `localtime([ input ])`
+| *Syntax* 3+| `localtime([ input, pattern ])`
 | *Description* 3+| Creates a `LOCAL TIME` instant.
-.2+| *Arguments* | *Name* | *Type* | *Description*
+.3+| *Arguments* | *Name* | *Type* | *Description*
 | `input` | `ANY` | Either a string representation of a temporal value, a map containing the single key 'timezone', or a map containing temporal values ('hour, 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond' as components.
+| `pattern` | `STRING` | A pattern used to parse the input. If a pattern is provided, `input` must be `STRING`.
 | *Returns* 3+| `LOCAL TIME`
 |===
 
@@ -2227,6 +2241,7 @@ RETURN
 | `localtime(null)` returns null.
 | If any of the optional parameters are provided, these will override the corresponding components of `time`.
 | `localtime(tt)` may be written instead of `localtime({time: tt})`.
+| The `pattern` argument is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-instance-types-characters[Allowed characters for instance types].
 
 |===
 
@@ -2320,7 +2335,8 @@ UNWIND [
 localtime('21:40:32.142'),
 localtime('214032.142'),
 localtime('21:40'),
-localtime('21')
+localtime('21'),
+localtime('6:04', 'k:mm')
 ] AS theTime
 RETURN theTime
 ----
@@ -2334,7 +2350,8 @@ RETURN theTime
 | 21:40:32.142
 | 21:40
 | 21:00
-1+d|Rows: 4
+| 06:04
+1+d|Rows: 5
 
 |===
 
@@ -2574,10 +2591,11 @@ RETURN
 
 .Details
 |===
-| *Syntax* 3+| `time([ input ])`
+| *Syntax* 3+| `time([ input, pattern ])`
 | *Description* 3+| Creates a `ZONED TIME` instant.
-.2+| *Arguments* | *Name* | *Type* | *Description*
+.3+| *Arguments* | *Name* | *Type* | *Description*
 | `input` | `ANY` | Either a string representation of a temporal value, a map containing the single key 'timezone', or a map containing temporal values ('hour', 'minute', 'second', 'millisecond', 'microsecond', 'nanosecond', 'timezone') as components.
+| `pattern` | `STRING` | A pattern used to parse the input. If a pattern is provided, `input` must be `STRING`.
 | *Returns* 3+| `ZONED TIME`
 |===
 
@@ -2629,6 +2647,7 @@ RETURN
 | `time(tt)` may be written instead of `+time({time: tt})+`.
 | Selecting a `ZONED TIME` or `ZONED DATETIME` value as the `time` component also selects its timezone. If a `LOCAL TIME` or `LOCAL DATETIME` is selected instead, the default timezone is used. In any case, the timezone can be overridden explicitly.
 | Selecting a `ZONED DATETIME` or `ZONED TIME` as the `time` component and overwriting the timezone will adjust the local time to keep the same point in time.
+| The `pattern` argument is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-instance-types-characters[Allowed characters for instance types].
 
 |===
 
@@ -2733,7 +2752,8 @@ time('214032-0100'),
 time('21:40-01:30'),
 time('2140-00:00'),
 time('2140-02'),
-time('22+18:00')
+time('22+18:00'),
+time('6:04', 'k:mm')
 ] AS theTime
 RETURN theTime
 ----
@@ -2751,7 +2771,8 @@ RETURN theTime
 | 21:40:00Z
 | 21:40:00-02:00
 | 22:00:00+18:00
-1+d|Rows: 8
+| 06:04:00Z
+1+d|Rows: 9
 
 |===