Gremlin standards compliance in Amazon Neptune - 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.

Gremlin standards compliance in Amazon Neptune

The following sections provide an overview of the Neptune implementation of Gremlin and how it differs from the Apache TinkerPop implementation.

Neptune implements some Gremlin steps natively in its engine, and uses the Apache TinkerPop Gremlin implementation to process others (see Native Gremlin step support in Amazon Neptune). The following sections provide an overview of cases where Neptune's implementation differs from the TinkerPop implementation.

Applicable Standards for Gremlin

Neptune Gremlin Implementation Differences

There are a few important differences between the Amazon Neptune implementation of Gremlin and the implementation defined by Apache TinkerPop.

Note

For some concrete examples of these implementation differences shown in Gremlin Console and Amazon Neptune, see the Using Gremlin to access the graph in Amazon Neptune section of the Quick Start.

The following is a list of implementation differences:

Pre-Bound Variables

The traversal object g is Pre-bound. The graph object is not supported.

TinkerPop Enumerations

Neptune does not support fully qualified class names for enumeration values. For example, you must use single and not org.apache.tinkerpop.gremlin.structure.VertexProperty.Cardinality.single in your Groovy request.

The enumeration type is determined by parameter type.

The following table shows the allowed enumeration values and the related TinkerPop fully qualified name.

Java Code

Neptune does not support calls to methods defined by arbitrary Java or Java library calls other than supported Gremlin APIs. For example, java.lang.*, Date(), and g.V().tryNext().orElseGet() are not allowed.

Script Execution

All queries must begin with g, the traversal object.

In String query submissions, multiple traversals can be issued separated by a semicolon (;) or a newline character (\n). To be executed, every statement other than the last must end with an .iterate() step. Only the final traversal data is returned. Note that this does not apply to GLV ByteCode query submissions.

Sessions

Sessions in Neptune are limited to only 10 minutes in duration. See Gremlin script-based sessions and the TinkerPop Session Reference for more information.

Transactions

Neptune opens a new transaction at the beginning of each Gremlin traversal and closes the transaction upon the successful completion of the traversal. The transaction is rolled back when there is an error.

Multiple statements separated by a semicolon (;) or a newline character (\n) are included in a single transaction. Every statement other than the last must end with a next() step to be executed. Only the final traversal data is returned.

Manual transaction logic using tx.commit() and tx.rollback() is not supported.

Important

This only applies to methods where you send the Gremlin query as a text string (see Gremlin transactions).

Vertex and Edge IDs

Neptune Gremlin Vertex and Edge IDs must be of type String. If you don't supply an ID when you add a vertex or an edge, a UUID is generated and converted to a string; for example, "48af8178-50ce-971a-fc41-8c9a954cea62". These ID strings support Unicode characters, and cannot exceed 55 MB in size.

Note

This means that user-supplied IDs are supported, but they are optional in normal usage. However, the Neptune Load command requires that all IDs be specified using the ~id field in the Neptune CSV format.

User-Supplied IDs

User-supplied IDs are allowed in Neptune Gremlin with the following stipulations.

  • Supplied IDs are optional.

  • Only vertexes and edges are supported.

  • Only type String is supported.

To create a new vertex with a custom ID, use the property step with the id keyword: g.addV().property(id, 'customid').

Note

Do not put quotation marks around the id keyword. It refers to T.id.

All vertex IDs must be unique, and all edge IDs must be unique. However, Neptune does allow a vertex and an edge to have the same ID.

If you try to create a new vertex using the g.addV() and a vertex with that ID already exists, the operation fails. The exception to this is if you specify a new label for the vertex, the operation succeeds but adds the new label and any additional properties specified to the existing vertex. Nothing is overwritten. A new vertex is not created. The vertex ID does not change and remains unique.

For example, the following Gremlin Console commands succeed:

gremlin> g.addV('label1').property(id, 'customid') gremlin> g.addV('label2').property(id, 'customid') gremlin> g.V('customid').label() ==>label1::label2

Vertex Property IDs

Vertex property IDs are generated automatically and can show up as positive or negative numbers when queried.

Cardinality of Vertex Properties

Neptune supports set cardinality and single cardinality. If it isn't specified, set cardinality is selected. This means that if you set a property value, it adds a new value to the property, but only if it doesn't already appear in the set of values. This is the Gremlin enumeration value of Set.

List is not supported. For more information about property cardinality, see the Vertex topic in the Gremlin JavaDoc.

Updating a Vertex Property

To update a property value without adding an additional value to the set of values, specify single cardinality in the property step.

g.V('exampleid01').property(single, 'age', 25)

This removes all existing values for the property.

Labels

Neptune supports multiple labels for a vertex. When you create a label, you can specify multiple labels by separating them with ::. For example, g.addV("Label1::Label2::Label3") adds a vertex with three different labels. The hasLabel step matches this vertex with any of those three labels: hasLabel("Label1"), hasLabel("Label2"), and hasLabel("Label3").

Important

