You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2019/11/06 14:46:21 UTC
[tinkerpop] 06/06: TINKERPOP-2235 Added upgrade and reference docs
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 088074305cac29ad2064aba1eafcfe7a05873e87
Author: stephen <sp...@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 50fa442..e17ad32 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 7372107..9e75caa 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