diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index 38315b153..1779cdcb4 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/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/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index bc6ccdf1a..dc042e559 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/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('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 +---- + +| 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]] diff --git a/modules/ROOT/pages/functions/index.adoc b/modules/ROOT/pages/functions/index.adoc index a72524852..d24012d48 100644 --- a/modules/ROOT/pages/functions/index.adoc +++ b/modules/ROOT/pages/functions/index.adoc @@ -764,6 +764,23 @@ Values of the xref::values-and-types/temporal.adoc[temporal types] -- `DATE`, `Z |=== +[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: + +[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 new file mode 100644 index 000000000..d7d7d4999 --- /dev/null +++ b/modules/ROOT/pages/functions/temporal/format.adoc @@ -0,0 +1,339 @@ +:description: Information about Cypher's function to format temporal instance and duration values. +:table-caption!: + +[[query-functions-temporal-format]] += Temporal functions - format + +[role=label--cypher-25-only label--new-Neo4j-2025.09] +[[query-functions-temporal-format-function]] +== format() + +The `format()` function creates dynamically formatted string representations of temporal instance and duration types. + +.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` +|=== + +.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 + +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. + + +[[query-functions-temporal-format-instance-types-examples]] +=== Examples + +.Instance formatting, US American and European dates +====== + +.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* 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 to determine the specifics of a duration. + + +[[query-functions-temporal-format-duration-types-examples]] +=== Examples + +.Duration formatting, years converted to quarters +====== + +.Query +// tag::functions_format_duration_type[] +[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 +---- +// end::functions_format_duration_type[] + +.Result +[role="queryresult",options="header,footer",cols="2*