The :: delimiter is reserved for this use only. You cannot specify multiple labels in the hasLabel step. For example, hasLabel("Label1::Label2") does not match anything.

Variables

Neptune does not support Gremlin variables and does not support the bindings property.

Escape Characters

Neptune resolves all escape characters as described in the Escaping Special Characters section of the Apache Groovy language documentation.

Groovy Limitations

Neptune doesn't support Groovy commands that don't start with g. This includes math (for example, 1+1), system calls (for example, System.nanoTime()), and variable definitions (for example, 1+1).

Important

Neptune does not support fully qualified class names. For example, you must use single and not org.apache.tinkerpop.gremlin.structure.VertexProperty.Cardinality.single in your Groovy request.

Serialization

Neptune supports the following serializations based on the requested MIME type.

MIME type Serialization Configuration

application/vnd.gremlin-v1.0+gryo

GryoMessageSerializerV1d0 ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV1d0]

application/vnd.gremlin-v1.0+gryo-stringd

GryoMessageSerializerV1d0 serializeResultToString: true}
application/vnd.gremlin-v3.0+gryo GryoMessageSerializerV3d0 ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0]

application/vnd.gremlin-v3.0+gryo-stringd

GryoMessageSerializerV3d0 serializeResultToString: true

application/vnd.gremlin-v1.0+json

GraphSONMessageSerializerGremlinV1d0 ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV1d0]

application/vnd.gremlin-v2.0+json

GraphSONMessageSerializerV2d0   (only works with WebSockets) ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV2d0]

application/vnd.gremlin-v3.0+json

GraphSONMessageSerializerV3d0

application/json

GraphSONMessageSerializerV3d0 ioRegistries: [org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3d0]

application/vnd.graphbinary-v1.0

GraphBinaryMessageSerializerV1

Lambda Steps

Neptune does not support Lambda Steps.

Unsupported Gremlin Methods

Neptune does not support the following Gremlin methods:

  • org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal.program(org.apache.tinkerpop.gremlin.process.computer.VertexProgram)

  • org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal.sideEffect(java.util.function.Consumer)

  • org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal.from(org.apache.tinkerpop.gremlin.structure.Vertex)

  • org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal.to(org.apache.tinkerpop.gremlin.structure.Vertex)

For example, the following traversal is not allowed: g.V().addE('something').from(__.V().next()).to(__.V().next()).

Important

This only applies to methods where you send the Gremlin query as a text string.

Unsupported Gremlin Steps

Neptune does not support the following Gremlin steps:

  • The Gremlin io( ) Step is only partially supported in Neptune. It can be used in a read context, as in g.io((url)).read(), but not to write.

Other Features

The Neptune implementation of Gremlin does not expose the graph object. The following section describes the supported and unsupported graph features.

Gremlin Graph Supported Features

The following is a set of features as implemented by the Neptune Gremlin graph. These features are the same as would be returned by the graph.features() command.

Graph Feature Enabled
Transactions true
ThreadedTransactions false
Computer false
Persistence true
ConcurrentAccess true
Variable Feature Enabled
Variables false
SerializableValues false
UniformListValues false
BooleanArrayValues false
DoubleArrayValues false
IntegerArrayValues false
StringArrayValues false
BooleanValues false
ByteValues false
DoubleValues false
FloatValues false
IntegerValues false
LongValues false
MapValues false
MixedListValues false
StringValues false
ByteArrayValues false
FloatArrayValues false
LongArrayValues false
Vertex Feature Enabled
MetaProperties false
DuplicateMultiProperties false
AddVertices true
RemoveVertices true
MultiProperties true
UserSuppliedIds true
AddProperty true
RemoveProperty true
NumericIds false
StringIds true
UuidIds false
CustomIds false
AnyIds false
Vertex Property Feature Enabled
UserSuppliedIds false
AddProperty true
RemoveProperty true
NumericIds true
StringIds true
UuidIds false
CustomIds false
AnyIds false
Properties true
SerializableValues false
UniformListValues false
BooleanArrayValues false
DoubleArrayValues false
IntegerArrayValues false
StringArrayValues false
BooleanValues true
ByteValues true
DoubleValues true
FloatValues true
IntegerValues true
LongValues true
MapValues false
MixedListValues false
StringValues true
ByteArrayValues false
FloatArrayValues false
LongArrayValues false
Edge Feature Enabled
AddEdges true
RemoveEdges true
UserSuppliedIds true
AddProperty true
RemoveProperty true
NumericIds false
StringIds true
UuidIds false
CustomIds false
AnyIds false
Edge Property Feature Enabled
Properties true
SerializableValues false
UniformListValues false
BooleanArrayValues false
DoubleArrayValues false
IntegerArrayValues false
StringArrayValues false
BooleanValues true
ByteValues true
DoubleValues true
FloatValues true
IntegerValues true
LongValues true
MapValues false
MixedListValues false
StringValues true
ByteArrayValues false
FloatArrayValues false
LongArrayValues false