Deprecations, additions and compatibility

This section list all of the features that have been removed, deprecated, added, or extended in different Cypher® versions. Replacement syntax for deprecated and removed features are also indicated.

Version 4.3

Deprecated features

Feature Details

Syntax Deprecated

CREATE CONSTRAINT [name]
ON (node:Label)
ASSERT exists(node.property)

Replaced by:

CREATE CONSTRAINT [name]
ON (node:Label)
ASSERT node.property IS NOT NULL

Syntax Deprecated

CREATE CONSTRAINT [name]
ON ()-[rel:REL]-()
ASSERT exists(rel.property)

Replaced by:

CREATE CONSTRAINT [name]
ON ()-[rel:REL]-()
ASSERT rel.property IS NOT NULL

Syntax Deprecated

exists(prop)

Replaced by:

prop IS NOT NULL

Syntax Deprecated

NOT exists(prop)

Replaced by:

prop IS NULL

Syntax Deprecated
BRIEF [OUTPUT] for SHOW INDEXES and SHOW CONSTRAINTS.

Replaced by default output columns.

Syntax Deprecated
VERBOSE [OUTPUT] for SHOW INDEXES and SHOW CONSTRAINTS.

Replaced by:

YIELD *

Syntax Deprecated

SHOW EXISTS CONSTRAINTS

Replaced by:

SHOW [PROPERTY] EXIST[ENCE] CONSTRAINTS

Still allows BRIEF and VERBOSE but not YIELD or WHERE.

Syntax Deprecated

SHOW NODE EXISTS CONSTRAINTS

Replaced by:

SHOW NODE [PROPERTY] EXIST[ENCE] CONSTRAINTS

Still allows BRIEF and VERBOSE but not YIELD or WHERE.

Syntax Deprecated

SHOW RELATIONSHIP EXISTS CONSTRAINTS

Replaced by:

SHOW RELATIONSHIP [PROPERTY] EXIST[ENCE] CONSTRAINTS

Still allows BRIEF and VERBOSE but not YIELD or WHERE.

Syntax Deprecated
For privilege commands:

ON DEFAULT DATABASE

Replaced by:

ON HOME DATABASE

Syntax Deprecated
For privilege commands:

ON DEFAULT GRAPH

Replaced by:

ON HOME GRAPH

Syntax Deprecated

MATCH (a) RETURN (a)--()

Pattern expressions producing lists of paths are deprecated, but they can still be used as existence predicates, for example in WHERE clauses. Instead, use a pattern comprehension:

MATCH (a) RETURN [p=(a)--() | p]

Updated features

Feature Details

Functionality Updated

SHOW INDEXES WHERE ...

Now allows filtering for:

SHOW INDEXES

Functionality Updated

SHOW CONSTRAINTS WHERE ...

Now allows filtering for:

SHOW CONSTRAINTS

Functionality Updated

SHOW INDEXES YIELD ...
[WHERE ...]
[RETURN ...]

Now allows YIELD, WHERE, and RETURN clauses to SHOW INDEXES to change the output.

Functionality Updated

SHOW CONSTRAINTS YIELD ...
[WHERE ...]
[RETURN ...]

Now allows YIELD, WHERE, and RETURN clauses to SHOW CONSTRAINTS to change the output.

Syntax Updated

SHOW [PROPERTY] EXIST[ENCE] CONSTRAINTS

New syntax for filtering SHOW CONSTRAINTS on property existence constraints.
Allows YIELD and WHERE but not BRIEF or VERBOSE.

Syntax Updated

SHOW NODE [PROPERTY] EXIST[ENCE] CONSTRAINTS

New syntax for filtering SHOW CONSTRAINTS on node property existence constraints.
Allows YIELD and WHERE but not BRIEF or VERBOSE.

Syntax Updated

SHOW REL[ATIONSHIP] [PROPERTY] EXIST[ENCE] CONSTRAINTS

New syntax for filtering SHOW CONSTRAINTS on relationship property existence constraints.
Allows YIELD and WHERE but not BRIEF or VERBOSE.

Functionality Updated

SHOW FULLTEXT INDEXES

