Skip to content

Temporal Parse deprecations #843

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 7, 2025
+344 −131
Merged

Temporal Parse deprecations #843

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7877c2f
Temporal Parse deprecations
JoelBergstrand Sep 11, 2025
d9f654b
Updated ArgumentDescriptionsTest
JoelBergstrand Oct 1, 2025
0bf27ed
Removed snapshot dependency
JoelBergstrand Oct 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions core/src/main/java/apoc/date/Date.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,31 @@ public double toYears(
}

@UserFunction("apoc.date.fields")
@QueryLanguageScope(scope = QueryLanguage.CYPHER_5)
@Description("Splits the given date into fields returning a `MAP` containing the values of each field.")
public Map<String, Object> fieldsCypher5(
final @Name(value = "date", description = "A string representation of a temporal value.") String date,
final @Name(
value = "pattern",
defaultValue = DEFAULT_FORMAT,
description = "The format the given temporal is formatted as.") String pattern) {
if (date == null) {
return Util.map();
}
DateTimeFormatter fmt = getSafeDateTimeFormatter(pattern);
TemporalAccessor temporal = fmt.parse(date);
FieldResult result = new FieldResult();

for (final TemporalQuery<Consumer<FieldResult>> query : DT_FIELDS_SELECTORS) {
query.queryFrom(temporal).accept(result);
}

return result.asMap();
}

@Deprecated
@UserFunction(value = "apoc.date.fields", deprecatedBy = "Cypher's temporal pattern constructors.")
Copy link
Contributor

Choose a reason for hiding this comment

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

Cypher's temporal pattern constructors.

An example would be golden here in my opinion, but perhaps that's not how we usually roll (applies to several of the deprecations)?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Not sure, for the format function it mapped nicely has every use of the apoc function used the same cypher signature. With parsing, all types use their respective type constructor so which type should be the example.

