Skip to content
GraphQLite

Cypher Clauses

MATCH

Section titled “MATCH”

Syntax

MATCH pattern [WHERE condition]

Reads nodes and relationships matching the given pattern. Binds variables to matched entities. Multiple comma-separated patterns in one MATCH form a cross-product constrained by shared variables. A WHERE clause immediately following MATCH filters before joining subsequent clauses.

Pattern forms

Pattern Example
Node (n:Label)
Relationship (a)-[r:TYPE]->(b)
Undirected relationship (a)-[r:TYPE]-(b)
Variable-length (a)-[*1..3]->(b)
Named path p = (a)-[*]->(b)
Multiple labels (n:Person:Employee)
Property filter (n:Person {name: 'Alice'})

Examples

MATCH (n:Person) RETURN n.name
MATCH (a:Person)-[:KNOWS]->(b:Person)
WHERE a.name = 'Alice'
RETURN b.name
MATCH p = (a)-[*1..3]->(b)
RETURN nodes(p)

OPTIONAL MATCH

Section titled “OPTIONAL MATCH”

Syntax

OPTIONAL MATCH pattern [WHERE condition]

Left outer join. Rows from preceding clauses are preserved even when no match exists. Unmatched variables are bound to null.

Example

MATCH (n:Person)
OPTIONAL MATCH (n)-[:HAS_PET]->(p:Pet)
RETURN n.name, p.name

CREATE

Section titled “CREATE”

Syntax

CREATE pattern

Creates nodes and/or relationships. Variables introduced in CREATE are available in subsequent clauses.

Examples

CREATE (n:Person {name: 'Alice', age: 30})
MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
CREATE (a)-[:KNOWS {since: 2020}]->(b)

MERGE

Section titled “MERGE”

Syntax

MERGE pattern
[ON CREATE SET assignment [, assignment ...]]
[ON MATCH SET assignment [, assignment ...]]

Matches the pattern or creates it if no match exists. ON CREATE SET executes only on creation; ON MATCH SET executes only when the pattern already exists. Both subclauses are optional and independent.

Examples

MERGE (n:Person {name: 'Alice'})
ON CREATE SET n.created = datetime()
ON MATCH SET n.updated = datetime()
MERGE (a:Person {name: 'Bob'})-[:KNOWS]->(b:Person {name: 'Carol'})

SET

Section titled “SET”

Syntax

SET item [, item ...]

Assignment forms

Form Behavior
n.prop = expr Set or overwrite one property
n = {map} Replace all properties with the map; unlisted properties are removed
n += {map} Merge map into existing properties; unlisted properties are kept
n:Label Add a label to a node

Examples

MATCH (n:Person {name: 'Alice'}) SET n.age = 31
MATCH (n:Person {name: 'Alice'}) SET n = {name: 'Alice', age: 31}
MATCH (n:Person {name: 'Alice'}) SET n += {age: 31, city: 'NYC'}
MATCH (n:Person {name: 'Alice'}) SET n:Employee

REMOVE

Section titled “REMOVE”

Syntax

REMOVE item [, item ...]

Item forms

Form Behavior
n.prop Delete a property from a node or relationship
n:Label Remove a label from a node

Examples

MATCH (n:Person {name: 'Alice'}) REMOVE n.age
MATCH (n:Employee) REMOVE n:Employee

DELETE

Section titled “DELETE”

Syntax

DELETE expr [, expr ...]

Deletes nodes or relationships. Attempting to delete a node that still has relationships raises an error. Use DETACH DELETE to cascade.

Examples

MATCH (n:Temp) DELETE n
MATCH (a)-[r:OLD]->(b) DELETE r

DETACH DELETE

Section titled “DETACH DELETE”

Syntax

DETACH DELETE expr [, expr ...]

Deletes a node and all its incident relationships in one operation.

Example

MATCH (n:Person {name: 'Alice'}) DETACH DELETE n

