flowquery 1.0.21 → 1.0.22

package/flowquery-py/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flowquery"
-version = "1.0.11"
+version = "1.0.12"
 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/tests/compute/test_runner.py

@@ -1539,4 +1539,49 @@ 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"]