flowquery 1.0.37 → 1.0.39

package/flowquery-py/pyproject.toml

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

package/flowquery-py/src/parsing/expressions/operator.py

@@ -163,7 +163,7 @@ class Not(Operator):
 
 class Is(Operator):
     def __init__(self) -> None:
-        super().__init__(-1, True)
+        super().__init__(0, True)
 
     def value(self) -> int:
         return 1 if self.lhs.value() == self.rhs.value() else 0
@@ -171,7 +171,7 @@ class Is(Operator):
 
 class IsNot(Operator):
     def __init__(self) -> None:
-        super().__init__(-1, True)
+        super().__init__(0, True)
 
     def value(self) -> int:
         return 1 if self.lhs.value() != self.rhs.value() else 0
@@ -179,7 +179,7 @@ class IsNot(Operator):
 
 class In(Operator):
     def __init__(self) -> None:
-        super().__init__(-1, True)
+        super().__init__(0, True)
 
     def value(self) -> int:
         lst = self.rhs.value()
@@ -190,7 +190,7 @@ class In(Operator):
 
 class NotIn(Operator):
     def __init__(self) -> None:
-        super().__init__(-1, True)
+        super().__init__(0, True)
 
     def value(self) -> int:
         lst = self.rhs.value()

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

@@ -10,6 +10,7 @@ from .limit import Limit
 from .load import Load
 from .match import Match
 from .operation import Operation
+from .order_by import OrderBy, SortField
 from .projection import Projection
 from .return_op import Return
 from .union import Union
@@ -36,4 +37,6 @@ __all__ = [
     "CreateRelationship",
     "Union",
     "UnionAll",
+    "OrderBy",
+    "SortField",
 ]

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

@@ -19,4 +19,7 @@ class AggregatedReturn(Return):
     def results(self) -> List[Dict[str, Any]]:
         if self._where is not None:
             self._group_by.where = self._where
-        return list(self._group_by.generate_results())
+        results = list(self._group_by.generate_results())
+        if self._order_by is not None:
+            results = self._order_by.sort(results)
+        return results

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

@@ -11,6 +11,17 @@ class Limit(Operation):
         self._count = 0
         self._limit = limit
 
+    @property
+    def is_limit_reached(self) -> bool:
+        return self._count >= self._limit
+
+    @property
+    def limit_value(self) -> int:
+        return self._limit
+
+    def increment(self) -> None:
+        self._count += 1
+
     async def run(self) -> None:
         if self._count >= self._limit:
             return

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