Now allows easy filtering for SHOW INDEXES on fulltext indexes.
Allows YIELD and WHERE but not BRIEF or VERBOSE.

Functionality Updated

SHOW LOOKUP INDEXES

Now allows easy filtering for SHOW INDEXES on token lookup indexes.
Allows YIELD and WHERE but not BRIEF or VERBOSE.

New features

Feature Details

Syntax New

CREATE DATABASE ...
[OPTIONS {...}]

New syntax to pass options to CREATE DATABASE. This can be used to specify a specific cluster node to seed data from.

Syntax New

CREATE CONSTRAINT [name]
ON (node:Label)
ASSERT node.property IS NOT NULL

New syntax for creating node property existence constraints.

Syntax New

CREATE CONSTRAINT [name]
ON ()-[rel:REL]-()
ASSERT rel.property IS NOT NULL

New syntax for creating relationship property existence constraints.

Syntax New

ALTER USER name IF EXISTS ...

Makes altering users idempotent. If the specified name does not exists, no error is thrown.

Syntax New

ALTER USER ...
SET HOME DATABASE ...

Now allows setting home database for user.

Syntax New

ALTER USER ...
REMOVE HOME DATABASE

Now allows removing home database for user.

Syntax New

CREATE USER ...
SET HOME DATABASE ...

CREATE USER now allows setting home database for user.

Syntax New

SHOW HOME DATABASE

New syntax for showing the home database of the current user.

Syntax New
New privilege:

SET USER HOME DATABASE

New Cypher command for administering privilege for changing users home database.

Syntax New
For privilege commands:

ON HOME DATABASE

New syntax for privileges affecting home database.

Syntax New
For privilege commands:

ON HOME GRAPH

New syntax for privileges affecting home graph.

Syntax New

CREATE FULLTEXT INDEX ...

Allows creating fulltext indexes on nodes or relationships. They can be dropped by using their name.

Functionality New

CREATE INDEX FOR ()-[r:TYPE]-() ...

Allows creating indexes on relationships with a particular relationship type and property combination. They can be dropped by using their name.

Functionality New

CREATE LOOKUP INDEX ...

Create token lookup index for nodes with any labels or relationships with any relationship type. They can be dropped by using their name.

Functionality New

RENAME ROLE

New Cypher command for changing the name of a role.

Functionality New

RENAME USER

New Cypher command for changing the name of a user.

Functionality New

SHOW PROCEDURE[S]
[EXECUTABLE [BY {CURRENT USER | username}]]
[YIELD ...]
[WHERE ...]
[RETURN ...]

New Cypher commands for listing procedures.

Functionality New

SHOW [ALL | BUILT IN | USER DEFINED] FUNCTION[S]
[EXECUTABLE [BY {CURRENT USER | username}]]
[YIELD ...]
[WHERE ...]
[RETURN ...]

New Cypher commands for listing functions.

Version 4.2

Deprecated features

Feature Details

Syntax Deprecated

0...

Replaced by 0o....

Syntax Deprecated

0X...

Only 0x... (lowercase x) is supported.

Syntax Deprecated

CALL { RETURN 1 }

Unaliased expressions are deprecated in subquery RETURN clauses. Replaced by:

CALL { RETURN 1 AS one }

Updated features

Feature Details

Functionality Updated

SHOW ROLE name PRIVILEGES

Can now handle multiple roles.

SHOW ROLES n1, n2, ... PRIVILEGES

Functionality Updated

SHOW USER name PRIVILEGES

Can now handle multiple users.

SHOW USERS n1, n2, ... PRIVILEGES

Functionality Updated

round(expression, precision)

The round() function can now take an additional argument to specify rounding precision.

Functionality Updated

round(expression, precision, mode)

The round() function can now take two additional arguments to specify rounding precision and rounding mode.

New features

Feature Details

Functionality New

SHOW PRIVILEGES [AS [REVOKE] COMMAND[S]]

Privileges can now be shown as Cypher commands.

Syntax New

DEFAULT GRAPH

New optional part of the Cypher commands for database privileges.

Syntax New

0o...

