Docs
View as markdown

Cypher versions

The version prefixes for Cypher 25 and Cypher 5, the default language and what ALTER DATABASE changes, RELATE_PREVIEW opt-ins, and the TCK record.

cyphercli

Every Cypher The declarative graph query language relate runs, written as ASCII-art patterns such as (a)-[:KNOWS]->(b); relate follows Neo4j's Cypher 25 by default. Read more in the glossary statement runs as Cypher 25 The Neo4j Cypher version aligned with GQL; the default language of every relate namespace, with CYPHER 5 as the per-statement alternative. Read more in the glossary, the Neo4j Cypher version aligned with GQL The ISO standard graph query language; Neo4j's Cypher 25 aligns Cypher with it, and relate follows that alignment. Read more in the glossary, the ISO graph query language. A CYPHER 5 prefix runs one statement as Cypher 5. Syntax that is not settled yet ships as a preview 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 and stays off until RELATE_PREVIEW names it. No other version exists, and nothing else changes the version a statement runs as.

Synopsis

[CYPHER 5 | CYPHER 25] [EXPLAIN | PROFILE] <statement>
ALTER DATABASE <namespace> SET DEFAULT LANGUAGE CYPHER 5 | CYPHER 25
RELATE_PREVIEW=<feature>[,<feature> …]

EXPLAIN or PROFILE may also come before the version prefix.

Version prefix

PrefixStatement runs asNotes
NoneCypher 25The default for every statement
CYPHER 25Cypher 25
CYPHER 5Cypher 5Some Cypher 25 forms fail, as the next table shows
Any other number—syntax error: parse error: SyntaxError: 22N10 invalid pre-parser option value: "<n>" is not a valid cypher version
Two prefixes—syntax error: parse error: SyntaxError: 22N09 conflicting pre-parser combination: multiple values for 'cypher version'

Under CYPHER 5, these Cypher 25 forms fail:

FormMessage
String interpolation, s'…'syntax error: SyntaxError: UnsupportedLanguageFeature: string interpolation (s'...') is only available in Cypher 25
vector(…)syntax error: UnknownFunction: unknown function 'vector'

Other Cypher 25 forms, such as LET and the || operator, run under both prefixes.

Default language

Each namespace One of the three fixed graphs in every store: neo4j for user data, system for administration, and system_ontologies, listed but not queryable. Read more in the glossary records a default language, which SHOW DATABASES reports in the defaultLanguage column.

SettingValue
Recorded defaultCYPHER 25 for neo4j, system and system_ontologies
ALTER DATABASE <namespace> SET DEFAULT LANGUAGE CYPHER 5Stores CYPHER 5 in the store; SHOW DATABASES reports it in this process, and after the store reopens
Effect on statementsNone: a statement without a prefix still runs as Cypher 25. Only the prefix selects Cypher 5

Preview features

RELATE_PREVIEW is an environment variable of the process that opens the store. The Cypher overview lists each feature, what it enables and the error it gives while off.

RuleBehavior
DefaultNo feature enabled
When it is readOnce, when the store opens
Several featuresComma-separated; spaces around a name are accepted
NamesLowercase, exactly as listed: Chronological-Comparisons is unknown
An unknown nameThe open fails with exit code 1 and lists the known names
A feature used while offUsually semantic error: SemanticError: preview feature '<name>' is not enabled: set RELATE_PREVIEW=<name>; the overview lists the exceptions
The cells on this siteRun on the WebAssembly build with no preview feature enabled

Conformance

The openCypher Technology Compatibility Kit (TCK) is the language contract. relate's published compliance record states that "no engine document publishes a current TCK pass count any more": coverage is measured by a spec harness that reports on each pull request ready for review and never blocks a merge.

The retired in-repository figures are on the Cypher overview, and the Cypher dialect explains why the pin carried deviations.

Examples

The cells run in page order on one in-memory store. The default language of each namespace:

Cypher
SHOW DATABASES YIELD name, defaultLanguage RETURN name, defaultLanguage
Recorded result
namedefaultLanguage
"neo4j""CYPHER 25"
"system""CYPHER 25"
"system_ontologies""CYPHER 25"

3 rows

String interpolation is a Cypher 25 form:

Cypher
CYPHER 25 RETURN s'{1 + 1} hops' AS label
Recorded result
label
"2 hops"

1 row
Cypher
CYPHER 5 RETURN s'{1 + 1} hops' AS label
Expected error
error: syntax error: SyntaxError: UnsupportedLanguageFeature: string interpolation (s'...') is only available in Cypher 25
Cypher
CYPHER 4 RETURN 1 AS one
Expected error
error: syntax error: parse error: SyntaxError: 22N10 invalid pre-parser option value: "4" is not a valid cypher version
  CYPHER 4 RETURN 1 AS one
         ^

Setting the default language to Cypher 5 changes what SHOW DATABASES reports:

Cypher
ALTER DATABASE neo4j SET DEFAULT LANGUAGE CYPHER 5;
SHOW DATABASES YIELD name, defaultLanguage WHERE name = 'neo4j'
RETURN name, defaultLanguage
Recorded result
namedefaultLanguage
"neo4j""CYPHER 5"

1 row

A statement without a prefix still runs as Cypher 25:

Cypher
RETURN s'{1 + 1} hops' AS label
Recorded result
label
"2 hops"

1 row

A preview feature without its opt-in:

Cypher
RETURN datetime('2026-01-01T00:00Z') IS BEFORE datetime('2026-06-01T00:00Z') AS earlier
Expected error
error: semantic error: SemanticError: preview feature 'chronological-comparisons' is not enabled: set RELATE_PREVIEW=chronological-comparisons

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

RELATE_PREVIEW=chronological-comparisons relate --mode table "RETURN datetime('2026-01-01T00:00Z') IS BEFORE datetime('2026-06-01T00:00Z') AS earlier"
+---------+
| earlier |
+---------+
| true    |
+---------+

A name that is not a preview feature fails the open:

RELATE_PREVIEW=chronological relate --mode table "RETURN 1 AS one"
Failed to open Relate: semantic error: SemanticError: invalid RELATE_PREVIEW value: unknown preview feature 'chronological' (known features: hybrid-search, local-callables, graph-type-opt-props, graph-type-default-values, graph-type-implied-labels, ontology, obfuscated-literals, mixed-label-syntax, float16-coordinate-types, chronological-comparisons, complex-search-patterns, coll-zip, coll-has, gql-stddev-aliases)

See also