@@ -0,0 +1,72 @@
+"""Represents an ORDER BY operation that sorts results."""
+
+from typing import Any, Dict, List
+
+from .operation import Operation
+
+
+class SortField:
+    """A single sort specification: field name and direction."""
+
+    def __init__(self, field: str, direction: str = "asc"):
+        self.field = field
+        self.direction = direction
+
+
+class OrderBy(Operation):
+    """Represents an ORDER BY operation that sorts results.
+
+    Can be attached to a RETURN operation (sorting its results),
+    or used as a standalone accumulating operation after a non-aggregate WITH.
+
+    Example:
+        RETURN x ORDER BY x DESC
+    """
+
+    def __init__(self, fields: List[SortField]):
+        super().__init__()
+        self._fields = fields
+        self._results: List[Dict[str, 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 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)
+                cmp = 0
+                if a_val is None and b_val is None:
+                    cmp = 0
+                elif a_val is None:
+                    cmp = -1
+                elif b_val is None:
+                    cmp = 1
+                elif a_val < b_val:
+                    cmp = -1
+                elif a_val > b_val:
+                    cmp = 1
+                if cmp != 0:
+                    return -cmp if sf.direction == "desc" else cmp
+            return 0
+
+        return sorted(records, key=functools.cmp_to_key(compare))
+
+    async def run(self) -> None:
+        """When used as a standalone operation, passes through to next."""
+        if self.next:
+            await self.next.run()
+
+    async def initialize(self) -> None:
+        self._results = []
+        if self.next:
+            await self.next.initialize()
+
+    @property
+    def results(self) -> List[Dict[str, Any]]:
+        return self._results

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

@@ -4,6 +4,8 @@ import copy
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 from ..ast_node import ASTNode
+from .limit import Limit
+from .order_by import OrderBy
 from .projection import Projection
 
 if TYPE_CHECKING:
@@ -24,6 +26,8 @@ class Return(Projection):
         super().__init__(expressions)
         self._where: Optional['Where'] = None
         self._results: List[Dict[str, Any]] = []
+        self._limit: Optional[Limit] = None
+        self._order_by: Optional[OrderBy] = None
 
     @property
     def where(self) -> Any:
@@ -35,9 +39,29 @@ class Return(Projection):
     def where(self, where: 'Where') -> None:
         self._where = where
 
+    @property
+    def limit(self) -> Optional[Limit]:
+        return self._limit
+
+    @limit.setter
+    def limit(self, limit: Limit) -> None:
+        self._limit = limit
+
+    @property
+    def order_by(self) -> Optional[OrderBy]:
+        return self._order_by
+
+    @order_by.setter
+    def order_by(self, order_by: OrderBy) -> None:
+        self._order_by = order_by
+
     async def run(self) -> None:
         if not self.where:
             return
+        # When ORDER BY is present, skip limit during accumulation;
+        # limit will be applied after sorting in results property
+        if self._order_by is None and self._limit is not None and self._limit.is_limit_reached:
+            return
         record: Dict[str, Any] = {}
         for expression, alias in self.expressions():
             raw = expression.value()
@@ -45,10 +69,17 @@ class Return(Projection):
             value = copy.deepcopy(raw) if isinstance(raw, (dict, list)) else raw
             record[alias] = value
         self._results.append(record)
+        if self._order_by is None and self._limit is not None:
+            self._limit.increment()
 
     async def initialize(self) -> None:
         self._results = []
 
     @property
     def results(self) -> List[Dict[str, Any]]:
-        return self._results
+        result = self._results
+        if self._order_by is not None:
+            result = self._order_by.sort(result)
+        if self._order_by is not None and self._limit is not None:
+            result = result[:self._limit.limit_value]
+        return result

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

@@ -61,6 +61,7 @@ from .operations.limit import Limit
 from .operations.load import Load
 from .operations.match import Match
 from .operations.operation import Operation
+from .operations.order_by import OrderBy, SortField
 from .operations.return_op import Return
 from .operations.union import Union
 from .operations.union_all import UnionAll
@@ -116,6 +117,9 @@ class Parser(BaseParser):
             if self.token.is_union():
                 break
 
+            if self.token.is_eof():
+                break
+
             operation = self._parse_operation()
             if operation is None and not is_sub_query:
                 raise ValueError("Expected one of WITH, UNWIND, RETURN, LOAD, OR CALL")
@@ -143,10 +147,21 @@ class Parser(BaseParser):
                     operation.add_sibling(where)
                     operation = where
 
+            order_by = self._parse_order_by()
+            if order_by is not None:
+                if isinstance(operation, Return):
+                    operation.order_by = order_by
+                else:
+                    operation.add_sibling(order_by)
+                    operation = order_by
+
             limit = self._parse_limit()
             if limit is not None:
-                operation.add_sibling(limit)
-                operation = limit
+                if isinstance(operation, Return):
+                    operation.limit = limit
+                else:
+                    operation.add_sibling(limit)
+                    operation = limit
 
             previous = operation
 
@@ -539,13 +554,11 @@ class Parser(BaseParser):
         node.properties = dict(self._parse_properties())
         if identifier is not None and identifier in self._state.variables:
             reference = self._state.variables.get(identifier)
-            # Resolve through Expression -> Reference -> Node (e.g., after WITH)
-            ref_child = reference.first_child() if isinstance(reference, Expression) else None
-            if isinstance(ref_child, Reference):
-                inner = ref_child.referred
-                if isinstance(inner, Node):
-                    reference = inner
-            if reference is None or (not isinstance(reference, Node) and not isinstance(reference, Unwind)):
+            if reference is None or (
+                not isinstance(reference, Node)
+                and not isinstance(reference, Unwind)
+                and not isinstance(reference, Expression)
+            ):
                 raise ValueError(f"Undefined node reference: {identifier}")
             node = NodeReference(node, reference)
         elif identifier is not None:
@@ -690,6 +703,41 @@ class Parser(BaseParser):
         self.set_next_token()
         return limit
 
+    def _parse_order_by(self) -> Optional[OrderBy]:
+        self._skip_whitespace_and_comments()
+        if not self.token.is_order():
+            return None
+        self._expect_previous_token_to_be_whitespace_or_comment()
+        self.set_next_token()
+        self._expect_and_skip_whitespace_and_comments()
+        if not self.token.is_by():
+            raise ValueError("Expected BY after ORDER")
+        self.set_next_token()
+        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()
+            self._skip_whitespace_and_comments()
+            direction = "asc"
+            if self.token.is_asc():
+                direction = "asc"
+                self.set_next_token()
+                self._skip_whitespace_and_comments()
+            elif self.token.is_desc():
+                direction = "desc"
+                self.set_next_token()
+                self._skip_whitespace_and_comments()
+            fields.append(SortField(field, direction))
+            if self.token.is_comma():
+                self.set_next_token()
+                self._skip_whitespace_and_comments()
+            else:
+                break
+        return OrderBy(fields)
+
     def _parse_expressions(
         self, alias_option: AliasOption = AliasOption.NOT_ALLOWED
     ) -> Iterator[Expression]:

package/flowquery-py/src/tokenization/token.py

@@ -630,6 +630,34 @@ class Token:
     def is_all(self) -> bool:
         return self._type == TokenType.KEYWORD and self._value == Keyword.ALL.value
 
+    @staticmethod
+    def ORDER() -> Token:
+        return Token(TokenType.KEYWORD, Keyword.ORDER.value)
+
+    def is_order(self) -> bool:
+        return self._type == TokenType.KEYWORD and self._value == Keyword.ORDER.value
+
+    @staticmethod
+    def BY() -> Token:
+        return Token(TokenType.KEYWORD, Keyword.BY.value)
+
+    def is_by(self) -> bool:
+        return self._type == TokenType.KEYWORD and self._value == Keyword.BY.value
+
+    @staticmethod
+    def ASC() -> Token:
+        return Token(TokenType.KEYWORD, Keyword.ASC.value)
+
+    def is_asc(self) -> bool:
+        return self._type == TokenType.KEYWORD and self._value == Keyword.ASC.value
+
+    @staticmethod
+    def DESC() -> Token:
+        return Token(TokenType.KEYWORD, Keyword.DESC.value)
+
+    def is_desc(self) -> bool:
+        return self._type == TokenType.KEYWORD and self._value == Keyword.DESC.value
+
     # End of file token
 
     @staticmethod

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

@@ -925,6 +925,20 @@ class TestRunner:
         results = runner.results
         assert len(results) == 50
 
+    @pytest.mark.asyncio
+    async def test_limit_as_last_operation(self):
+        """Test limit as the last operation after return."""
+        runner = Runner(
+            """
+            unwind range(1, 10) as i
+            return i
+            limit 5
+            """
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 5
+
     @pytest.mark.asyncio
     async def test_range_lookup(self):
         """Test range lookup."""
@@ -1457,6 +1471,71 @@ class TestRunner:
         assert results[0] == {"name1": "Person 1", "name2": "Person 2", "name3": "Person 3"}
         assert results[1] == {"name1": "Person 2", "name2": "Person 3", "name3": "Person 4"}
 
+    @pytest.mark.asyncio
+    async def test_match_with_aggregated_with_and_subsequent_match(self):
+        """Test match with aggregated WITH followed by another match using the same node reference."""
+        await Runner(
+            """
+            CREATE VIRTUAL (:AggUser) AS {
+                unwind [
+                    {id: 1, name: 'Alice'},
+                    {id: 2, name: 'Bob'},
+                    {id: 3, name: 'Carol'}
+                ] as record
+                RETURN record.id as id, record.name as name
+            }
+            """
+        ).run()
+        await Runner(
+            """
+            CREATE VIRTUAL (:AggUser)-[:KNOWS]-(:AggUser) AS {
+                unwind [
+                    {left_id: 1, right_id: 2},
+                    {left_id: 1, right_id: 3}
+                ] as record
+                RETURN record.left_id as left_id, record.right_id as right_id
+            }
+            """
+        ).run()
+        await Runner(
+            """
+            CREATE VIRTUAL (:AggProject) AS {
+                unwind [
+                    {id: 1, name: 'Project A'},
+                    {id: 2, name: 'Project B'}
+                ] as record
+                RETURN record.id as id, record.name as name
+            }
+            """
+        ).run()
+        await Runner(
+            """
+            CREATE VIRTUAL (:AggUser)-[:WORKS_ON]-(:AggProject) AS {
+                unwind [
+                    {left_id: 1, right_id: 1},
+                    {left_id: 1, right_id: 2}
+                ] as record
+                RETURN record.left_id as left_id, record.right_id as right_id
+            }
+            """
+        ).run()
+        match = Runner(
+            """
+            MATCH (u:AggUser)-[:KNOWS]->(s:AggUser)
+            WITH u, count(s) as acquaintances
+            MATCH (u)-[:WORKS_ON]->(p:AggProject)
+            RETURN u.name as name, acquaintances, collect(p.name) as projects
+            """
+        )
+        await match.run()
+        results = match.results
+        assert len(results) == 1
+        assert results[0] == {
+            "name": "Alice",
+            "acquaintances": 2,
+            "projects": ["Project A", "Project B"],
+        }
+
     @pytest.mark.asyncio
     async def test_match_and_return_full_node(self):
         """Test match and return full node."""
@@ -2719,6 +2798,58 @@ class TestRunner:
         assert len(results) == 3
         assert [r["n"] for r in results] == [10, 15, 20]
 
+    @pytest.mark.asyncio
+    async def test_where_with_and_before_in(self):
+        """Test WHERE with AND before IN (IN on right side of AND)."""
+        runner = Runner("""
+            unwind ['expert', 'intermediate', 'beginner'] as proficiency
+            with proficiency where 1=1 and proficiency in ['expert']
+            return proficiency
+        """)
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"proficiency": "expert"}
+
+    @pytest.mark.asyncio
+    async def test_where_with_and_before_not_in(self):
+        """Test WHERE with AND before NOT IN."""
+        runner = Runner("""
+            unwind ['expert', 'intermediate', 'beginner'] as proficiency
+            with proficiency where 1=1 and proficiency not in ['expert']
+            return proficiency
+        """)
+        await runner.run()
+        results = runner.results
+        assert len(results) == 2
+        assert [r["proficiency"] for r in results] == ["intermediate", "beginner"]
+
+    @pytest.mark.asyncio
+    async def test_where_with_or_before_in(self):
+        """Test WHERE with OR before IN."""
+        runner = Runner("""
+            unwind range(1, 10) as n
+            with n where 1=0 or n in [3, 7]
+            return n
+        """)
+        await runner.run()
+        results = runner.results
+        assert len(results) == 2
+        assert [r["n"] for r in results] == [3, 7]
+
+    @pytest.mark.asyncio
+    async def test_in_as_return_expression_with_and_in_where(self):
+        """Test IN as return expression with AND in WHERE."""
+        runner = Runner("""
+            unwind ['expert', 'intermediate', 'beginner'] as proficiency
+            with proficiency where 1=1 and proficiency in ['expert']
+            return proficiency, proficiency in ['expert'] as isExpert
+        """)
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"proficiency": "expert", "isExpert": 1}
+
     @pytest.mark.asyncio
     async def test_where_with_contains(self):
         """Test WHERE with CONTAINS."""
