The Gremlin Recipes documentation now has a new section which discusses anti-patterns in Gremlin. Its subsections detail commonly seen approaches to the Gremlin language which can lead to poorly written and/or under-performing traversals. The new Anti-Patterns Section can be found here.

See: TINKERPOP-2114

The AnonymousTraversalSource provides for a more unified syntax for TraversalSource construction by placing greater user emphasis on the creation of the source rather than the Graph it is connected to. It has a number of different static traversal() methods available and when imported as:

allows TraversalSource construction syntax such as:

Typically, this syntax is used for "remote" traversal construction for bytecode based requests, but has the option to bind a local Graph instance to it as well. It doesn’t save much typing to do so obviously, so it may not be best used in that situation. Python, Javascript and .NET have similar syntax.

See: TINKERPOP-2078

The Gremlin Console now has a new :bytecode command to help users work more directly with Gremlin bytecode. The command is more of a debugging tool than something that would be used for every day purposes. It is sometimes helpful to look at Gremlin bytecode directly and the process for viewing it in human readable format is not a single step process. It is also not immediately clear how to convert bytecode to a Gremlin string. The :bytecode command aims to help with both of these issues:

See: TINKERPOP-2050, Reference Documentation - Console Commands

The "class map" cache in Gremlin Server (specifically the GremlinGroovyScriptEngine) that holds compiled scripts is now fully configurable via the GroovyCompilerGremlinPlugin.classMapCacheSpecification.

See: TINKERPOP-2038, Reference Documentation - Cache Management

A new strategy named EarlyLimitStrategy was added. The strategy will try to find a better spot for any RangeStep, which is as early as possible in the traversal. If possible it will also merge multiple RangeStep`s into a single one by recalculating the range for the first step and removing the second. If it turns out that the merge of two steps won’t produce a valid range (an empty result), then the `EarlyLimitStrategy will remove the RangeStep`s and insert a `NoneStep instead.

This strategy is particularly useful when a provider implementation generates the queries to the underlying database. By making sure that the ranges are applied as early as possible, we can ensure that the underlying database is only asked for the least amount of data necessary to continue the traversal evaluation.

The Order enum originally introduced incr for ascending order and decr for descending order. It’s not clear why they were named this way when common querying parlance would call for asc and desc for those respective cases. Note that incr and decr have not been removed - just deprecated and thus marked for future removal. Prefer asc and desc going forward when writing Gremlin and look to update existing code using the deprecated values.

See: TINKERPOP-1956

In Gremlin Server, it is best not to use the timedInterrupt option on GroovyCompilerGremlinPlugin because it can compete with the scriptEvaluationTimeout setting and produce a different error path. Simply rely on scriptEvaluationTimeout as it covers both script evaluation time and result iteration time.

See: TINKERPOP-1778

The Credential DSL has been modified to work as a standard Java-based Gremlin DSL. The now deprecated old approach used a "graph wrapping" style that was developed long before the recommended method for building DSLs was published. Under this new model, the DSL is initialized via traversal as follows:

See: TINKERPOP-1903, Reference Documentation - Security

Graph traversals that return a Set from Java are now coerced to a List in Python. This change ensures that Python results match Java results for the same traversal. It is possible to see this problem in prior versions of gremlin-python where a Set of numbers of different types are returned. In Java, a set of:

would be deserialized to the following in Python:

Now that the Java Set is coerced to a List in Gremin Python, the Java Set can be fully represented. Users who require a Set will need to manually convert their List to a Set.

See: TINKERPOP-1844

There was a bug in GraphSON 3.0 serialization that prevented proper handling of results contain Path object. As a result, traversals that used and returned results from the path()-step in Python would return unusable results, but did not actually cause an exception condition. This problem is now resolved.

See: TINKERPOP-1799

GraphTraversal.math(String) was added. This step provides scientific calculator capabilities to a Gremlin traversal.

See: TINKERPOP-1632

The from() and to()-steps of GraphTraversal have a Traversal<E,Vertex> overload. The E has been changed to ? in order to reduce < >-based coersion in strongly type Gremlin language variants.

See: TINKERPOP-1793

The GraphTraversal and GraphTraversalSource methods of addV() and addE() have been extended to support dynamic label determination upon element creation. Both these methods can take a Traversal<?, String> where the first String returned by the traversal is used as the label of the respective element.

See: TINKERPOP-1793

There were two major bugs in the way in which PageRank was being calculated in PageRankVertexProgram. First, teleportation energy was not being distributed correctly amongst the vertices at each round. Second, terminal vertices (i.e. vertices with no outgoing edges) did not have their full gathered energy distributed via teleportation.

For users upgrading, note that while the relative rank orders will remain "the same," the actual PageRank values will differ from prior TinkerPop versions.

Normalization preserved through computation:

Two other additions to PageRankVertexProgram were provided as well.

See: TINKERPOP-1783

While 3.3.0 released Gryo 3.0 and GraphSON 3.0 and these versions were defaulted in a number of places, it seems that some key defaults were missed. Specifically, calls to Graph.io(graphson()) and Graph.io(gryo()) were still using the old versions. The defaults have now been changed to ensure 3.0 is properly referenced in those cases.

See Neo4j’s 3.2 Upgrade FAQ for a complete guide on how to upgrade from the previous 2.3.3 version. Also note that many of the configuration settings have changed from neo4j 2x to 3x

In particular, these properties referenced in TinkerPop documentation and configuration were renamed:

TinkerPop has always packaged sample graphs with its zip distributions. As of 3.3.0, the distributions will only include Gryo 3.0, GraphSON 3.0 and GraphML (which is unversioned) files. Other versions are not included, but could obviously be generated using the IO API directly.

GraphTraversal.hasXXX(), where XXX is Id, Label, Key, Value, was faulty in that they relied on calling an intermediate method for flattening Object[] arguments and thus, yielding a non 1-to-1 correspondence between GraphTraversal and Bytecode. This has been remedied. Most users will not notice this change. Perhaps only some users that may use Java reflection over GraphTraversal might have a simple problem.

See: TINKERPOP-1520

Graphite and Ganglia are no longer packaged with the Gremlin Server distribution. They are considered optional dependencies and therefore must be installed manually by the user.

See: TINKERPOP-1550, Reference Documentation - Metrics

