From 2d4b1c343220a889b1a3eee3913a8b009439ee2c Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Wed, 27 Aug 2025 19:15:06 +0200 Subject: [PATCH 01/25] WiP format function --- modules/ROOT/content-nav.adoc | 1 + ...ions-additions-removals-compatibility.adoc | 22 +++ .../ROOT/pages/functions/temporal/format.adoc | 142 ++++++++++++++++++ .../ROOT/pages/values-and-types/temporal.adoc | 49 ++++++ 4 files changed, 214 insertions(+) create mode 100644 modules/ROOT/pages/functions/temporal/format.adoc diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index ebe74336d..04cee20bd 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -100,6 +100,7 @@ ** xref:functions/string.adoc[] ** xref:functions/temporal/duration.adoc[] ** xref:functions/temporal/index.adoc[] +** xref:functions/temporal/format.adoc[] ** xref:functions/user-defined.adoc[] ** xref:functions/vector.adoc[] diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index a8188c351..dd958ffdb 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -22,6 +22,28 @@ 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.09]] +== Neo4j 2025.09 + +=== New in Cypher 25 + +[cols="2", options="header"] +|=== +| Feature +| Details + +a| +label:functionality[] +label:new[] +[source, cypher, role="noheader"] +---- +format() +---- + +| Format function xref:functions/temporal/format.adoc[]. +|=== + + [[cypher-deprecations-additions-removals-2025.08]] == Neo4j 2025.08 diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc new file mode 100644 index 000000000..685e8bb91 --- /dev/null +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -0,0 +1,142 @@ +:description: Cypher provides a function for creating dynamically formatted string representations of temporal instance and duration types. +:table-caption!: + +[[query-functions-temporal-format]] += Temporal functions - format + +The format function creates dynamically formatted string representations of temporal instance and duration types. +The output format can be customized via the `pattern` parameter. +If no pattern is specified, the function returns an ISO-formatted string. + +== format() + +.Details +|=== +| *Syntax* 3+| `format(value[, pattern])` +| *Description* 3+| Returns the temporal value as an ISO-formatted string or as a string formatted by the provided pattern. +.3+| *Arguments* | *Name* | *Type* | *Description* + | `value` | `DATE \| LOCAL TIME \| ZONED TIME \| LOCAL DATETIME \| ZONED DATETIME \| DURATION` | A temporal value to be formatted. + | `pattern` | `STRING` | A pattern used to format the temporal value. If the pattern is not provided the value will be formatted according to ISO 8601. +| *Returns* 3+| `STRING` +|=== + + +=== Instance types + +For instance types, the characters in table <<#character-table>> can be used to create a string pattern. +n be repeated to change their output. + +[#character-table] +.Allowed characters for an instance type string pattern +[options="header"] +|=== +| Character | Meaning | Presentation | Examples +| `G` | era | text | AD; Anno Domini; A +| `u` | year | year | 2004; 04 +| `y` | year-of-era | year | 2004; 04 +| `D` | day-of-year | number | 189 +| `M` / `L` | month-of-year | number/text | 7; 07; Jul; July; J +| `d` | day-of-month | number | 10 +| `g` | modified-julian-day | number | 2451334 +| `Q` / `q` | quarter-of-year | number/text | 3; 03; Q3; 3rd quarter +| `Y` | week-based-year | year | 1996; 96 +| `w` | week-of-week-based-year | number | 27 +| `W` | week-of-month | number | 4 +| `E` | day-of-week | text | Tue; Tuesday; T +| `e` / `c` | localized day-of-week | number/text | 2; 02; Tue; Tuesday; T +| `F` | aligned-week-of-month | number | 3 +| `a` | am-pm-of-day | text | PM +| `B` | period-of-day | text | in the morning +| `h` | clock-hour-of-am-pm (1-12) | number | 12 +| `K` | hour-of-am-pm (0-11) | number | 0 +| `k` | clock-hour-of-day (1-24) | number | 24 +| `H` | hour-of-day (0-23) | number | 0 +| `m` | minute-of-hour | number | 30 +| `s` | second-of-minute | number | 55 +| `S` | fraction-of-second | fraction | 978 +| `A` | milli-of-day | number | 1234 +| `n` | nano-of-second | number | 987654321 +| `N` | nano-of-day | number | 1234000000 +| `V` | time-zone ID | zone-id | America/Los_Angeles; Z; -08:30 +| `v` | generic time-zone name | zone-name | Pacific Time; PT +| `z` | time-zone name | zone-name | Pacific Standard Time; PST +| `O` | localized zone-offset | offset-O | GMT+8; GMT+08:00; UTC-08:00 +| `X` | zone-offset 'Z' for zero | offset-X | Z; -08; -0830; -08:30; -083015; -08:30:15 +| `x` | zone-offset | offset-x | +0000; -08; -0830; -08:30; -083015; -08:30:15 +| `Z` | zone-offset | offset-Z | +0000; -0800; -08:00 +| `p` | pad next | pad modifier | 1 +| `"` | escape for text | delimiter | +| `'` | single quote | literal | +| `[` | optional section start | | +| `]` | optional section end | | +|=== + +.Considerations +|=== + +| Some characters cannot be applied to certain types, for instance, `u` cannot be used to construct a string for a `LOCAL TIME` because it represents a year which is not part of the temporal value. + +| The "text" style is determined by how often the pattern character is repeated: less than 4 characters result in the short form ("AD"). Exactly 4 characters result in the full form ("Anno Domini"). Exactly 5 characters result in the narrow form ("A"). + +The characters 'L', 'q', and 'c' represent the standalone form of the text styles. + +| A single "number" character outputs the minimum number of digits without padding. With more "number" characters, the number of digits is used as the width of the output field, with the value zero-padded as necessary. + +The following characters have constraints on the count of letters: + +Only one letter of 'c' and 'F' can be specified. + +Up to two letters of 'd', 'H', 'h', 'K', 'k', 'm', and 's' can be specified. + +Up to three letters of 'D' can be specified. + +| If the number of characters in a "number/text" is 3 or greater, use the text rules, otherwise the number rules. + +| 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. + +| 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. + +| 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. + +| A "zone-name" outputs the display name of the timezone ID. + +If the pattern character is 'z', the output is the daylight saving time (DST) zone name. If there is insufficient information to determine whether DST applies, the name ignoring daylight saving time will be used.One, two or three characters output the short name, four characters output the full name, and five or more result in an error. + +If the character is 'v', the output provides the zone name ignoring daylight saving time. +One 'v' outputs the short name, two three and five result in an error, and four 'v's output the full name. + +| 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'. + +| 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. + +| 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. + +| 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. + +| 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. + +|=== + +.+duration()+ using duration components +====== + +.Query +[source, cypher, indent=0] +---- +WITH datetime('2024-06-27T14:30:45.123456789+02:00[Europe/Paris]') AS dt +RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x +---- + +.Result +[role="queryresult",options="header,footer",cols="1* Date: Thu, 28 Aug 2025 16:29:37 +0200 Subject: [PATCH 02/25] general structure, additions page entry, references --- ...ions-additions-removals-compatibility.adoc | 5 +- .../ROOT/pages/functions/temporal/format.adoc | 108 ++++++++++++++++-- .../ROOT/pages/values-and-types/temporal.adoc | 88 +++++++------- 3 files changed, 144 insertions(+), 57 deletions(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index dd958ffdb..657f47d1a 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -37,10 +37,11 @@ label:functionality[] label:new[] [source, cypher, role="noheader"] ---- -format() +WITH datetime('2024-06-27T14:30:45.123456789+02:00[Europe/Paris]') AS dt +RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x ---- -| Format function xref:functions/temporal/format.adoc[]. +| Cypher's new xref:functions/temporal/format.adoc[format function] can create dynamically formatted string representations of temporal instance and duration types. |=== diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 685e8bb91..873dc9348 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -20,13 +20,15 @@ If no pattern is specified, the function returns an ISO-formatted string. | *Returns* 3+| `STRING` |=== - +[[query-functions-temporal-format-instance-types]] === Instance types -For instance types, the characters in table <<#character-table>> can be used to create a string pattern. -n be repeated to change their output. +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]. + +Use the characters in table <<#instance-character-table>> to create a string pattern for instance types. +Most characters change yield a different output when they are repeated. -[#character-table] +[#instance-character-table] .Allowed characters for an instance type string pattern [options="header"] |=== @@ -94,9 +96,13 @@ Up to three letters of 'D' can be specified. | 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. -| 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. +| The "year" characters determine the minimum field width below which padding is used. + +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. -| 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. +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. + +| A "zone-id" outputs the timezone ID. Two characters output the timezone ID, other amounts result in an error. | A "zone-name" outputs the display name of the timezone ID. @@ -105,19 +111,48 @@ If the pattern character is 'z', the output is the daylight saving time (DST) zo If the character is 'v', the output provides the zone name ignoring daylight saving time. One 'v' outputs the short name, two three and five result in an error, and four 'v's output the full name. -| 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'. +| "offset-X" and "offset-x" format the offset based on the number of pattern characters. +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'. + +Two characters output the hour and minute, without a colon, such as '+0130'. + +Three characters output 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 result in an error. + +An upper case 'X' outputs 'Z' if the offset would be zero, whereas a lowwer case 'x' outputs '+00', '+0000', or '+00:00'. + +| With a non-zero offset, "offset-O" formats the localized offset based on the number of characters. + +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'. -| 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. +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'. -| 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. +If the offset is zero, only localized text is output. + +Other character amounts result in an error. + +| "offset-Z" formats the offset based on the number of characters. + +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'. + +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. + +Five characters output the hour, minute, with optional second if non-zero, with colon. If the offset is zero, the output is 'Z'. + +More characters will result in an error. | 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. -| 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. +| 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. |=== -.+duration()+ using duration components +.awesome example ====== .Query @@ -139,4 +174,53 @@ RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x ====== -=== Duration types \ No newline at end of file +[[query-functions-temporal-format-duration-types]] +=== Duration types + +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]. + +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". +This is because without a reference point, there is no way of determining the specifics of a duration. +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. + +Use the characters in table <> to create a string pattern for duration types. + +[#duration-character-table] +.Allowed characters for a duration type string pattern +[options="header"] +|=== +| Component Group | Characters | Field +| Months | y/Y/u | Years +| | q/Q | Quarters +| | M/L | Months +| Days | w/W | Weeks +| | d/D | Days +| Seconds | h/H/k/K | Hours +| | m | Minutes +| | s | Seconds +| | n/S | Fraction of Second +| | A | Milliseconds +| | N | Nanoseconds +|=== + +.awesome example +====== + +.Query +[source, cypher, indent=0] +---- +WITH datetime('2024-06-27T14:30:45.123456789+02:00[Europe/Paris]') AS dt +RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x +---- + +.Result +[role="queryresult",options="header,footer",cols="1* Date: Thu, 28 Aug 2025 17:54:12 +0200 Subject: [PATCH 03/25] examples for instance types --- .../ROOT/pages/functions/temporal/format.adoc | 214 +++++++++++++++++- 1 file changed, 209 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 873dc9348..3c5e051a8 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -78,9 +78,9 @@ Most characters change yield a different output when they are repeated. | Some characters cannot be applied to certain types, for instance, `u` cannot be used to construct a string for a `LOCAL TIME` because it represents a year which is not part of the temporal value. -| The "text" style is determined by how often the pattern character is repeated: less than 4 characters result in the short form ("AD"). Exactly 4 characters result in the full form ("Anno Domini"). Exactly 5 characters result in the narrow form ("A"). +| The "text" presentation is determined by how often the pattern character is repeated: less than 4 characters result in the short form ("AD"). Exactly 4 characters result in the full form ("Anno Domini"). Exactly 5 characters result in the narrow form ("A"). -The characters 'L', 'q', and 'c' represent the standalone form of the text styles. +The characters 'L', 'q', and 'c' represent the standalone form of the text presentation. | A single "number" character outputs the minimum number of digits without padding. With more "number" characters, the number of digits is used as the width of the output field, with the value zero-padded as necessary. @@ -152,13 +152,13 @@ More characters will result in an error. |=== -.awesome example +.Formatting with year, month, day, hour, minute, second, fraction-of-second and zone-offset ====== .Query [source, cypher, indent=0] ---- -WITH datetime('2024-06-27T14:30:45.123456789+02:00[Europe/Paris]') AS dt +WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x ---- @@ -167,13 +167,217 @@ RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x |=== | x -| "2024-06-27T14:30:45.123+0200" +| "1986-11-18T06:04:45.123+0100" +1+d|Rows: 1 + +|=== + +====== + +.Formatting with day-of-week, month-of-year, day-of-month, era and year +====== + +.Query +[source, cypher, indent=0] +---- +WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt +RETURN format(dt, "EEEE, MMMM d, G uuuu") AS x +---- + +.Result +[role="queryresult",options="header,footer",cols="1* Date: Thu, 28 Aug 2025 17:56:56 +0200 Subject: [PATCH 04/25] added a block title --- modules/ROOT/pages/functions/temporal/format.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 3c5e051a8..26c7c638a 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -354,7 +354,7 @@ RETURN format(dt, "QQQQ' of 'yyyy") AS x ====== -. +.Formatting with pad next and week-based-year ====== .Query From 81a5bf50483ad4e12965abe39788984bc189b649 Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Thu, 28 Aug 2025 18:14:54 +0200 Subject: [PATCH 05/25] examples for duration types --- .../ROOT/pages/functions/temporal/format.adoc | 143 ++++++++++++++---- .../ROOT/pages/values-and-types/temporal.adoc | 11 +- 2 files changed, 120 insertions(+), 34 deletions(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 26c7c638a..559e3de21 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -152,7 +152,7 @@ More characters will result in an error. |=== -.Formatting with year, month, day, hour, minute, second, fraction-of-second and zone-offset +.Instance formatting with year, month, day, hour, minute, second, fraction-of-second and zone-offset ====== .Query @@ -174,7 +174,7 @@ RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x ====== -.Formatting with day-of-week, month-of-year, day-of-month, era and year +.Instance formatting with day-of-week, month-of-year, day-of-month, era and year ====== .Query @@ -198,7 +198,7 @@ Four occurrences of `E` and `M` (text presentations) output the full form of the ====== -.Formatting with day-of-year and localized day-of-week +.Instance formatting with day-of-year and localized day-of-week ====== .Query @@ -220,7 +220,7 @@ RETURN format(dt, "DDD'th day of the year,' c'rd day of the week'") AS x ====== -.Formatting with day-of-year and localized day-of-week +.Instance formatting with day-of-year and localized day-of-week ====== .Query @@ -242,7 +242,7 @@ RETURN format(dt, "DDD'th day of the year,' c'rd day of the week'") AS x ====== -.Formatting with clock-hour-of-day (1-24), minute-of-hour and time-zone name +.Instance formatting with clock-hour-of-day (1-24), minute-of-hour and time-zone name ====== .Query @@ -264,7 +264,7 @@ RETURN format(dt, "k:mm z") AS x ====== -.Formatting with hour-of-am-pm (0-11), minute-of-hour and localized zone-offset +.Instance formatting with hour-of-am-pm (0-11), minute-of-hour and localized zone-offset ====== .Query @@ -286,7 +286,7 @@ RETURN format(dt, "K:mm O") AS x ====== -.Formatting with month-of-year, day-of-month, milli-of-day, minute-of-hour and second-of-minute +.Instance formatting with month-of-year, day-of-month, milli-of-day, minute-of-hour and second-of-minute ====== .Query @@ -310,7 +310,7 @@ Three occurrences of `L` (number/text presentation) output the short form ("Nov" ====== -.Formatting with nano-of-second and nano-of-day +.Instance formatting with nano-of-second and nano-of-day ====== .Query @@ -332,7 +332,7 @@ RETURN format(dt, "'Nano of second: 'n', nano of day: 'N") AS x ====== -.Formatting with quarter-of-year and year-of-era +.Instance formatting with quarter-of-year and year-of-era ====== .Query @@ -354,7 +354,7 @@ RETURN format(dt, "QQQQ' of 'yyyy") AS x ====== -.Formatting with pad next and week-based-year +.Instance formatting with pad next and week-based-year ====== .Query @@ -393,28 +393,115 @@ Use the characters in table <> to create a string patt .Allowed characters for a duration type string pattern [options="header"] |=== -| Component Group | Characters | Field -| Months | y/Y/u | Years -| | q/Q | Quarters -| | M/L | Months -| Days | w/W | Weeks -| | d/D | Days -| Seconds | h/H/k/K | Hours -| | m | Minutes -| | s | Seconds -| | n/S | Fraction of Second -| | A | Milliseconds -| | N | Nanoseconds -|=== - -.awesome example +| Component Group | Characters | Presentation +| Months | y/Y/u | years +| | q/Q | quarters +| | M/L | months +| Days | w/W | weeks +| | d/D | days +| Seconds | h/H/k/K | hours +| | m | minutes +| | s | seconds +| | n/S | fraction-of-second +| | A | milliseconds +| | N | nanoseconds +|=== + +.Duration formatting ====== .Query [source, cypher, indent=0] ---- -WITH datetime('2024-06-27T14:30:45.123456789+02:00[Europe/Paris]') AS dt -RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x +WITH duration({years: 1, months: 4, weeks: 3, days: 4, hours: 5, minutes: 6, seconds: 7, milliseconds: 8, microseconds: 9, nanoseconds: 10}) AS d +RETURN format(d, "y 'years' q 'quarters' M 'months' w 'weeks' d 'days' h 'hours' m 'minutes' s 'seconds' N 'nanos'") AS x +---- + +.Result +[role="queryresult",options="header,footer",cols="1* Date: Fri, 29 Aug 2025 09:46:06 +0200 Subject: [PATCH 06/25] clarification for duration conversions --- modules/ROOT/pages/functions/temporal/format.adoc | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 559e3de21..78c35dea9 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -381,12 +381,6 @@ The three occurrences of `p` add one space character of padding to the two digit [[query-functions-temporal-format-duration-types]] === Duration types -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]. - -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". -This is because without a reference point, there is no way of determining the specifics of a duration. -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. - Use the characters in table <> to create a string pattern for duration types. [#duration-character-table] @@ -407,6 +401,11 @@ Use the characters in table <> to create a string patt | | N | nanoseconds |=== +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]. +If the string pattern contains a character from a component group but does not contain a character denoting a longer duration from the same group, `format()` converts the longer duration to the equivalent duration with the character that is present, for example a missing `y` (year) will be converted to four quarters, if `q` is present in the string pattern. +This is because without a reference point, there is no way of determining the specifics of a duration. +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. + .Duration formatting ====== From 2cbca9a68fa62233f15a0ce5998f716138836cf4 Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Tue, 2 Sep 2025 13:56:44 +0200 Subject: [PATCH 07/25] nicer considerations block --- .../ROOT/pages/functions/temporal/format.adoc | 133 ++++++++++-------- 1 file changed, 72 insertions(+), 61 deletions(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 78c35dea9..94f84ae72 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -74,83 +74,94 @@ Most characters change yield a different output when they are repeated. |=== .Considerations -|=== - -| Some characters cannot be applied to certain types, for instance, `u` cannot be used to construct a string for a `LOCAL TIME` because it represents a year which is not part of the temporal value. - -| The "text" presentation is determined by how often the pattern character is repeated: less than 4 characters result in the short form ("AD"). Exactly 4 characters result in the full form ("Anno Domini"). Exactly 5 characters result in the narrow form ("A"). +[caption=""] +====== -The characters 'L', 'q', and 'c' represent the standalone form of the text presentation. +* Some characters cannot be applied to certain types, for instance, `u` cannot be used to construct a string for a `LOCAL TIME` because it represents a year which is not part of the temporal value. -| A single "number" character outputs the minimum number of digits without padding. With more "number" characters, the number of digits is used as the width of the output field, with the value zero-padded as necessary. +* The **text** presentation is determined by how often the pattern character is repeated: less than 4 characters result in the short form ("AD"). Exactly 4 characters result in the full form ("Anno Domini"). Exactly 5 characters result in the narrow form ("A"). ++ +The characters `L`, `q`, and `c` represent the standalone form of the text presentation. +* A single **number** character outputs the minimum number of digits without padding. With more **number** characters, the number of digits is used as the width of the output field, with the value zero-padded as necessary. ++ The following characters have constraints on the count of letters: ++ +Only a single `c` or `F` can be specified. ++ +Up to two `d`, `H`, `h`, `K`, `k`, `m`, and `s` can be specified. ++ +Up to three `D` can be specified. -Only one letter of 'c' and 'F' can be specified. - -Up to two letters of 'd', 'H', 'h', 'K', 'k', 'm', and 's' can be specified. - -Up to three letters of 'D' can be specified. - -| If the number of characters in a "number/text" is 3 or greater, use the text rules, otherwise the number rules. - -| 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. +* If the number of characters in a **number/text** is three or greater, use the text rules, otherwise the number rules. -| The "year" characters determine the minimum field width below which padding is used. +* 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. +* The **year** characters determine the minimum field width below which padding is used. ++ 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. - ++ 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. -| A "zone-id" outputs the timezone ID. Two characters output the timezone ID, other amounts result in an error. - -| A "zone-name" outputs the display name of the timezone ID. - -If the pattern character is 'z', the output is the daylight saving time (DST) zone name. If there is insufficient information to determine whether DST applies, the name ignoring daylight saving time will be used.One, two or three characters output the short name, four characters output the full name, and five or more result in an error. - -If the character is 'v', the output provides the zone name ignoring daylight saving time. -One 'v' outputs the short name, two three and five result in an error, and four 'v's output the full name. - -| "offset-X" and "offset-x" format the offset based on the number of pattern characters. -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'. - -Two characters output the hour and minute, without a colon, such as '+0130'. - -Three characters output 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 result in an error. - -An upper case 'X' outputs 'Z' if the offset would be zero, whereas a lowwer case 'x' outputs '+00', '+0000', or '+00:00'. - -| With a non-zero offset, "offset-O" formats the localized offset based on the number of characters. - -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'. - -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'. - -If the offset is zero, only localized text is output. - +* A **zone-id** outputs the timezone ID. Two characters output the timezone ID, other amounts result in an error. + +* A **zone-name** outputs the display name of the timezone ID. ++ +If the pattern character is `z`, the output is the daylight saving time (DST) zone name. +If there is insufficient information to determine whether DST applies, the name ignoring daylight saving time will be used. ++ +One, two or three characters output the short name, four characters output the full name, and five or more result in an error. ++ +If the character is `v`, the output provides the zone name ignoring daylight saving time. +One `v` outputs the short name, two three and five result in an error, and four `v` output the full name. + +* **offset-X** and **offset-x** format the offset based on the number of pattern characters. +One character outputs just the hour, like `+01`, unless the minute is non-zero. +In that case, the minute is also output, like `+0130`. ++ +Two characters output the hour and minute, without a colon, like `+0130`. ++ +Three characters output the hour and minute, with a colon, like `+01:30`. ++ +Four characters output the hour and minute and optional second, without a colon, like `+013015`. ++ +Five characters output the hour and minute and optional second, with a colon, like `+01:30:15`. ++ +Six or more characters result in an error. ++ +An upper case `X` outputs `Z` if the offset is zero, whereas a lower case `x` outputs `+00`, `+0000`, or `+00:00`. + +* With a non-zero offset, **offset-O** formats the localized offset based on the number of characters. ++ +One character outputs the short form of the localized offset, which is the localized offset text, like `GMT`. +It is 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`. ++ +Four characters output the full form, which is a localized offset text with a 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 the localized text is output. ++ Other character amounts result in an error. -| "offset-Z" formats the offset based on the number of characters. - -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'. - -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. - -Five characters output the hour, minute, with optional second if non-zero, with colon. If the offset is zero, the output is 'Z'. - +* **offset-Z** formats the offset based on the number of characters. ++ +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`. ++ +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. ++ +Five characters output the hour, minute, with optional second if non-zero, with colon. If the offset is zero, the output is `Z`. ++ More characters will result in an error. -| 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. +* 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. -| 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. +* Any character that is not reserved, other than `[`, `]`, `{`, `}`, `#`, and `'` are output directly. +To ensure future compatibility it is recommended to wrap all characters that you want to output directly with single quotes. -|=== +====== .Instance formatting with year, month, day, hour, minute, second, fraction-of-second and zone-offset ====== From f1f9c6c1ff5f36cb5e4cc0ba51a1e7303e3d5dec Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Tue, 2 Sep 2025 14:33:31 +0200 Subject: [PATCH 08/25] nicer character table for durations --- .../ROOT/pages/functions/temporal/format.adoc | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 94f84ae72..576d4d9ca 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -398,18 +398,18 @@ Use the characters in table <> to create a string patt .Allowed characters for a duration type string pattern [options="header"] |=== -| Component Group | Characters | Presentation -| Months | y/Y/u | years -| | q/Q | quarters -| | M/L | months -| Days | w/W | weeks -| | d/D | days -| Seconds | h/H/k/K | hours -| | m | minutes -| | s | seconds -| | n/S | fraction-of-second -| | A | milliseconds -| | N | nanoseconds +| Component Group | Characters | Presentation +.3+| Months | `y` / `Y`/ `u` | years + | `q` / `Q` | quarters + | `M` / `L` | months +.2+| Days | `w` / `W` | weeks + | `d` / `D` | days +.6+| Seconds | `h` / `H` / `k` / `K` | hours + | `m` | minutes + | `s` | seconds + | `n` / `S` | fraction-of-second + | `A` | milliseconds + | `N` | nanoseconds |=== 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]. From b7609879d576d7e10746d4aef38655a2c37cd387 Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Wed, 3 Sep 2025 14:33:08 +0200 Subject: [PATCH 09/25] reduced number of examples, reduced 'considerations' list, moved characters tables, added more headings --- .../ROOT/pages/functions/temporal/format.adoc | 339 ++++++------------ 1 file changed, 104 insertions(+), 235 deletions(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 576d4d9ca..63a7c92b3 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -4,12 +4,14 @@ [[query-functions-temporal-format]] = Temporal functions - format +[[query-functions-temporal-format-function]] +== format() + The format function creates dynamically formatted string representations of temporal instance and duration types. The output format can be customized via the `pattern` parameter. +Creating a pattern follows the rules for the link:https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter]. If no pattern is specified, the function returns an ISO-formatted string. -== format() - .Details |=== | *Syntax* 3+| `format(value[, pattern])` @@ -21,147 +23,15 @@ If no pattern is specified, the function returns an ISO-formatted string. |=== [[query-functions-temporal-format-instance-types]] -=== Instance types +== Instance types 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]. -Use the characters in table <<#instance-character-table>> to create a string pattern for instance types. -Most characters change yield a different output when they are repeated. - -[#instance-character-table] -.Allowed characters for an instance type string pattern -[options="header"] -|=== -| Character | Meaning | Presentation | Examples -| `G` | era | text | AD; Anno Domini; A -| `u` | year | year | 2004; 04 -| `y` | year-of-era | year | 2004; 04 -| `D` | day-of-year | number | 189 -| `M` / `L` | month-of-year | number/text | 7; 07; Jul; July; J -| `d` | day-of-month | number | 10 -| `g` | modified-julian-day | number | 2451334 -| `Q` / `q` | quarter-of-year | number/text | 3; 03; Q3; 3rd quarter -| `Y` | week-based-year | year | 1996; 96 -| `w` | week-of-week-based-year | number | 27 -| `W` | week-of-month | number | 4 -| `E` | day-of-week | text | Tue; Tuesday; T -| `e` / `c` | localized day-of-week | number/text | 2; 02; Tue; Tuesday; T -| `F` | aligned-week-of-month | number | 3 -| `a` | am-pm-of-day | text | PM -| `B` | period-of-day | text | in the morning -| `h` | clock-hour-of-am-pm (1-12) | number | 12 -| `K` | hour-of-am-pm (0-11) | number | 0 -| `k` | clock-hour-of-day (1-24) | number | 24 -| `H` | hour-of-day (0-23) | number | 0 -| `m` | minute-of-hour | number | 30 -| `s` | second-of-minute | number | 55 -| `S` | fraction-of-second | fraction | 978 -| `A` | milli-of-day | number | 1234 -| `n` | nano-of-second | number | 987654321 -| `N` | nano-of-day | number | 1234000000 -| `V` | time-zone ID | zone-id | America/Los_Angeles; Z; -08:30 -| `v` | generic time-zone name | zone-name | Pacific Time; PT -| `z` | time-zone name | zone-name | Pacific Standard Time; PST -| `O` | localized zone-offset | offset-O | GMT+8; GMT+08:00; UTC-08:00 -| `X` | zone-offset 'Z' for zero | offset-X | Z; -08; -0830; -08:30; -083015; -08:30:15 -| `x` | zone-offset | offset-x | +0000; -08; -0830; -08:30; -083015; -08:30:15 -| `Z` | zone-offset | offset-Z | +0000; -0800; -08:00 -| `p` | pad next | pad modifier | 1 -| `"` | escape for text | delimiter | -| `'` | single quote | literal | -| `[` | optional section start | | -| `]` | optional section end | | -|=== - -.Considerations -[caption=""] -====== +Use the characters in xref:#query-functions-temporal-format-instance-types-characters[] to create a string pattern for instance types. -* Some characters cannot be applied to certain types, for instance, `u` cannot be used to construct a string for a `LOCAL TIME` because it represents a year which is not part of the temporal value. - -* The **text** presentation is determined by how often the pattern character is repeated: less than 4 characters result in the short form ("AD"). Exactly 4 characters result in the full form ("Anno Domini"). Exactly 5 characters result in the narrow form ("A"). -+ -The characters `L`, `q`, and `c` represent the standalone form of the text presentation. - -* A single **number** character outputs the minimum number of digits without padding. With more **number** characters, the number of digits is used as the width of the output field, with the value zero-padded as necessary. -+ -The following characters have constraints on the count of letters: -+ -Only a single `c` or `F` can be specified. -+ -Up to two `d`, `H`, `h`, `K`, `k`, `m`, and `s` can be specified. -+ -Up to three `D` can be specified. - -* If the number of characters in a **number/text** is three or greater, use the text rules, otherwise the number rules. - -* 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. - -* The **year** characters determine the minimum field width below which padding is used. -+ -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. -+ -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. - -* A **zone-id** outputs the timezone ID. Two characters output the timezone ID, other amounts result in an error. - -* A **zone-name** outputs the display name of the timezone ID. -+ -If the pattern character is `z`, the output is the daylight saving time (DST) zone name. -If there is insufficient information to determine whether DST applies, the name ignoring daylight saving time will be used. -+ -One, two or three characters output the short name, four characters output the full name, and five or more result in an error. -+ -If the character is `v`, the output provides the zone name ignoring daylight saving time. -One `v` outputs the short name, two three and five result in an error, and four `v` output the full name. - -* **offset-X** and **offset-x** format the offset based on the number of pattern characters. -One character outputs just the hour, like `+01`, unless the minute is non-zero. -In that case, the minute is also output, like `+0130`. -+ -Two characters output the hour and minute, without a colon, like `+0130`. -+ -Three characters output the hour and minute, with a colon, like `+01:30`. -+ -Four characters output the hour and minute and optional second, without a colon, like `+013015`. -+ -Five characters output the hour and minute and optional second, with a colon, like `+01:30:15`. -+ -Six or more characters result in an error. -+ -An upper case `X` outputs `Z` if the offset is zero, whereas a lower case `x` outputs `+00`, `+0000`, or `+00:00`. - -* With a non-zero offset, **offset-O** formats the localized offset based on the number of characters. -+ -One character outputs the short form of the localized offset, which is the localized offset text, like `GMT`. -It is 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`. -+ -Four characters output the full form, which is a localized offset text with a 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 the localized text is output. -+ -Other character amounts result in an error. - -* **offset-Z** formats the offset based on the number of characters. -+ -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`. -+ -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. -+ -Five characters output the hour, minute, with optional second if non-zero, with colon. If the offset is zero, the output is `Z`. -+ -More characters will result in an error. - -* 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. - -* Any character that is not reserved, other than `[`, `]`, `{`, `}`, `#`, and `'` are output directly. -To ensure future compatibility it is recommended to wrap all characters that you want to output directly with single quotes. -====== +[[query-functions-temporal-format-instance-types-examples]] +=== Examples .Instance formatting with year, month, day, hour, minute, second, fraction-of-second and zone-offset ====== @@ -185,38 +55,36 @@ RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x ====== -.Instance formatting with day-of-week, month-of-year, day-of-month, era and year +.Instance formatting, European and US American dates ====== .Query [source, cypher, indent=0] ---- WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt -RETURN format(dt, "EEEE, MMMM d, G uuuu") AS x +RETURN format(dt, "MM/dd/yyyy") AS EU, format(dt, "dd/MM/yyyy") AS US ---- .Result [role="queryresult",options="header,footer",cols="1*> to create a string pattern for duration types. - -[#duration-character-table] -.Allowed characters for a duration type string pattern -[options="header"] -|=== -| Component Group | Characters | Presentation -.3+| Months | `y` / `Y`/ `u` | years - | `q` / `Q` | quarters - | `M` / `L` | months -.2+| Days | `w` / `W` | weeks - | `d` / `D` | days -.6+| Seconds | `h` / `H` / `k` / `K` | hours - | `m` | minutes - | `s` | seconds - | `n` / `S` | fraction-of-second - | `A` | milliseconds - | `N` | nanoseconds -|=== +Use the characters in xref:#query-functions-temporal-format-duration-types-characters[] to create a string pattern for duration types. 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]. + If the string pattern contains a character from a component group but does not contain a character denoting a longer duration from the same group, `format()` converts the longer duration to the equivalent duration with the character that is present, for example a missing `y` (year) will be converted to four quarters, if `q` is present in the string pattern. This is because without a reference point, there is no way of determining the specifics of a duration. + 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. +[[query-functions-temporal-format-duration-types-examples]] +=== Examples + .Duration formatting ====== @@ -524,4 +371,26 @@ RETURN format(d, "s 'seconds' n 'millis'") AS x |=== -====== \ No newline at end of file +====== + + +[[query-functions-temporal-format-duration-types-characters]] +=== String pattern characters + +[#duration-character-table] +.Allowed characters for a duration type string pattern +[options="header"] +|=== +| Component Group | Characters | Presentation +.3+| Months | `y` / `Y`/ `u` | years + | `q` / `Q` | quarters + | `M` / `L` | months +.2+| Days | `w` / `W` | weeks + | `d` / `D` | days +.6+| Seconds | `h` / `H` / `k` / `K` | hours + | `m` | minutes + | `s` | seconds + | `n` / `S` | fraction-of-second + | `A` | milliseconds + | `N` | nanoseconds +|=== \ No newline at end of file From 935e5a7c3d95beb09df12df3dbc5da97102f6769 Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Wed, 3 Sep 2025 15:28:14 +0200 Subject: [PATCH 10/25] improved examples --- .../ROOT/pages/functions/temporal/format.adoc | 90 +++++-------------- package-lock.json | 1 + 2 files changed, 24 insertions(+), 67 deletions(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 63a7c92b3..cc7bad9a5 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -66,12 +66,12 @@ RETURN format(dt, "MM/dd/yyyy") AS EU, format(dt, "dd/MM/yyyy") AS US ---- .Result -[role="queryresult",options="header,footer",cols="1* Date: Thu, 4 Sep 2025 16:46:05 +0200 Subject: [PATCH 11/25] review suggestions --- .../ROOT/pages/functions/temporal/format.adoc | 53 ++++++------------- .../ROOT/pages/values-and-types/temporal.adoc | 10 ++-- 2 files changed, 22 insertions(+), 41 deletions(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index cc7bad9a5..10d308df9 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -33,28 +33,6 @@ Use the characters in xref:#query-functions-temporal-format-instance-types-chara [[query-functions-temporal-format-instance-types-examples]] === Examples -.Instance formatting with year, month, day, hour, minute, second, fraction-of-second and zone-offset -====== - -.Query -[source, cypher, indent=0] ----- -WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt -RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x ----- - -.Result -[role="queryresult",options="header,footer",cols="1* Date: Fri, 5 Sep 2025 14:59:05 +0200 Subject: [PATCH 12/25] review suggestion --- modules/ROOT/pages/functions/temporal/format.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 10d308df9..b6a6a8ecb 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -237,7 +237,6 @@ Cypher's duration type `DURATION` has components and component groups, see xref: If the string pattern contains a character from a component group but does not contain a character denoting a longer duration from the same group, `format()` converts the longer duration to the equivalent duration with the character that is present, for example a missing `y` (year) will be converted to four quarters, if `q` is present in the string pattern. This is because without a reference point, there is no way of determining the specifics of a duration. -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. [[query-functions-temporal-format-duration-types-examples]] === Examples From 93e85bcc6f7e29c9981c1550a3f349fb2cab97be Mon Sep 17 00:00:00 2001 From: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com> Date: Mon, 8 Sep 2025 14:02:13 +0200 Subject: [PATCH 13/25] Update modules/ROOT/pages/functions/temporal/format.adoc Co-authored-by: Gem Lamont <106068376+gem-neo4j@users.noreply.github.com> --- modules/ROOT/pages/functions/temporal/format.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index b6a6a8ecb..6d21123a9 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -305,7 +305,7 @@ RETURN format(d, "m 'minutes' s 'seconds'") AS withMinutes, format(d, "s 'second |=== -Not how the days cannot be converted to hours and do not affect the query result. +Note how the days cannot be converted to hours and do not affect the query result. ====== From 7b991471413fcec328905ebdafd66f27e8c3d884 Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Mon, 8 Sep 2025 14:07:56 +0200 Subject: [PATCH 14/25] review suggestions --- modules/ROOT/pages/functions/temporal/format.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 6d21123a9..b1dc7cdc2 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -9,13 +9,13 @@ The format function creates dynamically formatted string representations of temporal instance and duration types. The output format can be customized via the `pattern` parameter. -Creating a pattern follows the rules for the link:https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter]. +Creating a pattern follows the rules for the link:https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter]. If no pattern is specified, the function returns an ISO-formatted string. .Details |=== | *Syntax* 3+| `format(value[, pattern])` -| *Description* 3+| Returns the temporal value as an ISO-formatted string or as a string formatted by the provided pattern. +| *Description* 3+| Returns the temporal value as an ISO-formatted `STRING` or as a `STRING` formatted by the provided pattern. .3+| *Arguments* | *Name* | *Type* | *Description* | `value` | `DATE \| LOCAL TIME \| ZONED TIME \| LOCAL DATETIME \| ZONED DATETIME \| DURATION` | A temporal value to be formatted. | `pattern` | `STRING` | A pattern used to format the temporal value. If the pattern is not provided the value will be formatted according to ISO 8601. @@ -222,7 +222,7 @@ The three occurrences of `p` add one space character of padding to the two digit |=== | Most characters yield a different output when they are repeated. | Some characters cannot be applied to certain types, for instance, `u` cannot be used to construct a string for a `LOCAL TIME` because it represents a year which is not part of the temporal value. -| For details, refer to the documentation of the link:https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter]. +| For details, refer to the documentation of the link:https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter]. | Any character that is not reserved, other than `[`, `]`, `{`, `}`, `#`, and `'`, are output directly. To ensure future compatibility it is recommended to wrap all characters that you want to output directly with single quotes. |=== From ef697e49ce39d0d3ab073d20a611051b283eb8be Mon Sep 17 00:00:00 2001 From: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com> Date: Wed, 10 Sep 2025 10:45:25 +0200 Subject: [PATCH 15/25] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jens Pryce-Åklundh <112686610+JPryce-Aklundh@users.noreply.github.com> --- ...ations-additions-removals-compatibility.adoc | 2 +- .../ROOT/pages/functions/temporal/format.adoc | 17 ++++++++++------- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 0a1660722..edd16197f 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -41,7 +41,7 @@ WITH datetime('2024-06-27T14:30:45.123456789+02:00[Europe/Paris]') AS dt RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x ---- -| Cypher's new xref:functions/temporal/format.adoc[format function] can create dynamically formatted string representations of temporal instance and duration types. +| Cypher's new xref:functions/temporal/format.adoc[`format()]` function can create dynamically formatted string representations of temporal instance and duration types. a| label:functionality[] diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index b1dc7cdc2..ed5528977 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -1,4 +1,4 @@ -:description: Cypher provides a function for creating dynamically formatted string representations of temporal instance and duration types. +:description: Information about Cypher's function to format temporal instance and duration values. :table-caption!: [[query-functions-temporal-format]] @@ -7,9 +7,9 @@ [[query-functions-temporal-format-function]] == format() -The format function creates dynamically formatted string representations of temporal instance and duration types. +The `format()` function creates dynamically formatted string representations of temporal instance and duration types. The output format can be customized via the `pattern` parameter. -Creating a pattern follows the rules for the link:https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter]. +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]. If no pattern is specified, the function returns an ISO-formatted string. .Details @@ -25,7 +25,8 @@ If no pattern is specified, the function returns an ISO-formatted string. [[query-functions-temporal-format-instance-types]] == Instance types -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]. +Cypher's instance types are `DATE`, `LOCAL TIME`, `ZONED TIME`, `LOCAL DATETIME` and `ZONED DATETIME`. +For more information, see xref:/values-and-types/temporal.adoc#cypher-temporal-instants[Values and types -> temporal instants]. Use the characters in xref:#query-functions-temporal-format-instance-types-characters[] to create a string pattern for instance types. @@ -232,10 +233,12 @@ The three occurrences of `p` add one space character of padding to the two digit Use the characters in xref:#query-functions-temporal-format-duration-types-characters[] to create a string pattern for duration types. -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]. +Cypher's duration type `DURATION` has components and component groups. +For more information, see see xref:values-and-types/temporal.adoc#cypher-temporal-accessing-components-durations[Values and types -> components of durations]. -If the string pattern contains a character from a component group but does not contain a character denoting a longer duration from the same group, `format()` converts the longer duration to the equivalent duration with the character that is present, for example a missing `y` (year) will be converted to four quarters, if `q` is present in the string pattern. -This is because without a reference point, there is no way of determining the specifics of a duration. +If the string pattern contains a character from a component group but does not contain a character denoting a longer duration from the same group, `format()` converts the longer duration to the equivalent duration with the character that is present. +For example a missing `y` (year) will be converted to four quarters, if `q` is present in the string pattern. +This is because without a reference point, there is no way to determine the specifics of a duration. [[query-functions-temporal-format-duration-types-examples]] From b7d6eb26ce0a41e5fe31448b986b978e20af9e8d Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Wed, 10 Sep 2025 11:16:47 +0200 Subject: [PATCH 16/25] review suggestions --- .../gql-conformance/additional-cypher.adoc | 14 ++++++++ .../ROOT/pages/functions/temporal/format.adoc | 32 +++++++++---------- 2 files changed, 30 insertions(+), 16 deletions(-) diff --git a/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc b/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc index a30d4fbbd..f50145571 100644 --- a/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc +++ b/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc @@ -542,6 +542,20 @@ If the points are in a Cartesian CRS, the function returns the Euclidean distanc |=== +[[temporal-format-functions]] +=== Temporal format functions + +[options="header", cols="2a,5a"] +|=== +| Cypher feature +| Description + +| xref:functions/temporal/format.adoc[`format()`] +| Returns the temporal value as an ISO-formatted `STRING` or as a `STRING` formatted by the provided pattern. + +|=== + + [[vector-functions]] === Vector functions diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index ed5528977..d4795f5b0 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -8,9 +8,6 @@ == format() The `format()` function creates dynamically formatted string representations of temporal instance and duration types. -The output format can be customized via the `pattern` parameter. -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]. -If no pattern is specified, the function returns an ISO-formatted string. .Details |=== @@ -22,6 +19,16 @@ If no pattern is specified, the function returns an ISO-formatted string. | *Returns* 3+| `STRING` |=== +.Considerations +|=== +| The output format can be customized via the `pattern` parameter. +| 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]. +| If no pattern is specified, the function returns an ISO-formatted string. +| Most characters yield a different output when they are repeated. +| Some characters cannot be applied to certain types, for instance, `u` cannot be used to construct a string for a `LOCAL TIME` because it represents a year which is not part of the temporal value. +| Any character that is not reserved, other than `[`, `]`, `{`, `}`, `#`, and `'`, are output directly. To ensure future compatibility it is recommended to wrap all characters that you want to output directly with single quotes. +|=== + [[query-functions-temporal-format-instance-types]] == Instance types @@ -219,14 +226,6 @@ The three occurrences of `p` add one space character of padding to the two digit | `'` | single quote | literal | |=== -.Considerations -|=== -| Most characters yield a different output when they are repeated. -| Some characters cannot be applied to certain types, for instance, `u` cannot be used to construct a string for a `LOCAL TIME` because it represents a year which is not part of the temporal value. -| For details, refer to the documentation of the link:https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/format/DateTimeFormatter.html[Java DateTimeFormatter]. -| Any character that is not reserved, other than `[`, `]`, `{`, `}`, `#`, and `'`, are output directly. To ensure future compatibility it is recommended to wrap all characters that you want to output directly with single quotes. -|=== - [[query-functions-temporal-format-duration-types]] == Duration types @@ -288,27 +287,28 @@ RETURN format(d, "w 'weeks' d 'days'") AS withWeeks, format(d, "d 'days'") AS wi ====== -.Duration formatting with hours converted to minutes +.Duration formatting, hours converted to minutes ====== .Query [source, cypher, indent=0] ---- WITH duration({days: 4, hours: 5, minutes: 6, seconds: 7}) AS d -RETURN format(d, "m 'minutes' s 'seconds'") AS withMinutes, format(d, "s 'seconds'") AS withoutMinutes +RETURN format(d, "h 'hours' m 'minutes'") AS withHours, format(d, "m 'minutes'") AS withoutHours ---- .Result [role="queryresult",options="header,footer",cols="2* Date: Wed, 10 Sep 2025 11:59:11 +0200 Subject: [PATCH 17/25] replaced the additions page example query --- .../pages/deprecations-additions-removals-compatibility.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index edd16197f..a9909c13a 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -37,8 +37,8 @@ label:functionality[] label:new[] [source, cypher, role="noheader"] ---- -WITH datetime('2024-06-27T14:30:45.123456789+02:00[Europe/Paris]') AS dt -RETURN format(dt, "yyyy-MM-dd'T'HH:mm:ss.SSSZ") AS x +WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt +RETURN format(dt, "MM/dd/yyyy") AS EU, format(dt, "dd/MM/yyyy") AS US ---- | Cypher's new xref:functions/temporal/format.adoc[`format()]` function can create dynamically formatted string representations of temporal instance and duration types. From 34579f22fb251c3ebe613438590886b5d383405c Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Wed, 10 Sep 2025 12:06:44 +0200 Subject: [PATCH 18/25] syntax fix --- .../pages/deprecations-additions-removals-compatibility.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index a9909c13a..52c1b0a43 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -41,7 +41,7 @@ WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt RETURN format(dt, "MM/dd/yyyy") AS EU, format(dt, "dd/MM/yyyy") AS US ---- -| Cypher's new xref:functions/temporal/format.adoc[`format()]` function can create dynamically formatted string representations of temporal instance and duration types. +| Cypher's new xref:functions/temporal/format.adoc[`format()`] function can create dynamically formatted string representations of temporal instance and duration types. a| label:functionality[] From 118abe6dc5523f13733d99c6cc240b12573d84cf Mon Sep 17 00:00:00 2001 From: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com> Date: Thu, 11 Sep 2025 09:47:11 +0200 Subject: [PATCH 19/25] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jens Pryce-Åklundh <112686610+JPryce-Aklundh@users.noreply.github.com> --- modules/ROOT/pages/functions/temporal/format.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index d4795f5b0..3acef3190 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -4,10 +4,11 @@ [[query-functions-temporal-format]] = Temporal functions - format +Cypher's `format()` function function creates dynamically formatted string representations of temporal instance and duration types. +[role=label--new-Neo4j-2025.09 label--cypher-25-only] [[query-functions-temporal-format-function]] == format() -The `format()` function creates dynamically formatted string representations of temporal instance and duration types. .Details |=== From e4bc6f837bd1d580b84a2dc9304669c6d7e7180f Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Thu, 11 Sep 2025 10:47:08 +0200 Subject: [PATCH 20/25] review suggestions --- modules/ROOT/pages/functions/index.adoc | 18 +++++++++++++++++- .../ROOT/pages/functions/temporal/format.adoc | 7 +++---- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/functions/index.adoc b/modules/ROOT/pages/functions/index.adoc index a72524852..b2562ea44 100644 --- a/modules/ROOT/pages/functions/index.adoc +++ b/modules/ROOT/pages/functions/index.adoc @@ -207,7 +207,7 @@ LOAD CSV functions can be used to get information about the file that is process |=== -[[header-query-functions-logarithmic]] +[[header-query-functions-logarithmic]]label:new[Introduced in Neo4j 2025.09] label:cypher[Cypher 25 only] == Logarithmic functions These functions all operate on numerical expressions only, and will return an error if used on any other values. @@ -764,6 +764,22 @@ Values of the xref::values-and-types/temporal.adoc[temporal types] -- `DATE`, `Z |=== +[[header-query-functions-temporal-format]]label:new[Introduced in Neo4j 2025.09] label:cypher[Cypher 25 only] +== Temporal format functions + +These functions format temporal instance and duration values: + +[options="header"] +|=== +| Function | Signature | Description + +1.1+| xref::functions/temporal/format.adoc#query-functions-temporal-format-function[`format()`] +| `format(value :: DATE \| LOCAL TIME \| ZONED TIME \| LOCAL DATETIME \| ZONED DATETIME \| DURATION[, pattern :: STRING]) :: STRING` +| Returns the temporal value as an ISO-formatted `STRING` or as a `STRING` formatted by the provided pattern. + +|=== + + [[header-query-functions-user-defined]] == User-defined functions diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 3acef3190..f267ad937 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -4,11 +4,10 @@ [[query-functions-temporal-format]] = Temporal functions - format -Cypher's `format()` function function creates dynamically formatted string representations of temporal instance and duration types. -[role=label--new-Neo4j-2025.09 label--cypher-25-only] [[query-functions-temporal-format-function]] == format() +The `format()` function creates dynamically formatted string representations of temporal instance and duration types. .Details |=== @@ -95,7 +94,7 @@ Four occurrences of `E` and `M` (text presentations) output the full form of the [source, cypher, indent=0] ---- WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt -RETURN format(dt, "DDD'th day of the year,' c'rd day of the week'") AS instanceString +RETURN format(dt, "DDD'nd day of the year,' c'rd day of the week'") AS instanceString ---- .Result @@ -103,7 +102,7 @@ RETURN format(dt, "DDD'th day of the year,' c'rd day of the week'") AS instanceS |=== | instanceString -| "322th day of the year, 3rd day of the week" +| "322nd day of the year, 3rd day of the week" 1+d|Rows: 1 |=== From e9b8b32bbcbde9b5b2d4d284a6068c6aeba3278f Mon Sep 17 00:00:00 2001 From: Richard Sill Date: Thu, 11 Sep 2025 11:32:57 +0200 Subject: [PATCH 21/25] removed labels from a test section --- modules/ROOT/pages/functions/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/functions/index.adoc b/modules/ROOT/pages/functions/index.adoc index b2562ea44..770753c72 100644 --- a/modules/ROOT/pages/functions/index.adoc +++ b/modules/ROOT/pages/functions/index.adoc @@ -207,7 +207,7 @@ LOAD CSV functions can be used to get information about the file that is process |=== -[[header-query-functions-logarithmic]]label:new[Introduced in Neo4j 2025.09] label:cypher[Cypher 25 only] +[[header-query-functions-logarithmic]] == Logarithmic functions These functions all operate on numerical expressions only, and will return an error if used on any other values. From 66ea4d75ccf2e086ae54a7151648c5771aa97acf Mon Sep 17 00:00:00 2001 From: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com> Date: Thu, 11 Sep 2025 11:35:21 +0200 Subject: [PATCH 22/25] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jens Pryce-Åklundh <112686610+JPryce-Aklundh@users.noreply.github.com> --- modules/ROOT/pages/functions/index.adoc | 3 ++- modules/ROOT/pages/functions/temporal/format.adoc | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/functions/index.adoc b/modules/ROOT/pages/functions/index.adoc index 770753c72..d24012d48 100644 --- a/modules/ROOT/pages/functions/index.adoc +++ b/modules/ROOT/pages/functions/index.adoc @@ -764,7 +764,8 @@ Values of the xref::values-and-types/temporal.adoc[temporal types] -- `DATE`, `Z |=== -[[header-query-functions-temporal-format]]label:new[Introduced in Neo4j 2025.09] label:cypher[Cypher 25 only] +[role=label--cypher-25-only label--new-Neo4j-2025.09] +[[header-query-functions-temporal-format]] == Temporal format functions These functions format temporal instance and duration values: diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index f267ad937..1c60bfa30 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -4,6 +4,7 @@ [[query-functions-temporal-format]] = Temporal functions - format +[role=label--cypher-25-only label--new-Neo4j-2025.09] [[query-functions-temporal-format-function]] == format() From 2d9bea543962a6278b690d19ae9b73f4dc9e1932 Mon Sep 17 00:00:00 2001 From: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com> Date: Fri, 12 Sep 2025 10:16:31 +0200 Subject: [PATCH 23/25] EU <-> US examples --- .../pages/deprecations-additions-removals-compatibility.adoc | 2 +- modules/ROOT/pages/functions/temporal/format.adoc | 4 ++-- modules/ROOT/pages/values-and-types/temporal.adoc | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 52c1b0a43..49af9b419 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -38,7 +38,7 @@ label:new[] [source, cypher, role="noheader"] ---- WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt -RETURN format(dt, "MM/dd/yyyy") AS EU, format(dt, "dd/MM/yyyy") AS US +RETURN format(dt, "MM/dd/yyyy") AS US, format(dt, "dd/MM/yyyy") AS EU ---- | Cypher's new xref:functions/temporal/format.adoc[`format()`] function can create dynamically formatted string representations of temporal instance and duration types. diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 1c60bfa30..907981140 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -49,14 +49,14 @@ Use the characters in xref:#query-functions-temporal-format-instance-types-chara [source, cypher, indent=0] ---- WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt -RETURN format(dt, "MM/dd/yyyy") AS EU, format(dt, "dd/MM/yyyy") AS US +RETURN format(dt, "MM/dd/yyyy") AS US, format(dt, "dd/MM/yyyy") AS EU ---- .Result [role="queryresult",options="header,footer",cols="2* Date: Fri, 12 Sep 2025 16:47:52 +0200 Subject: [PATCH 24/25] added cheat sheet tags --- modules/ROOT/pages/functions/temporal/format.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index 907981140..c500c019c 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -46,11 +46,13 @@ Use the characters in xref:#query-functions-temporal-format-instance-types-chara ====== .Query +// tag::functions_format_instance_type[] [source, cypher, indent=0] ---- WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt RETURN format(dt, "MM/dd/yyyy") AS US, format(dt, "dd/MM/yyyy") AS EU ---- +// end::functions_format_instance_type[] .Result [role="queryresult",options="header,footer",cols="2* Date: Fri, 12 Sep 2025 17:10:25 +0200 Subject: [PATCH 25/25] Apply suggestions from code review --- modules/ROOT/pages/functions/temporal/format.adoc | 2 +- modules/ROOT/pages/values-and-types/temporal.adoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/functions/temporal/format.adoc b/modules/ROOT/pages/functions/temporal/format.adoc index c500c019c..d7d7d4999 100644 --- a/modules/ROOT/pages/functions/temporal/format.adoc +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -42,7 +42,7 @@ Use the characters in xref:#query-functions-temporal-format-instance-types-chara [[query-functions-temporal-format-instance-types-examples]] === Examples -.Instance formatting, European and US American dates +.Instance formatting, US American and European dates ====== .Query diff --git a/modules/ROOT/pages/values-and-types/temporal.adoc b/modules/ROOT/pages/values-and-types/temporal.adoc index a187c9a74..5cc5f3747 100644 --- a/modules/ROOT/pages/values-and-types/temporal.adoc +++ b/modules/ROOT/pages/values-and-types/temporal.adoc @@ -1754,7 +1754,7 @@ Indexes for temporal instant types additionally support range lookups. 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. -.A string representation of an instance type +.String representations of an instance type ====== .Query