This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch TINKERPOP-2235 in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 222b72dee40c1cdf0036a9286a0f9382842987d3 Author: stephen <spmalle...@gmail.com> AuthorDate: Tue Nov 5 16:05:11 2019 -0500 TINKERPOP-2235 Added upgrade and reference docs --- CHANGELOG.asciidoc | 3 + .../reference/implementations-tinkergraph.asciidoc | 1 + docs/src/upgrade/release-3.5.x.asciidoc | 74 ++++++++++++++++++++-- 3 files changed, 72 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index 4e2642a..9dc385b 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -25,6 +25,9 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima This release also includes changes from <<release-3-4-3, 3.4.3>>. +* Allowed the possibility for the user of `null` in Gremlin. +* Added a `Graph.Feature` for `supportsNullPropertyValues`. +* Modified TinkerGraph to support `null` property values and can be configured to disable that feature. * Modified `null` handling in mutations to be consistent for a new `Vertex` as well as update to an existing one. * Upgraded to Apache Commons Configuration2. * Renamed `StoreStep` to `AggregateLocalStep`. diff --git a/docs/src/reference/implementations-tinkergraph.asciidoc b/docs/src/reference/implementations-tinkergraph.asciidoc index fe14d0f..e919bd4 100644 --- a/docs/src/reference/implementations-tinkergraph.asciidoc +++ b/docs/src/reference/implementations-tinkergraph.asciidoc @@ -121,6 +121,7 @@ TinkerGraph has several settings that can be provided on creation via `Configura |gremlin.tinkergraph.edgeIdManager |The `IdManager` implementation to use for edges. |gremlin.tinkergraph.vertexPropertyIdManager |The `IdManager` implementation to use for vertex properties. |gremlin.tinkergraph.defaultVertexPropertyCardinality |The default `VertexProperty.Cardinality` to use when `Vertex.property(k,v)` is called. +|gremlin.tinkergraph.allowNullPropertyValues |A boolean value that determines whether or not `null` property values are allowed and defaults to `true`. |gremlin.tinkergraph.graphLocation |The path and file name for where TinkerGraph should persist the graph data. If a value is specified here, the `gremlin.tinkergraph.graphFormat` should also be specified. If this value is not included (default), then the graph will stay in-memory and not be loaded/persisted to disk. diff --git a/docs/src/upgrade/release-3.5.x.asciidoc b/docs/src/upgrade/release-3.5.x.asciidoc index cd04b4e..cf0ee67 100644 --- a/docs/src/upgrade/release-3.5.x.asciidoc +++ b/docs/src/upgrade/release-3.5.x.asciidoc @@ -60,7 +60,6 @@ org.apache.commons.configuration.* to - [source,text] ---- org.apache.commons.configuration2.* @@ -73,10 +72,61 @@ upgrade information can be found in the link:https://commons.apache.org/proper/c See: link:https://issues.apache.org/jira/browse/TINKERPOP-2185[TINKERPOP-2185] -==== addV() and null +==== Use of null + +Gremlin has traditionally disallowed `null` as a value in traversals and not always in consistent ways: + +[source,text] +---- +gremlin> g.inject(1, null, null, 2, null) +java.lang.NullPointerException +Type ':help' or ':h' for help. +Display stack trace? [yN]n +gremlin> g.V().has('person','name','marko').property('age', null) +The AddPropertyStep does not have a provided value: AddPropertyStep({key=[age]}) +Type ':help' or ':h' for help. +Display stack trace? [yN] +gremlin> g.addV("person").property("name", 'stephen').property("age", null) +==>v[13] +gremlin> g.V().has('person','name','stephen').elementMap() +==>[id:13,label:person,name:stephen] +gremlin> g.V().constant(null) +gremlin> +---- + +Note how `null` can produce exception behavior or act as a filter. For 3.5.0, TinkerPop has not only made `null` usage +consistent, but has also made it an allowable value within a `Traversal`: + +[source,text] +---- +gremlin> g.inject(1, null, null, 2, null) +==>1 +==>null +==>null +==>null +==>2 +gremlin> g.addV("person").property("name", 'stephen').property("age", null) +==>v[13] +gremlin> g.V().has('person','name','stephen').elementMap() +==>[id:13,label:person,name:stephen,age:null] +gremlin> g.V().has('person','age',null) +==>v[13] +gremlin> g.V().constant(null) +==>null +==>null +==>null +==>null +==>null +==>null +---- + +Note that the above examples use TinkerGraph which now supports `null` as a property value (though it can be configured +to work in the prior fashion) and all graphs may not support this feature (for example, Neo4j does not). Please be +sure to check the new `supportsNullPropertyValues()` feature (or their documentation) to determine if the `Graph` +implementation allows `null` in this same fashion. -There was a bit of inconsistency in the handling of `null` in calls to `property()` depending on the type of mutation -being executed demonstrated as follows in earlier versions: +As a final consideration, there was a bit of inconsistency in the handling of `null` in calls to `property()` +depending on the type of mutation being executed demonstrated as follows in earlier versions: [source,text] ---- @@ -91,7 +141,8 @@ gremlin> g.V(13).properties() ==>vp[z->2] ---- -In this release, this behavior has been altered to become consistent as follows: +In this release, this behavior has been altered to become consistent. First, assuming `null` is not supported as a +property value: [source,text] ---- @@ -105,7 +156,18 @@ Type ':help' or ':h' for help. Display stack trace? [yN] ---- -See: link:https://issues.apache.org/jira/browse/TINKERPOP-2099[TINKERPOP-2099] +Then, assuming `null` is supported as a property value: + +[source,text] +---- +gremlin> g.V(1).property("x", 1).property("y", null).property("z", 2) +==>v[1] +gremlin> g.addV().property("x", 1).property("y", null).property("z", 2) +==>v[15] +---- + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-2235[TINKERPOP-2235], +link:https://issues.apache.org/jira/browse/TINKERPOP-2099[TINKERPOP-2099] ==== Remote SideEffects