Cypher coverage

This is the public preview documentation of Neo4j Virtual Graph. To provide feedback, please use the feedback form you were granted access to.

During the public preview, we advise you not to use sensitive or production data with Virtual Graph.

Virtual Graph currently does not fully support the Cypher® query language.

In general, query interpretation is partially done directly in Cypher and partially handed to the underlying SQL. This is dependant on the specific query.

It is also dependent on the data lakehouse solution you are using - the SQL implementation of Databricks may differ from the one in Snowflake.

Expect deviations from the Cypher standard when using Virtual Graph.

This page covers some aspects of the behavior deviation.

Check for Virtual Graph instances in Cypher

By executing CALL dbms.components, you can have Cypher reveal whether or not an instance is a Virtual Graph:

CALL dbms.components
CALL dbms.components
Table 1. Result
name version edition

"Neo4j Kernel"

["5.27-aura"]

"enterprise"

"Cypher"

["5", "25"]

""

"Virtual Graph"

["1.0-alpha-01"]

""

Rows: 3

Supported query shape

The following query shape is generally supported:

  • One or more MATCH clause including WHERE subclauses

  • Followed by a RETURN clause including ORDER BY, LIMIT and SKIP subclauses and some aggregations

Or, more formally:

MATCH <pattern-1> WHERE <where-expression>
MATCH <pattern-2>
...
MATCH <pattern-n>

RETURN <return-items>
SKIP <N>
LIMIT <M>
ORDER BY <order-by-expression>

However, there are some caveats. See below.

Supported patterns

Only simple patterns are supported:

Some examples:

  • (n) - nodes without label.

  • (n {name: 'The Name'}) - nodes with inline property predicate (the same holds for relationships).

  • (n:Movie) - nodes with a single label.

  • (n:Movie|Person) - nodes with label conjunction and other combinations of locigal operators.

  • (a:A)-[r0:R]→(b:B)←[r1]-(c:C) relationship chains of any length and direction, with node labels and types as above.

  • (a:A)-[r:R]-(b:B) - undirected patterns.

Supported expressions

Support for expressions is dependent on the subclause the expression is part of:

  • See Expressions in WHERE clauses for expressions in WHERE clauses

  • Expressions in ORDER BY clauses functions similar to expressions in WHERE clauses

  • Expressions in RETURN clauses are less restricted because in some cases they are processed by Cypher directly. Most non-aggregating expressions are supported in the scope of RETURN

Aggregations

MATCH (movie:Movie) RETURN movie.release_year, count(movie)

Some aggregations are handed to SQL but yield a correct result:

  • count()

  • sum()

  • min() and max()

  • avg()

  • collect()

Others are instead handled during post-processing similar to regular expressions.

Limitations

Write queries

Write queries are currently not supported. Virtual Graph only reads data, but doesn’t alter them via write operations.

This includes:

  • CREATE

  • MERGE

  • SET

  • INSERT

  • DELETE

  • REMOVE

  • DROP

  • ALTER

  • START

  • STOP

  • GRANT

  • REVOKE

OPTIONAL MATCH

Currently not supported.

WITH clauses

Only partially supported. If MATCH clauses follow a WITH clause, Virtual Graph does not support the query.

List operations

Virtual Graph only partially supports UNWIND while it doesn’t currently support range(). UNWIND is only supported when no MATCH clauses follow.

Post-processing in Cypher

Queries which need post-processing in Cypher are currently not fully supported.

For example, ordering and setting limits only work if they do not require post-processing in Cypher.

Property access and aggregation on the same node

The following query will fail:

MATCH (p:Person)
RETURN p.browserUsed, count(p) as c
ORDER BY c
DESC LIMIT 10

p.browserUsed is currently not resolved correctly because p is also used in the count(p) aggregation.

Variable length paths

Variable length paths are currently not supported.

Expressions in WHERE clauses

Expressions in WHERE clauses such as MATCH (n) WHERE n.p > 1 are currently restricted because the evaluation is always going to happen in SQL.

This affects comparisons, type casts, arithmetic, trigonometric, String and aggregation functions.

Subquery expressions and CALL clauses

Subquery expressions (for example EXISTS { MATCH (:X) }) and CALL clauses are not supported.

Vector search and fulltext search

Currently not supported.

APOC

APOC functions are not supported.

Checking for entities that do not exist

The handing of null values and checks for non-existent entities deviates from Cypher. Queries containing such checks currently always fail.