TuringDB v3 (turingdb 3.1 on PyPI and npm) runs every query on a new MLIR-based engine and supports most of openCypher, extended with versioning, vector search and fast lookup by native node ID.
If you know Cypher from Neo4j, you can write the queries you are used to. This page covers the basics and the handful of places where TuringDB differs. The rest of the language is documented in the pages that follow.
What is supported
| Area | Supported |
|---|---|
| Reading | MATCH, OPTIONAL MATCH, WHERE, WITH, RETURN [DISTINCT], ORDER BY, SKIP, LIMIT, UNWIND, UNION [ALL], LOAD CSV |
| Composing queries | NEXT to chain queries, WHEN ... THEN ... ELSE conditional queries |
| Patterns | Multiple labels, label expressions (:A|B, :!A, :A&B), edge type alternatives ([:A|B]), inline WHERE, variable-length paths (*1..3, ->+, {2,4}), quantified path patterns, named paths, pattern predicates |
| Expressions | Arithmetic, string and list concatenation, CASE, list and pattern comprehensions, reduce, allReduce, all / any / none / single, exists() over a pattern, IS label tests, list slicing, maps, map access (m.key, m['key']) and map projection (n {.name, .age}) |
| Functions | String (substring, split, replace, left, right, normalize, …), math, conversion, keys, properties, elementId, isEmpty, coll.indexOf, spatial (point, point.distance, point.withinBBox) |
| Aggregation | count, sum, avg, min, max, collect, stDev, stDevP, percentileCont, percentileDisc, DISTINCT, implicit grouping, aggregates inside expressions |
| Subqueries | EXISTS { }, COUNT { }, COLLECT { }, CALL { }, CALL (*) { } and OPTIONAL CALL { }, with UNION, NEXT and WHEN inside any of them |
| Writing | CREATE, MERGE with ON CREATE / ON MATCH, SET (including SET n = {...} and SET n += {...}), REMOVE, DELETE, DETACH DELETE, FOREACH |
| Parameters | Values anywhere an expression goes (WHERE n.age > $min, UNWIND $rows), labels and edge types (MATCH (n:$label)) |
| Types | String, Integer, Double, Boolean, List, Map, DateTime, Duration, Point, Embedding |
| TuringDB extras | Changes, commits and time travel, shortestPath, VECTOR SEARCH, gnn.graphSAGE, lookup by native node ID |
Basics
Queries are built from nodes and edges:
- Nodes are written in parentheses:
(n)is a node namedn. - Edges are written in square brackets:
[e]is an edge namede. - Labels are added with a colon:
(n:Person). A node can have several:(n:Person:Employee). - Edge types use the same syntax:
[e:FRIENDS_WITH]. An edge has exactly one edge type. - Properties are constrained with curly braces:
(n:Person {name: 'John', age: 20}).
MATCH (a:Person {name: 'Alice'})-[e:KNOWS]->(b:Person)
RETURN a.name, e.since, b.nameBy convention, node labels are written in PascalCase (Person, BankAccount), edge types in upper case with underscores (WORKS_AT, FRIENDS_WITH), and strings use single quotes.
Keywords are case-insensitive (MATCH and match are the same), and a keyword can also be a name: WITH n.name AS count, n.age AS order is valid. Labels, edge types and property names are case-sensitive. // starts a line comment and /* */ encloses a block comment:
// a line comment
MATCH (n:Person) /* a block comment */
RETURN n.name // also fine at the end of a lineSQL-style -- comments are not supported. Use // instead.
Running a query
Queries run through the Python SDK, the JavaScript SDK, or the interactive shell. Read queries run directly against the current graph; write queries must run inside a change.
from turingdb import TuringDB
client = TuringDB(host="localhost", port=6666)
# a pandas DataFrame
df = client.query("MATCH (n:Person) RETURN n.name, n.age")import { TuringClient } from "turingdb";
const client = new TuringClient({
url: "http://localhost:6686/query",
});
// chunks of columns
const chunks = await client.queryData(
"MATCH (n:Person) RETURN n.name, n.age",
);EXPLAIN <query> returns the compiled query plan without running the query, and EXPLAIN (db) <query> shows only the database plan. It is the easiest way to check how a lookup runs.
Query parameters
client.query() takes an optional dictionary of parameters. A $name parameter stands for a value anywhere an expression goes, so values travel next to the query text and need no quoting or escaping:
client.query(
"MATCH (n:Person) WHERE n.age >= $minAge RETURN n.name",
{"minAge": 30},
)
client.query(
"MATCH (n:Person {name: $name}) RETURN n.age",
{"name": "O'Brien"},
)
client.query(
"MATCH (n:Person) WHERE n.name IN $names RETURN n.name",
{"names": ["Alice", "Bob"]},
)
client.query(
"UNWIND $rows AS row RETURN row.name, row.age",
{"rows": [{"name": "Alice", "age": 30}]},
)
client.query(
"WITH $filter AS f MATCH (n:Person) WHERE n.city = f.city "
"RETURN n.name",
{"filter": {"city": "London"}},
)
# numbered parameter
client.query("RETURN $0 + 1 AS next", {"0": 41})
# inside a change
client.query(
"CREATE (n:Person {name: $name, age: $age})",
{"name": "Zoe", "age": 27},
)
client.query(
"MATCH (n:Person {name: 'Alice'}) SET n += $props",
{"props": {"city": "Berlin"}},
)A parameter can also stand for a label or an edge type, anywhere a label or type is written:
client.query(
"MATCH (n:$label) RETURN n.name", {"label": "Person"}
)
# every label in the list
client.query(
"MATCH (n:$labels) RETURN n.name",
{"labels": ["Person", "Employee"]},
)
# inside a label expression
client.query(
"MATCH (n:Person|$other) RETURN n.name", {"other": "Company"}
)
# in a label test
client.query(
"MATCH (n) WHERE n:$label RETURN n.name", {"label": "Company"}
)
client.query(
"MATCH (a)-[r:$type]->(b) RETURN a.name, b.name",
{"type": "WORKS_AT"},
)
# numbered parameter
client.query("MATCH (n:$0) RETURN n.name", {"0": "Company"})
# inside a change
client.query(
"CREATE (n:$label {name: 'Zoe'})", {"label": "Person"}
)
client.query("MERGE (t:$label {name: 'x'})", {"label": "Tag"})
client.query(
"MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})"
" MERGE (a)-[:$type]->(b)",
{"type": "FOLLOWS"},
)- Values. From Python, a parameter can hold a string, a number, a boolean,
None, a list, a dict, a time-zone-awaredatetime(a DateTime) or atimedelta(a Duration). Seequery()for the full list, and Parameters for JavaScript values. - Labels and edge types. The parameter holds a string, or a list of strings to require several labels.
- Missing parameters. A parameter used in the query but missing from the dictionary is reported when the query runs:
Parameter $label is not defined. - Where literals are still needed.
SKIPandLIMITtake a number written in the query:LIMIT $nis reported asUnsupported expression in SKIP/LIMIT: PARAMETER. The vector of aVECTOR SEARCHis written in the query too, and a list parameter is a List, not an Embedding. - Node IDs. Compare the node itself with an ID parameter,
WHERE n = $id, which looks the node up directly. For a list of IDs, see lookup by native node ID. - Size. Parameters count towards the 1 MiB limit of a request, but take far less room than the same values written into the query text.
In the interactive shell, set parameters with :param <name> => <value>. In the JavaScript SDK, pass them as client.query(cypher, { parameters }).
Coming from Neo4j
TuringDB follows openCypher closely, so the queries you know carry over. These are the TuringDB specifics worth knowing:
RETURN nreturns the node’s internal ID, an integer. Return the properties you need withRETURN n.name, n.age, a map projection such asRETURN n {.name, .age}, or all of them withRETURN properties(n). A path comes back as the list of its node and edge IDs, andelementId(n)is the same integer asid(n).- Parameters.
$nameparameters hold values, labels and edge types.SKIP,LIMITand vector search take literals. - One statement per request. Send each statement as its own request (a single trailing
;is fine), or chain steps in one request withNEXT. - Labels are set at creation. Every node has at least one label and every edge exactly one edge type, chosen when it is created.
- Property types are global. A property name has a single value type across the whole graph: if
ageis an Integer, it is an Integer on every node. - Comparing Doubles. Integers and Doubles compare by value (
n.age = 30.0matches 30). Match one Double against another with a range (n.score > 1.99 AND n.score < 2.01). - Forgiving names. An unknown label matches nothing and a misspelled property reads as
null. Check names withCALL db.labels()andCALL db.propertyTypes(). - String matching. Use
STARTS WITH,ENDS WITH,CONTAINSand the string functions. Regular expressions (=~) are not yet supported. - Testing for a property. Write
n.prop IS NOT NULL. As in Neo4j 5,exists()takes a pattern:exists((p)-[:LIKES]->()). - Uniqueness. Use
MERGEto avoid duplicates. - Shortest paths use a TuringDB statement, see Shortest path.
Coming from TuringDB 1.x? The v3 engine replaces the previous one, and many earlier limits are gone: OPTIONAL MATCH, WITH, DISTINCT, UNION, MERGE, DELETE, aggregates in any position, UNWIND over any list, LOAD CSV followed by MATCH, and CREATE ... SET all work now. One function changed name: edgeType(e) is now type(e).
Coming from TuringDB 3.0? Version 3.1 adds value parameters, map projection, SET n = {...} and SET n += {...}, points, exists(), allReduce and more. A few results change, to follow Neo4j:
- A path comes back as a list of IDs, node and edge alternating (
[0, 0, 1]), rather than a list of{type, id}dictionaries. list + nullisnull, and=between two maps isnullwhen anullinside decides it, as between two lists:{a: null} = {a: 1}isnull.STARTS WITH,ENDS WITHandCONTAINSbind more loosely than+:'a' + 'bc' ENDS WITH 'bc'istrue.- The Python SDK connects with
TuringDB(host="localhost", port=6666), see client backends.
Data types
TuringDB offers these types for node and edge properties and for values in queries:
| Type | Literal | Notes |
|---|---|---|
| String | 'Alice' or "Alice" | Backslash escapes (\'). Backticks quote identifiers, not strings |
| Integer | 30, 0x1F | Signed 64-bit. Integer division truncates |
| Double | 3.14, 1e3 | ^ always returns a Double |
| Boolean | true, false | |
| List | [1, 'a', [2]] | May mix types and nest |
| Map | {a: 1, b: [1, 2]} | See Maps |
| DateTime | datetime('2024-03-15T10:30:00Z') | Microsecond precision, always UTC |
| Duration | duration({days: 2}) | Microsecond precision, no month component |
| Point | point({x: 1, y: 2}), point({latitude: 51.5, longitude: -0.12}) | 2D or 3D, cartesian or WGS-84. See Points |
| Embedding | (1.2, 2.0, 0.0) | Parentheses, at least 2 numbers. See Vector search |
Embedding literals use parentheses. [1.2, 2.0, 0.0] is a List, which is a different type.
More detail on types, conversion and results is in Functions and data types.
Roadmap
We keep extending Cypher coverage and growing the library of procedures available through CALL. If there is a query form you would like to see, please tell us.