SelectStep and SelectOneStep (select()) are the only Scoping steps that default to Pop.mixed as their labeled path selection criteria. All other steps, like match(), where() and dedup(), use Pop.last. In order to better enable optimizations around total Pop.last traversals, the select()-steps now default to Pop.last. Most users will not notice a difference as it is rare for repeated labels to be used in practice. However, formal backwards compatibility is possible as outlined below.

Assuming that x is not a Pop argument:

If an explicit Pop argument is provided, then no changes are required.

See: TINKERPOP-1541

The optional()-step was previously implemented using ChooseStep. However, if the optional branch contained side-effects, then unexpected behaviors can emerge. Thus, a potential backwards compatibility issue arises if side-effects were being used in optional(). However, the behavior would be unpredictable so this backwards incompatibility is desirable.

See TINKERPOP-1506

It is no longer possible to intialize the Gremlin Console with a script without use of -e. In other words, prior versions allowed:

Such a command must now be written as:

See: TINKERPOP-1283, TINKERPOP-1651

GraphTraversal.valueMap(includeTokens,propertyKeys…​) now returns a Map<Object,E> to account for the presence of T.id or T.label if you pass true to it.

See: TINKERPOP-1483

The TinkerPop reference documentation has always mentioned that the gremlin-spark /lib directory needed to be added to HADOOP_GREMLIN_LIBS environment variable. In reality, that was not truly necessary. With Spark 1.x having gremlin-spark in HADOOP_GREMLIN_LIBS hasn’t been a problem, but Spark 2.0 introduces a check for duplicate jars on the path which will cause job initialization to fail. As a result, going forward with TinkerPop 3.3.0, the gremlin-spark lib directory should not be included in HADOOP_GREMLIN_LIBS.

The following deprecated classes, methods or fields have been removed in this version:

Please see the javadoc deprecation notes or upgrade documentation specific to when the deprecation took place to understand how to resolve this breaking change.

See: TINKERPOP-832, TINKERPOP-833, TINKERPOP-834, TINKERPOP-999, TINKERPOP-1010, TINKERPOP-1028, TINKERPOP-1040, TINKERPOP-1046, TINKERPOP-1049, TINKERPOP-1142, TINKERPOP-1169, TINKERPOP-1171, TINKERPOP-1275, TINKERPOP-1283, TINKERPOP-1289, TINKERPOP-1291, TINKERPOP-1420, TINKERPOP-1421, TINKERPOP-1465, TINKERPOP-1481, TINKERPOP-1526, TINKERPOP-1603, TINKERPOP-1612, TINKERPOP-1622, TINKERPOP-1651, TINKERPOP-1694, TINKERPOP-1700, TINKERPOP-1706, TINKERPOP-1721, TINKERPOP-1719, TINKERPOP-1720, TINKERPOP-880, TINKERPOP-1170, TINKERPOP-1729

gremlin-server.sh is now also an init script and can no longer be started without parameters. To start it in the foreground with defaults like previous usage, please use the console parameter. Also, gremlin-server.sh will continue to start in the foreground when provided a yaml configuration file.

How to install as a service has been added to the Reference Documentation - As A Service.

The switch name has changed for installing dependencies. -i has been deprecated and replaced by install.

See: TINKERPOP-980, Reference Documentation - Server Configuration.

The userMapperFromGraph serialization configuration option was used to allow the IO configurations of a specific graph to be assigned to a specific serializer. This feature has been removed completely now. Please use the ioRegistries configuration option to add one or more specific Graph serialization capabilities to a serializer.

see: TINKERPOP-1699

The switch name has changed for installing dependencies. -i has been deprecated and replaced by install.

Historically, SparkGraphComputer has used GryoSerializer to handle the serialization of objects in Spark. The reason this exists is because TinkerPop uses a shaded version of Kryo and thus, couldn’t use the standard KryoSerializer-model provided by Spark. However, a "shim model" was created which allows for the shaded and unshaded versions of Kryo to interact with one another. To this end, KryoSerializer can now be used with a GryoRegistrator. The properties file for a SparkGraphComputer now looks as follows:

If the old GryoSerializer model is desired, then the properties file should simply look as before:

See: TINKERPOP-1389

The API for the script provided to a ScriptInputFormat has changed slightly. The signature for parse(line, factory) is now simply parse(line). The inclusion of factory was deprecated in 3.1.2. Instead of using the {{factory}} to get the {{StarGraph}} there is a {{graph}} variable in the glocal context of the script. Simply use that directly in the script.

See: TINKERPOP-1137, Reference Documentation - Script I/O Format

The Gremlin Javascript Driver now supports SASL Plain Text authentication against a Gremlin Server.

See: TINKERPOP-1977, Reference Documentation - Gremlin Javascript

TinkerPop improves its security posture by removing insecure defaults and adding forward-looking standards support.

Gremlin Server no longer supports automatically creating self-signed certificates. Self-signed certificates can still be created manually outside of Gremlin Server. If ssl is enabled, a key store must be configured.

Cluster client no longer trusts all certs by default as this is an insecure configuration. Instead, if no trust store is configured, Cluster will use the default CA certs. To revert to the previous behavior and accept all certs, it must be explicitly configured.

This release introduces JKS and PKCS12 support. JKS is the legacy Java Key Store. PKCS12 has better cross-platform support and is gaining in adoption. Be aware that JKS is the default on Java 8. Java 9 and higher use PKCS12 as the default. Both Java keytool and OpenSSL tools can create, read, update PKCS12 files.

Other new features include specifying SSL protocols and cipher suites. The packaged *-secure.yaml files now restrict the protocol to TLSv1.2 by default.

PEM-based configurations are deprecated and may be removed in a future release.

See also Connecting via Java Configuration, Gremlin Server Configuration.

TINKERPOP-2022 TINKERPOP-2023

TinkerPop has provided some general methods for importing and exporting data, but more and more graph providers are producing their own bulk import/export facilities and they are more efficient and easier to use than TinkerPop’s methods. As a result, TinkerPop will now refer users to the bulk import/export features of individual graph providers and as such, has deprecated BulkLoaderVertexProgram as of this release.

As part of this change, the BulkDumperVertexProgram has been renamed to CloneVertexProgram with the former being deprecated. CloneVertexProgram is more aptly named, as it essentially copies a graph from a graph InputFormat to a graph OutputFormat.

TINKERPOP-1985

