flowquery 1.0.21 → 1.0.23

package/flowquery-py/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flowquery"
-version = "1.0.11"
+version = "1.0.13"
 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 Dict, Optional, Union
+from typing import Any, Dict, Optional, Union
 
 from ..parsing.ast_node import ASTNode
 from .node import Node
@@ -54,6 +54,30 @@ class Database:
         """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]]:
+        """Returns the graph schema with node/relationship labels and sample data."""
+        result: list[dict[str, Any]] = []
+
+        for label, physical_node in Database._nodes.items():
+            records = await physical_node.data()
+            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:
+                    entry["sample"] = sample
+            result.append(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}
+            if records:
+                sample = {k: v for k, v in records[0].items() if k not in ("left_id", "right_id")}
+                if sample:
+                    entry_rel["sample"] = sample
+            result.append(entry_rel)
+
+        return result
+
     async def get_data(self, element: Union['Node', 'Relationship']) -> Union['NodeData', 'RelationshipData']:
         """Gets data for a node or relationship."""
         if isinstance(element, Node):

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

@@ -27,6 +27,7 @@ from .range_ import Range
 from .reducer_element import ReducerElement
 from .replace import Replace
 from .round_ import Round
+from .schema import Schema
 from .size import Size
 from .split import Split
 from .stringify import Stringify
@@ -71,5 +72,6 @@ __all__ = [
     "ToJson",
     "Type",
     "Functions",
+    "Schema",
     "PredicateSum",
 ]

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

@@ -0,0 +1,36 @@
+"""Schema introspection function."""
+
+from typing import Any, AsyncGenerator
+
+from .async_function import AsyncFunction
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": (
+        "Returns the graph schema listing all nodes and relationships "
+        "with a sample of their data."
+    ),
+    "category": "async",
+    "parameters": [],
+    "output": {
+        "description": "Schema entry with kind, label/type, and optional sample data",
+        "type": "object",
+    },
+    "examples": [
+        "CALL schema() YIELD kind, label, type, sample RETURN kind, label, type, sample",
+    ],
+})
+class Schema(AsyncFunction):
+    """Returns the graph schema of the database.
+
+    Lists all nodes and relationships with their labels/types and a sample
+    of their data (excluding id from nodes, left_id and right_id from relationships).
+    """
+
+    async def generate(self) -> AsyncGenerator[Any, None]:
+        # Import at runtime to avoid circular dependency
+        from ...graph.database import Database
+        entries = await Database.get_instance().schema()
+        for entry in entries:
+            yield entry

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

@@ -326,7 +326,7 @@ class Parser(BaseParser):
             if not self.token.is_colon():
                 raise ValueError("Expected ':' for relationship type")
             self.set_next_token()
-            if not self.token.is_identifier():
+            if not self.token.is_identifier_or_keyword():
                 raise ValueError("Expected relationship type identifier")
             rel_type = self.token.value or ""
             self.set_next_token()
@@ -450,17 +450,17 @@ class Parser(BaseParser):
         self.set_next_token()
         self._skip_whitespace_and_comments()
         identifier: Optional[str] = None
-        if self.token.is_identifier():
+        if self.token.is_identifier_or_keyword():
             identifier = self.token.value
             self.set_next_token()
         self._skip_whitespace_and_comments()
         label: Optional[str] = None
         peek = self.peek()
-        if not self.token.is_colon() and peek is not None and peek.is_identifier():
+        if not self.token.is_colon() and peek is not None and peek.is_identifier_or_keyword():
             raise ValueError("Expected ':' for node label")
-        if self.token.is_colon() and (peek is None or not peek.is_identifier()):
+        if self.token.is_colon() and (peek is None or not peek.is_identifier_or_keyword()):
             raise ValueError("Expected node label identifier")
-        if self.token.is_colon() and peek is not None and peek.is_identifier():
+        if self.token.is_colon() and peek is not None and peek.is_identifier_or_keyword():
             self.set_next_token()
             label = cast(str, self.token.value)  # Guaranteed by is_identifier check
             self.set_next_token()
@@ -495,13 +495,13 @@ class Parser(BaseParser):
             return None
         self.set_next_token()
         variable: Optional[str] = None
-        if self.token.is_identifier():
+        if self.token.is_identifier_or_keyword():
             variable = self.token.value
             self.set_next_token()
         if not self.token.is_colon():
             raise ValueError("Expected ':' for relationship type")
         self.set_next_token()
-        if not self.token.is_identifier():
+        if not self.token.is_identifier_or_keyword():
             raise ValueError("Expected relationship type identifier")
         rel_type: str = self.token.value or ""
         self.set_next_token()
@@ -633,14 +633,14 @@ class Parser(BaseParser):
     def _parse_operand(self, expression: Expression) -> bool:
         """Parse a single operand (without operators). Returns True if an operand was parsed."""
         self._skip_whitespace_and_comments()
-        if self.token.is_identifier() and (self.peek() is None or not self.peek().is_left_parenthesis()):
+        if self.token.is_identifier_or_keyword() and (self.peek() is None or not self.peek().is_left_parenthesis()):
             identifier = self.token.value or ""
             reference = Reference(identifier, self._variables.get(identifier))
             self.set_next_token()
             lookup = self._parse_lookup(reference)
             expression.add_node(lookup)
             return True
-        elif self.token.is_identifier() and self.peek() is not None and self.peek().is_left_parenthesis():
+        elif self.token.is_identifier_or_keyword() and self.peek() is not None and self.peek().is_left_parenthesis():
             func = self._parse_predicate_function() or self._parse_function()
             if func is not None:
                 lookup = self._parse_lookup(func)
@@ -650,7 +650,7 @@ class Parser(BaseParser):
             self.token.is_left_parenthesis()
             and self.peek() is not None
             and (
-                self.peek().is_identifier()
+                self.peek().is_identifier_or_keyword()
                 or self.peek().is_colon()
                 or self.peek().is_right_parenthesis()
             )
@@ -734,7 +734,7 @@ class Parser(BaseParser):
         while True:
             if self.token.is_dot():
                 self.set_next_token()
-                if not self.token.is_identifier() and not self.token.is_keyword():
+                if not self.token.is_identifier_or_keyword():
                     raise ValueError("Expected identifier")
                 lookup = Lookup()
                 lookup.index = Identifier(self.token.value or "")
@@ -847,7 +847,7 @@ class Parser(BaseParser):
         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_identifier():
+        if not self.token.is_identifier_or_keyword():
             raise ValueError("Expected identifier")
         alias = Alias(self.token.value or "")
         self.set_next_token()

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

@@ -106,6 +106,24 @@ class Token:
     def is_identifier(self) -> bool:
         return self._type == TokenType.IDENTIFIER or self._type == TokenType.BACKTICK_STRING
 
+    def is_keyword_that_cannot_be_identifier(self) -> bool:
+        """Returns True for keywords that have special expression-level roles
+        and should not be treated as identifiers (NULL, CASE, WHEN, THEN, ELSE, END)."""
+        return self.is_keyword() and (
+            self.is_null()
+            or self.is_case()
+            or self.is_when()
+            or self.is_then()
+            or self.is_else()
+            or self.is_end()
+        )
+
+    def is_identifier_or_keyword(self) -> bool:
+        """Returns True if the token is an identifier or a keyword that can be used as an identifier."""
+        return self.is_identifier() or (
+            self.is_keyword() and not self.is_keyword_that_cannot_be_identifier()
+        )
+
     # String token
 
     @staticmethod

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

@@ -1539,4 +1539,108 @@ class TestRunner:
         await match.run()
         results = match.results
         assert len(results) == 1
-        assert results[0]["name"] == "Employee 1"
+        assert results[0]["name"] == "Employee 1"
+
+    @pytest.mark.asyncio
+    async def test_schema_returns_nodes_and_relationships_with_sample_data(self):
+        """Test schema() returns nodes and relationships with sample data."""
+        await Runner(
+            """
+            CREATE VIRTUAL (:Animal) AS {
+                UNWIND [
+                    {id: 1, species: 'Cat', legs: 4},
+                    {id: 2, species: 'Dog', legs: 4}
+                ] AS record
+                RETURN record.id AS id, record.species AS species, record.legs AS legs
+            }
+            """
+        ).run()
+        await Runner(
+            """
+            CREATE VIRTUAL (:Animal)-[:CHASES]-(:Animal) AS {
+                UNWIND [
+                    {left_id: 2, right_id: 1, speed: 'fast'}
+                ] AS record
+                RETURN record.left_id AS left_id, record.right_id AS right_id, record.speed AS speed
+            }
+            """
+        ).run()
+
+        runner = Runner(
+            "CALL schema() YIELD kind, label, type, sample RETURN kind, label, type, sample"
+        )
+        await runner.run()
+        results = runner.results
+
+        animal = next((r for r in results if r.get("kind") == "node" and r.get("label") == "Animal"), None)
+        assert animal is not None
+        assert animal["sample"] is not None
+        assert "id" not in animal["sample"]
+        assert "species" in animal["sample"]
+        assert "legs" in animal["sample"]
+
+        chases = next((r for r in results if r.get("kind") == "relationship" and r.get("type") == "CHASES"), None)
+        assert chases is not None
+        assert chases["sample"] is not None
+        assert "left_id" not in chases["sample"]
+        assert "right_id" not in chases["sample"]
+        assert "speed" in chases["sample"]
+
+    @pytest.mark.asyncio
+    async def test_reserved_keywords_as_identifiers(self):
+        """Test reserved keywords as identifiers."""
+        runner = Runner("""
+            WITH 1 AS return
+            RETURN return
+        """)
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0]["return"] == 1
+
+    @pytest.mark.asyncio
+    async def test_reserved_keywords_as_parts_of_identifiers(self):
+        """Test reserved keywords as parts of identifiers."""
+        runner = Runner("""
+            unwind [
+                {from: "Alice", to: "Bob", organizer: "Charlie"},
+                {from: "Bob", to: "Charlie", organizer: "Alice"},
+                {from: "Charlie", to: "Alice", organizer: "Bob"}
+            ] as data
+            return data.from as from, data.to as to, data.organizer as organizer
+        """)
+        await runner.run()
+        results = runner.results
+        assert len(results) == 3
+        assert results[0] == {"from": "Alice", "to": "Bob", "organizer": "Charlie"}
+        assert results[1] == {"from": "Bob", "to": "Charlie", "organizer": "Alice"}
+        assert results[2] == {"from": "Charlie", "to": "Alice", "organizer": "Bob"}
+
+    @pytest.mark.asyncio
+    async def test_reserved_keywords_as_relationship_types_and_labels(self):
+        """Test reserved keywords as relationship types and labels."""
+        await Runner("""
+            CREATE VIRTUAL (:Return) AS {
+                unwind [
+                    {id: 1, name: 'Node 1'},
+                    {id: 2, name: 'Node 2'}
+                ] as record
+                RETURN record.id as id, record.name as name
+            }
+        """).run()
+        await Runner("""
+            CREATE VIRTUAL (:Return)-[:With]-(:Return) AS {
+                unwind [
+                    {left_id: 1, right_id: 2}
+                ] as record
+                RETURN record.left_id as left_id, record.right_id as right_id
+            }
+        """).run()
+        runner = Runner("""
+            MATCH (a:Return)-[:With]->(b:Return)
+            RETURN a.name AS name1, b.name AS name2
+        """)
+        await runner.run()
+        results = runner.results
+        assert len(results) == 1
+        assert results[0] == {"name1": "Node 1", "name2": "Node 2"}

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

@@ -719,3 +719,12 @@ class TestParser:
         assert isinstance(relationship, Relationship)
         assert relationship.properties.get("since") is not None
         assert relationship.properties["since"].value() == 2022
+
+    def test_case_statement_with_keywords_as_identifiers(self):
+        """Test that CASE/WHEN/THEN/ELSE/END are not treated as identifiers."""
+        parser = Parser()
+        ast = parser.parse("RETURN CASE WHEN 1 THEN 2 ELSE 3 END")
+        assert "Case" in ast.print()
+        assert "When" in ast.print()
+        assert "Then" in ast.print()
+        assert "Else" in ast.print()

package/flowquery-py/tests/tokenization/test_tokenizer.py

@@ -162,3 +162,37 @@ class TestTokenizer:
         tokens = tokenizer.tokenize()
         assert tokens is not None
         assert len(tokens) > 0
+
+    def test_reserved_keywords_as_identifiers(self):
+        """Test reserved keywords as identifiers."""
+        tokenizer = Tokenizer("""
+            WITH 1 AS return
+            RETURN return
+        """)
+        tokens = tokenizer.tokenize()
+        assert tokens is not None
+        assert len(tokens) > 0
+
+    def test_reserved_keywords_as_part_of_identifiers(self):
+        """Test reserved keywords as part of identifiers."""
+        tokenizer = Tokenizer("""
+            unwind [
+                {from: "Alice", to: "Bob", organizer: "Charlie"},
+                {from: "Bob", to: "Charlie", organizer: "Alice"},
+                {from: "Charlie", to: "Alice", organizer: "Bob"}
+            ] as data
+            return data.from, data.to
+        """)
+        tokens = tokenizer.tokenize()
+        assert tokens is not None
+        assert len(tokens) > 0
+
+    def test_reserved_keywords_as_relationship_types_and_labels(self):
+        """Test reserved keywords as relationship types and labels."""
+        tokenizer = Tokenizer("""
+            MATCH (a:RETURN)-[r:WITH]->(b:RETURN)
+            RETURN a, b
+        """)
+        tokens = tokenizer.tokenize()
+        assert tokens is not None
+        assert len(tokens) > 0