Developer API

OpenCypher Query Engine.

KGL includes an in-memory OpenCypher query engine. There is no external database — the .kgl file system is the store. Queries run directly against a Graph loaded from disk.

Python API

from kgl.model import Graph
from kgl.query.engine import QueryEngine

graph = Graph.load("./")
engine = QueryEngine(graph)

results = engine.run("""
    MATCH (p:Person)-[r:mentors]->(q:Person)
    WHERE p.name = "Alice Nguyen"
    RETURN p.name, q.name, r.started
""")

for row in results:
    print(row)
# {"p.name": "Alice Nguyen", "q.name": "Diana Park", "r.started": "2023-06"}

engine.run(query_str) returns list[dict[str, Any]]. Each dict maps return variable names (or aliases) to their values.

Supported syntax

Phase 1 — core implemented

Phase 2 — extended planned

• OPTIONAL MATCH — missing match returns null row, not empty result
• WITH — pipeline intermediate results
• SKIP n — offset results

Phase 3 — aggregations planned

• COUNT(n), COUNT(*)
• COLLECT(n.field)
• DISTINCT
• Variable-length paths: (n)-[*1..3]->(m)

CLI usage

kgl query ./ "MATCH (p:Person)-[r:mentors]->(q:Person) RETURN p.name, q.name, r.started"

p.name        q.name      r.started
────────────  ──────────  ──────────
Alice Nguyen  Diana Park  2023-06

kgl query ./ "MATCH (n:Person) RETURN n.name" --format json

kgl query ./ "MATCH (n:Person) RETURN n.name" --format csv

Architecture

The query engine has three independently testable components:

1. Lexer (kgl/query/lexer.py) — tokenises an OpenCypher string into typed tokens
2. Parser (kgl/query/parser.py) — recursive-descent parser producing an AST
3. Engine (kgl/query/engine.py) — executes a parsed query against a Graph

Execution strategy

For v0.1, the engine uses brute-force enumeration. This is acceptable for human-scale graphs (thousands of nodes, not millions).

1. Seed — enumerate all candidate nodes/edges matching the first MATCH pattern
2. Extend — for each candidate, extend the pattern along each additional path segment
3. Filter — apply WHERE clause to each binding
4. Project — evaluate RETURN expressions
5. Post-process — apply ORDER BY and LIMIT

Known limitations vs full OpenCypher