Docker images are now available on Docker Hub for Gremlin Console and Gremlin Server.

See: TINKERPOP-1897, Reference Documentation - Gremlin Console, Reference Documentation - Gremlin Server,

In Gremlin Server, it is best not to use 'TimedInterruptCustomizerProvider' because it can compete with the 'scriptEvaluationTimeout' setting and produce a different error path. Simply rely on 'scriptEvaluationTimeout' as it covers both script evaluation time and result iteration time.

See: TINKERPOP-1778

The Grateful Dead dataset has been with TinkerPop since the early days of 1.x. It has always been available as a packaged dataset that needed to be loaded through the various IO options available, while other toy graphs had the benefit of TinkerFactory to help get them bootstrapped. For 3.2.10, Grateful Dead is now more conveniently loaded via that same method as the other toy graphs with TinkerFactory.createGratefulDead().

Gremlin Javascript can now submit script, with optional bindings, using the Client class:

and also allows translation of bytecode steps into script:

It was realized quite shortly after release of 3.2.8 that there was a bug in construction of Lambda instances:

The problem was related to a bug in Groovy 2.4.14 and was fixed in 2.4.15.

See: TINKERPOP-1953

Gremlin Server now has two new settings: idleConnectionTimeout and keepAliveInterval. The keepAliveInterval tells Gremlin Server how long it should wait between writes to a client before it issues a "ping" to that client to see if it is still present. The idleConnectionTimeout represents how long Gremlin Server should wait between requests from a client before it closes the connection on the server side. By default, these two configurations are set to zero, meaning that they are both disabled.

This change should help to alleviate issues where connections are left open on the server longer than they should be by clients that might mysteriously disappear without properly closing their connections.

See: TINKERPOP-1726

Gremlin.Net now has a Lambda class that can be used to construct Groovy or Java lambdas which will be evaluated on the server.

See: TINKERPOP-1854, Reference Documentation - Gremlin.Net - The Lambda Solution.

The various Gremlin tokens (e.g. T, Order, Operator, etc.) that were implemented as Enums before in Gremlin.Net are now implemented as classes. This mainly allows them to implement interfaces which their Java counterparts already did. T for example now implements the new interface IFunction which simply mirrors its Java counterpart Function. Steps that expect objects for those interfaces as arguments now explicitly use the interface. Before, they used just object as the type for these arguments which made it hard for users to know what kind of object they can use. However, usage of these tokens themselves shouldn’t change at all (e.g. T.Id is still T.Id).

See: TINKERPOP-1901

Gremlin.Net used two classes for traversal predicates: P and TraversalPredicate. Steps that worked with traversal predicates expected objects of type TraversalPredicate, but they were constructed from the P class (e.g. P.Gt(1) returned a TraversalPredicate). Merging these two classes into the P class should avoid unnecessary confusion. Most users should not notice this change as predicates can still be constructed exactly as before, e.g., P.Gt(1).And(P.Lt(3)) still works without any modifications. Only users that implemented their own predicates and used TraversalPredicate as the base class need to change their implementation to now use P as the new base class.

See: TINKERPOP-1919

With the addition of UUID, Date, and Timestamp, Gremlin-Python now implements serializers for all core GraphSON types. Users that were using other types to represent this data can now use the Python classes datetime.datetime and`uuid.UUID` in GLV traversals. Since Python does not support a native Timestamp object, Gremlin-Python now offers a dummy class Timestamp, which allows users to wrap a float and submit it to the Gremlin Server as a Timestamp GraphSON type. Timestamp can be found in gremlin_python.statics.

See: TINKERPOP-1807

EventStrategy forced detachment of mutated elements prior to raising them in events. While this was a desired outcome, it may not have always fit every use case. For example, a user may have wanted a reference element or the actual element itself. As a result, EventStrategy has changed to allow it to be constructed with a detach() option, where it is possible to specify any of the following: null for no detachment, DetachedFactory for the original behavior, and ReferenceFactory for detachment that returns reference elements.

See: TINKERPOP-1829

As Gremlin Language Variants (GLVs) expand their usage and use of withRemote() becomes more common, the need to mock the "remote" in unit tests increases. To simplify mocking in Java, the new EmbeddedRemoteConnection provides a simple way to provide a "remote" that is actually local to the same JVM.

See: TINKERPOP-1756

Prior to this version, the Java annotation processor for Gremlin DSLs has tried to infer the appropriate type specifications when generating anonymous methods. It largely performed this inference on simple conventions in the DSL method’s template specification and there were times where it would fail. For example, a method like this:

would generate an anonymous method like:

and, of course, generate a compile error and E was not recognized as a symbol. The preferred generation would likely be:

To remedy this situation, a new annotation has been added which allows the user to control the type specifications more directly providing a way to avoid/override the inference system:

which will then generate:

See: TINKERPOP-1791

The :remote connect command can now take a pre-defined Cluster object as its argument as opposed to a YAML configuration file.

See: TINKERPOP-1787

There was limited support for "timeouts" with remote traversals (i.e. those traversals executed using the withRemote() option) prior to 3.2.7. Remote traversals will now interrupt on the server using the scriptEvaluationTimeout setting in the same way that normal script evaluations would. As a reminder, interruptions for traversals are always considered "attempts to interrupt" and may not always succeed (a graph database implementation might not respect the interruption, for example).

See: TINKERPOP-1770

The match()-step has been generalized to support the local scoping of all barrier steps, not just reducing barrier steps. Previously, the order().limit() clause would have worked globally yielding:

However, now, order() (and all other barriers) are treated as local computations to the pattern and thus, the result set is:

Note that this is not that intense of a breaking change as all of the reducing barriers behaved in this manner previously. This includes steps like count(), min(), max(), sum(), group(), groupCount(), etc. This update has now generalized this behavior to all barriers and thus, adds aggregate(), dedup(), range(), limit(), tail(), and order() to the list of locally computed clauses.

See: TINKERPOP-1764

In gremlin-test there is a new GraphHelper class that has a cloneElements() method. It will clone elements from the first graph to the second - GraphHelper.cloneElements(Graph original, Graph clone). This helper method is primarily intended for use in tests.

