flowquery 1.0.35 → 1.0.37

package/flowquery-py/src/parsing/functions/localtime.py

@@ -0,0 +1,57 @@
+"""Local time function."""
+
+from datetime import datetime
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+from .temporal_utils import build_time_object, parse_temporal_arg
+
+
+@FunctionDef({
+    "description": (
+        "Returns a local time value (no timezone). With no arguments returns the current local time. "
+        "Accepts an ISO 8601 time string or a map of components."
+    ),
+    "category": "scalar",
+    "parameters": [
+        {
+            "name": "input",
+            "description": "Optional. An ISO 8601 time string (HH:MM:SS) or a map of components.",
+            "type": "string",
+            "required": False,
+        },
+    ],
+    "output": {
+        "description": "A time object with properties: hour, minute, second, millisecond, formatted",
+        "type": "object",
+    },
+    "examples": [
+        "RETURN localtime() AS now",
+        "RETURN localtime('14:30:00') AS t",
+        "WITH localtime() AS t RETURN t.hour, t.minute",
+    ],
+})
+class LocalTime(Function):
+    """Local time function.
+
+    Returns a local time value (no timezone offset).
+    When called with no arguments, returns the current local time.
+    When called with a string argument, parses it.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("localtime")
+        self._expected_parameter_count = None
+
+    def value(self) -> Any:
+        children = self.get_children()
+        if len(children) > 1:
+            raise ValueError("localtime() accepts at most one argument")
+
+        if len(children) == 1:
+            d = parse_temporal_arg(children[0].value(), "localtime")
+        else:
+            d = datetime.now()
+
+        return build_time_object(d, utc=False)

package/flowquery-py/src/parsing/functions/max_.py

@@ -0,0 +1,49 @@
+"""Max aggregate function."""
+
+from typing import Any
+
+from .aggregate_function import AggregateFunction
+from .function_metadata import FunctionDef
+from .reducer_element import ReducerElement
+
+
+class MaxReducerElement(ReducerElement):
+    """Reducer element for Max aggregate function."""
+
+    def __init__(self) -> None:
+        self._value: Any = None
+
+    @property
+    def value(self) -> Any:
+        return self._value
+
+    @value.setter
+    def value(self, val: Any) -> None:
+        if self._value is None or val > self._value:
+            self._value = val
+
+
+@FunctionDef({
+    "description": "Returns the maximum value across grouped rows",
+    "category": "aggregate",
+    "parameters": [
+        {"name": "value", "description": "Value to compare", "type": "number"}
+    ],
+    "output": {"description": "Maximum value", "type": "number", "example": 10},
+    "examples": ["WITH [3, 1, 2] AS nums UNWIND nums AS n RETURN max(n)"]
+})
+class Max(AggregateFunction):
+    """Max aggregate function.
+
+    Returns the maximum value across grouped rows.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("max")
+        self._expected_parameter_count = 1
+
+    def reduce(self, element: MaxReducerElement) -> None:
+        element.value = self.first_child().value()
+
+    def element(self) -> MaxReducerElement:
+        return MaxReducerElement()

package/flowquery-py/src/parsing/functions/min_.py

