flowquery 1.0.34 → 1.0.36

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

@@ -0,0 +1,39 @@
+"""Head function."""
+
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Returns the first element of a list",
+    "category": "scalar",
+    "parameters": [
+        {"name": "list", "description": "The list to get the first element from", "type": "array"}
+    ],
+    "output": {"description": "The first element of the list", "type": "any", "example": "1"},
+    "examples": [
+        "RETURN head([1, 2, 3])",
+        "WITH ['a', 'b', 'c'] AS items RETURN head(items)"
+    ]
+})
+class Head(Function):
+    """Head function.
+
+    Returns the first element of a list.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("head")
+        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("head() expects a list")
+        if len(val) == 0:
+            return None
+        return val[0]

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

@@ -0,0 +1,49 @@
+"""Id function."""
+
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": (
+        "Returns the id of a node or relationship. "
+        "For nodes, returns the id property. For relationships, returns the type."
+    ),
+    "category": "scalar",
+    "parameters": [
+        {"name": "entity", "description": "A node or relationship to get the id from", "type": "object"}
+    ],
+    "output": {"description": "The id of the entity", "type": "any", "example": "1"},
+    "examples": [
+        "MATCH (n:Person) RETURN id(n)",
+        "MATCH (a)-[r]->(b) RETURN id(r)"
+    ]
+})
+class Id(Function):
+    """Id function.
+
+    Returns the id of a node or relationship.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("id")
+        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("id() expects a node or relationship")
+
+        # If it's a RelationshipMatchRecord (has type, startNode, endNode, properties)
+        if all(k in obj for k in ("type", "startNode", "endNode", "properties")):
+            return obj["type"]
+
+        # If it's a node record (has id field)
+        if "id" in obj:
+            return obj["id"]
+
+        raise ValueError("id() expects a node or relationship")

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

@@ -0,0 +1,39 @@
+"""Last function."""
+
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Returns the last element of a list",
+    "category": "scalar",
+    "parameters": [
+        {"name": "list", "description": "The list to get the last element from", "type": "array"}
+    ],
+    "output": {"description": "The last element of the list", "type": "any", "example": "3"},
+    "examples": [
+        "RETURN last([1, 2, 3])",
+        "WITH ['a', 'b', 'c'] AS items RETURN last(items)"
+    ]
+})
+class Last(Function):
+    """Last function.
+
+    Returns the last element of a list.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("last")
+        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("last() expects a list")
+        if len(val) == 0:
+            return None
+        return val[-1]

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

@@ -0,0 +1,62 @@
+"""Local datetime function."""
+
+from datetime import datetime
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+from .temporal_utils import build_datetime_object, parse_temporal_arg
+
+
+@FunctionDef({
+    "description": (
+        "Returns a local datetime value (no timezone). With no arguments returns the current local datetime. "
+        "Accepts an ISO 8601 string or a map of components."
+    ),
+    "category": "scalar",
+    "parameters": [
+        {
+            "name": "input",
+            "description": "Optional. An ISO 8601 datetime string or a map of components.",
+            "type": "string",
+            "required": False,
+        },
+    ],
+    "output": {
+        "description": (
+            "A datetime object with properties: year, month, day, hour, minute, second, millisecond, "
+            "epochMillis, epochSeconds, dayOfWeek, dayOfYear, quarter, formatted"
+        ),
+        "type": "object",
+    },
+    "examples": [
+        "RETURN localdatetime() AS now",
+        "RETURN localdatetime('2025-06-15T12:30:00') AS dt",
+        "WITH localdatetime() AS dt RETURN dt.hour, dt.minute",
+    ],
+})
+class LocalDatetime(Function):
+    """Local datetime function.
+
+    Returns a local datetime value (date + time, no timezone offset).
+    When called with no arguments, returns the current local datetime.
+    When called with a string argument, parses it as an ISO 8601 datetime.
+
+    Equivalent to Neo4j's localdatetime() function.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("localdatetime")
+        self._expected_parameter_count = None
+
+    def value(self) -> Any:
+        children = self.get_children()
+        if len(children) > 1:
+            raise ValueError("localdatetime() accepts at most one argument")
+
+        if len(children) == 1:
+            d = parse_temporal_arg(children[0].value(), "localdatetime")
+        else:
+            d = datetime.now()
+
+        return build_datetime_object(d, utc=False)

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

@@ -0,0 +1,59 @@
+"""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.
+
+    Equivalent to Neo4j's localtime() function.
+    """
+
+    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/predicate_sum.py

@@ -1,6 +1,6 @@
 """PredicateSum function."""
 
-from typing import Any, Optional
+from typing import Any
 
 from .function_metadata import FunctionDef
 from .predicate_function import PredicateFunction
@@ -41,12 +41,9 @@ class PredicateSum(PredicateFunction):
         if array is None or not isinstance(array, list):
             raise ValueError("Invalid array for sum function")
 
-        _sum: Optional[Any] = None
+        _sum: int = 0
         for item in array:
             self._value_holder.holder = item
             if self.where is None or self.where.value():
-                if _sum is None:
-                    _sum = self._return.value()
-                else:
-                    _sum += self._return.value()
+                _sum += self._return.value()
         return _sum

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/schema.py

@@ -9,23 +9,27 @@ from .function_metadata import FunctionDef
 @FunctionDef({
     "description": (
         "Returns the graph schema listing all nodes and relationships "
-        "with a sample of their data."
+        "with their properties and a sample of their data."
     ),
     "category": "async",
     "parameters": [],
     "output": {
-        "description": "Schema entry with kind, label/type, and optional sample data",
+        "description": "Schema entry with label/type, properties, and optional sample data",
         "type": "object",
     },
     "examples": [
-        "CALL schema() YIELD kind, label, type, sample RETURN kind, label, type, sample",
+        "CALL schema() YIELD label, type, from_label, to_label, properties, sample "
+        "RETURN label, type, from_label, to_label, properties, sample",
     ],
 })
 class Schema(AsyncFunction):
     """Returns the graph schema of the database.
 
-    Lists all nodes and relationships with their labels/types and a sample
-    of their data (excluding id from nodes, left_id and right_id from relationships).
+    Lists all nodes and relationships with their labels/types, properties,
+    and a sample of their data (excluding id from nodes, left_id and right_id from relationships).
+
+    Nodes: {label, properties, sample}
+    Relationships: {type, from_label, to_label, properties, sample}
     """
 
     async def generate(self) -> AsyncGenerator[Any, None]:

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:]