Cypher now interprets literals with prefix 0o as an octal integer literal.

Syntax New

SET [PLAINTEXT | ENCRYPTED] PASSWORD

For CREATE USER and ALTER USER, it is now possible to set (or update) a password when the plaintext password is unknown, but the encrypted password is available.

Functionality New
New privilege:

EXECUTE

New Cypher commands for administering privileges for executing procedures and user defined functions. See The DBMS EXECUTE privileges.

Syntax New

CREATE [BTREE] INDEX ... [OPTIONS {...}]

Allows setting index provider and index configuration when creating an index.

Syntax New

CREATE CONSTRAINT ... IS NODE KEY [OPTIONS {...}]

Allows setting index provider and index configuration for the backing index when creating a node key constraint.

Syntax New

CREATE CONSTRAINT ... IS UNIQUE [OPTIONS {...}]

Allows setting index provider and index configuration for the backing index when creating a uniqueness constraint.

Syntax New

SHOW CURRENT USER

New Cypher command for showing current logged-in user and roles.

Functionality New

SHOW [ALL | BTREE] INDEX[ES] [BRIEF | VERBOSE [OUTPUT]]

New Cypher commands for listing indexes.

Replaces the procedures db.indexes, db.indexDetails (verbose), and partially db.schemaStatements (verbose).

Functionality New

SHOW [ALL | UNIQUE | NODE EXIST[S] | RELATIONSHIP EXIST[S] | EXIST[S] | NODE KEY] CONSTRAINT[S] [BRIEF | VERBOSE [OUTPUT]]

New Cypher commands for listing constraints.

Replaces the procedures db.constraints and partially db.schemaStatements (verbose).

Functionality New
New privilege:

SHOW INDEX

New Cypher command for administering privilege for listing indexes.

Functionality New
New privilege:

SHOW CONSTRAINT

New Cypher command for administering privilege for listing constraints.

Version 4.1.3

New features

Feature Details

Syntax New

CREATE INDEX [name] IF NOT EXISTS FOR ...

Makes index creation idempotent. If an index with the name or schema already exists no error will be thrown.

Syntax New

DROP INDEX name IF EXISTS

Makes index deletion idempotent. If no index with the name exists no error will be thrown.

Syntax New

CREATE CONSTRAINT [name] IF NOT EXISTS ON ...

Makes constraint creation idempotent. If a constraint with the name or type and schema already exists no error will be thrown.

Syntax New

DROP CONSTRAINT name IF EXISTS

Makes constraint deletion idempotent. If no constraint with the name exists no error will be thrown.

Version 4.1

Restricted features

Feature Details

Functionality Restricted

REVOKE ...

No longer revokes sub-privileges when revoking a compound privilege, e.g. when revoking INDEX MANAGEMENT, any CREATE INDEX and DROP INDEX privileges will no longer be revoked.

Functionality Restricted

ALL DATABASE PRIVILEGES

No longer includes the privileges START DATABASE and STOP DATABASE.

Updated features

Feature Details

Procedure Updated

queryId

The queryId procedure format has changed, and no longer includes the database name. For example, mydb-query-123 is now query-123. This change affects built-in procedures dbms.listQueries(), dbms.listActiveLocks(queryId), dbms.killQueries(queryIds) and dbms.killQuery(queryId).

Functionality Updated

SHOW PRIVILEGES

The returned privileges are a closer match to the original grants and denies, e.g. if granted MATCH the command will show that specific privilege and not the TRAVERSE and READ privileges. Added support for YIELD and WHERE clauses to allow filtering results.

New features

Feature Details

Functionality New
New role:

PUBLIC

The PUBLIC role is automatically assigned to all users, giving them a set of base privileges.

Syntax New
For privileges:

REVOKE MATCH

The MATCH privilege can now be revoked.

Functionality New

SHOW USERS

New support for YIELD and WHERE clauses to allow filtering results.

Functionality New

SHOW ROLES

New support for YIELD and WHERE clauses to allow filtering results.

Functionality New

SHOW DATABASES

New support for YIELD and WHERE clauses to allow filtering results.

Functionality New
TRANSACTION MANAGEMENT privileges