@@ -0,0 +1,49 @@
+"""Min aggregate function."""
+
+from typing import Any
+
+from .aggregate_function import AggregateFunction
+from .function_metadata import FunctionDef
+from .reducer_element import ReducerElement
+
+
+class MinReducerElement(ReducerElement):
+    """Reducer element for Min aggregate function."""
+
+    def __init__(self) -> None:
+        self._value: Any = None
+
+    @property
+    def value(self) -> Any:
+        return self._value
+
+    @value.setter
+    def value(self, val: Any) -> None:
+        if self._value is None or val < self._value:
+            self._value = val
+
+
+@FunctionDef({
+    "description": "Returns the minimum value across grouped rows",
+    "category": "aggregate",
+    "parameters": [
+        {"name": "value", "description": "Value to compare", "type": "number"}
+    ],
+    "output": {"description": "Minimum value", "type": "number", "example": 1},
+    "examples": ["WITH [3, 1, 2] AS nums UNWIND nums AS n RETURN min(n)"]
+})
+class Min(AggregateFunction):
+    """Min aggregate function.
+
+    Returns the minimum value across grouped rows.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("min")
+        self._expected_parameter_count = 1
+
+    def reduce(self, element: MinReducerElement) -> None:
+        element.value = self.first_child().value()
+
+    def element(self) -> MinReducerElement:
+        return MinReducerElement()

package/flowquery-py/src/parsing/functions/nodes.py

@@ -0,0 +1,48 @@
+"""Nodes function."""
+
+from typing import Any, List
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Returns all nodes in a path as an array",
+    "category": "scalar",
+    "parameters": [
+        {"name": "path", "description": "A path value returned from a graph pattern match", "type": "array"}
+    ],
+    "output": {
+        "description": "Array of node records", "type": "array",
+        "example": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
+    },
+    "examples": ["MATCH p=(:Person)-[:KNOWS]-(:Person) RETURN nodes(p)"]
+})
+class Nodes(Function):
+    """Nodes function.
+
+    Returns all nodes in a path as an array.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("nodes")
+        self._expected_parameter_count = 1
+
+    def value(self) -> Any:
+        path = self.get_children()[0].value()
+        if path is None:
+            return []
+        if not isinstance(path, list):
+            raise ValueError("nodes() expects a path (array)")
+        # A path is an array of alternating node and relationship objects:
+        # [node, rel, node, rel, node, ...]
+        # Nodes are plain dicts (have 'id' but not all of 'type'/'startNode'/'endNode'/'properties')
+        # Relationships are RelationshipMatchRecords (have 'type', 'startNode', 'endNode', 'properties')
+        result: List[Any] = []
+        for element in path:
+            if element is None or not isinstance(element, dict):
+                continue
+            # A RelationshipMatchRecord has type, startNode, endNode, properties
+            if not all(k in element for k in ("type", "startNode", "endNode", "properties")):
+                result.append(element)
+        return result

package/flowquery-py/src/parsing/functions/properties.py

@@ -0,0 +1,50 @@
+"""Properties function."""
+
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": (
+        "Returns a map containing all the properties of a node, relationship, or map. "
+        "For nodes and relationships, internal identifiers are excluded."
+    ),
+    "category": "scalar",
+    "parameters": [
+        {"name": "entity", "description": "A node, relationship, or map to extract properties from", "type": "object"}
+    ],
+    "output": {"description": "Map of properties", "type": "object", "example": {"name": "Alice", "age": 30}},
+    "examples": [
+        "MATCH (n:Person) RETURN properties(n)",
+        "WITH { name: 'Alice', age: 30 } AS obj RETURN properties(obj)"
+    ]
+})
+class Properties(Function):
+    """Properties function.
+
+    Returns a map containing all the properties of a node, relationship, or map.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("properties")
+        self._expected_parameter_count = 1
+
+    def value(self) -> Any:
+        obj = self.get_children()[0].value()
+        if obj is None:
+            return None
+        if not isinstance(obj, dict):
+            raise ValueError("properties() expects a node, relationship, or map")
+
+        # If it's a RelationshipMatchRecord (has type, startNode, endNode, properties)
+        if all(k in obj for k in ("type", "startNode", "endNode", "properties")):
+            return obj["properties"]
+
+        # If it's a node record (has id field), exclude id
+        if "id" in obj:
+            return {k: v for k, v in obj.items() if k != "id"}
+
+        # Otherwise, treat as a plain map and return a copy
+        return dict(obj)

package/flowquery-py/src/parsing/functions/relationships.py

@@ -0,0 +1,46 @@
+"""Relationships function."""
+
+from typing import Any, List
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Returns all relationships in a path as an array",
+    "category": "scalar",
+    "parameters": [
+        {"name": "path", "description": "A path value returned from a graph pattern match", "type": "array"}
+    ],
+    "output": {
+        "description": "Array of relationship records", "type": "array",
+        "example": [{"type": "KNOWS", "properties": {"since": "2020"}}]
+    },
+    "examples": ["MATCH p=(:Person)-[:KNOWS]-(:Person) RETURN relationships(p)"]
+})
+class Relationships(Function):
+    """Relationships function.
+
+    Returns all relationships in a path as an array.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("relationships")
+        self._expected_parameter_count = 1
+
+    def value(self) -> Any:
+        path = self.get_children()[0].value()
+        if path is None:
+            return []
+        if not isinstance(path, list):
+            raise ValueError("relationships() expects a path (array)")
+        # A path is an array of alternating node and relationship objects:
+        # [node, rel, node, rel, node, ...]
+        # Relationships are RelationshipMatchRecords (have 'type', 'startNode', 'endNode', 'properties')
+        result: List[Any] = []
+        for element in path:
+            if element is None or not isinstance(element, dict):
+                continue
+            if all(k in element for k in ("type", "startNode", "endNode", "properties")):
+                result.append(element)
+        return result

