diff --git a/mage/query-modules/python/date.md b/mage/query-modules/python/date.md new file mode 100644 index 00000000000..8f33731b08e --- /dev/null +++ b/mage/query-modules/python/date.md @@ -0,0 +1,143 @@ +--- +id: date +title: date +sidebar_label: date +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import RunOnSubgraph from '../../templates/_run_on_subgraph.mdx'; + +export const Highlight = ({children, color}) => ( + +{children} + +); + +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. + +[![docs-source](https://img.shields.io/badge/source-date-FB6E00?logo=github&style=for-the-badge)](https://github.com/memgraph/mage/tree/main/python/date.py) + +| Trait | Value | +| ------------------- | ----------------------------------------------------- | +| **Module type** | **algorithm** | +| **Implementation** | **C++** | +| **Graph direction** | **directed**/**undirected** | +| **Edge weights** | **weighted**/**unweighted** | +| **Parallelism** | **sequential** | + +### Procedures + +### `format(time, unit, format, timezone)` + +Returns a string representation of time value using the specified unit, specified format, and specified time zone. + +#### Input: + +- `time: int` ➡ time passed since the Unix epoch. +- `unit: str (default="ms")` ➡ unit of the given time. +- `format: str (default="%Y-%m-%d %H:%M:%S %Z")` ➡ pattern to be formatted to. +- `timezone: str (default="UTC")` ➡ timezone to be used. + +:::info + +The unit parameter supports the following values: +- "ms" for milliseconds +- "s" for seconds +- "m" for minutes +- "h" for hours +- "d" for days + +::: + +:::info + +The format parameter supports values defined under [Python strftime format codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes). + +::: + +:::info + +The timezone parameter can be specified with the database TZ identifier (text) name, as listed for [timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). + +::: + +#### Output: + +- `formatted: str` ➡ received time in the specified format. + +#### Usage: + +```cypher +CALL date.format(74976, "h", "%Y/%m/%d %H:%M:%S %Z", "Mexico/BajaNorte") +YIELD formatted RETURN formatted; +``` + +```plaintext ++-------------------------------+ +| formatted | ++-------------------------------+ +| "1978/07/21 17:00:00 PDT" | ++-------------------------------+ +``` + + +### `parse(time, unit, format, timezone)` + +Parses the date string using the specified format and specified timezone into the specified time unit. + +#### Input: + +- `time: str` ➡ a datetime. +- `unit: str (default="ms")` ➡ unit to be parsed to. +- `format: str (default="%Y-%m-%d %H:%M:%S")` ➡ format of the given DateTime. +- `timezone: str (default="UTC")` ➡ timezone to be used. + +:::info + +The unit parameter supports the following values: +- "ms" for milliseconds +- "s" for seconds +- "m" for minutes +- "h" for hours +- "d" for days + +::: + +:::info + +The format parameter supports values defined under [Python strftime format codes](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes). + +::: + +:::info + +The timezone parameter can be specified with the database TZ identifier (text) name, as listed for [timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). + +::: + +#### Output: + +- `parsed: int` ➡ number of time units that have elapsed since the Unix epoch. + +#### Usage: + +```cypher +CALL date.parse("2023/08/03 14:30:00", "h", "%Y/%m/%d %H:%M:%S", "Europe/Zagreb") +YIELD parsed RETURN parsed; +``` + +```plaintext ++---------------------+ +| parsed | ++---------------------+ +| 469740 | ++---------------------+ +``` + diff --git a/mage/templates/_mage_spells.mdx b/mage/templates/_mage_spells.mdx index 83634d4a33b..6410d941190 100644 --- a/mage/templates/_mage_spells.mdx +++ b/mage/templates/_mage_spells.mdx @@ -9,6 +9,7 @@ | [collections](/mage/query-modules/cpp/collections) | C++ | The collections module is a collection manipulation module that offers functions to work with lists in Cypher queries, allowing operations like filtering, sorting, and modification for efficient data handling. | | [community_detection](/mage/query-modules/cpp/community-detection) | C++ | The Louvain method for community detection is a greedy method for finding communities with maximum modularity in a graph. Runs in _O_(*n*log*n*) time. | | [cycles](/mage/query-modules/cpp/cycles) | C++ | Algorithm for detecting cycles on graphs. | +| [date](/mage/query-modules/python/date) | Python | A module that provides various utilities to handle date and time operations within the Cypher Query Language. | | [distance_calculator](/mage/query-modules/cpp/distance-calculator) | C++ | Module for finding the geographical distance between two points defined with 'lng' and 'lat' coordinates. | | [degree_centrality](/mage/query-modules/cpp/degree-centrality) | C++ | The basic measurement of centrality that refers to the number of edges adjacent to a node. | | [graph_coloring](/mage/query-modules/python/graph-coloring) | Python | Algorithm for assigning labels to the graph elements subject to certain constraints. In this form, it is a way of coloring the graph vertices such that no two adjacent vertices are of the same color. | diff --git a/sidebars/sidebarsMAGE.js b/sidebars/sidebarsMAGE.js index 3d940c7c061..72781b4703b 100644 --- a/sidebars/sidebarsMAGE.js +++ b/sidebars/sidebarsMAGE.js @@ -33,6 +33,7 @@ module.exports = { "query-modules/cpp/conditional-execution", "query-modules/cpp/cycles", "query-modules/cuda/cugraph", + "query-modules/python/date", "query-modules/cpp/degree-centrality", "query-modules/cpp/distance-calculator", "query-modules/python/elasticsearch-synchronization",