RETURN

Section titled “RETURN”

Syntax

RETURN [DISTINCT] expr [AS alias] [, ...]
[ORDER BY expr [ASC|DESC] [, ...]]
[SKIP expr]
[LIMIT expr]

Projects query results into the result set. * expands to all in-scope variables.

Modifiers

Modifier Description
DISTINCT Remove duplicate rows from output
AS alias Assign a column name
ORDER BY expr [ASC|DESC] Sort; default direction is ASC
SKIP n Skip the first n rows
LIMIT n Return at most n rows
* Return all variables in scope

Examples

MATCH (n:Person)
RETURN n.name AS name, n.age
ORDER BY n.age DESC
LIMIT 10
MATCH (n:Person) RETURN DISTINCT n.city
MATCH (n) RETURN *

WITH

Section titled “WITH”

Syntax

WITH [DISTINCT] expr [AS alias] [, ...]
[ORDER BY expr [ASC|DESC] [, ...]]
[SKIP expr]
[LIMIT expr]
[WHERE condition]

Pipelines intermediate results between query parts. Variables not listed in WITH go out of scope. Aggregation in WITH collapses rows; WHERE after WITH filters the aggregated result.

Examples

MATCH (n:Person)-[:KNOWS]->(m)
WITH n, count(m) AS friends
WHERE friends > 3
RETURN n.name, friends
MATCH (n:Person)
WITH n ORDER BY n.age LIMIT 5
MATCH (n)-[:KNOWS]->(m)
RETURN n.name, m.name

WHERE

Section titled “WHERE”

Syntax

WHERE condition

Filters rows. Appears after MATCH, OPTIONAL MATCH, or WITH. Supports all comparison operators, boolean operators, string predicates, IS NULL, IS NOT NULL, IN, and pattern predicates.

Predicate forms

Predicate Example
Comparison n.age > 25
String n.name STARTS WITH 'Al'
Regex n.name =~ 'Al.*'
Null check n.email IS NOT NULL
List membership n.role IN ['admin', 'mod']
Pattern existence (n)-[:KNOWS]->(m)
Negated pattern NOT (n)-[:BLOCKED]->(m)
exists{} exists{(n)-[:KNOWS]->(m)}

Examples

MATCH (n:Person)
WHERE n.age > 25 AND n.city = 'NYC'
RETURN n.name
MATCH (n:Person)
WHERE (n)-[:KNOWS]->(:Person {name: 'Bob'})
RETURN n.name

UNWIND

Section titled “UNWIND”

Syntax

UNWIND expr AS variable

Expands a list into one row per element. A null list produces zero rows. An empty list produces zero rows.

Examples

UNWIND [1, 2, 3] AS x RETURN x
MATCH (n:Person)
UNWIND labels(n) AS lbl
RETURN n.name, lbl

FOREACH

Section titled “FOREACH”

Syntax

FOREACH (variable IN list | update_clause [update_clause ...])

Executes mutation clauses (CREATE, MERGE, SET, REMOVE, DELETE) for each element of a list. Variables introduced inside FOREACH are scoped to the body and not available outside. Nested FOREACH is not supported.

Examples

FOREACH (name IN ['Alice', 'Bob', 'Carol'] |
  CREATE (:Person {name: name})
)
MATCH p = (a:Person)-[:KNOWS*]->(b:Person)
FOREACH (n IN nodes(p) | SET n.visited = true)

UNION / UNION ALL

Section titled “UNION / UNION ALL”

Syntax

query
UNION [ALL]
query

Combines results from two queries. Column names and count must match. UNION deduplicates rows; UNION ALL preserves all rows including duplicates.

Example

MATCH (n:Person) RETURN n.name AS name
UNION
MATCH (n:Company) RETURN n.name AS name

LOAD CSV

Section titled “LOAD CSV”

Syntax

LOAD CSV [WITH HEADERS] FROM 'file:///path/to/file.csv' AS row
[FIELDTERMINATOR char]

