additional-cypher.adoc

Additional Cypher features

While the GQL Standard incorporates a lot of capabilities in Cypher, Cypher contains additional features that are not part of GQL and no GQL alternatives currently exist for them. This page covers those Cypher features.

Clauses

Cypher feature	Description
LOAD CSV	Import data from CSV files.
MERGE	Ensures that a pattern exists in the graph. Either the pattern already exists, or it needs to be created.

Subqueries

Cypher feature	Description
CALL { …​ } IN TRANSACTIONS	CALL subqueries executed in separate, inner transactions, producing intermediate commits.
COLLECT	Used to create a list with the rows returned by a subquery.
COUNT	Used to count the number of rows returned by a subquery.
EXISTS	Used to discover if a specified pattern exists at least once in the graph

Values and types

Cypher feature	Description
POINT values	Spatial values.
MAP values.	Map values - the GQL equivalent is Records.

Comprehensions and projections

Cypher feature	Description
List comprehension	Syntactic construct for creating a LIST based on existing lists.
Map projection	Constructs MAP projections from nodes, relationships, and other MAP values.
Pattern comprehension	Syntactic construct for creating a LIST based on matchings of a pattern.

Dynamic queries

Node labels, relationship types, properties, and CSV columns can be referenced dynamically using Cypher. This allows for more flexible queries and mitigates the risk of Cypher injection. (For more information about Cypher injection, see Neo4j Knowledge Base → Protecting against Cypher injection).

Cypher feature	Description
MATCH (n:$($label)), ()-[r:$($type)]->()	MATCH nodes and relationships using dynamic node labels and relationship types
CREATE (n:$($label)), ()-[r:$($type)]->()	CREATE nodes and relationships using dynamic node labels and relationship types
MERGE (n:$($label)), ()-[r:$($type)]->()	MERGE nodes and relationships using dynamic node labels and relationship types
LOAD CSV WITH HEADERS FROM 'file:///artists-with-headers.csv' AS line CREATE (n:$(line.label) {name: line.Name})	Import CSV files using dynamic columns
MATCH (n) SET n[$key] = value	Dynamically SET or update a property
MATCH (n:Label) SET n:$(n.property)	Dynamically SET a node label
MATCH (n {name: 'Peter'}) REMOVE n:$($label)	Dynamically REMOVE a property
MATCH (n {name: 'Peter'}) REMOVE n:$($label)	Dynamically REMOVE a node label

Functions

Database functions

Cypher feature	Description
db.nameFromElementId()	Resolves the database name for the given element id.

GenAI functions

Cypher feature	Description
genai.vector.encode()	Generates a vector embedding for a single value.

Graph functions

Cypher feature	Description
graph.byElementId()	Returns the graph reference with the given element id. It is only supported in the USE clause. As of Neo4j 5.26, it is supported on both standard and composite databases. On earlier versions, it is only supported on composite databases.
graph.byName()	Returns the graph reference of the given name. It is only supported in the USE clause, on composite databases.
graph.names()	Lists the names of graphs in the current database.
graph.propertiesByName()	Returns the MAP of properties associated with a graph.

List functions

Cypher feature	Description
keys()	Returns a LIST<STRING> containing the STRING representations for all the property names of a NODE, RELATIONSHIP, or MAP.
labels()	Returns a LIST<STRING> containing the STRING representations for all the labels of a NODE.
nodes()	Returns a LIST<NODE> containing all the NODE values in a PATH.
range()	Returns a LIST<INTEGER> comprising all INTEGER values within a specified range.
reduce()	Runs an expression against individual elements of a LIST<ANY>, storing the result of the expression in an accumulator.
relationships()	Returns a LIST<RELATIONSHIP> containing all the RELATIONSHIP values in a PATH.
reverse()	Returns a STRING or LIST<ANY> in which the order of all characters or elements in the given STRING or LIST<ANY> have been reversed.
tail()	Returns all but the first element in a LIST<ANY>.
toBooleanList()	Converts a LIST<ANY> of values to a LIST<BOOLEAN> values. If any values are not convertible to BOOLEAN they will be null in the LIST<BOOLEAN> returned.
toFloatList()	Converts a LIST<ANY> to a LIST<FLOAT> values. If any values are not convertible to FLOAT they will be null in the LIST<FLOAT> returned.
toIntegerList()	Converts a LIST<ANY> to a LIST<INTEGER> values. If any values are not convertible to INTEGER they will be null in the LIST<INTEGER> returned.
toStringList()	Converts an INTEGER, FLOAT, BOOLEAN, POINT or temporal type (i.e. DATE, ZONED TIME, LOCAL TIME, ZONED DATETIME, LOCAL DATETIME or DURATION) value to a STRING, or null if the value cannot be converted.

