openCypher standards compliance in Amazon Neptune - Amazon Neptune
ClausesOperatorsExpressionsFunctionsNeptune openCypher differences
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

openCypher standards compliance in Amazon Neptune

The Amazon Neptune release of openCypher generally supports the Cypher Query Language Reference Version 9, including clauses, operators, expressions, and functions defined in that version. Limitations and differences in Neptune support for openCypher are called out below.

Support for openCypher clauses in Neptune

Neptune supports the following clauses, except as noted:

  • MATCH   –   Supported, except that shortestPath() and allShortestPaths() are not currently supported.

  • OPTIONAL MATCH

  • MANDATORY MATCH   –   is not currently supported in Neptune.

  • RETURN   –   Supported, except when used with non-static values for SKIP or LIMIT. 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 for SKIP or LIMIT. 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

  • CALL[YIELD...]   –   is not currently supported in Neptune.

  • 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 % modulo division operator is not currently supported in Neptune.

  • The ^ exponentiation operator is not currently supported in Neptune.

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 strings

  • startNode()

  • timestamp()   –   is not currently supported in Neptune.

  • toBoolean()

  • toFloat()

  • toInteger()

  • type()

Aggregating functions

  • avg()

  • collect()

  • count()

  • max()

  • min()

  • percentileCont()   –   is not currently supported in Neptune.

  • percentileDisc()   –   is not currently supported in Neptune.

  • stDev()   –   is not currently supported in Neptune.

  • stDevP()   –   is not currently supported in Neptune.

  • 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

  • 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()   –   is not currently supported in Neptune.

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 specifies that each edge must be traversed at most once per solution.

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 "dateTtime" 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() and rtrim() 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.