date

The date module provides various utilities to handle date and time operations within the Cypher Query Language. These functions can be used in conjunction with other Cypher expressions to handle date-related tasks such as formatting, parsing, comparisons, and arithmetic, thus enhancing the capabilities of Memgraph for managing time-based data.

Procedures

format()

Returns a string representation of time value using the specified unit, specified format, and specified timezone.

Input:

• time: int ➡ Time passed since the Unix epoch.
• unit: string (default="ms") ➡ The unit of the given time.
• format: string (default="%Y-%m-%d %H:%M:%S %Z") ➡ The pattern to be formatted to.
• timezone: string (default="UTC") ➡ The timezone to be used.

The unit parameter supports the following values:

• "ms" for milliseconds
• "s" for seconds
• "m" for minutes
• "h" for hours
• "d" for days

The format parameter supports values defined under Python strftime format codes (opens in a new tab).

The timezone parameter can be specified with the database TZ identifier (text) name, as listed for timezones (opens in a new tab).

Output:

• formatted: string ➡ The received time in the specified format.

Usage:

Use the following query to get a string representation from a time value:

CALL date.format(74976, "h", "%Y/%m/%d %H:%M:%S %Z", "Mexico/BajaNorte") 
YIELD formatted RETURN formatted;

+-------------------------------+
| formatted                     |
+-------------------------------+
| "1978/07/21 17:00:00 PDT"     |
+-------------------------------+

parse()

Parses the date string using the specified format and specified timezone into the specified time unit.

Input:

• time: string ➡ A datetime.
• unit: string (default="ms") ➡ The unit to be parsed to.
• format: string (default="%Y-%m-%d %H:%M:%S") ➡ The format of the given DateTime.
• timezone: string (default="UTC") ➡ The timezone to be used.

The unit parameter supports the following values:

• "ms" for milliseconds
• "s" for seconds
• "m" for minutes
• "h" for hours
• "d" for days

The format parameter supports values defined under Python strftime format codes (opens in a new tab).

The timezone parameter can be specified with the database TZ identifier (text) name, as listed for timezones (opens in a new tab).

Output:

• parsed: int ➡ The number of time units that have elapsed since the Unix epoch.

Usage:

Use the following query to parse the date string:

CALL date.parse("2023/08/03 14:30:00", "h", "%Y/%m/%d %H:%M:%S", "Europe/Zagreb") 
YIELD parsed RETURN parsed;

+---------------------+
| parsed              |
+---------------------+
| 469740              |
+---------------------+

add()

Adds two numeric values representing quantities of time in specific units.

Input:

• time: int ➡ The first term in the addition operation.
• unit: string ➡ The time unit of the above value.
• add_value: int ➡ The second term in the addition operation.
• add_unit: string ➡ The time unit of the above value.

The unit parameter supports the following values:

• "ms", "milli", "millis" and "milliseconds" for milliseconds
• "s", "second" and "seconds" for seconds
• "m", "minute" and "minutes" for minutes
• "h", "hour" and "hours" for hours
• "d", "day" and "days" for days

Output:

The output of this function is an int value representing the total time expressed in the time unit of the first parameter.

Usage:

RETURN date.add(100, "day", 24, "h") AS sum;

+---------------------+
| sum                 |
+---------------------+
| 101                 |
+---------------------+