AWS Documentation » Neptune » User Guide » Accessing the Neptune Graph with Gremlin » Neptune Gremlin Implementation Differences

Neptune Gremlin Implementation Differences

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

Note

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

The following are a list of the 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.

Allowed Values	Class
id, key, label, value	org.apache.tinkerpop.gremlin.structure.T
T.id, T.key, T.label, T.value	org.apache.tinkerpop.gremlin.structure.T
set, single	org.apache.tinkerpop.gremlin.structure.VertexProperty.Cardinality
decr, incr, shuffle	org.apache.tinkerpop.gremlin.process.traversal.Order
Order.decr, Order.incr, Order.shuffle	org.apache.tinkerpop.gremlin.process.traversal.Order
global, local	org.apache.tinkerpop.gremlin.process.traversal.Scope
Scope.global, Scope.local	org.apache.tinkerpop.gremlin.process.traversal.Scope
all, first, last, mixed	org.apache.tinkerpop.gremlin.process.traversal.Pop
normSack	org.apache.tinkerpop.gremlin.process.traversal.SackFunctions.Barrier
addAll, and, assign, div, max, min, minus, mult, or, sum, sumLong	org.apache.tinkerpop.gremlin.process.traversal.Operator
keys, values	org.apache.tinkerpop.gremlin.structure.Column
BOTH, IN, OUT	org.apache.tinkerpop.gremlin.structure.Direction
any, none	org.apache.tinkerpop.gremlin.process.traversal.step.TraversalOptionParent.Pick

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.

Date and Time

Neptune provides the datetime method for specifying dates and times for queries sent in the Gremlin Groovy variant. This includes the Gremlin Console, text strings using the HTTP REST API, and any other serialization that uses Groovy. A date and time value must be specified with the datetime() function.

Important

This only applies to methods where you send the Gremlin query as a text string. If you are using a Gremlin Language Variant (GLV), you must use the native date classes and functions for the language. For more information, see the Best Practices section, Using Native Date and Time for GLV Time Data.

The datetime() function takes a string value with an ISO8601 compliant datetime. For example, datetime('2018-01-01T00:00:00'). Supports the following formats: YYYY-MM-DD, YYYY-MM-DDTHH:mm, YYYY-MM-DDTHH:mm:SS, YYYY-MM-DDTHH:mm:SSZ

Script Execution

All queries must begin with g, the traversal object.

Multiple traversals can be issued separated by a semicolon (;) or a newline character (\n). Every statement other than the last must end with a next() step to be executed. Only the final traversal data is returned.

Sessions

Neptune is sessionless. It does not support the console session argument. For a description of the difference, see the TinkerPop Session Reference.

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.

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".

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.

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. Set cardinality is selected if not specified. This means that if you set a property value, it adds a new value to the property, but only if it does not 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)

Note

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.

Timeouts

The Gremlin Console command :remote config timeout sets the local timeout only. To set the remote query timeout for Neptune, use the neptune_query_timeout parameter. For more information, see Amazon Neptune DB Parameter Groups.

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
application/vnd.gremlin-v1.0+gryo	GryoMessageSerializerV1d0
application/vnd.gremlin-v1.0+gryo-stringd	GryoMessageSerializerV1d0
application/vnd.gremlin-v3.0+gryo	GryoMessageSerializerV3d0
application/vnd.gremlin-v3.0+gryo-stringd	GryoMessageSerializerV3d0
application/vnd.gremlin-v1.0+json	GraphSONMessageSerializerGremlinV1d0
application/vnd.gremlin-v2.0+json	GraphSONMessageSerializerGremlinV2d0
application/vnd.gremlin-v3.0+json	GraphSONMessageSerializerV3d0
application/json	GraphSONMessageSerializerV3d0

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().from(g.V().next()).

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

Here 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

Next Steps:

• Using the Gremlin Console to Connect to a Neptune DB Instance

• Using the HTTP REST Endpoint to Connect to a Neptune DB Instance

• Using Java to Connect to a Neptune DB Instance

• Using Python to Connect to a Neptune DB Instance

• Using the Gremlin Console to Connect to a Neptune DB Instance