Reads a CSV file (RFC 4180 quoting). With WITH HEADERS, each row is a map keyed by the header names. Without it, each row is a list. All values are strings; use toInteger(), toFloat(), or toBoolean() as needed. linenumber() gives the line of the current row, and file() gives the path.

Example

LOAD CSV WITH HEADERS FROM 'file:///data/people.csv' AS row
CREATE (:Person {name: row.name, age: toInteger(row.age)})

CALL procedure

Section titled “CALL procedure”

Syntax

CALL algorithm([args]) [YIELD * | YIELD column [AS alias], ... [WHERE expr]]

Runs a graph algorithm and gives one row for each result. See Graph algorithms for the algorithms and their columns.

Example

CALL pageRank() YIELD node, score
WHERE score > 0.1
RETURN node, score ORDER BY score DESC

EXPLAIN / PROFILE

Section titled “EXPLAIN / PROFILE”

Syntax

EXPLAIN query
PROFILE query

EXPLAIN gives the generated SQL and does not run the query. PROFILE runs the query and gives one row with the columns pattern, clauses, sql, plan (the SQLite query plan), rows, time_ms and the write counters.

Example

PROFILE MATCH (p:Person) WHERE p.age > 30 RETURN p.name

CREATE / DROP / SHOW INDEX

Section titled “CREATE / DROP / SHOW INDEX”

Syntax

CREATE INDEX [name] [IF NOT EXISTS] FOR (n:Label) ON (n.prop, ...)
CREATE INDEX ON :Label(prop, ...)
DROP INDEX name [IF EXISTS]
SHOW [ALL | RANGE] INDEXES

GraphQLite indexes each property already, so an index is a record only. The statements are accepted so that scripts from other databases run. Relationship indexes are not supported.

CREATE / DROP / SHOW CONSTRAINT

Section titled “CREATE / DROP / SHOW CONSTRAINT”

Syntax

CREATE CONSTRAINT [name] [IF NOT EXISTS] FOR (n:Label) REQUIRE n.prop IS UNIQUE
CREATE CONSTRAINT [name] [IF NOT EXISTS] FOR (n:Label) REQUIRE (n.a, n.b) IS UNIQUE
CREATE CONSTRAINT [name] [IF NOT EXISTS] FOR (n:Label) REQUIRE n.prop IS NOT NULL
DROP CONSTRAINT name [IF EXISTS]
SHOW CONSTRAINTS

The old forms ON (n:Label) ASSERT n.prop IS UNIQUE and ASSERT EXISTS (n.prop) are also accepted. GraphQLite checks the constraints after each write query. A query that breaks a constraint fails with ConstraintValidationFailed, and none of its writes stay. A new constraint fails if the data in the graph breaks it. The integer 1 and the float 1.0 are the same value; the string "1" is a different value. Relationship constraints are not supported.

Example

CREATE CONSTRAINT person_email FOR (p:Person) REQUIRE p.email IS UNIQUE

FROM (Multi-graph)

Section titled “FROM (Multi-graph)”

Syntax

FROM 'db_path'
MATCH ...

GraphQLite extension clause. Queries a different SQLite database file. The target database must have the GraphQLite schema initialized.

Example

FROM 'social.db'
MATCH (n:Person)
RETURN n.name

Pattern Predicates in WHERE

Section titled “Pattern Predicates in WHERE”

A pattern used as a boolean expression inside WHERE evaluates to true if at least one match exists. Supports full pattern syntax including property filters, relationship type filters, and variable-length paths.

WHERE (a)-[:KNOWS]->(b)
WHERE NOT (a)-[:BLOCKED]->(b)
WHERE (a)-[:KNOWS*1..3]->(b)
WHERE exists{(a)-[:KNOWS]->(:Person {active: true})}

Pattern predicates can reference variables bound in preceding MATCH clauses.