package/flowquery-py/src/parsing/functions/tail.py

@@ -0,0 +1,37 @@
+"""Tail function."""
+
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Returns all elements of a list except the first",
+    "category": "scalar",
+    "parameters": [
+        {"name": "list", "description": "The list to get all but the first element from", "type": "array"}
+    ],
+    "output": {"description": "All elements except the first", "type": "array", "example": [2, 3]},
+    "examples": [
+        "RETURN tail([1, 2, 3])",
+        "WITH ['a', 'b', 'c'] AS items RETURN tail(items)"
+    ]
+})
+class Tail(Function):
+    """Tail function.
+
+    Returns all elements of a list except the first.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("tail")
+        self._expected_parameter_count = 1
+
+    def value(self) -> Any:
+        val = self.get_children()[0].value()
+        if val is None:
+            return None
+        if not isinstance(val, list):
+            raise ValueError("tail() expects a list")
+        return val[1:]

package/flowquery-py/src/parsing/functions/temporal_utils.py

@@ -0,0 +1,186 @@
+"""Shared utility functions for temporal (date/time) operations.
+
+These helpers are used by the datetime_, date_, time_, localdatetime,
+localtime, and timestamp functions.
+"""
+
+from datetime import date, datetime, timezone
+from typing import Any, Dict
+
+
+def iso_day_of_week(d: date) -> int:
+    """Computes the ISO day of the week (1 = Monday, 7 = Sunday)."""
+    return d.isoweekday()
+
+
+def day_of_year(d: date) -> int:
+    """Computes the day of the year (1-based)."""
+    return d.timetuple().tm_yday
+
+
+def quarter(month: int) -> int:
+    """Computes the quarter (1-4) from a month (1-12)."""
+    return (month - 1) // 3 + 1
+
+
+def parse_temporal_arg(arg: Any, fn_name: str) -> datetime:
+    """Parses a temporal argument (string, number, or map) into a datetime object.
+
+    Args:
+        arg: The argument to parse (string, number, or dict with components)
+        fn_name: The calling function name for error messages
+
+    Returns:
+        A datetime object
+    """
+    if isinstance(arg, str):
+        try:
+            return datetime.fromisoformat(arg.replace("Z", "+00:00"))
+        except ValueError:
+            raise ValueError(f"{fn_name}(): Invalid temporal string: '{arg}'")
+
+    if isinstance(arg, (int, float)):
+        # Treat as epoch milliseconds
+        return datetime.fromtimestamp(arg / 1000, tz=timezone.utc)
+
+    if isinstance(arg, dict):
+        # Map-style construction: {year, month, day, hour, minute, second, millisecond}
+        now = datetime.now()
+        year = arg.get("year", now.year)
+        month = arg.get("month", 1)
+        day = arg.get("day", 1)
+        hour = arg.get("hour", 0)
+        minute = arg.get("minute", 0)
+        second = arg.get("second", 0)
+        millisecond = arg.get("millisecond", 0)
+        return datetime(year, month, day, hour, minute, second, millisecond * 1000)
+
+    raise ValueError(
+        f"{fn_name}(): Expected a string, number (epoch millis), or map argument, "
+        f"got {type(arg).__name__}"
+    )
+
+
+def build_datetime_object(d: datetime, utc: bool) -> Dict[str, Any]:
+    """Builds a datetime result object with full temporal properties.
+
+    Args:
+        d: The datetime object
+        utc: If True, use UTC values; if False, use local values
+
+    Returns:
+        A dict with year, month, day, hour, minute, second, millisecond,
+        epochMillis, epochSeconds, dayOfWeek, dayOfYear, quarter, formatted
+    """
+    if utc:
+        if d.tzinfo is None:
+            d = d.replace(tzinfo=timezone.utc)
+        d_utc = d.astimezone(timezone.utc)
+        year = d_utc.year
+        month = d_utc.month
+        day = d_utc.day
+        hour = d_utc.hour
+        minute = d_utc.minute
+        second = d_utc.second
+        millisecond = d_utc.microsecond // 1000
+        formatted = d_utc.strftime("%Y-%m-%dT%H:%M:%S.") + f"{millisecond:03d}Z"
+    else:
+        if d.tzinfo is not None:
+            d = d.astimezone(tz=None).replace(tzinfo=None)
+        year = d.year
+        month = d.month
+        day = d.day
+        hour = d.hour
+        minute = d.minute
+        second = d.second
+        millisecond = d.microsecond // 1000
+        formatted = d.strftime("%Y-%m-%dT%H:%M:%S.") + f"{millisecond:03d}"
+
+    date_part = date(year, month, day)
+    epoch_millis = int(d.timestamp() * 1000) if d.tzinfo else int(
+        datetime(year, month, day, hour, minute, second, millisecond * 1000).timestamp() * 1000
+    )
+
+    return {
+        "year": year,
+        "month": month,
+        "day": day,
+        "hour": hour,
+        "minute": minute,
+        "second": second,
+        "millisecond": millisecond,
+        "epochMillis": epoch_millis,
+        "epochSeconds": epoch_millis // 1000,
+        "dayOfWeek": iso_day_of_week(date_part),
+        "dayOfYear": day_of_year(date_part),
+        "quarter": quarter(month),
+        "formatted": formatted,
+    }
+
+
+def build_date_object(d: datetime) -> Dict[str, Any]:
+    """Builds a date result object (no time component).
+
+    Args:
+        d: The datetime object
+
+    Returns:
+        A dict with year, month, day, epochMillis, dayOfWeek, dayOfYear, quarter, formatted
+    """
+    year = d.year
+    month = d.month
+    day_val = d.day
+
+    date_only = datetime(year, month, day_val)
+    epoch_millis = int(date_only.timestamp() * 1000)
+
+    date_part = date(year, month, day_val)
+
+    return {
+        "year": year,
+        "month": month,
+        "day": day_val,
+        "epochMillis": epoch_millis,
+        "dayOfWeek": iso_day_of_week(date_part),
+        "dayOfYear": day_of_year(date_part),
+        "quarter": quarter(month),
+        "formatted": f"{year}-{month:02d}-{day_val:02d}",
+    }
+
+
+def build_time_object(d: datetime, utc: bool) -> Dict[str, Any]:
+    """Builds a time result object (no date component).
+
+    Args:
+        d: The datetime object
+        utc: If True, use UTC values; if False, use local values
+
+    Returns:
+        A dict with hour, minute, second, millisecond, formatted
+    """
+    if utc:
+        if d.tzinfo is None:
+            d = d.replace(tzinfo=timezone.utc)
+        d_utc = d.astimezone(timezone.utc)
+        hour = d_utc.hour
+        minute = d_utc.minute
+        second = d_utc.second
+        millisecond = d_utc.microsecond // 1000
+    else:
+        if d.tzinfo is not None:
+            d = d.astimezone(tz=None).replace(tzinfo=None)
+        hour = d.hour
+        minute = d.minute
+        second = d.second
+        millisecond = d.microsecond // 1000
+
+    time_part = f"{hour:02d}:{minute:02d}:{second:02d}.{millisecond:03d}"
+    formatted = f"{time_part}Z" if utc else time_part
+
+    return {
+        "hour": hour,
+        "minute": minute,
+        "second": second,
+        "millisecond": millisecond,
+        "formatted": formatted,
+    }

package/flowquery-py/src/parsing/functions/time_.py

@@ -0,0 +1,57 @@
+"""Time function."""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+from .temporal_utils import build_time_object, parse_temporal_arg
+
+
+@FunctionDef({
+    "description": (
+        "Returns a time value. With no arguments returns the current UTC time. "
+        "Accepts an ISO 8601 time string or a map of components (hour, minute, second, millisecond)."
+    ),
+    "category": "scalar",
+    "parameters": [
+        {
+            "name": "input",
+            "description": "Optional. An ISO 8601 time string (HH:MM:SS) or a map of components.",
+            "type": "string",
+            "required": False,
+        },
+    ],
+    "output": {
+        "description": "A time object with properties: hour, minute, second, millisecond, formatted",
+        "type": "object",
+    },
+    "examples": [
+        "RETURN time() AS now",
+        "RETURN time('12:30:00') AS t",
+        "WITH time() AS t RETURN t.hour, t.minute",
+    ],
+})
+class Time(Function):
+    """Time function.
+
+    Returns a time value (with timezone offset awareness).
+    When called with no arguments, returns the current UTC time.
+    When called with a string argument, parses it.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("time")
+        self._expected_parameter_count = None
+
+    def value(self) -> Any:
+        children = self.get_children()
+        if len(children) > 1:
+            raise ValueError("time() accepts at most one argument")
+
+        if len(children) == 1:
+            d = parse_temporal_arg(children[0].value(), "time")
+        else:
+            d = datetime.now(timezone.utc)
+
+        return build_time_object(d, utc=True)

