flowquery 1.0.34 → 1.0.36

package/flowquery-py/pyproject.toml

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

package/flowquery-py/src/graph/database.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, Optional, Union
+from typing import Any, AsyncIterator, Dict, List, Optional, Union
 
 from ..parsing.ast_node import ASTNode
 from .node import Node
@@ -48,35 +48,57 @@ class Database:
         physical = PhysicalRelationship()
         physical.type = relationship.type
         physical.statement = statement
+        if relationship.source is not None:
+            physical.source = relationship.source
+        if relationship.target is not None:
+            physical.target = relationship.target
         Database._relationships[relationship.type] = physical
 
     def get_relationship(self, relationship: 'Relationship') -> Optional['PhysicalRelationship']:
         """Gets a relationship from the database."""
         return Database._relationships.get(relationship.type) if relationship.type else None
 
-    async def schema(self) -> list[dict[str, Any]]:
+    def get_relationships(self, relationship: 'Relationship') -> list['PhysicalRelationship']:
+        """Gets multiple physical relationships for ORed types."""
+        result = []
+        for rel_type in relationship.types:
+            physical = Database._relationships.get(rel_type)
+            if physical:
+                result.append(physical)
+        return result
+
+    async def schema(self) -> List[Dict[str, Any]]:
         """Returns the graph schema with node/relationship labels and sample data."""
-        result: list[dict[str, Any]] = []
+        return [item async for item in self._schema()]
 
+    async def _schema(self) -> AsyncIterator[Dict[str, Any]]:
+        """Async generator for graph schema with node/relationship labels and sample data."""
         for label, physical_node in Database._nodes.items():
             records = await physical_node.data()
-            entry: dict[str, Any] = {"kind": "node", "label": label}
+            entry: Dict[str, Any] = {"kind": "Node", "label": label}
             if records:
                 sample = {k: v for k, v in records[0].items() if k != "id"}
-                if sample:
+                properties = list(sample.keys())
+                if properties:
+                    entry["properties"] = properties
                     entry["sample"] = sample
-            result.append(entry)
+            yield entry
 
         for rel_type, physical_rel in Database._relationships.items():
             records = await physical_rel.data()
-            entry_rel: dict[str, Any] = {"kind": "relationship", "type": rel_type}
+            entry_rel: Dict[str, Any] = {
+                "kind": "Relationship",
+                "type": rel_type,
+                "from_label": physical_rel.source.label if physical_rel.source else None,
+                "to_label": physical_rel.target.label if physical_rel.target else None,
+            }
             if records:
                 sample = {k: v for k, v in records[0].items() if k not in ("left_id", "right_id")}
-                if sample:
+                properties = list(sample.keys())
+                if properties:
+                    entry_rel["properties"] = properties
                     entry_rel["sample"] = sample
-            result.append(entry_rel)
-
-        return result
+            yield entry_rel
 
     async def get_data(self, element: Union['Node', 'Relationship']) -> Union['NodeData', 'RelationshipData']:
         """Gets data for a node or relationship."""
@@ -87,6 +109,17 @@ class Database:
             data = await node.data()
             return NodeData(data)
         elif isinstance(element, Relationship):
+            if len(element.types) > 1:
+                physicals = self.get_relationships(element)
+                if not physicals:
+                    raise ValueError(f"No physical relationships found for types {', '.join(element.types)}")
+                all_records = []
+                for i, physical in enumerate(physicals):
+                    records = await physical.data()
+                    type_name = element.types[i]
+                    for record in records:
+                        all_records.append({**record, "_type": type_name})
+                return RelationshipData(all_records)
             relationship = self.get_relationship(element)
             if relationship is None:
                 raise ValueError(f"Physical relationship not found for type {element.type}")

package/flowquery-py/src/graph/relationship.py

@@ -19,7 +19,7 @@ class Relationship(ASTNode):
     def __init__(self) -> None:
         super().__init__()
         self._identifier: Optional[str] = None
-        self._type: Optional[str] = None
+        self._types: List[str] = []
         self._hops: Hops = Hops()
         self._source: Optional['Node'] = None
         self._target: Optional['Node'] = None
@@ -39,11 +39,19 @@ class Relationship(ASTNode):
 
     @property
     def type(self) -> Optional[str]:
-        return self._type
+        return self._types[0] if self._types else None
 
     @type.setter
     def type(self, value: str) -> None:
-        self._type = value
+        self._types = [value]
+
+    @property
+    def types(self) -> List[str]:
+        return self._types
+
+    @types.setter
+    def types(self, value: List[str]) -> None:
+        self._types = value
 
     @property
     def hops(self) -> Hops:

package/flowquery-py/src/graph/relationship_data.py

@@ -25,11 +25,12 @@ class RelationshipData(Data):
         return self._find(id, hop, key)
 
     def properties(self) -> Optional[Dict[str, Any]]:
-        """Get properties of current relationship, excluding left_id and right_id."""
+        """Get properties of current relationship, excluding left_id, right_id, and _type."""
         current = self.current()
         if current:
             props = dict(current)
             props.pop("left_id", None)
             props.pop("right_id", None)
+            props.pop("_type", None)
             return props
         return None

package/flowquery-py/src/graph/relationship_match_collector.py

@@ -28,9 +28,15 @@ class RelationshipMatchCollector:
         """Push a new match onto the collector."""
         start_node_value = relationship.source.value() if relationship.source else None
         rel_data = relationship.get_data()
+        current_record = rel_data.current() if rel_data else None
+        default_type = relationship.type or ""
+        if current_record and isinstance(current_record, dict):
+            actual_type = current_record.get('_type', default_type)
+        else:
+            actual_type = default_type
         rel_props: Dict[str, Any] = (rel_data.properties() or {}) if rel_data else {}
         match: RelationshipMatchRecord = {
-            "type": relationship.type or "",
+            "type": actual_type,
             "startNode": start_node_value or {},
             "endNode": None,
             "properties": rel_props,

package/flowquery-py/src/graph/relationship_reference.py

@@ -10,8 +10,8 @@ class RelationshipReference(Relationship):
     def __init__(self, relationship: Relationship, referred: ASTNode) -> None:
         super().__init__()
         self._referred = referred
-        if relationship.type:
-            self.type = relationship.type
+        if relationship.types:
+            self.types = relationship.types
 
     @property
     def referred(self) -> ASTNode:

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,12 +48,16 @@ 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
+from .trim import Trim
 from .type_ import Type
 from .value_holder import ValueHolder
 
@@ -63,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",
@@ -75,10 +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")