Skip to main content
TuringDB supports most of the Cypher query language, extended with versioning, metadata search, and flexible property matching. This guide covers some examples of queries types, including MATCH, CREATE, property filters, metaqueries, and available data types.

​
Basics

Queries are built by referencing nodes and edges. TuringDB supports the standard CYPHER syntax, in that nodes are denoted using parentheses (), whilst edges are denoted using square brackets []. For example, (n) would denote a node named n, whilst [e] would denote an edge named e. Nodes and edges can have both label and property constraints. As in standard CYPHER, property constraints are specified using curly brackets {}, whilst labels are specified using colon : syntax. An example of a node with a label constraint would be (n:Person). An example of an edge with a property constraint would be [e {duration: 10}]. Property and label constraints may be combined, for instance, (n:Person {name: 'John'}) specifies a node which both has the label Person, and a name property with the value John. Nodes and edges can have label and property multiple constraints, which are specified in a comma-separated list: (n:Person:Man {name: 'John', age: 20}). These lists can be arbitrarily long. By convention:
  • we prefer using single quotes around strings (even if double quotes alsowork )
  • node label are written in Pascal case (no spaces): e.g. Person, BankAccount, BloodType
  • edge label are written in upper case (spaces replaced by underscores): e.g. TRANSACTION, FRIENDS_WITH, IS_CLIENT_OF

​
Summary:

Queries are built around nodes and edges:
  • Nodes are written in parentheses () e.g. (n) - a node with alias n
  • Edges are written in square brackets [] e.g. [e] - an edge with alias e
You can add:
  • Labels with a colon : - e.g. (n:Person)
  • Property constraints with curly braces {} - e.g. [e {duration: 10}]
  • Both at once - e.g. (n:Person {name: 'John'})
Multiple labels and properties can be specified: 
(n:Person:Man {name: 'John', age: 20})

​
Queries

Queries are built up of combinations of nodes and edges, as specified above. TuringDB supports two main query operations: MATCH and CREATE.

​
MATCH queries

MATCH queries are used to retrieve nodes, edges, and their property values from the database via specification of relationships and properties. It is easiest to demonstrate the syntax of a MATCH query with a concrete example: 
MATCH (n)-[e]->(m) RETURN n, e, m
MATCH (m)<-[e]-(n) RETURN n, e, m  // also works
The above query will look for all the directed edges in the graph. The query will return the internal ID of the node n.
When using RETURN n, other implementations of CYPHER may return all properties of n, whilst TuringDB only returns the internal ID of n.
MATCH queries are flexible: they can contain a single node and no edges, or any number of node, edge pairs. For example: 
MATCH (n) RETURN n
will match all nodes in the database. An example of a multi-hop MATCH query would be: 
MATCH (n)-[e]->(m)-[f]->(p) RETURN n, m, p

Queries have variables, which in the above examples are those such as n, m, e, etc. Variables are a way to give a name to a node or an edge, so that those nodes or edges can be specified in the RETURN clause. However, if you do not want to return an edge or its properties, the edge need not have a name. For example:
MATCH (n)-->(m) RETURN m
Both node and edges can omit a variable name if they specify at least a label constraint:
MATCH (:Person)-[:FRIENDS_WITH]->(m) RETURN m
You can also return multiple properties using a comma separated list: 
MATCH (n:Person)-->(m:Person) RETURN n.name, m.age
Combining the syntax of MATCH queries, and the ability to specify constraints, here are a few examples of some syntactically correct TuringDB MATCH queries:
  • MATCH (n:Person) RETURN n.name
  • MATCH (:Person)-->(n:Person) RETURN n.name
  • MATCH (n:Person:Woman:SoftwareEngineer) RETURN n.name
  • MATCH (n:Person:Woman:SoftwareEngineer)-->(m)-[e]->(p:Man)-[f]->(q) RETURN e, f
Note that whilst all the above the queries are all syntactically valid, if the graph does not have a node property which is used in a query, it will fail to execute.

​
CREATE queries

CREATE queries follow exactly the same syntax as MATCH queries when it comes to specifying nodes, edges, and property/label constraints. CREATE queries may have RETURN clauses, but they do not need them. There is also the additional requirement that all nodes and edges must have at least one label. This means a query such as 
CREATE (n)
is not valid, whilst 
CREATE (n:Person)
is a valid query. There is no requirement to declare any names for any variables. This means we can have queries such as 
CREATE (:Person)-[:FRIENDS_WITH]->(:Person)
However, naming variables can be useful if you want to create multiple edges to or from a given node. For instance, if you would like to create a triangle pattern, this can be achieved using the following approach 
CREATE (a:Corner)-[:EDGE]->(b:Corner), (b)-[:EDGE]->(c:Corner), (c)-[:EDGE]->(a)

​
MATCH ... CREATE ... and MATCH ... CREATE ... RETURN ... queries

MATCH, CREATE and RETURN statements can be used together in queries. For example, to create a edge between two existing graph, the following queries can be used: 
// Create two nodes Person
CREATE (:Person {name: 'Alice', age: 24})
CREATE (:Person {name: 'John', age: 27})

