openCypher standards compliance in Amazon Neptune
The Amazon Neptune release of openCypher generally supports the Cypher Query Language
Reference Version 9
Support for openCypher clauses in Neptune
Neptune supports the following clauses, except as noted:
MATCH
– Supported, except that
andshortestPath()
are not currently supported.allShortestPaths()
OPTIONAL MATCH
– is not currently supported in Neptune.MANDATORY MATCH
-
RETURN
– Supported, except when used with non-static values forSKIP
orLIMIT
. For example, the following currently does not work:MATCH (n) RETURN n LIMIT toInteger(rand()9) // Does NOT work!
-
WITH
– Supported, except when used with non-static values forSKIP
orLIMIT
. For example, the following currently does not work:MATCH (n) WITH n SKIP toInteger(rand()9) WITH count() AS count RETURN count > 0 AS nonEmpty // Does NOT work!
UNWIND
WHERE
ORDER BY
SKIP
LIMIT
CREATE
DELETE
SET
REMOVE
MERGE
– is not currently supported in Neptune.CALL[YIELD...]
UNION, UNION ALL
– read-only queries are supported, but mutation queries are not currently supported.
Support for openCypher operators in Neptune
Neptune supports the following operators, except as noted:
General operators
DISTINCT
The
.
operator for accessing properties of a nested literal map.
Mathematical operators
The
+
addition operator.The
-
subtraction operator.The
*
multiplication operator.The
/
division operator.The
is not currently supported in Neptune.%
modulo division operatorThe
is not currently supported in Neptune.^
exponentiation operator
Comparison operators
The
=
addition operator.The
<>
inequality operator.The
<
less-than operator is supported except when either of the arguments is a Path, List, or Map.The
>
greater-than operator is supported except when either of the arguments is a Path, List, or Map.The
<=
less-than-or-equal-to operator is supported except when either of the arguments is a Path, List, or Map.The
>=
greater-than-or-equal-to operator is supported except when either of the arguments is a Path, List, or Map.IS NULL
IS NOT NULL
STARTS WITH
is supported if the data being searched for is a string.ENDS WITH
is supported if the data being searched for is a string.CONTAINS
is supported if the data being searched for is a string.
Boolean operators
AND
OR
XOR
NOT
String operators
The
+
concatenation operator.
List operators
The
+
concatenation operator.IN
(checks for the presence of an item in the list)
Support for openCypher expressions in Neptune
Neptune supports the following expressions, except as noted:
CASE
-
The
[]
expression is is not currently supported in Neptune for accessing dynamically computed property keys within a node, relationship, or map. For example, the following does not work:MATCH (n) WITH [5, n, {key: 'value'}] AS list RETURN list[1].name
Support for openCypher functions in Neptune
Neptune supports the following functions, except as noted:
Predicate functions
exists()
Scalar functions
coalesce()
endNode()
head()
id()
last()
length()
properties()
size()
– this overloaded method currently only works for pattern expressions, lists, and stringsstartNode()
– is not currently supported in Neptune.timestamp()
toBoolean()
toFloat()
toInteger()
type()
Aggregating functions
avg()
collect()
count()
max()
min()
– is not currently supported in Neptune.percentileCont()
– is not currently supported in Neptune.percentileDisc()
– is not currently supported in Neptune.stDev()
– is not currently supported in Neptune.stDevP()
sum()
List functions
join() (concatenates strings in a list into a single string)
keys()
labels()
nodes()
range()
relationships()
reverse()
tail()
Mathematical functions – numeric
abs()
ceil()
floor()
rand()
round()
sign()
Mathematical functions – logarithmic
e()
exp()
log()
log10()
sqrt()
Mathematical functions – trigonometric
– is not currently supported in Neptune.acos()
– is not currently supported in Neptune.asin()
– is not currently supported in Neptune.atan()
– is not currently supported in Neptune.atan2()
– is not currently supported in Neptune.cos()
– is not currently supported in Neptune.cot()
– is not currently supported in Neptune.degrees()
– is not currently supported in Neptune.pi()
– is not currently supported in Neptune.radians()
– is not currently supported in Neptune.sin()
– is not currently supported in Neptune.tan()
String functions
join() (concatenates strings in a list into a single string)
left()
lTrim()
replace()
reverse()
right()
rTrim()
split()
substring()
toLower()
toString()
toUpper()
trim()
User-defined functions
User-defined functions
are not currently
supported in Neptune.
Neptune-specific openCypher implementation details
The following sections describe ways in which the Neptune implementation of
openCypher may differ from or go beyond the openCypher spec
Variable-length path (VLP) evaluations in Neptune
Variable length path (VLP
) evaluations discover paths between nodes
in the graph. Path length can be unrestricted in a query. To prevent cycles, the
openCypher spec
For VLPs, the Neptune implementation deviates from the openCypher spec in that it only supports constant values for property equality filters. Take the following query:
MATCH (x)-[:route*1..2 {dist:33, code:x.name}]->(y) return x,y
Because the x.name
property equality filter value is a not a constant,
this query results in an UnsupportedOperationException
with the message:
Property predicate over variable-length relationships with non-constant
expression is not supported in this release.
Temporal support in the Neptune openCypher implementation
Neptune currently provides limited support for temporal function in openCypher.
It supports the DateTime
data type for temporal types.
The datetime()
function can be used to get the current UTC date and time
like this:
RETURN datetime() as res
Date and time values can be converted from data stored in Neptune like this:
MATCH (n) RETURN datetime(n.createdDate)
Date and time values can be parsed from strings in a
"
dateT
time"
format
where date and time are both expressed in
one of the supported forms below:
Supported date formats
yyyy-MM-dd
yyyyMMdd
yyyy-MM
yyyy-DDD
yyyyDDD
yyyy
Supported time formats
HH:mm:ssZ
HHmmssZ
HH:mm:ssZ
HH:mmZ
HHmmZ
HHZ
HHmmss
HH:mm:ss
HH:mm
HHmm
HH
For example:
RETURN datetime('2022-01-01T00:01') // or another example: RETURN datetime('2022T0001')
Note that all date/time values in Neptune openCypher are stored and retrieved as UTC values.
Neptune openCypher uses a statement
clock, meaning
that the same instant in time is used throughout the duration of a query.
A different query within the same transaction may use a different instant
in time.
Neptune doesn't support use of a function within a call to
datetime()
. For example, the following won't work:
CREATE (:n {date:datetime(tostring(2021))}) // ---> NOT ALLOWED!
Neptune doesn't currently support other functions and operations on
DateTime
objects, such as addition and subtraction.
Differences in Neptune openCypher language semantics
Neptune represents node and relationship IDs as strings rather than
integers. The ID equals the ID supplied via the data loader. If there is a namespace
for the column, the namespace plus the ID. Consequently, the id
function
returns a string instead of an integer.
The INTEGER
datatype is limited to 64 bits. When converting larger
floating point or string values to an integer using the TOINTEGER
function,
negative values are truncated to LLONG_MIN
and positive values are
truncated to LLONG_MAX
.
For example:
RETURN TOINTEGER(2^100) > 9223372036854775807 RETURN TOINTEGER(-1 * 2^100) > -9223372036854775808
The Neptune-specific join()
function
Neptune implements a join()
function that is not present in the
openCypher specification. It creates a string literal from a list of string literals
and a string delimiter. It takes two arguments:
The first argument is a list of string literals.
The second argument is the delimiter string, which can consist of zero, one, or more than one characters.
Example:
join(["abc", "def", "ghi"], ", ") // Returns "abc, def, ghi"
Other differences between Neptune openCypher and Cypher
Neptune only supports TCP connections for the Bolt protocol. WebSockets connections for Bolt are not supported.
Neptune openCypher removes whitespace as defined by Unicode in the
trim()
,ltrim()
andrtrim()
functions.In Neptune openCypher,
tostring(
double)
does not automatically switch to E notation for large values of the double.Although openCypher CREATE does not create multi-valued properties, they can exist in data created using Gremlin. If Neptune openCypher encounters a multi-value property, one of the values is arbitrarily chosen, creating a non-deterministic result.