Deprecations, additions and compatibility

Cypher is a language that is constantly evolving. New features get added to the language continuously, and occasionally, some features become deprecated and are subsequently removed.

1. Removals, deprecations, additions, and extensions

The following tables list all of the features which have been removed, deprecated, added, or extended in Cypher. Replacement syntax for deprecated and removed features are also indicated.

1.1. Version 4.2

Feature Type Change Details

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

Functionality

Added

Privileges can now be shown as Cypher commands

SHOW ROLE name PRIVILEGES

Functionality

Updated

Can now handle multiple roles, SHOW ROLES n1, n2, …​ PRIVILEGES

SHOW USER name PRIVILEGES

Functionality

Updated

Can now handle multiple users, SHOW USERS n1, n2, …​ PRIVILEGES

round(expression, precision)

Functionality

Updated

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

round(expression, precision, mode)

Functionality

Updated

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

DEFAULT GRAPH

Syntax

Added

New optional part of the Cypher commands for database privileges

0o…​

Syntax

Added

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

0…​

Syntax

Deprecated

Replaced by 0o…​ (see above).

0X…​

Syntax

Deprecated

Only 0x…​ (lowercase x) will be supported.

SET [PLAINTEXT | ENCRYPTED] PASSWORD

Syntax

Added

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.

EXECUTE privileges

Functionality

Added

New Cypher commands for administering privileges for executing procedures and user defined functions.

CREATE [BTREE] INDEX …​ [OPTIONS {…​}]

Syntax

Added

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

CREATE CONSTRAINT …​ IS NODE KEY [OPTIONS {…​}]

Syntax

Added

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

CREATE CONSTRAINT …​ IS UNIQUE [OPTIONS {…​}]

Syntax

Added

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

db.createIndex

Procedure

Deprecated

Replaced by CREATE INDEX command.

db.createNodeKey

Procedure

Deprecated

Replaced by CREATE CONSTRAINT …​ IS NODE KEY command.

db.createUniquePropertyConstraint

Procedure

Deprecated

Replaced by CREATE CONSTRAINT …​ IS UNIQUE command.

SHOW CURRENT USER

Syntax

Added

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

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

Functionality

Added

New Cypher commands for listing indexes.

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

Functionality

Added

New Cypher commands for listing constraints.

db.indexes

Procedure

Deprecated

Replaced by SHOW INDEXES

db.indexDetails

Procedure

Deprecated

Replaced by SHOW INDEXES VERBOSE

db.constraints

Procedure

Deprecated

Replaced by SHOW CONSTRAINTS

db.schemaStatements

Procedure

Deprecated

Replaced by SHOW INDEXES VERBOSE and SHOW CONSTRAINTS VERBOSE

SHOW INDEX privilege

Functionality

Added

New Cypher command for administering privilege for listing indexes.

SHOW CONSTRAINT privilege

Functionality

Added

New Cypher command for administering privilege for listing constraints.

1.2. Version 4.1.3

Feature Type Change Details

CREATE INDEX [name] IF NOT EXISTS FOR …​

Syntax

Added

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

DROP INDEX name IF EXISTS

Syntax

Added

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

CREATE CONSTRAINT [name] IF NOT EXISTS ON …​

Syntax

Added

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

DROP CONSTRAINT name IF EXISTS

Syntax

Added

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

1.3. Version 4.1

Feature Type Change Details

queryId

Procedure

Updated

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)

PUBLIC role

Functionality

Added

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

REVOKE MATCH

Syntax

Added

The MATCH privilege can now be revoked

REVOKE …​

Functionality

Restricted

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

SHOW PRIVILEGES

Functionality

Updated

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.

SHOW USERS

Functionality

Added

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

SHOW ROLES

Functionality

Added

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

SHOW DATABASES

Functionality

Added

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

ALL DATABASE PRIVILEGES

Functionality

Restricted

No longer includes the privileges START DATABASE and STOP DATABASE

TRANSACTION MANAGEMENT privileges

Functionality

Added

New Cypher commands for administering transaction management

DBMS USER MANAGEMENT privileges

Functionality

Added

New Cypher commands for administering user management

DBMS DATABASE MANAGEMENT privileges

Functionality

Added

New Cypher commands for administering database management