// Match two nodes to create the edge between them
MATCH (n:Person {name: 'Alice'}), (m:Person {name: 'John'})
CREATE (n)-[:FRIENDS_WITH]->(m)

// RETURN clause can also be added
MATCH (n:Person {name: 'Alice'}), (m:Person {name: 'John'})
CREATE (n)-[:FRIENDS_WITH]->(m)
RETURN n.name, n.age, m.name, m.age

​
WHERE queries

The WHERE clause allows to filter the results on node and/or edge labels and/or properties. To filter on node label: 
MATCH (n)
WHERE n:Person
RETURN n, n.age
To filter on node property: 
MATCH (n)
WHERE n.name = 'Alice'
RETURN n, n.age
To filter on edge label: 
MATCH (n)-[e]->(m)
WHERE e:PLAYPOKER
RETURN n.name, m.age
To filter on edge property: 
MATCH (n)-[e]->(m:Person)
WHERE n.name = 'Gabby'
AND e.play_poker = true
RETURN n.name, m.age

​
Data Types

TuringDB offers the following data types for node and edge properties:
  • String
  • Boolean
  • Integer (signed)
  • Double (decimal)
String properties can be enclosed using double quotes ("), single quotes ('), or backticks (```).

​
Operators

​
Boolean operators

The OR and AND operartors are used to filter on multiple conditions: 
MATCH (n:Person)
WHERE n.medication = "Aspirin"
OR n.medication = "Ibuprofen"
RETURN n.name

MATCH (n)
WHERE n.name = 'Matt'
AND n.age = 20
AND n.hasPhD = false
RETURN n

​
Comparison operators

TuringDB allows you to query against node and edge properties using the : operator for exact matching of the property value. 
MATCH (n {name: 'Matt', age: 20, hasPhD: false}) RETURN n
You can also pass through the WHERE clause to do the exact equivalent query: 
MATCH (n)
WHERE n.name = 'Matt'
AND n.age = 20
AND n.hasPhD = false
RETURN n
Implemented comparison operators:
  • Equal: = 
    # Find antibodies targeting proteins in Human
MATCH (ab:Antibody)-->(prot:Protein)
WHERE prot.host = 'Human'
RETURN ab.name, prot.name
  • Inequal: <> 
    # Find antibodies (associated to a protein) used together
# in same publication (2-hop)
MATCH (ab1:Antibody)-->(prot:Protein), (ab2:Antibody)-->(prot:Protein)
WHERE ab1.name <> ab2.name
RETURN ab1.name, ab2.name, prot.name, prot.gene_name
  • Less than: <
  • Less than or equal to: <=
  • Greater than: >
  • Greater than or equal to: >= 
    # Publications published on 2020 or after
MATCH (pub:Publication)
WHERE pub.published_year >= 2020
RETURN pub.displayName, pub.pubmedid, pub.published_year, pub.country
  • is null:IS NULL
  • is not null:IS NOT NULL 
    # Publications from the United States
MATCH (pub:Publication)
WHERE pub.country = 'United States'
AND pub.institution IS NOT NULL
RETURN pub.displayName, pub.institution, pub.published_year

​
Metaqueries

On top of supporting queries which return or alter information in the graph, TuringDB supports a number of “metaqueries” which return information, or metadata, about the graph. These queries follow the CALL syntax, and the following variants are supported:
  1. CALL db.propertyTypes () - returns a column of all the different node and edge properties and their types in the database
  2. CALL db.labels () - returns a column of all the different node labels
  3. CALL db.edgeTypes() - returns a column of all the different edge types (edge equivalent of node labels)
  4. CALL db.history () - returns a dataframe containing commit history
These metaqueries are useful for exploring the data which is available in the graph, and using this to plan MATCH queries.

​
Commands

Outside of CYPHER, there are a number of commands which you can use to interact with the TuringDB engine.
CommandExplanation
CREATE GRAPH <graph name>Create a graph with the specified name
LOAD GRAPH <graph name>Load the specified TuringDB graph. Requires the graph files to be accessible in TuringDB directory (--turing-dir, graphs subdir)
LOAD GML 'mygraph.gml' AS my_graphLoad the specified GML as TuringDB graph. Requires the GML to be accessible in TuringDB directory (--turing-dir, data subdir)
LOAD JSONL 'mygraph.gml' AS my_graphLoad the specified JSONL as TuringDB graph. Requires the JSONL to be accessible in TuringDB directory (--turing-dir, data subdir)
CHANGE NEWCreates a new change, returning a column with the ID of the created change
CHANGE SUBMITWhen checked out on a specific change, submits all changes made to the “master branch”
CHANGE DELETEDeletes the currently checked out change
CHANGE LISTLists the currently active (uncommitted) changes
LIST GRAPHLists the available graphs

​
Roadmap

Whilst TuringDB currently supports most of CYPHER, 100% of CYPHER can be parsed but we are working on supporting query execution for some rare CYPHER queries types. TuringDB also has a CALL function which over time will contain more and more algorithms.