@QueryLanguageScope(scope = QueryLanguage.CYPHER_25)
@Description("Splits the given date into fields returning a `MAP` containing the values of each field.")
public Map<String, Object> fields(
final @Name(value = "date", description = "A string representation of a temporal value.") String date,
Expand Down Expand Up @@ -278,6 +303,22 @@ public Long fromISO8601(final @Name(value = "time", description = "The datetime
}

@UserFunction("apoc.date.parse")
@QueryLanguageScope(scope = QueryLanguage.CYPHER_5)
@Description("Parses the given date `STRING` from a specified format into the specified time unit.")
public Long parseCypher5(
@Name(value = "time", description = "The datetime to convert.") String time,
@Name(value = "unit", defaultValue = "ms", description = "The conversion unit.") String unit,
@Name(value = "format", defaultValue = DEFAULT_FORMAT, description = "The format the given datetime is in.")
String format,
final @Name(value = "timezone", defaultValue = "", description = "The timezone the given datetime is in.")
String timezone) {
Long value = StringUtils.isBlank(time) ? null : parseOrThrow(time, getFormat(format, timezone));
return value == null ? null : unit(unit).convert(value, TimeUnit.MILLISECONDS);
}

@Deprecated
@UserFunction(value = "apoc.date.parse", deprecatedBy = "Cypher's temporal pattern constructors.")
@QueryLanguageScope(scope = QueryLanguage.CYPHER_25)
@Description("Parses the given date `STRING` from a specified format into the specified time unit.")
public Long parse(
@Name(value = "time", description = "The datetime to convert.") String time,
Expand Down Expand Up @@ -306,6 +347,32 @@ public Long convert(
}

@UserFunction("apoc.date.convertFormat")
@QueryLanguageScope(scope = QueryLanguage.CYPHER_5)
@Description("Converts a `STRING` of one type of date format into a `STRING` of another type of date format.")
public String convertFormatCypher5(
@Name(value = "temporal", description = "A string representation of a temporal value.") String input,
@Name(value = "currentFormat", description = "The format the given temporal is formatted as.")
String currentFormat,
@Name(
value = "convertTo",
defaultValue = "yyyy-MM-dd",
description = "The format to convert the given temporal value to.")
String convertTo) {
if (input == null || input.isEmpty()) {
return null;
}

DateTimeFormatter currentFormatter = DateFormatUtil.getOrCreate(currentFormat);
DateTimeFormatter convertToFormatter = DateFormatUtil.getOrCreate(convertTo);

return convertToFormatter.format(currentFormatter.parse(input));
}

@Deprecated
@UserFunction(
value = "apoc.date.convertFormat",
deprecatedBy = "Cypher's temporal pattern constructors and format() function.")
@QueryLanguageScope(scope = QueryLanguage.CYPHER_25)
@Description("Converts a `STRING` of one type of date format into a `STRING` of another type of date format.")
public String convertFormat(
@Name(value = "temporal", description = "A string representation of a temporal value.") String input,
Expand Down
15 changes: 15 additions & 0 deletions core/src/main/java/apoc/temporal/TemporalProcedures.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,21 @@ public String formatDuration(
}

@UserFunction("apoc.temporal.toZonedTemporal")
@QueryLanguageScope(scope = QueryLanguage.CYPHER_5)
@Description("Parses the given date `STRING` using the specified format into the given time zone.")
public ZonedDateTime toZonedTemporalCypher5(
@Name(value = "time", description = "The date string to be parsed.") String time,
@Name(value = "format", defaultValue = DEFAULT_FORMAT, description = "The format of the given date string.")
String format,
final @Name(value = "timezone", defaultValue = "UTC", description = "The timezone the given string is in.")
String timezone) {
Long value = parseOrThrow(time, getFormat(format, timezone));
return value == null ? null : Instant.ofEpochMilli(value).atZone(ZoneId.of(timezone));
}

@Deprecated
@UserFunction(value = "apoc.temporal.toZonedTemporal", deprecatedBy = "Cypher's temporal pattern constructors.")
@QueryLanguageScope(scope = QueryLanguage.CYPHER_25)
@Description("Parses the given date `STRING` using the specified format into the given time zone.")
public ZonedDateTime toZonedTemporal(
@Name(value = "time", description = "The date string to be parsed.") String time,
Expand Down
131 changes: 0 additions & 131 deletions core/src/test/resources/functions/common/functions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1675,104 +1675,6 @@
}
]
},
{
"isDeprecated": false,
"aggregating": false,
"signature": "apoc.date.convertFormat(temporal :: STRING, currentFormat :: STRING, convertTo = yyyy-MM-dd :: STRING) :: STRING",
"name": "apoc.date.convertFormat",
"description": "Converts a `STRING` of one type of date format into a `STRING` of another type of date format.",
"returnDescription": "STRING",
"deprecatedBy": null,
"category": "",
"isBuiltIn": false,
"argumentDescription": [
{
"name": "temporal",
"description": "A string representation of a temporal value.",
"isDeprecated": false,
"type": "STRING"
},
{
"name": "currentFormat",
"description": "The format the given temporal is formatted as.",
"isDeprecated": false,
"type": "STRING"
},
{
"name": "convertTo",
"description": "The format to convert the given temporal value to.",
"isDeprecated": false,
"default": "DefaultParameterValue{value=yyyy-MM-dd, type=STRING}",
"type": "STRING"
}
]
},
{
"isDeprecated": false,
"aggregating": false,
"signature": "apoc.date.fields(date :: STRING, pattern = yyyy-MM-dd HH:mm:ss :: STRING) :: MAP",
"name": "apoc.date.fields",
"description": "Splits the given date into fields returning a `MAP` containing the values of each field.",
"returnDescription": "MAP",
"deprecatedBy": null,
"category": "",
"isBuiltIn": false,
"argumentDescription": [
{
"name": "date",
"description": "A string representation of a temporal value.",
"isDeprecated": false,
"type": "STRING"
},
{
"name": "pattern",
"description": "The format the given temporal is formatted as.",
"isDeprecated": false,
"default": "DefaultParameterValue{value=yyyy-MM-dd HH:mm:ss, type=STRING}",
"type": "STRING"
}
]
},
{
"isDeprecated": false,
"aggregating": false,
"signature": "apoc.date.parse(time :: STRING, unit = ms :: STRING, format = yyyy-MM-dd HH:mm:ss :: STRING, timezone = :: STRING) :: INTEGER",
"name": "apoc.date.parse",
"description": "Parses the given date `STRING` from a specified format into the specified time unit.",
"returnDescription": "INTEGER",
"deprecatedBy": null,
"category": "",
"isBuiltIn": false,
"argumentDescription": [
{
"name": "time",
"description": "The datetime to convert.",
"isDeprecated": false,
"type": "STRING"
},
{
"name": "unit",
"description": "The conversion unit.",
"isDeprecated": false,
"default": "DefaultParameterValue{value=ms, type=STRING}",
"type": "STRING"
},
{
"name": "format",
"description": "The format the given datetime is in.",
"isDeprecated": false,
"default": "DefaultParameterValue{value=yyyy-MM-dd HH:mm:ss, type=STRING}",
"type": "STRING"
},
{
"name": "timezone",
"description": "The timezone the given datetime is in.",
"isDeprecated": false,
"default": "DefaultParameterValue{value=, type=STRING}",
"type": "STRING"
}
]
},
{
"isDeprecated": false,
"aggregating": false,
Expand Down Expand Up @@ -3716,39 +3618,6 @@
}
]
},
{
"isDeprecated": false,
"aggregating": false,
"signature": "apoc.temporal.toZonedTemporal(time :: STRING, format = yyyy-MM-dd HH:mm:ss :: STRING, timezone = UTC :: STRING) :: ZONED DATETIME",
"name": "apoc.temporal.toZonedTemporal",
"description": "Parses the given date `STRING` using the specified format into the given time zone.",
"returnDescription": "ZONED DATETIME",
"deprecatedBy": null,
"category": "",
"isBuiltIn": false,
"argumentDescription": [
{
"name": "time",
"description": "The date string to be parsed.",
"isDeprecated": false,
"type": "STRING"
},
{
"name": "format",
"description": "The format of the given date string.",
"isDeprecated": false,
"default": "DefaultParameterValue{value=yyyy-MM-dd HH:mm:ss, type=STRING}",
"type": "STRING"
},
{
"name": "timezone",
"description": "The timezone the given string is in.",
"isDeprecated": false,
"default": "DefaultParameterValue{value=UTC, type=STRING}",
"type": "STRING"
}
]
},
{
"isDeprecated": false,
"aggregating": false,
Expand Down
Loading