The MutationListener has a method called vertexPropertyChanged which gathered callbacks when a property on a vertex was modified. The method had an incorrect signature though using Property instead of VertexProperty. The old method that used Property has now been deprecated and a new method added that uses VertexProperty. This new method has a default implementation that calls the old method, so this change should not cause breaks in compilation on upgrade. Internally, TinkerPop no longer calls the old method except by way of that proxy. Users who have MutationListener implementations can simply add the new method and override its behavior. The old method can thus be ignored completely.

See: TINKERPOP-1798

Prior to this release, there was no semantic check to determine whether a self-edge (e.g. e[1][2-self→2]) would be returned twice on a BOTH. The semantics have been specified now in the test suite where the edge should be returned twice as it is both an incoming edge and an outgoing edge.

See: TINKERPOP-1821

The userMapperFromGraph configuration option for the Gremlin Server serializers has been deprecated. Change configuration files to use the ioRegistries option instead. The ioRegistries option is not a new feature, but it has not been promoted as the primary way to add IoRegistry instances to serializers.

See: TINKERPOP-1694

The WsAndHttpChannelizer has been added to allow for processing both WebSocket and HTTP requests on the same port and gremlin server. The SaslAndHttpBasicAuthenticationHandler has also been added to service authentication for both protocols in conjunction with the SimpleAuthenticator.

See: TINKERPOP-915

ReferenceVertex.label() was hard coded to return EMPTY_STRING. At some point, ReferenceElements were suppose to return labels and ReferenceVertex was never updated as such. Note that ReferenceEdge and ReferenceVertexProperty work as expected. However, given a general change at ReferenceElement, the Gryo serialization of ReferenceXXX is different. If the vertex does not have a label Vertex.DEFAULT_LABEL is assumed.

See: TINKERPOP-1789

It has always been possible to construct Domain Specific Languages (DSLs) with Gremlin, but the approach has required a somewhat deep understanding of the TinkerPop code base and it is not something that has had a recommended method for implementation. With this release, TinkerPop simplifies DSL development and provides the best practices for their implementation.

See: TINKERPOP-786, Reference Documentation

Serialization of Path with GraphSON was inconsistent with Gryo in that all the properties on any elements of the Path were being included. With Gryo that, correctly, was not happening as that could be extraordinarily expensive. GraphSON serialization has now been modified to properly not include properties. That change can cause breaks in application code if that application code tries to access properties on elements in a Path as they will no longer be there. Applications that require the properties will need to alter their Gremlin to better restrict the data they want to retrieve.

See: TINKERPOP-1676

The server settings previously used authentication.className to set an authenticator for the the two provided authentication handler and channelizer classes to use. This has been deprecated in favor of authentication.authenticator. A class that extends AbstractAuthenticationHandler may also now be provided as authentication.authenticationHandler to be used in either of the provided channelizer classes to handle the provided authenticator

See: TINKERPOP-1657

It was learned that compilation for scripts with large numbers of parameters is more expensive than those with less parameters. It therefore becomes possible to make some mistakes with how Gremlin Server is used. A new setting on the StandardOpProcessor and SessionOpProcessor called maxParameters controls the number of parameters that can be passed in on a request. This setting is defaulted to sixteen.

Users upgrading to this version may notice errors in their applications if they use more than sixteen parameters. To fix this problem simply reconfigure Gremlin Server with a configuration as follows:

The above configuration allows sixty-four parameters to be passed on each request.

See: TINKERPOP-1663

The GremlinScriptEngine has a number of new metrics about its cache size and script compilation times which should be helpful in understanding usage problems. As GremlinScriptEngine instances are used in Gremlin Server these metrics are naturally exposed as part of the standard metrics set. Note that metrics are captured for both sessionless requests as well as for each individual session that is opened.

See: TINKERPOP-1644

Additional information on error responses from Gremlin Server should help make debugging errors easier. Error responses now have both the exception hierarchy and the stack trace that was generated on the server. In this way, receiving an error on a client doesn’t mean having to rifle through Gremlin Server logs to try to find the associated error.

This change has been applied to all Gremlin Server protocols. For the binary protocol and the Java driver this change means that the ResponseException thrown from calls to submit() requests to the server now have the following methods:

The HTTP protocol has also been updated and returns both exceptions and stackTrace fields in the response:

Note that the Exception-Class which was added in a previous version has been deprecated and replaced by these new fields.

See: TINKERPOP-1044

The gremlin.sh command has two flags, -i and -e, which are used to pass a script and arguments into the Gremlin Console for execution. Those flags now allow for passing multiple scripts and related arguments to be supplied which can yield greater flexibility in automation tasks.

See: TINKERPOP-1653

It is now possible to extract analyze sub-paths using from() and to() modulations with respective, path-based steps. Likewise, simplePath() and cyclicPath() now support, along with from() and to(), by()-modulation so the cyclicity is determined by projections of the path data. This extension is fully backwards compatible.

See: TINKERPOP-1387

Gremlin Server previously implemented its own final GraphManager class. Now, the GraphManager has been changed to an interface, and users can supply their own GraphManager implementations in their YAML. The previous GraphManager class was meant be used by classes internal to Gremlin Server, but it was public so if it was used for some reason by users then then a compile error can be expected. To correct this problem, which will likely manifest as a compile error when trying to create a new GraphManager() instance, simply change the code to new DefaultGraphManager(Settings).

In addition to the change mentioned above, several methods on GraphManager were deprecated:

See: TINKERPOP-1438

Gremlin-Python now offers a more complete driver implementation that uses connection pooling and the Python concurrent.futures module to provide asynchronous I/0 using threading. The default underlying WebSocket client implementation is still provided by Tornado, but it is trivial to plug in another client by defining the Transport interface.

Using the DriverRemoteConnection class is the exact same as in previous versions; however, DriverRemoteConnection now uses the new Client class to submit messages to the server.

The Client class implementation/interface is based on the Java Driver, with some restrictions. Most notably, Gremlin-Python does not yet implement the Cluster class. Instead, Client is instantiated directly. Usage is as follows:

See: TINKERPOP-1599

A TinkerGraph deserialized from Gryo or GraphSON is now configured with multi-properties enabled. This change allows TinkerGraphs returned from Gremlin Server to properly return multi-properties, which was a problem seen when subgraphing a graph that contained properties with a setting other than Cardinality.single.

