flowquery 1.0.43 → 1.0.45

package/flowquery-py/pyproject.toml

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

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

@@ -42,6 +42,8 @@ class Join(Function):
     def value(self) -> Any:
         array = self.get_children()[0].value()
         delimiter = self.get_children()[1].value()
+        if array is None:
+            return None
         if not isinstance(array, list) or not isinstance(delimiter, str):
             raise ValueError("Invalid arguments for join function")
         return delimiter.join(str(item) for item in array)

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

@@ -28,7 +28,7 @@ class Keys(Function):
     def value(self) -> Any:
         obj = self.get_children()[0].value()
         if obj is None:
-            return []
+            return None
         if not isinstance(obj, dict):
             raise ValueError("keys() expects an object, not an array or primitive")
         return list(obj.keys())

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

@@ -34,6 +34,8 @@ class Range(Function):
     def value(self) -> Any:
         start = self.get_children()[0].value()
         end = self.get_children()[1].value()
+        if start is None or end is None:
+            return None
         if not isinstance(start, (int, float)) or not isinstance(end, (int, float)):
             raise ValueError("Invalid arguments for range function")
         return list(range(int(start), int(end) + 1))

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

@@ -32,6 +32,8 @@ class Replace(Function):
         text = self.get_children()[0].value()
         pattern = self.get_children()[1].value()
         replacement = self.get_children()[2].value()
+        if text is None:
+            return None
         if not isinstance(text, str) or not isinstance(pattern, str) or not isinstance(replacement, str):
             raise ValueError("Invalid arguments for replace function")
         return re.sub(re.escape(pattern), replacement, text)

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

@@ -27,6 +27,8 @@ class Round(Function):
 
     def value(self) -> Any:
         val = self.get_children()[0].value()
+        if val is None:
+            return None
         if not isinstance(val, (int, float)):
             raise ValueError("Invalid argument for round function")
         return round(val)

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

@@ -27,6 +27,8 @@ class Size(Function):
 
     def value(self) -> Any:
         val = self.get_children()[0].value()
+        if val is None:
+            return None
         if not isinstance(val, (list, str)):
             raise ValueError("Invalid argument for size function")
         return len(val)

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

@@ -47,6 +47,8 @@ class Split(Function):
     def value(self) -> Any:
         text = self.get_children()[0].value()
         delimiter = self.get_children()[1].value()
+        if text is None:
+            return None
         if not isinstance(text, str) or not isinstance(delimiter, str):
             raise ValueError("Invalid arguments for split function")
         return text.split(delimiter)

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

@@ -1,5 +1,7 @@
 """String distance function using Levenshtein distance."""
 
+from typing import Optional
+
 from .function import Function
 from .function_metadata import FunctionDef
 
@@ -80,9 +82,11 @@ class StringDistance(Function):
         super().__init__("string_distance")
         self._expected_parameter_count = 2
 
-    def value(self) -> float:
+    def value(self) -> Optional[float]:
         str1 = self.get_children()[0].value()
         str2 = self.get_children()[1].value()
+        if str1 is None or str2 is None:
+            return None
         if not isinstance(str1, str) or not isinstance(str2, str):
             raise ValueError("Invalid arguments for string_distance function: both arguments must be strings")
         return _levenshtein_distance(str1, str2)

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

@@ -42,6 +42,8 @@ class Stringify(Function):
     def value(self) -> Any:
         val = self.get_children()[0].value()
         indent = int(self.get_children()[1].value())
+        if val is None:
+            return None
         if not isinstance(val, (dict, list)):
             raise ValueError("Invalid argument for stringify function")
         return json.dumps(val, indent=indent, default=str)

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

@@ -52,6 +52,8 @@ class Substring(Function):
         original = children[0].value()
         start = children[1].value()
 
