Cypher Query Language

Traverse supports the Cypher query language for creating, reading, updating, and deleting graph data.

Clauses

Data Types

Patterns

Node Patterns

()                           -- anonymous node
(n)                          -- named node
(n:Person)                   -- with label
(n:Person {name: "Alice"})   -- with inline properties
(n:Person:Employee)          -- multiple labels

Relationship Patterns

(a)-[r]->(b)                 -- directed (outgoing)
(a)<-[r]-(b)                 -- directed (incoming)
(a)-[r]-(b)                  -- undirected (either direction)
(a)-[r:KNOWS]->(b)           -- typed
(a)-[r:KNOWS|LIKES]->(b)     -- multiple types (OR)
(a)-[r:KNOWS {since: 2020}]->(b)  -- with properties
(a)-[*1..3]->(b)             -- variable-length (1 to 3 hops)
(a)-[*3]->(b)                -- exactly 3 hops
(a)-[*2..]->(b)              -- at least 2 hops
(a)-[*..5]->(b)              -- up to 5 hops

Named Paths

p = (a)-[:KNOWS]->(b)        -- bind entire path to variable

Operators

Functions

String Functions

Math Functions

Aggregate Functions

List Functions

Predicate Functions

Type Conversion

Graph Element Functions

Path Functions

Temporal Functions

Constructors

Truncation

Truncate a temporal value to a coarser precision:

date.truncate(temporal)
localtime.truncate(temporal)
time.truncate(temporal)
localdatetime.truncate(temporal)
datetime.truncate(temporal)

Duration Computation

Epoch Conversion

Clock Functions

Each temporal type supports three clock sources:

datetime.transaction()    -- fixed at transaction start
datetime.statement()      -- fixed at statement start
datetime.realtime()       -- current wall clock

Also available for date, localtime, time, localdatetime.

Schema Commands

Node Indexes

-- Create a named index
CREATE INDEX idx_person_name FOR (n:Person) ON (n.name);

-- Legacy syntax (also supported)
CREATE INDEX ON :Person(name);

-- Drop by name
DROP INDEX idx_person_name;
DROP INDEX idx_person_name IF EXISTS;

-- List all indexes
SHOW INDEXES;

Edge Indexes

-- Index on edge property
CREATE EDGE INDEX idx_knows_since ON :KNOWS(since);

-- Index on edge type only (speeds up type-filtered traversals)
CREATE EDGE INDEX idx_knows ON :KNOWS;

-- Drop
DROP EDGE INDEX idx_knows_since;

Constraints

-- Uniqueness constraint
CREATE CONSTRAINT unique_person_email FOR (n:Person) REQUIRE n.email IS UNIQUE;

-- Not-null constraint
CREATE CONSTRAINT person_name_required FOR (n:Person) REQUIRE n.name IS NOT NULL;

-- Drop
DROP CONSTRAINT unique_person_email;
DROP CONSTRAINT unique_person_email IF EXISTS;

-- List all constraints
SHOW CONSTRAINTS;

Analyze Graph

-- Collect statistics for query optimization
ANALYZE GRAPH;

-- Analyze specific labels
ANALYZE GRAPH LABEL Person, Company;

User Management

CREATE USER alice SET PASSWORD 'hunter2' SET ROLE EDITOR;
ALTER USER alice SET ROLE ADMIN;
DROP USER alice;
SHOW USERS;

Shortest Path

-- Single shortest path (BFS)
MATCH p = shortestPath((a:Person {name: "Alice"})-[*..15]->(b:Person {name: "Bob"}))
RETURN p;

-- All shortest paths
MATCH p = allShortestPaths((a)-[*..5]->(b))
RETURN p;

-- Weighted shortest path (Dijkstra)
MATCH p = (a:City {name: "Paris"})-[r *wShortest (r, node | r.distance) totalCost]->(b:City {name: "Berlin"})
RETURN p, totalCost;

Expressions

CASE

-- Searched CASE
MATCH (n:Person)
RETURN n.name,
  CASE
    WHEN n.age < 18 THEN "minor"
    WHEN n.age < 65 THEN "adult"
    ELSE "senior"
  END AS category;

-- Simple CASE
RETURN CASE n.status WHEN "A" THEN "Active" WHEN "I" THEN "Inactive" ELSE "Unknown" END;

List Comprehension

-- Transform list with optional filter
RETURN [x IN range(1,10) WHERE x % 2 = 0 | x * x] AS squares;

-- From a path
MATCH p = (a)-[*1..3]->(b)
RETURN [node IN nodes(p) | node.name] AS names;

Pattern Comprehension

-- Collect values from matched sub-patterns
MATCH (p:Person)
RETURN p.name, [(p)-[:KNOWS]->(f) | f.name] AS friends;

Reduce

-- Fold/reduce over a list
RETURN reduce(total = 0, x IN [1,2,3,4,5] | total + x) AS sum;

Map Projection

-- Project specific properties from a node
MATCH (p:Person)
RETURN p {.name, .age} AS person;

Existential Subqueries

-- Check if a pattern exists
MATCH (p:Person)
WHERE EXISTS { (p)-[:KNOWS]->(:Person {name: "Alice"}) }
RETURN p.name;

Count Subqueries

-- Count matching sub-patterns
MATCH (p:Person)
WHERE COUNT { (p)-[:KNOWS]->() } > 5
RETURN p.name;

Parameters

Use $param syntax to pass query parameters safely:

MATCH (n:Person) WHERE n.name = $name RETURN n;

LOAD CSV

-- With headers (columns as map keys)
LOAD CSV WITH HEADERS FROM 'file:///path/to/data.csv' AS row
CREATE (n:Person {name: row.name, age: toInteger(row.age)});

-- Custom delimiter
LOAD CSV WITH HEADERS FROM 'file:///data.tsv' AS row FIELDTERMINATOR '\t'
CREATE (n:Record {id: row.id});

SET Variants

-- Set individual properties
SET n.name = "Alice", n.age = 30;

-- Replace all properties (removes existing ones)
SET n = {name: "Alice", age: 30};

-- Merge properties (keeps existing, adds/overwrites specified)
SET n += {age: 31, email: "alice@example.com"};

-- Add a label
SET n:Employee;

RETURN and WITH

-- Return all variables in scope
MATCH (n:Person)-[r]->(m)
RETURN *;

-- Pass all variables through WITH
MATCH (n:Person)
WITH * WHERE n.age > 25
RETURN n.name;

Procedures

-- Call a procedure and yield specific columns
CALL db.labels() YIELD label
RETURN label;

-- Yield all columns
CALL db.indexes() YIELD *;

Query Examples

Create Data

CREATE (a:Person {name: "Alice", age: 30})
CREATE (b:Person {name: "Bob", age: 25})
CREATE (a)-[:KNOWS {since: 2020}]->(b)
RETURN a, b;

Read & Filter

MATCH (p:Person)
WHERE p.age > 25
RETURN p.name, p.age
ORDER BY p.age DESC
LIMIT 10;

Regex Filtering

MATCH (p:Person)
WHERE p.name =~ 'Al.*'
RETURN p.name;

Aggregation

MATCH (p:Person)-[:KNOWS]->(friend)
RETURN p.name, count(friend) AS friendCount
ORDER BY friendCount DESC;

Variable-Length Paths

MATCH path = (a:Person {name: "Alice"})-[:KNOWS*1..3]->(b)
RETURN b.name, length(path) AS distance;

Merge (Upsert)

MERGE (p:Person {name: "Charlie"})
ON CREATE SET p.created = datetime()
ON MATCH SET p.lastSeen = datetime()
RETURN p;