This change could be considered breaking in the odd chance that a TinkerGraph returned from Gremlin Server was later mutated, because calls to property(k,v) would default to Cardinality.list instead of Cardinality.single. In the event that this is a problem, simple change calls to property(k,v) to property(Cardinality.single,k,v) and explicitly set the Cardinality.

See: TINKERPOP-1587

The Traversal API now has a new promise() method. These methods return a promise in the form of a CompleteableFuture. Usage is as follows:

At this time, this method is only used for traversals that are configured using withRemote().

See: TINKERPOP-1490

Gremlin’s choose()-step supports if/then/else-semantics. Thus, to effect if/then-semantics, identity() was required. Thus, the following two traversals below are equivalent with the later being possible in this release.

See: TINKERPOP-1508

Previously, a call to Traversal.next() that did not have a result would throw a FastNoSuchElementException. This has been changed to a regular NoSuchElementException that includes the stack trace. Code that explicitly catches FastNoSuchElementException should be converted to check for the more general class of NoSuchElementException.

See: TINKERPOP-1330

ScriptEngine and GremlinPlugin infrastructure has been moved from gremlin-groovy to gremlin-core to allow for better re-use across different Gremlin Language Variants. At this point, this change is non-breaking as it was implemented through deprecation.

The basic concept of a ScriptEngine has been replaced by the notion of a GremlinScriptEngine (i.e. a "ScriptEngine" that is specifically tuned for executing Gremlin-related scripts). "ScriptEngine" infrastructure has been developed to help support this new interface, specifically GremlinScriptEngineFactory and GremlinScriptEngineManager. Prefer use of this infrastructure when instantiating a GremlinScriptEngine rather than trying to instantiate directly.

For example, rather than instantiate a GremlinGroovyScriptEngine with the constructor:

prefer to instantiate it as follows:

Related to the addition of GremlinScriptEngine, org.apache.tinkerpop.gremlin.groovy.plugin.GremlinPlugin in gremlin-groovy has been deprecated and then replaced by org.apache.tinkerpop.gremlin.jsr223.GremlinPlugin. The new version of GremlinPlugin is similar but does carry some new methods to implement that involves the new Customizer interface. The Customizer interface is the way in which GremlinScriptEngine instance can be configured with imports, initialization scripts, compiler options, etc.

Note that a GremlinPlugin can be applied to a GremlinScriptEngine by adding it to the GremlinScriptEngineManager that creates it.

All of this new infrastructure is currently optional on the 3.2.x line of code. More detailed documentation will for these changes will be supplied as part of 3.3.0 when these features become mandatory and the deprecated code is removed.

See: TINKERPOP-1562

Added new server configuration option ssl.needClientAuth.

See: TINKERPOP-1602

In 3.2.2, the Gremlin Console introduced a setting called empty.result.indicator, which controlled the output that was presented when no result was returned. For consistency, this setting has been renamed to result.indicator.null and can be set as follows:

See: TINKERPOP-1409

The Java Driver now has a keepAliveInterval setting, which controls the amount of time in milliseconds it should wait on an inactive connection before it sends a message to the server to keep the connection maintained. This should help environments that use a load balancer in front of Gremlin Server by ensuring connections are actively maintained even during periods of inactivity.

See: TINKERPOP-1249

It is now possible to use by() with where() predicate-based steps. Previously, without using match(), if you wanted to know who was older than their friend, the following traversal would be used.

Now, with where().by() support, the above traversal can be expressed more succinctly and more naturally as follows.

See: TINKERPOP-1330

The TinkerPop 3.2.2 release unintentionally introduced a breaking change for some has() method overloads. In particular the behavior for single item array arguments was changed:

Prior this change single item arrays were treated like there was only that single item:

TinkerPop 3.2.3 fixes this misbehavior and all has() method overloads behave like before, except that they no longer support no arguments.

The reconnectInitialDelay setting on the Cluster builder has been deprecated. It no longer serves any purpose. The value for the "initial delay" now comes from reconnectInterval (there are no longer two separate settings to control).

See: TINKERPOP-1460

TraversalSource now implements AutoCloseable, which means that the close() method is now available. This new method is important in cases where withRemote() is used, as withRemote() can open "expensive" resources that need to be released.

In the case of TinkerPop’s DriverRemoteConnection, close() will destroy the Client instance that is created internally by withRemote() as shown below:

Note that the withRemote() method will call close() on a RemoteConnection passed directly to it as well, so there is no need to do that manually.

See: TINKERPOP-790

There is new reference documentation for the various IO formats. The documentation provides more details and samples that should be helpful to users and providers who intend to work directly with the TinkerPop supported serialization formats: GraphML, GraphSON and Gryo.

See: IO Reference Documentation

GraphSON 2.0 has been introduced to improve and normalize the format of types embedded in GraphSON.

See: TINKERPOP-1274, Reference Documentation - GraphSON 2.0.

There were a number of changes to the Log4j dependencies in the various modules. Log4j was formerly included as part of the slf4j-log4j12 in gremlin-core, however that "forced" use of Log4j as a logger implementation when that really wasn’t necessary or desired. If a project depended on gremlin-core or other TinkerPop project to get its Log4j implementation then those applications will need to now include the dependency themselves directly.

Note that Gremlin Server and Gremlin Console explicitly package Log4j in their respective binary distributions.

See: TINKERPOP-1151

The gremlinPool setting in Gremlin Server is now defaulted to zero. When set to zero, Gremlin Server will use the value provided by Runtime.availableProcessors() to set the pool size. Note that the packaged YAML files no longer contain the thread pool settings as all are now driven by sensible defaults. Obviously these values can be added and overridden as needed.

See: TINKERPOP-1373

The Gremlin Console can now have its text colorized. For example, you can set the color of the Gremlin ascii art to the more natural color of green by using the :set command:

It is also possible to colorize results, like vertices, edges, and other common returns. Please see the reference documentation for more details on all the settings.

The console also now includes better multi-line support:

This is a nice feature in that it can help you understand if a line is incomplete and unevaluated.

See: TINKERPOP-1285, TINKERPOP-1037, Reference Documentation - Console Preferences

This is only a rename to clarify the design of the API. There is no change to the API itself.

The Gephi Plugin has been updated to support Gephi 0.9.x. Please upgrade to this latest version to use the Gephi Plugin for Gremlin Console.

See: TINKERPOP-1297