LOAD CSV functions

Cypher feature	Description
file()	Returns the absolute path of the file that LOAD CSV is using.
lineNumber	Returns the line number that LOAD CSV is currently using.

Logarithmic functions

Cypher feature	Description
e()	Returns the base of the natural logarithm, e.

Numeric functions

Cypher feature	Description
isNaN()	Returns whether the given INTEGER or FLOAT is NaN.
rand()	Returns a random FLOAT in the range from 0 (inclusive) to 1 (exclusive).
round()	Returns the value of a number rounded to the nearest INTEGER.
sign()	Returns the signum of an INTEGER or FLOAT: 0 if the number is 0, -1 for any negative number, and 1 for any positive number.

Predicate functions

Cypher feature	Description
all()	Returns true if the predicate holds for all elements in the given LIST<ANY>.
any()	Returns true if the predicate holds for at least one element in the given LIST<ANY>.
isEmpty()	Checks whether a STRING, MAP, or LIST<ANY> is empty.
none()	Returns true if the predicate holds for no element in the given LIST<ANY>.
single()	Returns true if the predicate holds for exactly one of the elements in the given LIST<ANY>.

Scalar functions

Cypher feature	Description
endNode()	Returns the end NODE of a RELATIONSHIP.
head()	Returns the first element in a LIST<ANY>.
last()	Returns the last element in a LIST<ANY>.
properties()	Returns a MAP containing all the properties of a NODE, RELATIONSHIP, or MAP.
randomUUID()	Generates a random UUID.
startNode()	Returns the start NODE of a RELATIONSHIP.
type()	Returns a STRING representation of the RELATIONSHIP type.
valueType()	Returns a STRING representation of the most precise value type that the given expression evaluates to.

Spatial functions

Cypher feature	Description
point()	Returns a 2D or 3D point object, given two or respectively three coordinate values in the Cartesian coordinate system or WGS 84 geographic coordinate system.
point.distance()	Returns a FLOAT representing the distance between any two points in the same CRS. If the points are in the WGS 84 CRS, the function returns the geodesic distance (i.e., the shortest path along the curved surface of the Earth). If the points are in a Cartesian CRS, the function returns the Euclidean distance (i.e., the shortest straight-line distance in a flat, planar space).
point.withinBBox()	Returns true if the provided point is within the bounding box defined by the two provided points.

String functions

Cypher feature	Description
replace()	Returns a STRING in which all occurrences of a specified search STRING in the given STRING have been replaced by another (specified) replacement STRING.
reverse()	Returns a STRING or LIST<ANY> in which the order of all characters or elements in the given STRING or LIST<ANY> have been reversed.
split()	Returns a LIST<STRING> resulting from the splitting of the given STRING around matches of the given delimiter(s).
substring()	Returns a substring of the given STRING, beginning with a 0-based index start.

Trigonometric functions

Cypher feature	Description
atan2()	Returns the arctangent2 of a set of coordinates in radians.
haversin()	Returns half the versine of a number.
pi()	Returns the mathematical constant pi.

Temporal duration functions

Cypher feature	Description
duration.inDays()	Computes the DURATION between the from instant (inclusive) and the to instant (exclusive) in days.
duration.inMonths()	Computes the DURATION between the from instant (inclusive) and the to instant (exclusive) in months.
duration.inSeconds()	Computes the DURATION between the from instant (inclusive) and the to instant (exclusive) in seconds.

Temporal instant functions