+        if original is None:
+            return None
         if not isinstance(original, str):
             raise ValueError(
                 "Invalid argument for substring function: expected a string as the first argument"

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

@@ -28,6 +28,8 @@ class ToJson(Function):
 
     def value(self) -> Any:
         text = self.get_children()[0].value()
+        if text is None:
+            return None
         if not isinstance(text, str):
             raise ValueError("Invalid arguments for tojson function")
         return json.loads(text)

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

@@ -30,6 +30,8 @@ class ToLower(Function):
 
     def value(self) -> Any:
         val = self.get_children()[0].value()
+        if val is None:
+            return None
         if not isinstance(val, str):
             raise ValueError("Invalid argument for toLower function: expected a string")
         return val.lower()

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

@@ -33,7 +33,7 @@ class ToString(Function):
     def value(self) -> Any:
         val = self.get_children()[0].value()
         if val is None:
-            return "null"
+            return None
         if isinstance(val, bool):
             return str(val).lower()
         if isinstance(val, (dict, list)):

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

@@ -30,6 +30,8 @@ class Trim(Function):
 
     def value(self) -> Any:
         val = self.get_children()[0].value()
+        if val is None:
+            return None
         if not isinstance(val, str):
             raise ValueError("Invalid argument for trim function: expected a string")
         return val.strip()

package/flowquery-py/src/parsing/operations/order_by.py

@@ -1,15 +1,19 @@
 """Represents an ORDER BY operation that sorts results."""
 
-from typing import Any, Dict, List
+import functools
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 from .operation import Operation
 
+if TYPE_CHECKING:
+    from ..expressions.expression import Expression
+
 
 class SortField:
-    """A single sort specification: field name and direction."""
+    """A single sort specification: expression and direction."""
 
-    def __init__(self, field: str, direction: str = "asc"):
-        self.field = field
+    def __init__(self, expression: 'Expression', direction: str = "asc"):
+        self.expression = expression
         self.direction = direction
 
 
@@ -19,27 +23,63 @@ class OrderBy(Operation):
     Can be attached to a RETURN operation (sorting its results),
     or used as a standalone accumulating operation after a non-aggregate WITH.
 
-    Example:
+    Supports both simple field references and arbitrary expressions:
+
+    Example::
+
         RETURN x ORDER BY x DESC
+        RETURN x ORDER BY toLower(x.name) ASC
+        RETURN x ORDER BY string_distance(toLower(x.name), toLower('Thomas')) ASC
     """
 
     def __init__(self, fields: List[SortField]):
         super().__init__()
         self._fields = fields
         self._results: List[Dict[str, Any]] = []
+        self._sort_keys: List[List[Any]] = []
 
     @property
     def fields(self) -> List[SortField]:
         return self._fields
 
-    def sort(self, records: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-        """Sorts an array of records according to the sort fields."""
-        import functools
+    def capture_sort_keys(self) -> None:
+        """Evaluate every sort-field expression against the current runtime
+        context and store the resulting values.  Must be called once per
+        accumulated row (from ``Return.run()``)."""
+        self._sort_keys.append([f.expression.value() for f in self._fields])
 
-        def compare(a: Dict[str, Any], b: Dict[str, Any]) -> int:
-            for sf in self._fields:
-                a_val = a.get(sf.field)
-                b_val = b.get(sf.field)
+    def sort(self, records: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Sort records using pre-computed sort keys captured during
+        accumulation.  When no keys have been captured (e.g. aggregated
+        returns), falls back to looking up simple reference identifiers
+        in each record."""
+        from ..expressions.reference import Reference
+
+        use_keys = len(self._sort_keys) == len(records)
+        keys = self._sort_keys
+
+        # Pre-compute fallback field names for when sort keys aren't
+        # available (aggregated returns).
+        fallback_fields: List[Optional[str]] = []
+        for f in self._fields:
+            root = f.expression.first_child()
+            if isinstance(root, Reference) and f.expression.child_count() == 1:
+                fallback_fields.append(root.identifier)
+            else:
+                fallback_fields.append(None)
+
+        indices = list(range(len(records)))
+
+        def compare(ai: int, bi: int) -> int:
+            for f_idx, sf in enumerate(self._fields):
+                if use_keys:
+                    a_val = keys[ai][f_idx]
+                    b_val = keys[bi][f_idx]
+                elif fallback_fields[f_idx] is not None:
+                    a_val = records[ai].get(fallback_fields[f_idx])  # type: ignore[arg-type]
+                    b_val = records[bi].get(fallback_fields[f_idx])  # type: ignore[arg-type]
+                else:
+                    continue
                 cmp = 0
                 if a_val is None and b_val is None:
                     cmp = 0
@@ -55,7 +95,8 @@ class OrderBy(Operation):
                     return -cmp if sf.direction == "desc" else cmp
             return 0
 
-        return sorted(records, key=functools.cmp_to_key(compare))
+        indices.sort(key=functools.cmp_to_key(compare))
+        return [records[i] for i in indices]
 
     async def run(self) -> None:
         """When used as a standalone operation, passes through to next."""
@@ -64,6 +105,7 @@ class OrderBy(Operation):
 
     async def initialize(self) -> None:
         self._results = []
+        self._sort_keys = []
         if self.next:
             await self.next.initialize()
 

package/flowquery-py/src/parsing/operations/return_op.py

@@ -68,6 +68,9 @@ class Return(Projection):
             # Deep copy objects to preserve their state
             value = copy.deepcopy(raw) if isinstance(raw, (dict, list)) else raw
             record[alias] = value
+        # Capture sort-key values while expression bindings are still live.
+        if self._order_by is not None:
+            self._order_by.capture_sort_keys()
         self._results.append(record)
         if self._order_by is None and self._limit is not None:
             self._limit.increment()

package/flowquery-py/src/parsing/parser.py

@@ -767,10 +767,9 @@ class Parser(BaseParser):
         self._expect_and_skip_whitespace_and_comments()
         fields: list[SortField] = []
         while True:
-            if not self.token.is_identifier_or_keyword():
-                raise ValueError("Expected field name in ORDER BY")
-            field = self.token.value
-            self.set_next_token()
+            expression = self._parse_expression()
+            if expression is None:
+                raise ValueError("Expected expression in ORDER BY")
             self._skip_whitespace_and_comments()
             direction = "asc"
             if self.token.is_asc():
@@ -781,7 +780,7 @@ class Parser(BaseParser):
                 direction = "desc"
                 self.set_next_token()
                 self._skip_whitespace_and_comments()
-            fields.append(SortField(field, direction))
+            fields.append(SortField(expression, direction))
             if self.token.is_comma():
                 self.set_next_token()
                 self._skip_whitespace_and_comments()

package/flowquery-py/tests/compute/test_runner.py

@@ -849,6 +849,134 @@ class TestRunner:
         assert len(results) == 1
         assert results[0] == {"result": ""}
 
+    # --- Null propagation tests ---
+
+    @pytest.mark.asyncio
+    async def test_to_lower_with_null_returns_null(self):
+        """Test toLower with null returns null."""
+        runner = Runner("RETURN toLower(null) as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_trim_with_null_returns_null(self):
+        """Test trim with null returns null."""
+        runner = Runner("RETURN trim(null) as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_replace_with_null_returns_null(self):
+        """Test replace with null returns null."""
+        runner = Runner("RETURN replace(null, 'a', 'b') as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_substring_with_null_returns_null(self):
+        """Test substring with null returns null."""
+        runner = Runner("RETURN substring(null, 0, 3) as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_split_with_null_returns_null(self):
+        """Test split with null returns null."""
+        runner = Runner("RETURN split(null, ',') as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_size_with_null_returns_null(self):
+        """Test size with null returns null."""
+        runner = Runner("RETURN size(null) as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_round_with_null_returns_null(self):
+        """Test round with null returns null."""
+        runner = Runner("RETURN round(null) as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_join_with_null_returns_null(self):
+        """Test join with null returns null."""
+        runner = Runner("RETURN join(null, ',') as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_string_distance_with_null_returns_null(self):
+        """Test string_distance with null returns null."""
+        runner = Runner("RETURN string_distance(null, 'hello') as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_stringify_with_null_returns_null(self):
+        """Test stringify with null returns null."""
+        runner = Runner("RETURN stringify(null) as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_tojson_with_null_returns_null(self):
+        """Test tojson with null returns null."""
+        runner = Runner("RETURN tojson(null) as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_range_with_null_returns_null(self):
+        """Test range with null returns null."""
+        runner = Runner("RETURN range(null, 5) as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_to_string_with_null_returns_null(self):
+        """Test toString with null returns null."""
+        runner = Runner("RETURN toString(null) as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
+    @pytest.mark.asyncio
+    async def test_keys_with_null_returns_null(self):
+        """Test keys with null returns null."""
+        runner = Runner("RETURN keys(null) as result")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"result": None}
+
     @pytest.mark.asyncio
     async def test_associative_array_with_key_which_is_keyword(self):
         """Test associative array with key which is keyword."""
@@ -4280,6 +4408,133 @@ class TestRunner:
         assert results[3] == {"x": 4}
         assert results[4] == {"x": 3}
 
+    @pytest.mark.asyncio
+    async def test_order_by_with_property_access_expression(self):
+        """Test ORDER BY with property access expression."""
+        runner = Runner(
+            "unwind [{name: 'Charlie', age: 30}, {name: 'Alice', age: 25}, {name: 'Bob', age: 35}] as person "
+            "return person.name as name, person.age as age "
+            "order by person.name asc"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"name": "Alice", "age": 25}
+        assert results[1] == {"name": "Bob", "age": 35}
+        assert results[2] == {"name": "Charlie", "age": 30}
+
+    @pytest.mark.asyncio
+    async def test_order_by_with_function_expression(self):
+        """Test ORDER BY with function expression."""
+        runner = Runner(
+            "unwind ['BANANA', 'apple', 'Cherry'] as fruit "
+            "return fruit "
+            "order by toLower(fruit)"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"fruit": "apple"}
+        assert results[1] == {"fruit": "BANANA"}
+        assert results[2] == {"fruit": "Cherry"}
+
+    @pytest.mark.asyncio
+    async def test_order_by_with_function_expression_descending(self):
+        """Test ORDER BY with function expression descending."""
+        runner = Runner(
+            "unwind ['BANANA', 'apple', 'Cherry'] as fruit "
+            "return fruit "
+            "order by toLower(fruit) desc"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"fruit": "Cherry"}
+        assert results[1] == {"fruit": "BANANA"}
+        assert results[2] == {"fruit": "apple"}
+
+    @pytest.mark.asyncio
+    async def test_order_by_with_nested_function_expression(self):
+        """Test ORDER BY with nested function expression."""
+        runner = Runner(
+            "unwind ['Alice', 'Bob', 'ALICE', 'bob'] as name "
+            "return name "
+            "order by string_distance(toLower(name), toLower('alice')) asc"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 4
+        # 'Alice' and 'ALICE' have distance 0 from 'alice', should come first
+        assert results[0]["name"] == "Alice"
+        assert results[1]["name"] == "ALICE"
+        # 'Bob' and 'bob' have higher distance from 'alice'
+        assert results[2]["name"] == "Bob"
+        assert results[3]["name"] == "bob"
+
+    @pytest.mark.asyncio
+    async def test_order_by_with_arithmetic_expression(self):
+        """Test ORDER BY with arithmetic expression."""
+        runner = Runner(
+            "unwind [{a: 3, b: 1}, {a: 1, b: 5}, {a: 2, b: 2}] as item "
+            "return item.a as a, item.b as b "
+            "order by item.a + item.b asc"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"a": 3, "b": 1}  # sum = 4
+        assert results[1] == {"a": 2, "b": 2}  # sum = 4
+        assert results[2] == {"a": 1, "b": 5}  # sum = 6
+
+    @pytest.mark.asyncio
+    async def test_order_by_expression_does_not_leak_synthetic_keys(self):
+        """Test ORDER BY expression does not leak synthetic keys."""
+        runner = Runner(
+            "unwind ['B', 'a', 'C'] as x "
+            "return x "
+            "order by toLower(x) asc"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        # Results should only contain 'x', no extra keys
+        for r in results:
+            assert list(r.keys()) == ["x"]
+        assert results[0] == {"x": "a"}
+        assert results[1] == {"x": "B"}
+        assert results[2] == {"x": "C"}
+
+    @pytest.mark.asyncio
+    async def test_order_by_with_expression_and_limit(self):
+        """Test ORDER BY with expression and limit."""
+        runner = Runner(
+            "unwind ['BANANA', 'apple', 'Cherry', 'date', 'ELDERBERRY'] as fruit "
+            "return fruit "
+            "order by toLower(fruit) asc "
+            "limit 3"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"fruit": "apple"}
+        assert results[1] == {"fruit": "BANANA"}
+        assert results[2] == {"fruit": "Cherry"}
+
+    @pytest.mark.asyncio
+    async def test_order_by_with_mixed_simple_and_expression_fields(self):
+        """Test ORDER BY with mixed simple and expression fields."""
+        runner = Runner(
+            "unwind [{name: 'Alice', score: 3}, {name: 'Alice', score: 1}, {name: 'Bob', score: 2}] as item "
+            "return item.name as name, item.score as score "
+            "order by name asc, item.score desc"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"name": "Alice", "score": 3}  # Alice, score 3 desc
+        assert results[1] == {"name": "Alice", "score": 1}  # Alice, score 1 desc
+        assert results[2] == {"name": "Bob", "score": 2}    # Bob
+
     @pytest.mark.asyncio
     async def test_delete_virtual_node_operation(self):
         """Test delete virtual node operation."""

package/flowquery-py/tests/parsing/test_parser.py

@@ -1172,3 +1172,66 @@ class TestParser:
         parser = Parser()
         with pytest.raises(Exception, match="Expected MATCH after OPTIONAL"):
             parser.parse("OPTIONAL RETURN 1")
+
+    # ORDER BY expression tests
+
+    def test_order_by_simple_identifier(self):
+        """Test ORDER BY with a simple identifier parses correctly."""
+        parser = Parser()
+        ast = parser.parse("unwind [1, 2] as x return x order by x")
+        assert ast is not None
+
+    def test_order_by_property_access(self):
+        """Test ORDER BY with property access parses correctly."""
+        parser = Parser()
+        ast = parser.parse(
+            "unwind [{name: 'Bob'}, {name: 'Alice'}] as person "
+            "return person.name as name order by person.name asc"
+        )
+        assert ast is not None
+
+    def test_order_by_function_call(self):
+        """Test ORDER BY with function call parses correctly."""
+        parser = Parser()
+        ast = parser.parse(
+            "unwind ['HELLO', 'WORLD'] as word "
+            "return word order by toLower(word) asc"
+        )
+        assert ast is not None
+
+    def test_order_by_nested_function_calls(self):
+        """Test ORDER BY with nested function calls parses correctly."""
+        parser = Parser()
+        ast = parser.parse(
+            "unwind ['Alice', 'Bob'] as name "
+            "return name order by string_distance(toLower(name), toLower('alice')) asc"
+        )
+        assert ast is not None
+
+    def test_order_by_arithmetic_expression(self):
+        """Test ORDER BY with arithmetic expression parses correctly."""
+        parser = Parser()
+        ast = parser.parse(
+            "unwind [{a: 3, b: 1}, {a: 1, b: 5}] as item "
+            "return item.a as a, item.b as b order by item.a + item.b desc"
+        )
+        assert ast is not None
+
+    def test_order_by_multiple_expression_fields(self):
+        """Test ORDER BY with multiple expression fields parses correctly."""
+        parser = Parser()
+        ast = parser.parse(
+            "unwind [{a: 1, b: 2}] as item "
+            "return item.a as a, item.b as b "
+            "order by toLower(item.a) asc, item.b desc"
+        )
+        assert ast is not None
+
+    def test_order_by_expression_with_limit(self):
+        """Test ORDER BY with expression and LIMIT parses correctly."""
+        parser = Parser()
+        ast = parser.parse(
+            "unwind ['c', 'a', 'b'] as x "
+            "return x order by toLower(x) asc limit 2"
+        )
+        assert ast is not None