Amazon Neptune Engine Version (2022-07-21) - Amazon Neptune

Amazon Neptune Engine Version (2022-07-21)

As of 2022-07-21, engine version is being generally deployed. Please note that it takes several days for a new release to become available in every region.


Upgrades to engine version are temporarily disabled. However, you can create a new Neptune DB cluster that uses engine version


Starting with this engine release, all custom parameter groups and custom cluster parameter groups that you are using must be created using parameter group family neptune1.2. Previous releases used parameter group family neptune1, and those parameter groups will not work with this release. See Amazon Neptune parameter groups for more information.


Also, there is a breaking change in this release for code using the Bolt protocol with IAM authentication. Starting with this engine release, Bolt needs a resource path for IAM signing. In Java, setting the resource path might look like:


In other languages, the /openCypher can be appended to the endpoint URI. See Using the Bolt protocol for examples.

New Features in This Engine Release

  • Added support for global databases. A Neptune global database spans multiple AWS Regions, and consists of a primary DB cluster in one region, and up to five secondary DB clusters in other regions.

  • Added support for more granular access control in Neptune IAM policies than has been available previously, based on data plane actions. This is a breaking change in that existing IAM policies that are based on the deprecated connect action must be adjusted to use the more granular data plane actions. See Types of IAM policies.

  • Improved reader instance availability. Previously, when a writer instance restarted, all reader instances in the Neptune cluster automatically restarted too. Starting with engine release, reader instances remain active after a writer restart, which improves reader availability. Reader instances can be restarted separately to pick up parameter group changes. See Rebooting a DB instance in Amazon Neptune.

  • Added a new neptune_streams_expiry_days DB cluster parameter which lets you set the number of days that stream records are kept on the server before being deleted. The range is 1 through 90, and the default is 7.

Improvements in This Engine Release

  • Improved Gremlin serialization performance for ByteCode queries.

  • Neptune now processes text predicates using the DFE engine, for improved performance.

  • Neptune now processes Gremlin limit() steps using the DFE engine, including non-terminal and child traversal limits.

  • Changed DFE handling of the Gremlin union() step to work with other new features, which means that reference nodes show up in query profiles as expected.

  • Improved performance by up to a factor of 5 of some expensive join operations within DFE by parallelizing them.

  • Added by() modulation support for OrderGlobalStep order(global) for the Gremlin DFE engine.

  • Added display of injected static values in explain details for DFE.

  • Improved performance when pruning duplicate patterns.

  • Added order preservation support in the Gremlin DFE engine.

  • Improved the performance of Gremlin queries having empty filters, such as these:

  • Improved error messaging when a SPARQL query uses a numeric value that is too large for Neptune to represent internally.

  • Improved performance for dropping vertices with associated edges by reducing index searches when streams are disabled.

  • Extended DFE support to more variants of the has() step, in particular to hasKey(), hasLabel(), and to range predicates for strings/URIs within has(). This affects queries such as the following:

    // hasKey() on properties g.V().properties().hasKey("name") g.V().properties().has(T.key, TextP.startingWith("a")) g.E().properties().hasKey("weight") g.E().properties().hasKey(TextP.containing("t")) // hasLabel() on vertex properties g.V().properties().hasLabel("name") // range predicates on ID and Label fields g.V().has(T.label, gt("person")) g.E().has(, lte("(an ID value)"))
  • Added a Neptune-specific openCypher join() function that concatenates strings in a list into a single string.

  • Updated the Neptune managed policies to include data-access permissions and permissions for the new global database APIs.

Defects Fixed in This Engine Release

  • Fixed a bug where an HTTP request with no content-type specified would automatically fail.

  • Fixed a SPARQL bug in the query optimizer that prevented use of a service call inside a query.

  • Fixed a SPARQL bug in the Turtle RDF parser where a particular combination of Unicode data caused failure.

  • Fixed a SPARQL bug where a particular combination of GRAPH andSELECT clauses produced incorrect query results.

  • Fixed a Gremlin bug that caused a correctness issue for queries that used any filter step within a union step, such as the following:

    g.V("1").union(hasLabel("person"), out())
  • Fixed a Gremlin bug where count() of both().simplePath() would result in double the actual number of results returned without count().

  • Fixed an openCypher bug where a faulty signature mismatch exception was generated by the server for Bolt requests to clusters with IAM authentication enabled.

  • Fixed an openCypher bug where a query using HTTP keep-alive could be incorrectly closed if it was submitted after a failed request.

  • Fixed an openCypher bug that could cause an internal error to be thrown when a query that returns a constant value is submitted.

  • Fixed a bug in the explain details so that DFE subquery Time(ms) now correctly sums the CPU times of operators within the DFE subquery. Consider the following excerpt of explain output as an example:

    subQuery1 ╔════╤════════╤════════╤═══════════════════════╤═══════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗ ║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║ ╠════╪════════╪════════╪═══════════════════════╪═══════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣ ... ╟────┼────────┼────────┼───────────────────────┼───────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢ ║ 1 │ 2 │ - │ DFEChunkLocalSubQuery │ subQuery=...graph#336e.../graph_1 │ - │ 1 │ 1 │ 1.00 │ 0.38 ║ ║ │ │ │ │ coordinationTime(ms)=0.026 │ │ │ │ │ ║ ╟────┼────────┼────────┼───────────────────────┼───────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢ ... subQuery=...graph#336e.../graph_1 ╔════╤════════╤════════╤═══════════════════════╤═══════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗ ║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║ ╠════╪════════╪════════╪═══════════════════════╪═══════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣ ║ 0 │ 1 │ - │ DFESolutionInjection │ solutions=[?100 -> [-10^^<LONG>]] │ - │ 0 │ 1 │ 0.00 │ 0.04 ║ ║ │ │ │ │ outSchema=[?100] │ │ │ │ │ ║ ╟────┼────────┼────────┼───────────────────────┼───────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢ ║ 1 │ 3 │ - │ DFERelationalJoin │ joinVars=[] │ - │ 2 │ 1 │ 0.50 │ 0.29 ║ ╟────┼────────┼────────┼───────────────────────┼───────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢ ║ 2 │ 1 │ - │ DFESolutionInjection │ outSchema=[] │ - │ 0 │ 1 │ 0.00 │ 0.01 ║ ╟────┼────────┼────────┼───────────────────────┼───────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢ ║ 3 │ - │ - │ DFEDrain │ - │ - │ 1 │ 0 │ 0.00 │ 0.02 ║ ╚════╧════════╧════════╧═══════════════════════╧═══════════════════════════════════╧══════╧══════════╧═══════════╧═══════╧═══════════╝

    The subQuery times in the last column of the lower table add up to 0.36 ms (.04 + .29 + .01 + .02 = .36). When you add in to the coordination time for that subquery (.36 + .026 = .386), you get a result that is close to the time for the subQuery recorded in the last column of the upper table, namely 0.38 ms.