Cypher feature	Description
date.realtime()	Returns the current DATE instant using the realtime clock.
date.statement()	Returns the current DATE instant using the statement clock.
date.transaction()	Returns the current DATE instant using the transaction clock.
date.truncate()	Returns the current DATE instant using the transaction clock.
datetime.fromEpoch()	Creates a ZONED DATETIME given the seconds and nanoseconds since the start of the epoch.
datetime.fromEpochMillis()	Creates a ZONED DATETIME given the milliseconds since the start of the epoch.
datetime.realtime()	Returns the current ZONED DATETIME instant using the realtime clock.
datetime.statement()	Returns the current ZONED DATETIME instant using the statement clock.
datetime.transaction()	Returns the current ZONED DATETIME instant using the transaction clock.
datetime.truncate()	Truncates the given temporal value to a ZONED DATETIME instant using the specified unit.
localdatetime.realtime()	Returns the current LOCAL DATETIME instant using the realtime clock.
localdatetime.statement()	Returns the current LOCAL DATETIME instant using the statement clock.
localdatetime.transaction()	Returns the current LOCAL DATETIME instant using the transaction clock.
localdatetime.truncate()	Truncates the given temporal value to a LOCAL DATETIME instant using the specified unit.
localtime.realtime()	Returns the current LOCAL TIME instant using the realtime clock.
localtime.statement()	Returns the current LOCAL TIME instant using the statement clock.
localtime.transaction()	Returns the current LOCAL TIME instant using the transaction clock.
localtime.truncate()	Truncates the given temporal value to a LOCAL TIME instant using the specified unit.
time.realtime()	Returns the current ZONED TIME instant using the realtime clock.
time.statement()	Returns the current ZONED TIME instant using the statement clock.
time.transaction()	Returns the current ZONED TIME instant using the transaction clock.
time.truncate()	Truncates the given temporal value to a ZONED TIME instant using the specified unit.

Vector functions

Cypher feature	Description
vector.similarity.cosine()	Returns a FLOAT representing the similarity between the argument vectors based on their cosine.
vector.similarity.euclidean()	Returns a FLOAT representing the similarity between the argument vectors based on their Euclidean distance.

Indexes

Cypher feature	Description
Range indexes	Neo4j’s default index. Supports most types of predicates.
Text indexes	Solves predicates operating on STRING values. Optimized for queries filtering with the STRING operators CONTAINS and ENDS WITH.
Point indexes	Solves predicates on spatial POINT values. Optimized for queries filtering on distance or within bounding boxes.
Token lookup indexes	Only solves node label and relationship type predicates (i.e. they cannot solve any predicates filtering on properties).
Full text indexes	Enables searching within the content of STRING properties and for similarity comparisons between query strings and STRING values stored in the database.
Vector indexes	Enables similarity searches and complex analytical queries by representing nodes or properties as vectors in a multidimensional space.
Index hints	Cypher allows for index hints to influence the planner when creating execution plans. Index hints are specified with the USING keyword.

Constraints

GQL supports GRAPH TYPES as a way of constraining a graph schema, but does not support individual constraints.

Cypher feature	Description
Property uniqueness constraints	Ensures that the combined property values are unique for all nodes with a specific label or all relationships with a specific type.
Property existence constraints	Ensures that a property exists either for all nodes with a specific label or for all relationships with a specific type.
Property type constraints	Ensures that a property has the required property type for all nodes with a specific label or for all relationships with a specific type.
Key constraints	Ensures that all properties exist and that the combined property values are unique for all nodes with a specific label or all relationships with a specific type.

Operators

Cypher feature	Description
STARTS WITH, CONTAINS, ENDS WITH, and regular expressions.	STRING comparison operators.
IN	IN predicate for LIST values.

Query optimization

Cypher feature	Description
EXPLAIN/PROFILE	Optionally prepended to queries to produce execution plans. EXPLAIN will only generate an execution plan but not run the query; PROFILE will do both.
CYPHER runtime=parallel	Cypher allows for setting the runtime of queries, determining how the query will be executed. The available Cypher runtimes are: slotted, pipelined, parallel.
CYPHER inferSchemaParts=off	Cypher allows for setting numerous query options. For more information, see Query options.

Administration

Note	The documentation for Cypher’s administration commands is located in Neo4j’s Operation Manual.

Cypher feature	Description
Database management	Commands to CREATE, SHOW, ALTER, and DROP standard and composite databases.
Alias management	Commands to CREATE, SHOW, ALTER, and DROP database aliases.
Server management	Commands to administer servers in a cluster and the databases allocated to them.
Authentication and authorization	Commands to manage users, roles, and privileges.