It is now possible to override existing serializers with calls to addCustom on the GryoMapper builder. This option allows complete control over the serializers used by Gryo. Of course, this also makes it possible to produce completely non-compliant Gryo files. This feature should be used with caution.

TraversalVertexProgram always maintained a HALTED_TRAVERSERS TraverserSet for each vertex throughout the life of the OLAP computation. However, if there are no halted traversers in the set, then there is no point in keeping that compute property around as without it, time and space can be saved. Users that have VertexPrograms that are chained off of TraversalVertexProgram and have previously assumed that HALTED_TRAVERSERS always exists at each vertex, should no longer assume that.

Traversals now better respect calls to Thread.interrupt(), which mean that a running Traversal can now be cancelled. There are some limitations that remain, but most OLTP-based traversals should cancel without issue. OLAP-based traversals for Spark will also cancel and clean up running jobs in Spark itself. Mileage may vary on other process implementations and it is possible that graph providers could potentially write custom step implementations that prevent interruption. If it is found that there are configurations or specific traversals that do not respect interruption, please mention them on the mailing list.

See: TINKERPOP-946

Gremlin Console had several methods for executing scripts from file at the start-up of bin/gremlin.sh. There were two options:

Changes in this version of TinkerPop have added much more flexibility here and only a minor breaking change should be considered when using this version. First of all, recognize that hese two lines are currently equivalent:

but users should start to explicitly specify the -i flag as TinkerPop will eventually remove the old syntax. Despite the one used beware of the fact that neither will close the console on script failure anymore. In that sense, this behavior represents a breaking change to consider. To ensure the console closes on failure or success, a script will have to use the -e option.

The console also has a number of new features in addition to -e and -i:

See: TINKERPOP-1268, TINKERPOP-1155, TINKERPOP-1156, TINKERPOP-1157, Reference Documentation - Interactive Mode, Reference Documentation - Execution Mode

The HadoopGremlinPlugin defines two variables: hdfs and fs. The first is a reference to the HDFS FileSystemStorage and the latter is a reference to the local FileSystemStorage. Prior to 3.2.x, fs was called local. However, there was a variable name conflict with Scope.local. As such local is now fs. This issue existed prior to 3.2.x, but was not realized until this release. Finally, this only effects Gremlin Console users.

Note that gremlin.hadoop.graphInputFormat, gremlin.hadoop.graphOutputFormat, gremlin.spark.graphInputRDD, and gremlin.spark.graphOuputRDD have all been deprecated. Using them still works, but moving forward, users only need to leverage gremlin.hadoop.graphReader and gremlin.hadoop.graphWriter. An example properties file snippet is provided below.

See: TINKERPOP-1082, TINKERPOP-1222

There were changes to TraversalSideEffect both at the semantic level and at the API level. Users that have traversals of the form sideEffect{…​} that leverage global side-effects should read the following carefully. If the user’s traversals do not use lambda-based side-effect steps (e.g. groupCount("m")), then the changes below will not effect them. Moreover, if user’s traversal only uses sideEffect{…​} with closure (non-TraversalSideEffect) data references, then the changes below will not effect them. If the user’s traversal uses sideEffects in OLTP only, the changes below will not effect them. Finally, providers should not be effected by the changes save any tests cases.

The profile()-step has been refactored into 2 steps — ProfileStep and ProfileSideEffectStep. Users who previously used the profile() in conjunction with cap(TraversalMetrics.METRICS_KEY) can now simply omit the cap step. Users who retrieved TraversalMetrics from the side-effects after iteration can still do so, but will need to specify a side-effect key when using the profile(). For example, profile("myMetrics").

See: TINKERPOP-958

There was a bug in BranchStep that also rears itself in subclass steps such as UnionStep and ChooseStep. For traversals with branches that have barriers (e.g. count(), max(), groupCount(), etc.), the traversal needs to be updated. For instance, if a traversal is of the form g.V().union(out().count(),both().count()), the result is now different (the bug fix yields a different output). In order to yield the same result, the traversal should be rewritten as g.V().local(union(out().count(),both().count())). Note that if a branch does not have a barrier, then no changes are required. For instance, g.V().union(out(),both()) does not need to be updated. Moreover, if the user’s traversal already used the local()-form, then no change are required either.

See: TINKERPOP-1188

Users that have custom VertexProgram implementations will need to change their implementations to support the new VertexComputeKey and MemoryComputeKey classes. In the VertexPrograms provided by TinkerPop, these changes were trivial, taking less than 5 minutes to make all the requisite updates.

An example migration looks as follows. What might currently look like:

Should now look like:

A similar patterns should also be used for VertexProgram.getVertexComputeKeys().

See: TINKERPOP-1162

The MapReduce-based steps in TraversalVertexProgram have been removed and replaced using a new Memory-reduction model. MapReduce jobs always created a persistence footprint, e.g. in HDFS. Memory data was never persisted to HDFS. As such, there will be no data on the disk that is accessible. For instance, there is no more ~reducing, ~traversers, and specially named side-effects such as m from a groupCount('m'). The data is still accessible via ComputerResult.memory(), it simply does not have a corresponding on-disk representation.

RemoteGraph is a lightweight Graph implementation that acts as a proxy for sending traversals to Gremlin Server for remote execution. It is an interesting alternative to the other methods for connecting to Gremlin Server in that all other methods involved construction of a String representation of the Traversal which is then submitted as a script to Gremlin Server (via driver or HTTP).

Note that g.V().valueMap(true) is executing in Gremlin Server and not locally in the console.

See: TINKERPOP-575, Reference Documentation - Remote Graph

There were some inconsistencies in the GraphML format supported in TinkerPop 2.x. These issues were corrected on the initial release of TinkerPop 3.0.0, but as a result, attempting to read GraphML from 2.x will end with an error. A newly added XSLT file in gremlin-core, called tp2-to-tp3-graphml.xslt, transforms 2.x GraphML into 3.x GraphML, making it possible easily read in legacy GraphML through a 3.x GraphMLReader.

See: TINKERPOP-1608

There were a few problems noted around the close() of Cluster and Client instances, including issues that presented as system hangs. These issues have been resolved, however, it is worth noting that an unchecked exception that was thrown under a certain situation has changed as part of the bug fixes. When submitting an in-session request on a Client that was closed (or closing) an IllegalStateException is thrown. This replaces older functionality that threw a ConnectionException and relied logic far deeper in the driver to produce that error and had the potential to open additional resources despite the intention of the user to "close".