Query-Language Versions Supported in This Release

Before upgrading a DB cluster to version, make sure that your project is compatible with these query-language versions:

  • Gremlin version: 3.5.2

  • openCypher version: Neptune-9.0.20190305-1.0

  • SPARQL version: 1.1

Upgrade Paths to Engine Release

Because this is a major engine release, there is no automatic upgrade to it.

You can only upgrade to release manually, from the latest patch release of engine release Earlier engine releases must first be upgraded to the latest release of before they can be upgraded to

Therefore, before you try to upgrade to this release, please confirm that you are currently running the latest patch release of release If you are not, start by upgrading to the latest patch release of

Before upgrading, you must also re-create any custom DB cluster parameter group that you have been using with your previous version, using parameter group family neptune1.2. See Amazon Neptune parameter groups for more information.

If you are upgrading first to release and then immediately to, you may encounter an error such as the following:

We're sorry, your request to modify DB cluster (cluster identifier)
        has failed. Cannot modify engine version because instance (instance identifier) is
        running on an old configuration. Apply any pending maintenance actions on the instance
        before proceeding with the upgrade.

If you encounter this error, wait for the pending action to finish, or trigger a maintenance window immediately to let the previous upgrade complete.

Upgrading to This Release

If a DB cluster is running an engine version from which there is an upgrade path to this release, it is eligible to be upgraded now. You can upgrade any eligible cluster using the DB cluster operations on the console or by using the SDK. The following CLI command will upgrade an eligible cluster immediately:

For Linux, OS X, or Unix:

aws neptune modify-db-cluster \ --db-cluster-identifier (your-neptune-cluster) \ --engine neptune \ --engine-version \ --allow-major-version-upgrade \ --apply-immediately

For Windows:

aws neptune modify-db-cluster ^ --db-cluster-identifier (your-neptune-cluster) ^ --engine neptune ^ --engine-version ^ --allow-major-version-upgrade ^ --apply-immediately

Instead of --apply-immediately, you can specify --no-apply-immediately. To perform a major version upgrade, the allow-major-version-upgrade parameter is required. Also, be sure to include the engine version or your engine may be upgraded to a different version.

If your cluster uses a custom cluster parameter group, be sure to include this paramater to specify it:

--db-cluster-parameter-group-name (name of the custom DB cluster parameter group)

Similarly, if any instances in the cluster use a custom DB parameter group, be sure to include this parameter to specify it:

--db-instance-parameter-group-name (name of the custom instance parameter group)

Always test before you upgrade

When a new major or minor Neptune engine version is released, always test your Neptune applications on it first before upgrading to it. Even a minor upgrade could introduce new features or behavior that would affect your code.

Start by comparing the release notes pages from your current version to those of the targeted version to see if there will be changes in query language versions or other breaking changes.

The best way to test a new version before upgrading your production DB cluster is to clone your production cluster so that the clone is running the new engine version. You can then run queries on the clone without affecting the production DB cluster.

Always create a manual snapshot before you upgrade

Before performing an upgrade, we strongly recommend that you always create a manual snapshot of your DB cluster. Having an automatic snapshot only offers short-term protection, whereas a manual snapshot remains available until you explicitly delete it.

In certain cases Neptune creates a manual snapshot for you as a part of the upgrade process, but you should not rely on this, and should create your own manual snapshot in any case.

When you are certain that you won't need to revert your DB cluster to its pre-upgrade state, you can explicitly delete the manual snapshot that you created yourself, as well as the manual snapshot that Neptune might have created. If Neptune creates a manual snapshot, it will have a name that begins with preupgrade, followed by the name of your DB cluster, the source engine version, the target engine version, and the date.

For more information about upgrading your engine version, see Neptune engine updates. If you have any questions or concerns, the AWS Support team is available on the community forums and through AWS Premium Support.