Cypher overview

relate runs openCypheropenCypher The open specification of Cypher and its Technology Compatibility Kit (TCK) of scenarios; relate treats it as the floor of its dialect. Read more in the glossary, plus a large part of Neo4j's Cypher 25 and its extensions aligned with GQL, the ISO graph query language. Statements run as Cypher 25 unless a CYPHER 5 prefix says otherwise. Preview features stay off until RELATE_PREVIEW names them. Cypher for servers and clusters, such as users, roles and composite databases, is out of scope for an engine that runs inside one process.

Synopsis

[CYPHER 5 | CYPHER 25] [EXPLAIN | PROFILE] <statement>

Conformance

The openCypher Technology Compatibility Kit (TCK) is the language contract. The relate project measures coverage against it outside the engine's own repository, and its published compliance record says that "no engine document publishes a current TCK pass count any more". This page therefore states no current pass rate.

Supported Cypher 25 and GQL-aligned features

Each feature runs on the WebAssembly build the cells on this site use and on the CLI, without an opt-in. The exception is a generated identifier: uuid() with no argument and randomUUID() run on the CLI and the clients, and on the WebAssembly build the engine panics with time not implemented on this platform and the instance stops. uuid('<uuid string>') runs on both.

Preview features

A preview featurepreview feature A Cypher feature from a not-yet-settled proposal that relate ships switched off; it runs only when RELATE_PREVIEW names it when the store opens. Read more in the glossary ships in the engine and stays off until its name is in RELATE_PREVIEW, which is read once when the storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary opens. Several names are separated by commas. An unknown name fails the open with exit code 1 and lists the known names. The error a feature gives while it is off depends on the feature, as the When off column shows. Most give the preview message, semantic error: SemanticError: preview feature '<name>' is not enabled: set RELATE_PREVIEW=<name>, which names the opt-in. A name gate fails as an unknown function, and a few fail as the parser or the SEARCH rules would without the feature; those messages do not mention RELATE_PREVIEW.

Out of scope

Limitations lists each limit and the reason for it.

Examples

The cells run in page order on one in-memory store, starting from the shared example graph:

CREATE (ada:Person {name: 'Ada', role: 'engineer'}),
       (grace:Person {name: 'Grace', role: 'engineer'}),
       (noor:Person {name: 'Noor', role: 'maintainer'}),
       (relate:Project {name: 'relate', language: 'Rust'}),
       (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}),
       (ada)-[:WORKS_ON {since: 2024}]->(relate),
       (grace)-[:WORKS_ON {since: 2023}]->(relate),
       (grace)-[:WORKS_ON {since: 2022}]->(tck),
       (noor)-[:MAINTAINS]->(relate),
       (ada)-[:KNOWS]->(grace)

(no rows) · nodes created: 5, relationships created: 5, properties set: 13, labels added: 5

The default language of each namespace:

SHOW DATABASES YIELD name, defaultLanguage RETURN name, defaultLanguage

| name                | defaultLanguage |
|---------------------|-----------------|
| "neo4j"             | "CYPHER 25"     |
| "system"            | "CYPHER 25"     |
| "system_ontologies" | "CYPHER 25"     |
3 rows

A label expressionlabel expression A test on a node's labels or a relationship's type built with &, |, ! and %, such as (n:Person|Project) or (n IS Person). Read more in the glossary with a pattern predicate, and a quantified path pattern:

MATCH (p:Person&!Project WHERE p.role = 'engineer') RETURN p.name AS name ORDER BY name

| name    |
|---------|
| "Ada"   |
| "Grace" |
2 rows

MATCH (:Person {name: 'Ada'}) ((a)-[:KNOWS|WORKS_ON]->(b)){1,2} (reached)
RETURN DISTINCT reached.name AS reached ORDER BY reached

| reached          |
|------------------|
| "Grace"          |
| "opencypher-tck" |
| "relate"         |
3 rows

LET, FILTER and a COUNT subquery in one pipeline:

MATCH (p:Person)
LET projects = COUNT { (p)-[:WORKS_ON]->() }
FILTER projects > 0
RETURN p.name AS name, projects ORDER BY name

| name    | projects |
|---------|----------|
| "Ada"   | 1        |
| "Grace" | 2        |
2 rows

String interpolation, and explicit grouping:

MATCH (p:Person)-[w:WORKS_ON]->(proj:Project)
RETURN s'{p.name} works on {proj.name}' AS line ORDER BY line

| line                            |
|---------------------------------|
| "Ada works on relate"           |
| "Grace works on opencypher-tck" |
| "Grace works on relate"         |
3 rows

MATCH (p:Person) RETURN p.role AS role, count(*) AS people GROUP BY role ORDER BY role

| role         | people |
|--------------|--------|
| "engineer"   | 2      |
| "maintainer" | 1      |
2 rows

A preview feature without its opt-in:

DEFINE FUNCTION twice(x) = x * 2
RETURN twice(21) AS answer

error: semantic error: SemanticError: preview feature 'local-callables' is not enabled: set RELATE_PREVIEW=local-callables

The same statement on the CLI, with the opt-in in the command's environment:

RELATE_PREVIEW=local-callables relate --mode envelope "DEFINE FUNCTION twice(x) = x * 2 RETURN twice(21) AS answer"

{"columnTypes":["INTEGER"],"columns":["answer"],"notifications":[],"planCache":"miss","rows":[{"answer":42}],"timings":{"elapsed_ms":0.438125,"execute_ms":0.246333,"lex_parse_ms":0.025042,"lower_ms":0.042208,"parse_ms":0.113125,"plan_ms":0.07037500000000001,"result_generation_ms":0.00020800000000000001,"rewrite_ms":0.020583},"truncated":false}

See also

• Differences from Neo4j: the Neo4j habits that fail in relate, and what to write instead.
• Search: vector and full-text indexes and the SEARCH clause.
• Limitations: the scope choices, with their reasons.
• The Cypher dialect: why the dialect is shaped this way.