New Cypher commands for administering transaction management.

Functionality New
DBMS USER MANAGEMENT privileges

New Cypher commands for administering user management.

Functionality New
DBMS DATABASE MANAGEMENT privileges

New Cypher commands for administering database management.

Functionality New
DBMS PRIVILEGE MANAGEMENT privileges

New Cypher commands for administering privilege management.

Functionality New

ALL DBMS PRIVILEGES

New Cypher command for administering role, user, database and privilege management.

Functionality New

ALL GRAPH PRIVILEGES

New Cypher command for administering read and write privileges.

Functionality New
Write privileges

New Cypher commands for administering write privileges.

Functionality New

ON DEFAULT DATABASE

New optional part of the Cypher commands for database privileges.

Version 4.0

Removed features

Feature Details

Function Removed

rels()

Replaced by relationships().

Function Removed

toInt()

Replaced by toInteger().

Function Removed

lower()

Replaced by toLower().

Function Removed

upper()

Replaced by toUpper().

Function Removed

extract()

Replaced by list comprehension.

Function Removed

filter()

Replaced by list comprehension.

Functionality Removed
For Rule planner:

CYPHER planner=rule

The RULE planner was removed in 3.2, but still possible to trigger using START or CREATE UNIQUE clauses. Now it is completely removed.

Functionality Removed
Explicit indexes

The removal of the RULE planner in 3.2 was the beginning of the end for explicit indexes. Now they are completely removed, including the removal of the built-in procedures for Neo4j 3.3 to 3.5.

Functionality Removed
For compiled runtime:

CYPHER runtime=compiled

Replaced by the new pipelined runtime which covers a much wider range of queries.

Clause Removed

CREATE UNIQUE

Running queries with this clause will cause a syntax error. Running with CYPHER 3.5 will cause a runtime error due to the removal of the rule planner.

Clause Removed

START

Running queries with this clause will cause a syntax error. Running with CYPHER 3.5 will cause a runtime error due to the removal of the rule planner.

Syntax Removed

MATCH (n)-[:A|:B|:C {foo: 'bar'}]-() RETURN n

Replaced by MATCH (n)-[:A|B|C {foo: 'bar'}]-() RETURN n.

Syntax Removed

MATCH (n)-[x:A|:B|:C]-() RETURN n

Replaced by MATCH (n)-[x:A|B|C]-() RETURN n.

Syntax Removed

MATCH (n)-[x:A|:B|:C*]-() RETURN n

Replaced by MATCH (n)-[x:A|B|C*]-() RETURN n.

Syntax Removed

{parameter}

Replaced by $parameter.

Deprecated features

Feature Details

Syntax Deprecated

MATCH (n)-[rs*]-() RETURN rs

As in Cypher 3.2, this is replaced by:

MATCH p=(n)-[*]-() RETURN relationships(p) AS rs

Syntax Deprecated

CREATE INDEX ON :Label(prop)

Replaced by CREATE INDEX FOR (n:Label) ON (n.prop).

Syntax Deprecated

DROP INDEX ON :Label(prop)

Replaced by DROP INDEX name.

Syntax Deprecated

DROP CONSTRAINT ON (n:Label) ASSERT (n.prop) IS NODE KEY

Replaced by DROP CONSTRAINT name.

Syntax Deprecated

DROP CONSTRAINT ON (n:Label) ASSERT (n.prop) IS UNIQUE

Replaced by DROP CONSTRAINT name.

Syntax Deprecated

DROP CONSTRAINT ON (n:Label) ASSERT exists(n.prop)

Replaced by DROP CONSTRAINT name.

Syntax Deprecated

DROP CONSTRAINT ON ()-[r:Type]-() ASSERT exists(r.prop)

Replaced by DROP CONSTRAINT name.

Restricted features

Feature Details

Function Restricted

length()

Restricted to only work on paths. See length() for more details.

Function Restricted

size()

No longer works for paths. Only works for strings, lists and pattern expressions. See size() for more details.

Updated features

Feature Details

Syntax Extended

CREATE CONSTRAINT [name] ON ...