See: TINKERPOP-1467

In release 3.1.3, a recommendation was made to ensure that the threadPoolWorker setting for Gremlin Server was no less than 2 in cases where Gremlin Server was being used with sessions that accept parallel requests. In 3.1.4, that is no longer the case and a size of 1 remains acceptable even in that specific case.

See: TINKERPOP-1350

Gremlin Server has always considered certain binding keys (request parameters) as reserved, but that list has now expanded to be more inclusive all the static enums that are imported to the script engine. It is possible that those using Gremlin Server may have to rename their keys if they somehow successfully were using some of the now reserved terms in previous versions.

See: TINKERPOP-1354

Disabling the timeout for a :remote to Gremlin Server was previously accomplished by setting the timeout to max as in:

where max would set the timeout to be Integer.MAX_VALUE. While this feature is still supported, it has been deprecated in favor of the new configuration option of none, as in:

The use of none completely disables the timeout rather than just setting an arbitrarily high one. Note that it is still possible to get a timeout on a request if the server timeout limits are reached. The console timeout value only refers to how long the console will wait for a response from the server before giving up. By default, the timeout is set to none.

See: TINKERPOP-1267

Past configuration recommendations for the threadPoolWorker setting on Gremlin Server stated this value could be safely set to 1 at the low end. A size of 1 is still valid for most cases, however, if Gremlin Server is being used with sessions that accept parallel requests, then this value should be no less than 2 or else certain scripts (i.e. those that block for an extended period of time) may cause Gremlin Server to lock up the session.

See: TINKERPOP-1350

Calls to SessionedClient.alias() used to throw UnsupportedOperationException and it was therefore not possible to use that capability with a session. That method is now properly implemented and aliasing is allowed.

See: TINKERPOP-1096

The :remote console command provides a way to avoid having to prefix the :> command to scripts when remoting. This mode of console usage can be convenient when working exclusively with a remote like Gremlin Server and there is only a desire to view the returned data and not to actually work with it locally in any way.

See: Reference Documentation - Remote Console

The :remote tinkerpop.server command now allows for a "session" argument to be passed to connect. This argument, tells the remote to configure it with a Gremlin Server session. In this way, the console can act as a window to script exception on the server and behave more like a standard "local" console when it comes to script execution.

See: TINKERPOP-1097

TinkerPop now offers Maven archetypes, which provide example project templates to quickly get started with TinkerPop. The available archetypes are as follows:

See: TINKERPOP-1085, Reference Documentation - Archetypes

When connecting to a session with gremlin-driver, it is now possible to configure the Client instance so as to request that the server manage the transaction for each requests.

Specifying true to the connect() method signifies that the client should make each request as one encapsulated in a transaction. With this configuration of client there is no need to close a transaction manually.

See: TINKERPOP-1039, Reference Documentation - Considering Sessions

The gremlin-driver now has a setting called maxWaitForSessionClose that allows control of how long it will wait for an in-session connection to respond to a close request before it simply times-out and moves on. When that happens, the server will either eventually close the connection via at session expiration or at the time of shutdown.

See: TINKERPOP-1160

The gremlin-core io-package now has a Storage interface. The methods that were available via hdfs (e.g. rm(), ls(), head(), etc.) are now part of Storage. Both HDFS and Spark implement Storage via FileSystemStorage and SparkContextStorage, respectively. SparkContextStorage adds support for interacting with persisted RDDs in the Spark cache.

This update changed a few of the file handling methods. As it stands, these changes only effect manual Gremlin Console usage as HDFS support was previously provided via Groovy meta-programing. Thus, these are not "code-based" breaking changes.

Given that HDFS (and now Spark) interactions are possible via Storage and no longer via Groovy meta-programming, developers can use these Storage implementations in their Java code. In fact, Storage has greatly simplified complex file/RDD operations in both GiraphGraphComputer and SparkGraphComputer.

Finally, note that the following low-level/internal classes have been removed: HadoopLoader and HDFSTools.

See: TINKERPOP-1033, TINKERPOP-1023

Gremlin Server now has a setting called strictTransactionManagement, which forces the user to pass aliases for all requests. The aliases are then used to determine which graphs will have their transactions closed for that request. The alternative is to continue with default operations where the transactions of all configured graphs will be closed. It is likely that strictTransactionManagement (which is false by default so as to be backward compatible with previous versions) will become the future standard mode of operation for Gremlin Server as it provides a more efficient method for transaction management.

See: TINKERPOP-930, Reference Documentation - Considering Transactions

The credentialsDbLocation setting was a TinkerGraph only configuration option to the SimpleAuthenticator for Gremlin Server. It provided the file system location to a "credentials graph" that TinkerGraph would read from a Gryo file at that spot. This setting was only required because TinkerGraph did not support file persistence at the time that SimpleAuthenticator was created.

As of 3.1.0-incubating, TinkerGraph received a limited persistence feature that allowed the "credentials graph" location to be specified in the TinkerGraph properties file via gremlin.tinkergraph.graphLocation and as such the need for credentialsDbLocation was eliminated.

This deprecation is not a breaking change, however users should be encouraged to convert their configurations to use the gremlin.tinkergraph.graphLocation as soon as possible, as the deprecated setting will be removed in a future release.

See: TINKERPOP-981, Reference Documentation - Gremlin Server Security

TinkerGraph’s 'gremlin.tinkergraph.graphLocation' configuration setting can now take a fully qualified class name of a Io.Builder implementation, which means that custom IO implementations can be used to read and write TinkerGraph instances.

See: TINKERPOP-886

For users who have a custom Authenticator implementation for Gremlin Server, there will be a new method present:

Implementation of this method is now preferred over the old method with the same name that has no arguments. The old method has been deprecated. This is a non-breaking change as the new method has a default implementation that simply calls the old deprecated method. In this way, existing Authenticator implementations will still work.

See: TINKERPOP-995

Spark RDD persistence is now much safer with a "job server" system that ensures that persisted RDDs are not garbage collected by Spark. With this, the user is provider a spark object that enables them to manage persisted RDDs much like the hdfs object is used for managing files in HDFS.

Finally, InputRDD instance no longer need a reduceByKey() postfix as view merges happen prior to writing the graphRDD. Note that a reduceByKey() postfix will not cause problems if continued, it is simply inefficient and no longer required.

