Document format function

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[]
 

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

@@ -32,6 +32,17 @@ For more information, see xref:queries/select-version.adoc[].
 | Feature
 | Details
 
+a|
+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
+----
+
+| 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[]
 label:new[]
@@ -40,6 +51,7 @@ New operator: `LockNodes`
 
 
 a| Introduced xref::planning-and-tuning/operators/operators-detail.adoc#query-plan-lock-nodes[`LockNodes`] operator, sometimes used in conjunction with the `LockingMerge` operator to lock nodes.
+
 |===
 
 [[cypher-deprecations-additions-removals-2025.08]]

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

@@ -0,0 +1,332 @@
+: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
+
+[[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.
+
+.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`
+|===
+
+[[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].
+
+Use the characters in xref:#query-functions-temporal-format-instance-types-characters[] to create a string pattern for instance types.
+
+
+[[query-functions-temporal-format-instance-types-examples]]
+=== Examples
+
+.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, "MM/dd/yyyy") AS EU, format(dt, "dd/MM/yyyy") AS US
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+
+| EU            | US
+| "11/18/1986" | "18/11/1986"
+2+d|Rows: 1
+
+|===
+
+======
+
+.Instance 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 instanceString
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+
+| instanceString
+| "Tuesday, November 18, AD 1986"
+1+d|Rows: 1
+
+|===
+
+Four occurrences of `E` and `M` (text presentations) output the full form of the day and month.
+
+======
+
+.Instance formatting with day-of-year and localized day-of-week
+======
+
+.Query
+[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
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+
+| instanceString
+| "322th day of the year, 3rd day of the week"
+1+d|Rows: 1
+
+|===
+
+======
+
+.Instance formatting with clock-hour-of-day (1-24), minute-of-hour and time-zone name
+======
+
+.Query
+[source, cypher, indent=0]
+----
+WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
+RETURN format(dt, "k:mm z") AS CET, format(dt, "K:mm O") AS GMT
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+
+| CET          | GMT
+| "6:04 CET" | "6:04 GMT+1"
+2+d|Rows: 1
+
+|===
+
+======
+
+.Instance formatting with month-of-year, day-of-month, milli-of-day, minute-of-hour and second-of-minute
+======
+
+.Query
+[source, cypher, indent=0]
+----
+WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
+RETURN format(dt, "LLL d,' minute 'm', second 's', millisecond of the day 'A") AS instanceString
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+
+| instanceString
+| "Nov 18, minute 4, second 45, millisecond of the day 21885123"
+1+d|Rows: 1
+
+|===
+
+Three occurrences of `L` (number/text presentation) output the short form ("Nov").
+
+======
+
+.Instance formatting with pad next and week-based-year
+======
+
+.Query
+[source, cypher, indent=0]
+----
+WITH datetime('1986-11-18T6:04:45.123456789+01:00[Europe/Berlin]') AS dt
+RETURN format(dt, "pppYY") AS instanceString
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+
+| instanceString
+| " 86"
+1+d|Rows: 1
+
+|===
+
+The three occurrences of `p` add one space character of padding to the two digit form output by two occurrences of `Y`.
+
+======
+
+
+[[query-functions-temporal-format-instance-types-characters]]
+=== String pattern characters
+
+[#instance-character-table]
+.Allowed characters for instance type string patterns
+[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      | 
+|===
+
+.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/javase/8/docs/api/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
+
+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.
+
+
+[[query-functions-temporal-format-duration-types-examples]]
+=== Examples
+
+.Duration formatting, years converted to quarters
+======
+
+.Query
+[source, cypher, indent=0]
+----
+WITH duration({years: 1, months: 4}) AS d
+RETURN format(d, "y 'years' q 'quarters' M 'months'") AS withYears, format(d, "q 'quarters' M 'months'") AS withoutYears
+
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+
+| withYears                     | withoutYears
+| "1 years 1 quarters 1 months" | "5 quarters 1 months"
+2+d|Rows: 1
+
+|===
+======
+
+.Duration formatting, weeks converted to days
+======
+
+.Query
+[source, cypher, indent=0]
+----
+WITH duration({weeks: 3, days: 4}) AS d
+RETURN format(d, "w 'weeks' d 'days'") AS withWeeks, format(d, "d 'days'") AS withoutWeeks
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+
+| withWeeks                     | withoutWeeks
+| "3 weeks 4 days"              | "25 days"
+2+d|Rows: 1
+
+|===
+
+======
+
+.Duration formatting with 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 
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+
+| withMinutes             | withoutMinutes
+| "306 minutes 7 seconds" | "18367 seconds"
+2+d|Rows: 1
+
+|===
+
+Not how the days cannot be converted to hours and do not affect the query result.
+
+======
+
+
+[[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
+|===