flowquery 1.0.35 → 1.0.36

package/flowquery-py/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flowquery"
-version = "1.0.25"
+version = "1.0.26"
 description = "A declarative query language for data processing pipelines"
 readme = "README.md"
 requires-python = ">=3.10"

package/flowquery-py/src/parsing/data_structures/lookup.py

@@ -38,6 +38,8 @@ class Lookup(ASTNode):
 
     def value(self) -> Any:
         obj = self.variable.value()
+        if obj is None:
+            return None
         key = self.index.value()
         # Try dict-like access first, then fall back to attribute access for objects
         try:

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

@@ -3,8 +3,13 @@
 from .aggregate_function import AggregateFunction
 from .async_function import AsyncFunction
 from .avg import Avg
+from .coalesce import Coalesce
 from .collect import Collect
 from .count import Count
+from .date_ import DateFunction
+from .datetime_ import Datetime
+from .duration import Duration
+from .element_id import ElementId
 from .function import Function
 from .function_factory import FunctionFactory
 from .function_metadata import (
@@ -19,13 +24,23 @@ from .function_metadata import (
     get_registered_function_metadata,
 )
 from .functions import Functions
+from .head import Head
+from .id_ import Id
 from .join import Join
 from .keys import Keys
+from .last import Last
+from .localdatetime import LocalDatetime
+from .localtime import LocalTime
+from .max_ import Max
+from .min_ import Min
+from .nodes import Nodes
 from .predicate_function import PredicateFunction
 from .predicate_sum import PredicateSum
+from .properties import Properties
 from .rand import Rand
 from .range_ import Range
 from .reducer_element import ReducerElement
+from .relationships import Relationships
 from .replace import Replace
 from .round_ import Round
 from .schema import Schema
@@ -33,9 +48,12 @@ from .size import Size
 from .split import Split
 from .string_distance import StringDistance
 from .stringify import Stringify
-
-# Built-in functions
 from .sum import Sum
+from .tail import Tail
+from .time_ import Time
+from .timestamp import Timestamp
+from .to_float import ToFloat
+from .to_integer import ToInteger
 from .to_json import ToJson
 from .to_lower import ToLower
 from .to_string import ToString
@@ -64,10 +82,23 @@ __all__ = [
     # Built-in functions
     "Sum",
     "Avg",
+    "DateFunction",
+    "Datetime",
+    "Coalesce",
     "Collect",
     "Count",
+    "Duration",
+    "ElementId",
+    "Head",
+    "Id",
     "Join",
+    "Last",
     "Keys",
+    "Max",
+    "Min",
+    "Nodes",
+    "Properties",
+    "Relationships",
     "Rand",
     "Range",
     "Replace",
@@ -76,11 +107,18 @@ __all__ = [
     "Split",
     "StringDistance",
     "Stringify",
+    "Tail",
+    "Time",
+    "Timestamp",
+    "ToFloat",
+    "ToInteger",
     "ToJson",
     "ToLower",
     "ToString",
     "Trim",
     "Type",
+    "LocalDatetime",
+    "LocalTime",
     "Functions",
     "Schema",
     "PredicateSum",

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

@@ -0,0 +1,44 @@
+"""Coalesce function."""
+
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Returns the first non-null value from a list of expressions",
+    "category": "scalar",
+    "parameters": [
+        {"name": "expressions", "description": "Two or more expressions to evaluate", "type": "any"}
+    ],
+    "output": {"description": "The first non-null value, or null if all values are null", "type": "any"},
+    "examples": [
+        "RETURN coalesce(null, 'hello', 'world')",
+        "MATCH (n) RETURN coalesce(n.nickname, n.name) AS displayName"
+    ]
+})
+class Coalesce(Function):
+    """Coalesce function.
+
+    Returns the first non-null value from a list of expressions.
+    Equivalent to Neo4j's coalesce() function.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("coalesce")
+        self._expected_parameter_count = None  # variable number of parameters
+
+    def value(self) -> Any:
+        children = self.get_children()
+        if len(children) == 0:
+            raise ValueError("coalesce() requires at least one argument")
+        for child in children:
+            try:
+                val = child.value()
+            except (KeyError, AttributeError):
+                # Treat missing properties/keys as null, matching Neo4j behavior
+                val = None
+            if val is not None:
+                return val
+        return None

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

@@ -0,0 +1,63 @@
+"""Date function."""
+
+from datetime import datetime
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+from .temporal_utils import build_date_object, parse_temporal_arg
+
+
+@FunctionDef({
+    "description": (
+        "Returns a date value. With no arguments returns the current date. "
+        "Accepts an ISO 8601 date string or a map of components (year, month, day)."
+    ),
+    "category": "scalar",
+    "parameters": [
+        {
+            "name": "input",
+            "description": "Optional. An ISO 8601 date string (YYYY-MM-DD) or a map of components.",
+            "type": "string",
+            "required": False,
+        },
+    ],
+    "output": {
+        "description": (
+            "A date object with properties: year, month, day, "
+            "epochMillis, dayOfWeek, dayOfYear, quarter, formatted"
+        ),
+        "type": "object",
+    },
+    "examples": [
+        "RETURN date() AS today",
+        "RETURN date('2025-06-15') AS d",
+        "RETURN date({year: 2025, month: 6, day: 15}) AS d",
+        "WITH date() AS d RETURN d.year, d.month, d.dayOfWeek",
+    ],
+})
+class DateFunction(Function):
+    """Date function.
+
+    Returns a date value (no time component).
+    When called with no arguments, returns the current date.
+    When called with a string argument, parses it as an ISO 8601 date.
+
+    Equivalent to Neo4j's date() function.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("date")
+        self._expected_parameter_count = None
+
+    def value(self) -> Any:
+        children = self.get_children()
+        if len(children) > 1:
+            raise ValueError("date() accepts at most one argument")
+
+        if len(children) == 1:
+            d = parse_temporal_arg(children[0].value(), "date")
+        else:
+            d = datetime.now()
+
+        return build_date_object(d)

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

@@ -0,0 +1,64 @@
+"""Datetime function."""
+
+from datetime import datetime, timezone
+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 datetime value. With no arguments returns the current UTC datetime. "
+        "Accepts an ISO 8601 string or a map of components (year, month, day, hour, minute, second, millisecond)."
+    ),
+    "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 datetime() AS now",
+        "RETURN datetime('2025-06-15T12:30:00Z') AS dt",
+        "RETURN datetime({year: 2025, month: 6, day: 15, hour: 12}) AS dt",
+        "WITH datetime() AS dt RETURN dt.year, dt.month, dt.day",
+    ],
+})
+class Datetime(Function):
+    """Datetime function.
+
+    Returns a datetime value (date + time + timezone offset).
+    When called with no arguments, returns the current UTC datetime.
+    When called with a string argument, parses it as an ISO 8601 datetime.
+    When called with a map argument, constructs a datetime from components.
+
+    Equivalent to Neo4j's datetime() function.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("datetime")
+        self._expected_parameter_count = None
+
+    def value(self) -> Any:
+        children = self.get_children()
+        if len(children) > 1:
+            raise ValueError("datetime() accepts at most one argument")
+
+        if len(children) == 1:
+            d = parse_temporal_arg(children[0].value(), "datetime")
+        else:
+            d = datetime.now(timezone.utc)
+
+        return build_datetime_object(d, utc=True)

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

@@ -0,0 +1,159 @@
+"""Duration function."""
+
+import re
+from typing import Any, Dict
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+ISO_DURATION_REGEX = re.compile(
+    r"^P(?:(\d+(?:\.\d+)?)Y)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)W)?"
+    r"(?:(\d+(?:\.\d+)?)D)?(?:T(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?"
+    r"(?:(\d+(?:\.\d+)?)S)?)?$"
+)
+
+
+def _parse_duration_string(s: str) -> Dict[str, float]:
+    """Parse an ISO 8601 duration string into components."""
+    match = ISO_DURATION_REGEX.match(s)
+    if not match:
+        raise ValueError(f"duration(): Invalid ISO 8601 duration string: '{s}'")
+    return {
+        "years": float(match.group(1)) if match.group(1) else 0,
+        "months": float(match.group(2)) if match.group(2) else 0,
+        "weeks": float(match.group(3)) if match.group(3) else 0,
+        "days": float(match.group(4)) if match.group(4) else 0,
+        "hours": float(match.group(5)) if match.group(5) else 0,
+        "minutes": float(match.group(6)) if match.group(6) else 0,
+        "seconds": float(match.group(7)) if match.group(7) else 0,
+    }
+
+
+def _build_duration_object(components: Dict[str, Any]) -> Dict[str, Any]:
+    """Build a duration result object from components."""
+    years = components.get("years", 0) or 0
+    months = components.get("months", 0) or 0
+    weeks = components.get("weeks", 0) or 0
+    days = components.get("days", 0) or 0
+    hours = components.get("hours", 0) or 0
+    minutes = components.get("minutes", 0) or 0
+    raw_seconds = components.get("seconds", 0) or 0
+    seconds = int(raw_seconds)
+    fractional_seconds = raw_seconds - seconds
+
+    if "milliseconds" in components and components["milliseconds"]:
+        milliseconds = int(components["milliseconds"])
+    else:
+        milliseconds = round(fractional_seconds * 1000)
+
+    if "nanoseconds" in components and components["nanoseconds"]:
+        nanoseconds = int(components["nanoseconds"])
+    else:
+        nanoseconds = round(fractional_seconds * 1_000_000_000) % 1_000_000
+
+    # Total days including weeks
+    total_days = int(days + weeks * 7)
+
+    # Total seconds for the time portion
+    total_seconds = int(hours * 3600 + minutes * 60 + seconds)
+
+    # Total months
+    total_months = int(years * 12 + months)
+
+    # Build ISO 8601 formatted string
+    formatted = "P"
+    if years:
+        formatted += f"{int(years)}Y"
+    if months:
+        formatted += f"{int(months)}M"
+    if weeks:
+        formatted += f"{int(weeks)}W"
+    raw_days = int(total_days - weeks * 7)
+    if raw_days:
+        formatted += f"{raw_days}D"
+    has_time = hours or minutes or seconds or milliseconds
+    if has_time:
+        formatted += "T"
+        if hours:
+            formatted += f"{int(hours)}H"
+        if minutes:
+            formatted += f"{int(minutes)}M"
+        if seconds or milliseconds:
+            if milliseconds:
+                formatted += f"{seconds}.{milliseconds:03d}S"
+            else:
+                formatted += f"{seconds}S"
+    if formatted == "P":
+        formatted = "PT0S"
+
+    return {
+        "years": int(years),
+        "months": int(months),
+        "weeks": int(weeks),
+        "days": total_days,
+        "hours": int(hours),
+        "minutes": int(minutes),
+        "seconds": seconds,
+        "milliseconds": milliseconds,
+        "nanoseconds": nanoseconds,
+        "totalMonths": total_months,
+        "totalDays": total_days,
+        "totalSeconds": total_seconds,
+        "formatted": formatted,
+    }
+
+
+@FunctionDef({
+    "description": (
+        "Creates a duration value representing a span of time. "
+        "Accepts an ISO 8601 duration string (e.g., 'P1Y2M3DT4H5M6S') or a map of components "
+        "(years, months, weeks, days, hours, minutes, seconds, milliseconds, nanoseconds)."
+    ),
+    "category": "scalar",
+    "parameters": [
+        {
+            "name": "input",
+            "description": (
+                "An ISO 8601 duration string or a map of components "
+                "(years, months, weeks, days, hours, minutes, seconds, milliseconds, nanoseconds)"
+            ),
+            "type": "any",
+        }
+    ],
+    "output": {
+        "description": (
+            "A duration object with properties: years, months, weeks, days, hours, minutes, seconds, "
+            "milliseconds, nanoseconds, totalMonths, totalDays, totalSeconds, formatted"
+        ),
+        "type": "object",
+    },
+    "examples": [
+        "RETURN duration('P1Y2M3D') AS d",
+        "RETURN duration('PT2H30M') AS d",
+        "RETURN duration({days: 14, hours: 16}) AS d",
+        "RETURN duration({months: 5, days: 1, hours: 12}) AS d",
+    ],
+})
+class Duration(Function):
+    """Duration function.
+
+    Creates a duration value representing a span of time.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("duration")
+        self._expected_parameter_count = 1
+
+    def value(self) -> Any:
+        arg = self.get_children()[0].value()
+        if arg is None:
+            return None
+
+        if isinstance(arg, str):
+            components = _parse_duration_string(arg)
+            return _build_duration_object(components)
+
+        if isinstance(arg, dict):
+            return _build_duration_object(arg)
+
+        raise ValueError("duration() expects a string or map argument")

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

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

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)