Skip to content

Cypher Query Language

TurboLynx's query language is Cypher, as defined by the openCypher specification. A subset of the specification's clauses is currently implemented — see the compatibility matrix below.

Supported Clauses

Clause Status Notes
MATCH ✅ Pattern matching on vertices and edges
OPTIONAL MATCH ✅ Left-outer join semantics
WHERE ✅ Filter predicates on node/rel properties
RETURN ✅ Projection; supports aliases
RETURN DISTINCT / WITH DISTINCT ✅ Deduplicate projected rows
WITH ✅ Pipeline results between clauses
UNWIND ✅ Iterate over a list
ORDER BY ✅ Ascending / descending sort
LIMIT ✅ Limit result count
SKIP ✅ Skip N results
UNION / UNION ALL ✅ Single- and multi-branch UNION (post-#236 fix)
CREATE ✅ Nodes (single/multi-label) and edges through the mutation path shared by the shell, C API, and Python API
SET ✅ Property updates and label widening (SET n:Label)
DELETE / DETACH DELETE ✅ Node + edge delete; DETACH DELETE cascades incident edges
REMOVE ✅ Property and label removal
MERGE 🚧 Basic single-node MERGE only; full pattern MERGE (paths, ON MATCH / ON CREATE) is not implemented

Write queries (CRUD). CREATE, SET, DELETE, DETACH DELETE, REMOVE, and basic node MERGE execute through the native mutation path shared by the shell, C API, and Python API. Mutation queries print an acknowledgment instead of a rowset, so inspect the updated graph with a follow-up MATCH query. Node.js and MCP remain read-only. See test/query/test_ldbc_crud.cpp, test/query/test_ldbc_robustness.cpp, and test/bulkload/test_smoke_cli.cpp for coverage.

Inline Property Filters

Node and relationship patterns support inline property filters using {key: value} syntax. These are semantically equivalent to WHERE predicates:

-- Inline filter (equivalent to WHERE p.id = 933)
MATCH (p:Person {id: 933})-[:KNOWS]->(friend:Person)
RETURN count(friend)

-- WHERE form (equivalent)
MATCH (p:Person)-[:KNOWS]->(friend:Person)
WHERE p.id = 933
RETURN count(friend)

Supported Functions

Function Description
count(*) Count all matching rows
count(expr) Count non-null values of an expression
collect(expr) Aggregate into a list
min(expr), max(expr) Min/max aggregation
sum(expr) Sum aggregation
avg(expr) Arithmetic mean

Supported Expressions

Expression Example
Property access n.firstName
Arithmetic a.age + 1, b.score * 2.0
Comparison =, <>, <, >, <=, >=
Logical AND, OR, NOT
String n.name STARTS WITH 'Al' (via function)
IS NULL / IS NOT NULL WHERE n.email IS NOT NULL
CASE expression CASE WHEN ... THEN ... ELSE ... END

Pattern Comprehension

A pattern comprehension [(a)-[r]->(b) WHERE … | <expr>] evaluates a path pattern against the current row's bindings and projects an expression per match, returning a list. Same shape as Cypher 5 pattern comprehensions.

-- For each Person, collect the firstNames of their friends
MATCH (p:Person)
RETURN p.firstName,
       [(p)-[:KNOWS]->(f:Person) | f.firstName] AS friends;

-- Project a computed value instead of a property
MATCH (p:Person)
RETURN p.firstName,
       [(p)-[:KNOWS]->(f:Person) | f.firstName + ' (' + toString(f.age) + ')'] AS friend_labels;

Path-function comprehensions (length(p), nodes(p), relationships(p)) are supported alongside scalar projections.

Variable-Length Paths

-- 1 to 3 hops
MATCH (a:Person)-[:KNOWS*1..3]->(b:Person)
WHERE a.id = 1
RETURN b.firstName, b.lastName

The lower bound defaults to 1; the upper bound can be omitted for unbounded traversal (*).

Example Queries

Filtered hop traversal

MATCH (a:Person)-[:KNOWS]->(b:Person)
WHERE a.firstName = 'Alice'
RETURN b.firstName, b.lastName;

Aggregation

MATCH (n:Person)
RETURN n.city, COUNT(*) AS cnt
ORDER BY cnt DESC
LIMIT 10;

Multi-hop

MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person)
WHERE a.id = 1
RETURN DISTINCT c.firstName;

Inline property filter

MATCH (p:Person {id: 933})-[:KNOWS]->(friend:Person)
RETURN friend.firstName, friend.lastName;

WITH pipeline

MATCH (p:Person)-[:KNOWS]->(friend:Person)
WHERE p.id = 1
WITH friend
ORDER BY friend.lastName
LIMIT 20
RETURN friend.firstName, friend.lastName;