Skip to content

Document temporal parsing #1392

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Oct 8, 2025
Merged

Document temporal parsing #1392

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
3f1ae26
duplicated date table
rsill-neo4j Sep 11, 2025
c77f04f
WiP
rsill-neo4j Sep 12, 2025
bf9d210
Merge branch 'dev' into document-temporal-parsing
rsill-neo4j Sep 23, 2025
ccaa206
added examples
rsill-neo4j Sep 24, 2025
beca803
Apply suggestions from code review
rsill-neo4j Sep 24, 2025
a7595ad
Merge branch 'dev' into document-temporal-parsing
rsill-neo4j Oct 2, 2025
f20d685
review suggestions
rsill-neo4j Oct 3, 2025
61269d0
Merge branch 'dev' into document-temporal-parsing
rsill-neo4j Oct 6, 2025
8856b01
Update modules/ROOT/pages/deprecations-additions-removals-compatibili…
rsill-neo4j Oct 7, 2025
6cad915
review suggestions
rsill-neo4j Oct 7, 2025
42bcf67
added a missing T
rsill-neo4j Oct 8, 2025
434314d
Merge branch 'dev' into document-temporal-parsing
rsill-neo4j Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
13 changes: 9 additions & 4 deletions modules/ROOT/pages/functions/temporal/duration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,11 @@ 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*
.3+| *Arguments* | *Name* | *Type* | *Description*
| `input` | `ANY` | 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`
|===

Expand All @@ -33,6 +34,7 @@ See also xref::values-and-types/temporal.adoc[Temporal values] and xref::express
| The values of the parameters may be arbitrarily large.
| The values of the parameters may be negative.
| The xref:values-and-types/temporal.adoc#cypher-temporal-accessing-components-durations[components of `DURATION` objects] are individually accessible.
| The `pattern` parameter is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-duration-types-characters[Allowed characters for duration types].
Copy link
Contributor

@Lojjs Lojjs Oct 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we want to call it 'pattern argument' rather than 'pattern parameter', as in the table above it is referred to as an argument? If you decide to change this, it also applies to other parts of the PR.

A few of the bullet points above mentions parameter, but they seem to be about the values of the map/the numeric parts of the string in the input argument. It is not really part of this PR but I also feel like that use of the world parameter is also a bit confusing for a user, maybe 'component' would be better (that is what we call it in Example 1)?

Copy link
Contributor Author

@rsill-neo4j rsill-neo4j Oct 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

changing to 'argument' to be consistent with the table(s). also accepting 'component' to make this clearer.

thanks for noticing 👍


|===

Expand Down Expand Up @@ -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
----
Expand All @@ -101,7 +104,8 @@ RETURN aDuration
| P22DT19H51M49.5S
| PT45S
| P2012Y2M2DT14H37M21.545S
1+d|Rows: 5
| P5H6M
Copy link
Contributor

@JoelBergstrand JoelBergstrand Oct 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| P5H6M
| PT5H6M

1+d|Rows: 6

|===

Expand All @@ -128,6 +132,7 @@ RETURN aDuration
| If `from` has a time component and `to` does not, the time component of `to` is assumed to be midnight, and vice versa.
| If `from` has a time zone component and `to` does not, the time zone component of `to` is assumed to be the same as that of `from`, and vice versa.
| If `to` has a date component and `from` does not, the date component of `from` is assumed to be the same as that of `to`, and vice versa.
| The `pattern` parameter follows the link:https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter].
Copy link
Contributor

@Lojjs Lojjs Oct 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this really be under duration.between() and not in the other bullet point list under duration()?

Copy link
Contributor Author

@rsill-neo4j rsill-neo4j Oct 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

copy-paste error i think :) removed it


|===

Expand Down
61 changes: 41 additions & 20 deletions modules/ROOT/pages/functions/temporal/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
|===
Expand Down Expand Up @@ -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` parameter is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-instance-types-characters[Allowed characters for instance types].

|===

Expand Down Expand Up @@ -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
----
Expand All @@ -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

|===

Expand Down Expand Up @@ -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`
|===

Expand Down Expand Up @@ -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` parameter is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-instance-types-characters[Allowed characters for instance types].

|===

Expand Down Expand Up @@ -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
----
Expand All @@ -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

|===

Expand Down Expand Up @@ -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`
|===

Expand Down Expand Up @@ -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` parameter is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-instance-types-characters[Allowed characters for instance types].

|===

Expand Down Expand Up @@ -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
----
Expand All @@ -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

|===

Expand Down Expand Up @@ -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`
|===

Expand Down Expand Up @@ -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` parameter is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-instance-types-characters[Allowed characters for instance types].

|===

Expand Down Expand Up @@ -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
----
Expand All @@ -2334,7 +2350,8 @@ RETURN theTime
| 21:40:32.142
| 21:40
| 21:00
1+d|Rows: 4
| 06:04
1+d|Rows: 5

|===

Expand Down Expand Up @@ -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`
|===

Expand Down Expand Up @@ -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` parameter is constructed from xref:functions/temporal/format.adoc#query-functions-temporal-format-instance-types-characters[Allowed characters for instance types].

|===

Expand Down Expand Up @@ -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
----
Expand All @@ -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

|===

Expand Down