Using Gremlin with the Neptune DFE query engine - Amazon Neptune
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.

Using Gremlin with the Neptune DFE query engine

If you fully enable the Neptune alternative query engine known as the DFE in lab mode (by setting the neptune_lab_mode DB cluster parameter to DFEQueryEngine=enabled), then Neptune translates read-only Gremlin queries/traversals into an intermediate logical representation and runs them on the DFE engine whenever possible.

However, the DFE does not yet support all Gremlin steps. When a step can't be run natively on the DFE, Neptune falls back on TinkerPop to run the step. The explain and profile reports include warnings when this happens.


Beginning with engine release, the default DFE behavior for handling Gremlin steps without native support has changed. Where previously the DFE engine fell back on the Neptune Gremlin engine, now it falls back on the vanilla TinkerPop engine.

Gremlin steps that are natively supported by the DFE engine

  • GraphStep

  • VertexStep

  • EdgeVertexStep

  • IdStep

  • TraversalFilterStep

  • PropertiesStep

  • HasStep filtering support for vertices and edges on properties and ids and labels, with the exception of text and Without predicates.

  • WherePredicateStep with Path-scoped filters, but no ByModulation, SideEffect or Map look up support

  • DedupGlobalStep, excepting ByModulation, SideEffect, and Map look-up support.

Query planning interleaving

When the translation process encounters a Gremlin step that does not have a corresponding native DFE operator, before falling back to using Tinkerpop it tries to find other intermediate query parts that can be run natively on the DFE engine. It does this by applying interleaving logic to the top level traversal. The result is that supported steps are used wherever possible.

Any such intermediate, non-prefix query translation is represented using NeptuneInterleavingStep in the explain and profile outputs.

For performance comparison, you might want to turn off interleaving in a query, while still using the DFE engine to run the prefix part. Or, you might want to use only the TinkerPop engine for non-prefix query execution. You can do this by using disableInterleaving query hint.

Just as the useDFE query hint with a value of false prevents a query from being run on the DFE at all, the disableInterleaving query hint with a value of true turns off DFE interleaving for translation of a query. For example:

g.with('Neptune#disableInterleaving', true) .V().has('genre','drama').in('likes')

Updated Gremlin explain and profile output

Gremlin explain provides details about the optimized traversal that Neptune uses to run a query. See the sample DFE explain output for an example of what explain output looks like when the DFE engine is enabled.

The Gremlin profile API runs a specified Gremlin traversal, collects various metrics about the run, and produces a profile report that contains details about the optimized query plan and the runtime statistics of various operators. See sample DFE profile output for an example of what profile output looks like when the DFE engine is enabled.


Because the DFE engine is an experimental feature released in lab mode, the exact format of the explain and profile output is subject to change.