package/flowquery-py/src/parsing/functions/timestamp.py

@@ -0,0 +1,37 @@
+"""Timestamp function."""
+
+import time
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": (
+        "Returns the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z)."
+    ),
+    "category": "scalar",
+    "parameters": [],
+    "output": {
+        "description": "Milliseconds since Unix epoch",
+        "type": "number",
+        "example": 1718450000000,
+    },
+    "examples": [
+        "RETURN timestamp() AS ts",
+        "WITH timestamp() AS before, timestamp() AS after RETURN after - before",
+    ],
+})
+class Timestamp(Function):
+    """Timestamp function.
+
+    Returns the number of milliseconds since the Unix epoch (1970-01-01T00:00:00Z).
+    """
+
+    def __init__(self) -> None:
+        super().__init__("timestamp")
+        self._expected_parameter_count = 0
+
+    def value(self) -> Any:
+        return int(time.time() * 1000)

package/flowquery-py/src/parsing/functions/to_float.py

@@ -0,0 +1,46 @@
+"""ToFloat function."""
+
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Converts a value to a floating point number",
+    "category": "scalar",
+    "parameters": [
+        {"name": "value", "description": "The value to convert to a float", "type": "any"}
+    ],
+    "output": {"description": "The floating point representation of the value", "type": "number", "example": 3.14},
+    "examples": [
+        'RETURN toFloat("3.14")',
+        "RETURN toFloat(42)",
+        "RETURN toFloat(true)"
+    ]
+})
+class ToFloat(Function):
+    """ToFloat function.
+
+    Converts a value to a floating point number.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("tofloat")
+        self._expected_parameter_count = 1
+
+    def value(self) -> Any:
+        val = self.get_children()[0].value()
+        if val is None:
+            return None
+        if isinstance(val, bool):
+            return 1.0 if val else 0.0
+        if isinstance(val, (int, float)):
+            return float(val)
+        if isinstance(val, str):
+            trimmed = val.strip()
+            try:
+                return float(trimmed)
+            except (ValueError, OverflowError):
+                raise ValueError(f'Cannot convert string "{val}" to float')
+        raise ValueError("toFloat() expects a number, string, or boolean")