gestaltdb 0.3.0__py3-none-any.whl

gestaltdb/__init__.py

@@ -0,0 +1,7 @@
+"""GestaltDB package."""
+
+from .sampling import SamplingHop, SamplingPattern
+from .ingestion import EdgeList, NodeList
+from .cypher import QueryResult
+
+__all__ = ["EdgeList", "NodeList", "QueryResult", "SamplingHop", "SamplingPattern"]

gestaltdb/cypher.py

@@ -0,0 +1,104 @@
+"""Minimal read-only Cypher support for GestaltDB.
+
+The supported subset maps directly to existing typed adjacency and sampling APIs:
+
+    MATCH (a {id: "node-id"})-[:TYPE1]->(b)<-[:TYPE2]-(c) RETURN a.name, b LIMIT 10
+    CALL pg.sample_typed_paths(["node-id"], [{"edge_type": "TYPE", "sample_size": 2}]) YIELD path RETURN path
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .cypher_ast import MatchQuery, MultiMatchQuery, NodeScanQuery, RelationshipScanQuery, SampleTypedPathsCall
+from .cypher_plan import LogicalPlan, plan_query
+from .cypher_parser import parse as _parse_query, split_top_level_args as _split_top_level_args
+from .cypher_runtime import QueryContext, execute_match, execute_multi_match, execute_node_scan, execute_relationship_scan
+
+
+@dataclass(frozen=True)
+class QueryResult:
+    """Tabular query result returned by ``GraphDB.query``.
+
+    ``columns`` contains projected column names in return order. ``records`` is
+    a list of dictionaries keyed by column name.
+
+    Examples:
+        >>> result = QueryResult(columns=("n",), records=[{"n": "node"}])
+        >>> len(result)
+        1
+        >>> list(result)[0]["n"]
+        'node'
+    """
+
+    columns: tuple[str, ...]
+    records: list[dict[str, object]]
+
+    def __iter__(self):
+        """Iterate over result records."""
+        return iter(self.records)
+
+    def __len__(self):
+        """Return the number of result records."""
+        return len(self.records)
+
+
+def parse(query: str) -> MatchQuery | SampleTypedPathsCall | NodeScanQuery | RelationshipScanQuery | MultiMatchQuery:
+    """Parse the supported Cypher subset.
+
+    Args:
+        query: Cypher query text.
+
+    Returns:
+        Parsed query object.
+
+    Raises:
+        ValueError: If the query is outside the supported subset.
+
+    Examples:
+        >>> parse('MATCH (n:Drug) RETURN n').label
+        'Drug'
+    """
+    return _parse_query(query)
+
+
+def plan(query: str) -> LogicalPlan:
+    """Return the logical plan for a supported Cypher query."""
+    return plan_query(parse(query))
+
+
+def execute(graph, query: str, parameters: dict[str, object] | None = None) -> QueryResult:
+    """Execute a supported Cypher query against a ``GraphDB`` instance.
+
+    Args:
+        graph: ``GraphDB`` instance used for indexed lookups and traversal.
+        query: Cypher query text.
+
+    Returns:
+        ``QueryResult`` with projected records.
+
+    Examples:
+        >>> execute(graph_db, 'MATCH (n:Drug) RETURN n')  # doctest: +SKIP
+    """
+    parsed = parse(query)
+    plan_query(parsed)
+    parameters = parameters or {}
+    if isinstance(parsed, SampleTypedPathsCall):
+        paths = graph.sample_typed_paths(parsed.seed_ids, parsed.pattern)
+        if parsed.limit is not None:
+            paths = paths[:parsed.limit]
+        return QueryResult(
+            columns=parsed.returns,
+            records=[{"path": path} for path in paths],
+        )
+    if isinstance(parsed, NodeScanQuery):
+        records = execute_node_scan(parsed, QueryContext(graph=graph, parameters=parameters))
+        return QueryResult(columns=parsed.returns, records=records)
+    if isinstance(parsed, RelationshipScanQuery):
+        records = execute_relationship_scan(parsed, QueryContext(graph=graph, parameters=parameters))
+        return QueryResult(columns=parsed.returns, records=records)
+    if isinstance(parsed, MultiMatchQuery):
+        records = execute_multi_match(parsed, QueryContext(graph=graph, parameters=parameters))
+        return QueryResult(columns=parsed.returns, records=records)
+    records = execute_match(parsed, QueryContext(graph=graph, parameters=parameters))
+    return QueryResult(columns=parsed.returns, records=records)

gestaltdb/cypher_ast.py

@@ -0,0 +1,180 @@
+"""AST objects for the GestaltDB Cypher subset."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Parameter:
+    """Cypher query parameter reference, such as ``$name``."""
+
+    name: str
+
+
+@dataclass(frozen=True)
+class PropertyRef:
+    """Reference to a variable property, such as ``n.name``."""
+
+    variable: str
+    property_name: str
+
+
+@dataclass(frozen=True)
+class ComparisonExpression:
+    """Binary comparison expression for the current Cypher subset."""
+
+    left: PropertyRef
+    operator: str
+    right: object
+
+
+@dataclass(frozen=True)
+class InExpression:
+    """Membership predicate, such as ``n.kind IN ["drug"]``."""
+
+    left: PropertyRef
+    values: object
+
+
+@dataclass(frozen=True)
+class NullPredicate:
+    """Null check predicate."""
+
+    expression: PropertyRef
+    negated: bool = False
+
+
+@dataclass(frozen=True)
+class AndExpression:
+    """Conjunction of boolean expressions."""
+
+    expressions: tuple[object, ...]
+
+
+@dataclass(frozen=True)
+class OrderItem:
+    """One ORDER BY item."""
+
+    expression: str
+    descending: bool = False
+
+
+@dataclass(frozen=True)
+class TraversalHop:
+    """One typed relationship expansion in a parsed ``MATCH`` pattern."""
+
+    rel_var: str | None
+    edge_type: str
+    target_var: str
+    direction: str = "out"
+    edge_types: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class MatchQuery:
+    """Parsed anchored typed path query."""
+
+    source_var: str
+    source_id: str
+    hops: tuple[TraversalHop, ...]
+    returns: tuple[str, ...]
+    limit: int | None = None
+    where: object | None = None
+    projections: tuple[str, ...] = ()
+    order_by: tuple[OrderItem, ...] = ()
+    skip: int | None = None
+    distinct: bool = False
+
+
+@dataclass(frozen=True)
+class NodePatternClause:
+    """One node pattern in a multi-clause ``MATCH`` query."""
+
+    variable: str
+    label: str | None = None
+    property_name: str | None = None
+    property_value: object = None
+    labels: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class RelationshipPatternClause:
+    """One relationship pattern in a multi-clause ``MATCH`` query."""
+
+    source_var: str
+    rel_var: str | None
+    edge_type: str
+    target_var: str
+    direction: str = "out"
+    edge_types: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class AnchoredPatternClause:
+    """One anchored traversal pattern in a multi-clause ``MATCH`` query."""
+
+    source_var: str
+    source_id: str
+    hops: tuple[TraversalHop, ...]
+
+
+@dataclass(frozen=True)
+class MultiMatchQuery:
+    """Parsed query containing multiple ``MATCH`` clauses."""
+
+    clauses: tuple[object, ...]
+    returns: tuple[str, ...]
+    where: object | None = None
+    projections: tuple[str, ...] = ()
+    order_by: tuple[OrderItem, ...] = ()
+    skip: int | None = None
+    limit: int | None = None
+    distinct: bool = False
+
+
+@dataclass(frozen=True)
+class SampleTypedPathsCall:
+    """Parsed ``pg.sample_typed_paths`` procedure call."""
+
+    seed_ids: list[str]
+    pattern: list[dict[str, object]]
+    returns: tuple[str, ...] = ("path",)
+    limit: int | None = None
+
+
+@dataclass(frozen=True)
+class NodeScanQuery:
+    """Parsed indexed node label scan query."""
+
+    variable: str
+    label: str | None
+    property_name: str | None
+    property_value: object
+    returns: tuple[str, ...]
+    limit: int | None = None
+    where: object | None = None
+    labels: tuple[str, ...] = ()
+    projections: tuple[str, ...] = ()
+    order_by: tuple[OrderItem, ...] = ()
+    skip: int | None = None
+    distinct: bool = False
+
+
+@dataclass(frozen=True)
+class RelationshipScanQuery:
+    """Parsed unanchored typed relationship scan query."""
+
+    source_var: str
+    rel_var: str | None
+    edge_type: str
+    target_var: str
+    returns: tuple[str, ...]
+    direction: str = "out"
+    edge_types: tuple[str, ...] = ()
+    where: object | None = None
+    projections: tuple[str, ...] = ()
+    order_by: tuple[OrderItem, ...] = ()
+    skip: int | None = None
+    limit: int | None = None
+    distinct: bool = False