See: TINKERPOP-1023, TINKERPOP-1027

Logging to Gremlin Server and Gremlin Console can now be consistently controlled by the log4j-server.properties and log4j-console.properties which are in the respective conf/ directories of the packaged distributions.

See: TINKERPOP-859

A number of improvements were made to the sandboxing feature of Gremlin Server (more specifically the GremlinGroovyScriptEngine). A new base class for sandboxing was introduce with the AbstractSandboxExtension, which makes it a bit easier to build white list style sandboxes. A usable implementation of this was also supplied with the FileSandboxExtension, which takes a configuration file containing a white list of accessible methods and variables that can be used in scripts. Note that the original SandboxExtension has been deprecated in favor of the AbsstractSandboxExtension or extending directly from Groovy’s TypeCheckingDSL.

See: TINKERPOP-891, Reference Documentation - Script Execution

It was realized that VertexPropertyFeatures.supportsAddProperty() was effectively a duplicate of VertexFeatures.supportsMetaProperties(). As a result, supportsAddProperty() was deprecated in favor of the other. If using supportsAddProperty(), simply modify that code to instead utilize supportsMetaProperties().

The Jackson library is now shaded to gremlin-shaded, which will allow Jackson to version independently without breaking compatibility with dependent libraries or with those who depend on TinkerPop. The downside is that if a library depends on TinkerPop and uses the Jackson classes, those classes will no longer exist with the standard Jackson package naming. They will have to shifted as follows:

See: TINKERPOP-835

PartitionStrategy now supports partitioning within VertexProperty. The Graph needs to be able to support meta-properties for this feature to work.

See: TINKERPOP-333

Gremlin Server provides a configuration option to turn on support for Netty native transport on Linux, which has been shown to help improve performance.

See: TINKERPOP-901

The notion of "rebindings" has been deprecated in favor of the term "aliases". Alias is a better and more intuitive term than rebindings which should make it easier for newcomers to understand what they are for.

See: TINKERPOP-913, Reference Documentation - Aliases

The Gremlin Driver now allows the Channerlizer to be supplied as a configuration, which means that custom implementations may be supplied.

See: TINKERPOP-680

The GraphMLReader now has a strict option on the Builder so that if a data type for a value is invalid in some way, GraphMLReader will simply skip that problem value. In that way, it is a bit more forgiving than before especially with empty data.

See: TINKERPOP-756

The default behavior of Transaction.close() is to rollback the transaction. This is in contrast to previous versions where the default behavior was commit. Using rollback as the default should be thought of as a like a safer approach to closing where a user must now explicitly call commit() to persist their mutations.

See TINKERPOP-805 for more information.

The Transaction.onReadWrite() and Transaction.onClose() settings now need to be set for each thread (if another behavior than the default is desired). For gremlin-server users that may be changing these settings via scripts. If the settings are changed for a sessionless request they will now only apply to that one request. If the settings are changed for an in-session request they will now only apply to all future requests made in the scope of that session.

See TINKERPOP-885

See link:https://issues.apache.org/jira/browse/TINKERPOP-616

See link:https://issues.apache.org/jira/browse/TINKERPOP-868, link:https://issues.apache.org/jira/browse/TINKERPOP-925

TinkerGraph is serializable over Gryo, which means that it can shipped over the wire from Gremlin Server. This feature can be useful when working with remote subgraphs.

See: TINKERPOP-728

The public static String configurations have been renamed. The old public static variables have been deprecated. If the deprecated variables were being used, then convert to the replacements as soon as possible.

See: TINKERPOP-926

The closure wrappers classes GFunction, GSupplier, GConsumer have been deprecated. In Groovy, a closure can be specified using as Function and thus, these wrappers are not needed. Also, the GremlinExecutor.promoteBindings() method which was previously deprecated has been removed.

See: TINKERPOP-879, TINKERPOP-897

The process for visualizing a traversal has been simplified. There is no longer a need to "name" steps that will represent visualization points for Gephi. It is possible to just "configure" a visualTraversal in the console:

which creates a special TraversalSource from graph called vg. The traversals created from vg can be used to :submit to Gephi.

See: Reference Documentation - Gephi

There were a number of changes to GraphTraversal. Many of the changes came by way of deprecation, but some semantics have changed as well:

The :remote command in Gremlin Console has a new alias configuration option. This alias option allows specification of a set of key/value alias/binding pairs to apply to the remote. In this way, it becomes possible to refer to a variable on the server as something other than what it is referred to for purpose of the submitted script. For example once a :remote is created, this command:

would allow "g" on the server to be referred to as "x".

See: TINKERPOP-914

BulkLoaderVertexProgram now supports arbitrary inputs (i addition to HadoopGraph, which was already supported in version 3.0.1-incubating). It can now also read from any TP3 enabled graph, like TinkerGraph or Neo4jGraph.

See: TINKERPOP-319, Reference Documentation - BLVP

TinkerGraph can now be configured to support persistence, where TinkerGraph will try to load a graph from a specified location and calls to close() will save the graph data to that location.

See: TINKERPOP-828, Reference Documentation - TinkerGraph

There were a number of fixes to gremlin-driver that prevent protocol desynchronization when talking to Gremlin Server.

On the Gremlin Server side, Websocket sub-protocol introduces a new "close" operation to explicitly close sessions. Prior to this change, sessions were closed in a more passive fashion (i.e. session timeout). There were also so bug fixes around the protocol as it pertained to third-party drivers (e.g. python) using JSON for authentication.

See: TINKERPOP-814, TINKERPOP-816, TINKERPOP-817, TINKERPOP-855, TINKERPOP-870, TINKERPOP-877

Gremlin Server now supports a SASL-based (Simple Authentication and Security Layer) authentication model and a default SimpleAuthenticator which implements the PLAIN SASL mechanism (i.e. plain text) to authenticate requests. This gives Gremlin Server some basic security capabilities, especially when combined with its built-in SSL feature.

There have also been changes in how global variable bindings in Gremlin Server are established via initialization scripts. The initialization scripts now allow for a Map of values that can be returned from those scripts. That Map will be used to set global bindings for the server. See this sample script for an example.

See: TINKERPOP-576

Problems related to using :install to get the Neo4j plugin operating in Gremlin Console on Windows have been resolved.

See: TINKERPOP-804