The create constraint syntax can now include a name.

The IS NODE KEY and IS UNIQUE versions of this command replace the procedures db.createNodeKey and db.createUniquePropertyConstraint, respectively.

New features

Feature Details

Functionality New
Pipelined runtime:

CYPHER runtime=pipelined

This Neo4j Enterprise Edition only feature involves a new runtime that has many performance enhancements.

Functionality New
Multi-database administration

New Cypher commands for administering multiple databases.

Functionality New
Access control

New Cypher commands for administering role-based access control.

Functionality New
Fine-grained security

New Cypher commands for administering dbms, database, graph and sub-graph access control.

Syntax New

CREATE INDEX [name] FOR (n:Label) ON (n.prop)

New syntax for creating indexes, which can include a name.

Replaces the db.createIndex procedure.

Syntax New

DROP INDEX name

New command for dropping an index by name.

Syntax New

DROP CONSTRAINT name

New command for dropping a constraint by name, no matter the type.

Clause New

WHERE EXISTS {...}

Existential sub-queries are sub-clauses used to filter the results of a MATCH, OPTIONAL MATCH, or WITH clause.

Clause New

USE neo4j

New clause to specify which graph a query, or query part, is executed against.

Version 3.5

Deprecated features

Feature Details

Functionality Deprecated
Compiled runtime:

CYPHER runtime=compiled

The compiled runtime will be discontinued in the next major release. It might still be used for default queries in order to not cause regressions, but explicitly requesting it will not be possible.

Function Deprecated

extract()

Replaced by list comprehension.

Function Deprecated

filter()

Replaced by list comprehension.

Version 3.4

Feature Type Change Details

Spatial point types

Functionality

Amendment

A point — irrespective of which Coordinate Reference System is used — can be stored as a property and is able to be backed by an index. Prior to this, a point was a virtual property only.

point() - Cartesian 3D

Function

Added

point() - WGS 84 3D

Function

Added

randomUUID()

Function

Added

Temporal types

Functionality

Added

Supports storing, indexing and working with the following temporal types: Date, Time, LocalTime, DateTime, LocalDateTime and Duration.

Temporal functions

Functionality

Added

Functions allowing for the creation and manipulation of values for each temporal type — Date, Time, LocalTime, DateTime, LocalDateTime and Duration.

Temporal operators

Functionality

Added

Operators allowing for the manipulation of values for each temporal type — Date, Time, LocalTime, DateTime, LocalDateTime and Duration.

toString()

Function

Extended

Now also allows temporal values as input (i.e. values of type Date, Time, LocalTime, DateTime, LocalDateTime or Duration).

Version 3.3

Feature Type Change Details

START

Clause

Removed

As in Cypher 3.2, any queries using the START clause will revert back to Cypher 3.1 planner=rule. However, there are built-in procedures for Neo4j versions 3.3 to 3.5 for accessing explicit indexes. The procedures will enable users to use the current version of Cypher and the cost planner together with these indexes. An example of this is CALL db.index.explicit.searchNodes('my_index','email:me*').

CYPHER runtime=slotted (Faster interpreted runtime)

Functionality

Added

Neo4j Enterprise Edition only

max(), min()

Function

Extended

Now also supports aggregation over sets containing lists of strings and/or numbers, as well as over sets containing strings, numbers, and lists of strings and/or numbers

Version 3.2

Feature Type Change Details

CYPHER planner=rule (Rule planner)

Functionality

Removed

All queries now use the cost planner. Any query prepended thus will fall back to using Cypher 3.1.

CREATE UNIQUE

Clause

Removed

Running such queries will fall back to using Cypher 3.1 (and use the rule planner)

START

Clause

Removed

Running such queries will fall back to using Cypher 3.1 (and use the rule planner)

MATCH (n)-[rs*]-() RETURN rs

Syntax

Deprecated

Replaced by MATCH p=(n)-[*]-() RETURN relationships(p) AS rs

MATCH (n)-[:A|:B|:C {foo: 'bar'}]-() RETURN n

Syntax

Deprecated

Replaced by MATCH (n)-[:A|B|C {foo: 'bar'}]-() RETURN n