DBMS PRIVILEGE MANAGEMENT privileges

Functionality

Added

New Cypher commands for administering privilege management

ALL DBMS PRIVILEGES

Functionality

Added

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

ALL GRAPH PRIVILEGES

Functionality

Added

New Cypher command for administering read and write privileges

Write privileges

Functionality

Added

New Cypher commands for administering write privileges

ON DEFAULT DATABASE

Syntax

Added

New optional part of the Cypher commands for database privileges

1.4. Version 4.0

Feature Type Change Details

rels()

Function

Removed

Replaced by relationships()

toInt()

Function

Removed

Replaced by toInteger()

lower()

Function

Removed

Replaced by toLower()

upper()

Function

Removed

Replaced by toUpper()

extract()

Function

Removed

Replaced by list comprehension

filter()

Function

Removed

Replaced by list comprehension

length()

Function

Restricted

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

size()

Function

Restricted

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

CYPHER planner=rule (Rule planner)

Functionality

Removed

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

CREATE UNIQUE

Clause

Removed

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.

START

Clause

Removed

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.

Explicit indexes

Functionality

Removed

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.

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

Syntax

Deprecated

As in Cypher 3.2, this is replaced by MATCH p=(n)-[*]-() RETURN relationships(p) AS rs

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

Syntax

Removed

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

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

Syntax

Removed

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

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

Syntax

Removed

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

{parameter}

Syntax

Removed

Replaced by $parameter

CYPHER runtime=pipelined (Pipelined runtime)

Functionality

Added

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

CYPHER runtime=compiled (Compiled runtime)

Functionality

Removed

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

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

Syntax

Added

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

CREATE CONSTRAINT [name] ON …​

Syntax

Extended

The create constraint syntax can now include a name.

DROP INDEX name

Syntax

Added

New command for dropping an index by name.

DROP CONSTRAINT name

Syntax

Added

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

CREATE INDEX ON :Label(prop)

Syntax

Deprecated

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

DROP INDEX ON :Label(prop)

Syntax

Deprecated

Replaced by DROP INDEX name

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

Syntax

Deprecated

Replaced by DROP CONSTRAINT name

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

Syntax

Deprecated

Replaced by DROP CONSTRAINT name

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

Syntax

Deprecated

Replaced by DROP CONSTRAINT name

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

Syntax

Deprecated

Replaced by DROP CONSTRAINT name

WHERE EXISTS {…​}

Clause

Added

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

Multi-database administration

Functionality

Added

New Cypher commands for administering multiple databases

Security administration

Functionality

Added

New Cypher commands for administering role-based access-control

Fine-grained security

Functionality

Added

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

USE neo4j

Clause

Added

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

1.5. Version 3.5

Feature Type Change Details

CYPHER runtime=compiled (Compiled runtime)

Functionality

Deprecated

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.

extract()

Function

Deprecated

Replaced by list comprehension

filter()

Function

Deprecated

Replaced by list comprehension

1.6. 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).

1.7. 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

1.8. 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

1.9. 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

1.10. 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

2. Compatibility

The ability of Neo4j to support multiple older versions of the Cypher language has been changing. In versions of Neo4j before 3.5 the backwards compatibility layer included the Cypher language parser, planner and runtime. All supported versions of Cypher would run on the same Neo4j kernel. In Neo4j 3.4, however, this was changed such that the compatibility layer no longer included the runtime. This meant that running, for example, a CYPHER 3.1 query inside Neo4j 3.5 would plan the query using the 3.1 planner, and run it using the 3.5 runtime and kernel. In Neo4j 4.0 this was changed again, such that the compatibility layer includes only the parser. For example, running a CYPHER 3.5 query inside Neo4j will parse older language features, but plan using the 4.2 planner, and run using the 4.2 runtime and kernel. The primary reason for this change has been optimizations in the Cypher runtime to allow Cypher query 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.2 some older language features are understood by the Cypher parser even if they are no longer supported by the Neo4j kernel. These features will result in runtime errors. See the table at Cypher Version 4.0 for the list of affected features.

3. Supported language versions

Neo4j 4.2 supports the following versions of the Cypher language:

  • Neo4j Cypher 3.5

  • Neo4j Cypher 4.1

  • Neo4j Cypher 4.2

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.