TinkerPop 3.5.0 - Null Semantics Changes (Breaking)

[David Bechberger]

In addition to all the other changes already mentioned, one thing I am most excited about in the TinkerPop 3.5.0 release is the change in the semantics of how null values are handled (TINKERPOP-2235). If you, like me, have ever been frustrated by the error message “The property does not exist as the key has no associated value for the provided element” when ordering/grouping elements then this change will make your life much easier. Currently, when performing operations such as grouping/ordering with heterogeneous data, where elements are not guaranteed to have a property then you either get this:


Or you handle this by writing a gremlin traversal that uses coalesce() to prevent the error above by returning a dummy value:

While these methods work they have several drawbacks:

• This meaning of the error message is not obvious to those not familiar with Gremlin and the way to fix it is not discoverable to users new to Gremlin.
• Gremlin’s handling of null data fields is different from most other database query languages and is a constant point where new users are confused.
• It adds complexity to a traversal which, while minimal in the example above, quickly become unwieldy as the number of values used expands.
• The value being returned does not accurately represent the data as an empty string or other substitute value (e.g. -999 for age) and must be transformed by the consuming application to provide an accurate representation of the data.

With the changes in null semantics in the 3.5.0 release these concerns are now addressed. When you run grouping and ordering operations they now represent non-existent values as a null, as shown below.



This change in the semantics better matches with user expectations, provides for a simpler traversal (since the coalesce() statement(s) are no longer needed), and more accurately reflects that the data does not exist. In addition to the changes to the behavior of the order and grouping steps the property() step can now also set the value = null to remove a property.


This change is especially helpful when using application code that has had to implement logic to handle transforming null values in maps to property() steps. With this change applications will no longer have to implement this logic, and instead can simply create null values, using the native representation of null values in that language.

Now that we have seen how leveraging these new features can help simplify our lives, lets take a moment to discuss some warnings for using this feature:

• This is a breaking change. Since this changes the return behavior for data, you should ensure that your application is ready to handle the new format.
• This is a 3.5+ feature, it has not been back ported to earlier versions, so you need to make sure that your chosen database solution is compatible with 3.5.
• The ability to set property values to null to delete them is an optional feature so not all databases do/will support all or part of these semantics. Check with your chosen database for compatibility details by lookup for the vertex supportsNullPropertyValues feature.

While this change might seem like a small deal, it will really help in smoothing the traversal writing process for new and existing Gremlin users. I’d like to thank everyone from the development side that participated in helping make this change happen.

Dave