@@ -3932,4 +4063,110 @@ class TestRunner:
         assert d["hours"] == 2
         assert d["minutes"] == 30
         assert d["totalSeconds"] == 9000
-        assert d["formatted"] == "PT2H30M"
+        assert d["formatted"] == "PT2H30M"
+
+    # ORDER BY tests
+
+    @pytest.mark.asyncio
+    async def test_order_by_ascending(self):
+        """Test ORDER BY ascending (default)."""
+        runner = Runner("unwind [3, 1, 2] as x return x order by x")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"x": 1}
+        assert results[1] == {"x": 2}
+        assert results[2] == {"x": 3}
+
+    @pytest.mark.asyncio
+    async def test_order_by_descending(self):
+        """Test ORDER BY descending."""
+        runner = Runner("unwind [3, 1, 2] as x return x order by x desc")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"x": 3}
+        assert results[1] == {"x": 2}
+        assert results[2] == {"x": 1}
+
+    @pytest.mark.asyncio
+    async def test_order_by_ascending_explicit(self):
+        """Test ORDER BY with explicit ASC."""
+        runner = Runner("unwind [3, 1, 2] as x return x order by x asc")
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"x": 1}
+        assert results[1] == {"x": 2}
+        assert results[2] == {"x": 3}
+
+    @pytest.mark.asyncio
+    async def test_order_by_with_multiple_fields(self):
+        """Test ORDER BY with multiple sort fields."""
+        runner = Runner(
+            "unwind [{name: 'Alice', age: 30}, {name: 'Bob', age: 25}, {name: 'Alice', age: 25}] as person "
+            "return person.name as name, person.age as age "
+            "order by name asc, age asc"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"name": "Alice", "age": 25}
+        assert results[1] == {"name": "Alice", "age": 30}
+        assert results[2] == {"name": "Bob", "age": 25}
+
+    @pytest.mark.asyncio
+    async def test_order_by_with_strings(self):
+        """Test ORDER BY with string values."""
+        runner = Runner(
+            "unwind ['banana', 'apple', 'cherry'] as fruit return fruit order by 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_aggregated_return(self):
+        """Test ORDER BY with aggregated RETURN."""
+        runner = Runner(
+            "unwind [1, 1, 2, 2, 3, 3] as x "
+            "return x, count(x) as cnt "
+            "order by x desc"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"x": 3, "cnt": 2}
+        assert results[1] == {"x": 2, "cnt": 2}
+        assert results[2] == {"x": 1, "cnt": 2}
+
+    @pytest.mark.asyncio
+    async def test_order_by_with_limit(self):
+        """Test ORDER BY combined with LIMIT."""
+        runner = Runner(
+            "unwind [3, 1, 4, 1, 5, 9, 2, 6] as x return x order by x limit 3"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"x": 1}
+        assert results[1] == {"x": 1}
+        assert results[2] == {"x": 2}
+
+    @pytest.mark.asyncio
+    async def test_order_by_with_where(self):
+        """Test ORDER BY combined with WHERE."""
+        runner = Runner(
+            "unwind [3, 1, 4, 1, 5, 9, 2, 6] as x return x where x > 2 order by x desc"
+        )
+        await runner.run()
+        results = runner.results
+        assert len(results) == 5
+        assert results[0] == {"x": 9}
+        assert results[1] == {"x": 6}
+        assert results[2] == {"x": 5}
+        assert results[3] == {"x": 4}
+        assert results[4] == {"x": 3}