MATCH (n)-[x:A|:B|:C]-() RETURN n

Syntax

Deprecated

Replaced by MATCH (n)-[x:A|B|C]-() RETURN n

MATCH (n)-[x:A|:B|:C*]-() RETURN n

Syntax

Deprecated

Replaced by MATCH (n)-[x:A|B|C*]-() RETURN n

User-defined aggregation functions

Functionality

Added

Composite indexes

Index

Added

Node Key

Index

Added

Neo4j Enterprise Edition only

CYPHER runtime=compiled (Compiled runtime)

Functionality

Added

Neo4j Enterprise Edition only

reverse()

Function

Extended

Now also allows a list as input

max(), min()

Function

Extended

Now also supports aggregation over a set containing both strings and numbers

Version 3.1

Feature Type Change Details

rels()

Function

Deprecated

Replaced by relationships()

toInt()

Function

Deprecated

Replaced by toInteger()

lower()

Function

Deprecated

Replaced by toLower()

upper()

Function

Deprecated

Replaced by toUpper()

toBoolean()

Function

Added

Map projection

Syntax

Added

Pattern comprehension

Syntax

Added

User-defined functions

Functionality

Added

CALL...YIELD...WHERE

Clause

Extended

Records returned by YIELD may be filtered further using WHERE

Version 3.0

Feature Type Change Details

has()

Function

Removed

Replaced by exists()

str()

Function

Removed

Replaced by toString()

{parameter}

Syntax

Deprecated

Replaced by $parameter

properties()

Function

Added

CALL [...YIELD]

Clause

Added

point() - Cartesian 2D

Function

Added

point() - WGS 84 2D

Function

Added

distance()

Function

Added

User-defined procedures

Functionality

Added

toString()

Function

Extended

Now also allows Boolean values as input

Compatibility

Neo4j’s ability to support multiple older versions of the Cypher language has changed over time. In versions prior to Neo4j 3.4, the backwards compatibility layer included the Cypher language parser, planner, and runtime. All supported versions of Cypher ran on the same Neo4j kernel. However, this changed in Neo4j 3.4 when the runtime was excluded from the compatibility layer. When you run, e.g. a CYPHER 3.1 query in Neo4j 3.5, the query is planned with the 3.1 planner, but run with 3.5 runtime and kernel. The compatibility layer changed again in Neo4j 4.0 and it now includes only the Cypher language parser. When you run a CYPHER 3.5 query, e.g., in Neo4j 4.3, Neo4j parses the older language features, but uses the 4.3 planner, runtime, and kernel to plan and run the query. The primary reason for these changes is the optimizations in the Cypher runtime to allow Cypher queries to perform better.

Older versions of the language can still be accessed if required. There are two ways to select which version to use in queries.

  1. Setting a version for all queries: You can configure your database with the configuration parameter cypher.default_language_version, and enter which version you’d like to use (see Supported language versions). Every Cypher query will use this version, provided the query hasn’t explicitly been configured as described in the next item below.

  2. Setting a version on a query by query basis: The other method is to set the version for a particular query. Prepending a query with CYPHER 3.5 will execute the query with the version of Cypher included in Neo4j 3.5.

Below is an example using the older parameter syntax {param}:

CYPHER 3.5
MATCH (n:Person)
WHERE n.age > {agelimit}
RETURN n.name, n.age

Without the CYPHER 3.5 prefix this query would fail with a syntax error. With CYPHER 3.5 however, it will only generate a warning and still work.

In Neo4j 4.3 the Cypher parser understands some older language features, even if they are no longer supported by the Neo4j kernel. These features result in runtime errors. See the table at Cypher Version 4.0 for the list of affected features.

Supported language versions

Neo4j 4.3 supports the following versions of the Cypher language:

  • Neo4j Cypher 3.5

  • Neo4j Cypher 4.2

  • Neo4j Cypher 4.3

Each release of Neo4j supports a limited number of old Cypher Language Versions. When you upgrade to a new release of Neo4j, please make sure that it supports the Cypher language version you need. If not, you may need to modify your queries to work with a newer Cypher language version.