Moved references to TinkerPop 2.x to upgrade docs By now we're pretty much just "TinkerPop" - anything else is just sorta confusing. CTR
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/849349af Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/849349af Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/849349af Branch: refs/heads/shortest-path-wip Commit: 849349afc901ef543e36726b276645cb74cb20d1 Parents: dbf3a0e Author: Stephen Mallette <[email protected]> Authored: Tue May 29 16:13:01 2018 -0400 Committer: Stephen Mallette <[email protected]> Committed: Tue May 29 16:13:01 2018 -0400 ---------------------------------------------------------------------- docs/src/dev/future/index.asciidoc | 4 +- docs/src/dev/provider/index.asciidoc | 24 ++-- .../src/reference/gremlin-applications.asciidoc | 8 +- .../implementations-hadoop-start.asciidoc | 8 +- .../reference/implementations-neo4j.asciidoc | 4 +- .../implementations-tinkergraph.asciidoc | 6 +- docs/src/reference/intro.asciidoc | 38 +++---- docs/src/reference/preface.asciidoc | 10 +- docs/src/reference/the-graph.asciidoc | 90 ++------------- docs/src/reference/the-graphcomputer.asciidoc | 17 +-- docs/src/reference/the-traversal.asciidoc | 22 ++-- .../the-gremlin-console/index.asciidoc | 4 +- docs/src/upgrade/appendix.asciidoc | 113 +++++++++++++++++++ docs/src/upgrade/index.asciidoc | 2 + .../Process/Traversal/GraphTraversal.cs | 9 ++ .../lib/process/graph-traversal.js | 10 ++ .../gremlin_python/process/graph_traversal.py | 4 + 17 files changed, 216 insertions(+), 157 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/dev/future/index.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/dev/future/index.asciidoc b/docs/src/dev/future/index.asciidoc index 11115cf..6e41cf9 100644 --- a/docs/src/dev/future/index.asciidoc +++ b/docs/src/dev/future/index.asciidoc @@ -40,8 +40,8 @@ image:tp4-think.png[] == The Main Features -TinkerPop4 should focus on the most successful aspects of TinkerPop3 and it should avoid the traps realized in TinkerPop3. -These items include: +TinkerPop 4.x should focus on the most successful aspects of TinkerPop 3.x and it should avoid the traps realized in +TinkerPop 3.x. These items include: * The concept of Gremlin as both a virtual machine and language. ** A standard bytecode specification should be provided. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/dev/provider/index.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/dev/provider/index.asciidoc b/docs/src/dev/provider/index.asciidoc index 467b3f3..f6a964b 100644 --- a/docs/src/dev/provider/index.asciidoc +++ b/docs/src/dev/provider/index.asciidoc @@ -39,17 +39,17 @@ This document attempts to address the needs of the different providers that have [[graph-system-provider-requirements]] == Graph System Provider Requirements -image:tinkerpop-enabled.png[width=140,float=left] At the core of TinkerPop3 is a Java8 API. The implementation of this +image:tinkerpop-enabled.png[width=140,float=left] At the core of TinkerPop 3.x is a Java8 API. The implementation of this core API and its validation via the `gremlin-test` suite is all that is required of a graph system provider wishing to -provide a TinkerPop3-enabled graph engine. Once a graph system has a valid implementation, then all the applications +provide a TinkerPop-enabled graph engine. Once a graph system has a valid implementation, then all the applications provided by TinkerPop (e.g. Gremlin Console, Gremlin Server, etc.) and 3rd-party developers (e.g. Gremlin-Scala, Gremlin-JS, etc.) will integrate properly. Finally, please feel free to use the logo on the left to promote your -TinkerPop3 implementation. +TinkerPop implementation. [[graph-structure-api]] === Graph Structure API -The graph structure API of TinkerPop3 provides the interfaces necessary to create a TinkerPop enabled system and +The graph structure API of TinkerPop provides the interfaces necessary to create a TinkerPop enabled system and exposes the basic components of a property graph to include `Graph`, `Vertex`, `Edge`, `VertexProperty` and `Property`. The structure API can be used directly as follows: @@ -77,11 +77,7 @@ In the above code all the vertices are created first and then their respective e `Graph.addVertex(Object...)` or `Vertex.addEdge(String,Vertex,Object...)`, the respective element is created along with the provided key/value pair properties appended to it. -Below is a sequence of basic graph mutation operations represented in Java 8. One of the major differences between -TinkerPop2 and TinkerPop3 is that in TinkerPop3, the Java convention of using setters and getters has been abandoned -in favor of a syntax that is more aligned with the syntax of Gremlin-Groovy in TinkerPop2. Given that Gremlin-Java8 -and Gremlin-Groovy are nearly identical due to the inclusion of Java 8 lambdas, a big effort was made to ensure that -both languages are as similar as possible. +Below is a sequence of basic graph mutation operations represented in Java 8. image:basic-mutation.png[width=240,float=right] [source,java] @@ -160,7 +156,7 @@ image:pipes-character-1.png[width=110,float=right] The most important interfaces package. These include interfaces like Graph, Vertex, Edge, Property, Transaction, etc. The `StructureStandardSuite` will ensure that the semantics of the methods implemented are correct. Moreover, there are numerous `Exceptions` classes with static exceptions that should be thrown by the graph system so that all the exceptions and their -messages are consistent amongst all TinkerPop3 implementations. +messages are consistent amongst all TinkerPop implementations. [[olap-implementations]] ==== OLAP Implementations @@ -219,7 +215,7 @@ that will be readable by the receiving vertices in the subsequent round. ===== Implementing MapReduce Emitters -image:hadoop-logo-notext.png[width=150,float=left] The MapReduce framework in TinkerPop3 is similar to the model +image:hadoop-logo-notext.png[width=150,float=left] The MapReduce framework in TinkerPop is similar to the model popularized by link:http://hadoop.apache.org[Hadoop]. The primary difference is that all Mappers process the vertices of the graph, not an arbitrary key/value pair. However, the vertices' edges can not be accessed -- only their properties. This greatly reduces the amount of data needed to be pushed through the MapReduce engine as any edge @@ -274,7 +270,7 @@ public class TinkerMapEmitter<K, V> implements MapReduce.MapEmitter<K, V> { <1> If the MapReduce job has a reduce, then use one data structure (`reduceMap`), else use another (`mapList`). The difference being that a reduction requires a grouping by key and therefore, the `Map<K,Queue<V>>` definition. If no reduction/grouping is required, then a simple `Queue<KeyValue<K,V>>` can be leveraged. -<2> If reduce is to follow, then increment the Map with a new value for the key. `MapHelper` is a TinkerPop3 class +<2> If reduce is to follow, then increment the Map with a new value for the key. `MapHelper` is a TinkerPop class with static methods for adding data to a Map. <3> If no reduce is to follow, then simply append a KeyValue to the queue. <4> When the map phase is complete, any map-result sorting required can be executed at this point. @@ -767,7 +763,7 @@ SureFire Plugin, this is done via the configuration argLine with `-Dbuild.dir=${ === Accessibility via GremlinPlugin -image:gremlin-plugin.png[width=100,float=left] The applications distributed with TinkerPop3 do not distribute with +image:gremlin-plugin.png[width=100,float=left] The applications distributed with TinkerPop do not distribute with any graph system implementations besides TinkerGraph. If your implementation is stored in a Maven repository (e.g. Maven Central Repository), then it is best to provide a <<gremlin-plugins,`GremlinPlugin`>> implementation so the respective jars can be downloaded according and when required by the user. Neo4j's GremlinPlugin is provided below for reference. @@ -793,7 +789,7 @@ gremlin> g = Neo4jGraph.open('/tmp/neo4j') === In-Depth Implementations image:gremlin-painting.png[width=200,float=right] The graph system implementation details presented thus far are -minimum requirements necessary to yield a valid TinkerPop3 implementation. However, there are other areas that a +minimum requirements necessary to yield a valid TinkerPop implementation. However, there are other areas that a graph system provider can tweak to provide an implementation more optimized for their underlying graph engine. Typical areas of focus include: http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/reference/gremlin-applications.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/gremlin-applications.asciidoc b/docs/src/reference/gremlin-applications.asciidoc index 6298d11..c54b290 100644 --- a/docs/src/reference/gremlin-applications.asciidoc +++ b/docs/src/reference/gremlin-applications.asciidoc @@ -670,7 +670,7 @@ They are all still evaluated locally. </dependency> ---- -image:gremlin-java.png[width=175,float=left] TinkerPop3 comes equipped with a reference client for Java-based +image:gremlin-java.png[width=175,float=left] TinkerPop comes equipped with a reference client for Java-based applications. It is referred to as Gremlin Driver, which enables applications to send requests to Gremlin Server and get back results. @@ -802,7 +802,7 @@ approach when it configures it's serializers, so using this same model will ensu pip install gremlinpython ---- -TinkerPop3 also includes a client for Python-based applications. It is referred to as Gremlin-Python Driver. +TinkerPop also includes a client for Python-based applications. It is referred to as Gremlin-Python Driver. 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: @@ -2275,13 +2275,13 @@ installed in conjuction with the <<hadoop-plugin,Hadoop-Plugin>>. image:gremlin-sugar.png[width=120,float=left] In previous versions of Gremlin-Groovy, there were numerous link:http://en.wikipedia.org/wiki/Syntactic_sugar[syntactic sugars] that users could rely on to make their traversals more succinct. Unfortunately, many of these conventions made use of link:http://docs.oracle.com/javase/tutorial/reflect/[Java reflection] -and thus, were not performant. In TinkerPop3, these conveniences have been removed in support of the standard +and thus, were not performant. In TinkerPop, these conveniences have been removed in support of the standard Gremlin-Groovy syntax being both inline with Gremlin-Java8 syntax as well as always being the most performant representation. However, for those users that would like to use the previous syntactic sugars (as well as new ones), there is `SugarGremlinPlugin` (a.k.a Gremlin-Groovy-Sugar). IMPORTANT: It is important that the sugar plugin is loaded in a Gremlin Console session prior to any manipulations of -the respective TinkerPop3 objects as Groovy will cache unavailable methods and properties. +the respective TinkerPop objects as Groovy will cache unavailable methods and properties. [source,groovy] ---- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/reference/implementations-hadoop-start.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/implementations-hadoop-start.asciidoc b/docs/src/reference/implementations-hadoop-start.asciidoc index 8825009..4dcd13b 100644 --- a/docs/src/reference/implementations-hadoop-start.asciidoc +++ b/docs/src/reference/implementations-hadoop-start.asciidoc @@ -28,8 +28,8 @@ limitations under the License. image:hadoop-logo-notext.png[width=100,float=left] link:http://hadoop.apache.org/[Hadoop] is a distributed computing framework that is used to process data represented across a multi-machine compute cluster. When the -data in the Hadoop cluster represents a TinkerPop3 graph, then Hadoop-Gremlin can be used to process the graph -using both TinkerPop3's OLTP and OLAP graph computing models. +data in the Hadoop cluster represents a TinkerPop graph, then Hadoop-Gremlin can be used to process the graph +using both TinkerPop's OLTP and OLAP graph computing models. IMPORTANT: This section assumes that the user has a Hadoop 2.x cluster functioning. For more information on getting started with Hadoop, please see the @@ -160,10 +160,10 @@ image:hadoop-furnace.png[width=180,float=left] Hadoop-Gremlin was designed to ex `GraphComputer`. The OLTP examples presented previously are reproduced below, but using `TraversalVertexProgram` for the execution of the Gremlin traversal. -A `Graph` in TinkerPop3 can support any number of `GraphComputer` implementations. Out of the box, Hadoop-Gremlin +A `Graph` in TinkerPop can support any number of `GraphComputer` implementations. Out of the box, Hadoop-Gremlin supports the following two implementations. -* <<sparkgraphcomputer,`SparkGraphComputer`>>: Leverages Apache Spark to execute TinkerPop3 OLAP computations. +* <<sparkgraphcomputer,`SparkGraphComputer`>>: Leverages Apache Spark to execute TinkerPop OLAP computations. ** The graph may fit within the total RAM of the cluster (supports larger graphs). Message passing is coordinated via Spark map/reduce/join operations on in-memory and disk-cached data (average speed traversals). http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/reference/implementations-neo4j.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/implementations-neo4j.asciidoc b/docs/src/reference/implementations-neo4j.asciidoc index 1d156b3..c4541f4 100644 --- a/docs/src/reference/implementations-neo4j.asciidoc +++ b/docs/src/reference/implementations-neo4j.asciidoc @@ -62,7 +62,7 @@ configuration file must be edited to include the `Neo4jGremlinPlugin` as shown i === Indices -Neo4j 2.x indices leverage vertex labels to partition the index space. TinkerPop3 does not provide method interfaces +Neo4j 2.x indices leverage vertex labels to partition the index space. TinkerPop does not provide method interfaces for defining schemas/indices for the underlying graph system. Thus, in order to create indices, it is important to call the Neo4j API directly. @@ -175,7 +175,7 @@ by simply placing the Cypher string in `graph.cypher(...)` before submission to === Multi-Label -TinkerPop3 requires every `Element` to have a single, immutable string label (i.e. a `Vertex`, `Edge`, and +TinkerPop requires every `Element` to have a single, immutable string label (i.e. a `Vertex`, `Edge`, and `VertexProperty`). In Neo4j, a `Node` (vertex) can have an link:http://neo4j.com/docs/developer-manual/current/#graphdb-neo4j-labels[arbitrary number of labels] while a `Relationship` (edge) can have one and only one. Furthermore, in Neo4j, `Node` labels are mutable while `Relationship` labels are http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/reference/implementations-tinkergraph.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/implementations-tinkergraph.asciidoc b/docs/src/reference/implementations-tinkergraph.asciidoc index b6b5bf4..5b04126 100644 --- a/docs/src/reference/implementations-tinkergraph.asciidoc +++ b/docs/src/reference/implementations-tinkergraph.asciidoc @@ -28,8 +28,8 @@ limitations under the License. image:tinkerpop-character.png[width=100,float=left] TinkerGraph is a single machine, in-memory (with optional persistence), non-transactional graph engine that provides both OLTP and OLAP functionality. It is deployed with -TinkerPop3 and serves as the reference implementation for other providers to study in order to understand the -semantics of the various methods of the TinkerPop3 API. Its status as a reference implementation does not however imply +TinkerPop and serves as the reference implementation for other providers to study in order to understand the +semantics of the various methods of the TinkerPop API. Its status as a reference implementation does not however imply that it is not suitable for production. TinkerGraph has many practical use cases in production applications and their development. Some examples of TinkerGraph use cases include: @@ -102,7 +102,7 @@ clock(1000){g.V().has('name','Garcia').iterate()} <2> <1> Determine the average runtime of 1000 vertex lookups when no `name`-index is defined. <2> Determine the average runtime of 1000 vertex lookups when a `name`-index is defined. -IMPORTANT: Each graph system will have different mechanism by which indices and schemas are defined. TinkerPop3 +IMPORTANT: Each graph system will have different mechanism by which indices and schemas are defined. TinkerPop does not require any conformance in this area. In TinkerGraph, the only definitions are around indices. With other graph systems, property value types, indices, edge labels, etc. may be required to be defined _a priori_ to adding data to the graph. http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/reference/intro.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/intro.asciidoc b/docs/src/reference/intro.asciidoc index 890034d..cc81c90 100644 --- a/docs/src/reference/intro.asciidoc +++ b/docs/src/reference/intro.asciidoc @@ -35,9 +35,7 @@ called "TinkerPop Modern" as it is a modern variation of the original demo graph in 2009 (i.e. the good ol' days -- it was the best of times and it was the worst of times). TIP: The TinkerPop graph is available with <<tinkergraph-gremlin,TinkerGraph>> via `TinkerFactory.createModern()`. -TinkerGraph is the reference implementation of TinkerPop3 and is used in nearly all the examples in this documentation. -Note that there also exists the classic `TinkerFactory.createClassic()` which is the graph used in TinkerPop2 and does -not include vertex labels. +TinkerGraph is the reference implementation of TinkerPop and is used in nearly all the examples in this documentation. TIP: All of the toy graphs available in TinkerPop are described in link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/the-gremlin-console/#toy-graphs[The Gremlin Console] tutorial. @@ -46,7 +44,7 @@ link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/the-gremlin-console/#toy-g .TinkerPop Modern image::tinkerpop-modern.png[width=500] -TinkerPop3 is the third incarnation of the TinkerPop graph computing framework. Similar to computing in general, graph +TinkerPop 3.x is the third incarnation of the TinkerPop graph computing framework. Similar to computing in general, graph computing makes a distinction between *structure* (graph) and *process* (traversal). The structure of the graph is the data model defined by a vertex/edge/property link:http://en.wikipedia.org/wiki/Network_topology[topology]. The process of the graph is the means by which the structure is analyzed. The typical form of graph processing is called a @@ -58,7 +56,7 @@ who are utilizing a graph system from a graph provider. While the components of they are described in greater detail in the link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/gremlins-anatomy/[Gremlin's Anatomy] tutorial. -.Primary components of the TinkerPop3 *structure* API +.Primary components of the TinkerPop *structure* API * `Graph`: maintains a set of vertices and edges, and access to database functions such as transactions. * `Element`: maintains a collection of properties and a string label denoting the element type. ** `Vertex`: extends Element and maintains a set of incoming and outgoing edges. @@ -66,7 +64,7 @@ tutorial. * `Property<V>`: a string key associated with a `V` value. ** `VertexProperty<V>`: a string key associated with a `V` value as well as a collection of `Property<U>` properties (*vertices only*) -.Primary components of the TinkerPop3 *process* API +.Primary components of the TinkerPop *process* API * `TraversalSource`: a generator of traversals for a particular graph, link:http://en.wikipedia.org/wiki/Domain-specific_language[domain specific language] (DSL), and execution engine. ** `Traversal<S,E>`: a functional data flow process transforming objects of type `S` into object of type `E`. *** `GraphTraversal`: a traversal DSL that is oriented towards the semantics of the raw graph (i.e. vertices, edges, etc.). @@ -74,20 +72,20 @@ tutorial. ** `VertexProgram`: code executed at all vertices in a logically parallel manner with intercommunication via message passing. ** `MapReduce`: a computations that analyzes all vertices in the graph in parallel and yields a single reduced result. -IMPORTANT: TinkerPop3 is licensed under the popular link:http://www.apache.org/licenses/LICENSE-2.0.html[Apache2] -free software license. However, note that the underlying graph engine used with TinkerPop3 may have a different +IMPORTANT: TinkerPop is licensed under the popular link:http://www.apache.org/licenses/LICENSE-2.0.html[Apache2] +free software license. However, note that the underlying graph engine used with TinkerPop may have a different license. Thus, be sure to respect the license caveats of the graph system product. -image:tinkerpop-enabled.png[width=135,float=left] When a graph system implements the TinkerPop3 structure and process +image:tinkerpop-enabled.png[width=135,float=left] When a graph system implements the TinkerPop structure and process link:http://en.wikipedia.org/wiki/Application_programming_interface[APIs], their technology is considered -_TinkerPop3-enabled_ and becomes nearly indistinguishable from any other TinkerPop-enabled graph system save for +_TinkerPop-enabled_ and becomes nearly indistinguishable from any other TinkerPop-enabled graph system save for their respective time and space complexity. The purpose of this documentation is to describe the structure/process -dichotomy at length and in doing so, explain how to leverage TinkerPop3 for the sole purpose of graph system-agnostic +dichotomy at length and in doing so, explain how to leverage TinkerPop for the sole purpose of graph system-agnostic graph computing. Before deep-diving into the various structure/process APIs, a short introductory review of both APIs is provided. -NOTE: The TinkerPop3 API rides a fine line between providing concise "query language" method names and respecting -Java method naming standards. The general convention used throughout TinkerPop3 is that if a method is "user exposed," +NOTE: The TinkerPop API rides a fine line between providing concise "query language" method names and respecting +Java method naming standards. The general convention used throughout TinkerPop is that if a method is "user exposed," then a concise name is provided (e.g. `out()`, `path()`, `repeat()`). If the method is primarily for graph systems providers, then the standard Java naming convention is followed (e.g. `getNextStep()`, `getSteps()`, `getElementComputeKeys()`). @@ -107,7 +105,7 @@ more about it in the link:http://tinkerpop.apache.org/docs/x.y.z/dev/provider/[G == The Graph Process image:gremlin-running.png[width=125,float=left] The primary way in which graphs are processed are via graph -traversals. The TinkerPop3 process API is focused on allowing users to create graph traversals in a +traversals. The TinkerPop process API is focused on allowing users to create graph traversals in a syntactically-friendly way over the structures defined in the previous section. A traversal is an algorithmic walk across the elements of a graph according to the referential structure explicit within the graph data structure. For example: _"What software does vertex 1's friends work on?"_ This English-statement can be represented in the @@ -191,8 +189,8 @@ out of the right of the traversal (e.g. "vadas" and "josh"). image::traversal-mechanics.png[width=500] -In TinkerPop3, the objects propagating through the traversal are wrapped in a `Traverser<T>`. The traverser concept -is new to TinkerPop3 and provides the means by which steps remain stateless. A traverser maintains all the metadata +In TinkerPop, the objects propagating through the traversal are wrapped in a `Traverser<T>`. The traverser concept +is new to TinkerPop and provides the means by which steps remain stateless. A traverser maintains all the metadata about the traversal -- e.g., how many times the traverser has gone through a loop, the path history of the traverser, the current object being traversed, etc. Traverser metadata may be accessed by a step. A classic example is the <<path-step,`path()`>>-step. @@ -215,13 +213,13 @@ g.V(marko).repeat(out()).times(2).values('name') ---- WARNING: A Traversal's result are never ordered unless explicitly by means of <<order-step,`order()`>>-step. Thus, -never rely on the iteration order between TinkerPop3 releases and even within a release (as traversal optimizations +never rely on the iteration order between TinkerPop releases and even within a release (as traversal optimizations may alter the flow). == On Gremlin Language Variants Gremlin is written in Java 8. There are various language variants of Gremlin such as Gremlin-Groovy (packaged with -TinkerPop3), Gremlin-Python (packaged with TinkerPop3), link:https://github.com/mpollmeier/gremlin-scala[Gremlin-Scala], +TinkerPop), Gremlin-Python (packaged with TinkerPop), link:https://github.com/mpollmeier/gremlin-scala[Gremlin-Scala], Gremlin-JavaScript, Gremlin-Clojure (known as link:https://github.com/clojurewerkz/ogre[Ogre]), etc. It is best to think of Gremlin as a style of graph traversing that is not bound to a particular programming language per se. Within a programming language familiar to the developer, there is a Gremlin variant that they can use that leverages @@ -232,7 +230,7 @@ variants wishes to offer arbitrary computations beyond the provided Gremlin step Throughout the documentation, the examples provided are primarily written in Gremlin-Groovy. The reason for this is the <<gremlin-console,Gremlin Console>> -- an interactive programming environment exists that does not require -code compilation. For learning TinkerPop3 and interacting with a live graph system in an ad hoc manner, the Gremlin +code compilation. For learning TinkerPop and interacting with a live graph system in an ad hoc manner, the Gremlin Console is invaluable. However, for developers interested in working with Gremlin-Java, a few Groovy-to-Java patterns are presented below. @@ -264,7 +262,7 @@ Please see the <<gremlin-variants, Gremlin Variants>> section for more informati == Graph System Integration image:provider-integration.png[width=395,float=right] TinkerPop is a framework composed of various interoperable -components. At the foundation there is the <<graph,core TinkerPop3 API>> which defines what a `Graph`, `Vertex`, +components. At the foundation there is the <<graph,core TinkerPop API>> which defines what a `Graph`, `Vertex`, `Edge`, etc. are. At minimum a graph system provider must implement the core API. Once implemented, the Gremlin <<traversal,traversal language>> is available to the graph system's users. However, the provider can go further and develop specific <<traversalstrategy,`TraversalStrategy`>> optimizations that allow the graph system to inspect a http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/reference/preface.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/preface.asciidoc b/docs/src/reference/preface.asciidoc index f54e168..4776a75 100644 --- a/docs/src/reference/preface.asciidoc +++ b/docs/src/reference/preface.asciidoc @@ -15,7 +15,7 @@ See the License for the specific language governing permissions and limitations under the License. //// [[preface]] -= TinkerPop3 Documentation += TinkerPop Documentation In the beginning... @@ -74,7 +74,7 @@ The machines, simply moving algorithmically through Gremlin's world, endorsed hi more efficient, more expressive, better capable of reasoning upon his thoughts. Faster, quickly, now towards the world's end, where there would be forever currently, emanatingly engulfing that which is -- The TinkerPop. -== TinkerPop3 +== TinkerPop image::tinkerpop3-splash.png[width=450] @@ -86,7 +86,5 @@ realized realizations are just as real. For that is -- The TinkerPop. image::gremlintron.png[width=400] -NOTE: TinkerPop2 and below made a sharp distinction between the various TinkerPop projects: Blueprints, Pipes, -Gremlin, Frames, Furnace, and Rexster. With TinkerPop3, all of these projects have been merged and are generally -known as Gremlin. *Blueprints* -> Gremlin Structure API : *Pipes* -> `GraphTraversal` : *Frames* -> `Traversal` : -*Furnace* -> `GraphComputer` and `VertexProgram` : *Rexster* -> GremlinServer. +NOTE: For more information about differences between TinkerPop 3.x and earlier versions, please see the +link:http://tinkerpop.apache.org/docs/x.y.z/upgrade/#appendix http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/reference/the-graph.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/the-graph.asciidoc b/docs/src/reference/the-graph.asciidoc index cc500af..b735c81 100644 --- a/docs/src/reference/the-graph.asciidoc +++ b/docs/src/reference/the-graph.asciidoc @@ -53,7 +53,7 @@ against a `Feature` may not always reflect the behavior exhibited when the `Grap [[vertex-properties]] == Vertex Properties -image:vertex-properties.png[width=215,float=left] TinkerPop3 introduces the concept of a `VertexProperty<V>`. All the +image:vertex-properties.png[width=215,float=left] TinkerPop introduces the concept of a `VertexProperty<V>`. All the properties of a `Vertex` are a `VertexProperty`. A `VertexProperty` implements `Property` and as such, it has a key/value pair. However, `VertexProperty` also implements `Element` and thus, can have a collection of key/value pairs. Moreover, while an `Edge` can only have one property of key "name" (for example), a `Vertex` can have multiple @@ -120,7 +120,7 @@ represent the literal vertex's properties. The "literal vertex" can not have any associated vertex). [[the-crew-toy-graph]] -TIP: A toy graph demonstrating all of the new TinkerPop3 graph structure features is available at +TIP: A toy graph demonstrating all of the new TinkerPop graph structure features is available at `TinkerFactory.createTheCrew()` and `data/tinkerpop-crew*`. This graph demonstrates multi-properties and meta-properties. .TinkerPop Crew @@ -140,9 +140,8 @@ g.V().has('name','gremlin').inE('uses'). == Graph Variables -TinkerPop3 introduces the concept of `Graph.Variables`. Variables are key/value pairs associated with the graph -itself -- in essence, a `Map<String,Object>`. These variables are intended to store metadata about the graph. Example -use cases include: +`Graph.Variables` are key/value pairs associated with the graph itself -- in essence, a `Map<String,Object>`. These +variables are intended to store metadata about the graph. Example use cases include: * *Schema information*: What do the namespace prefixes resolve to and when was the schema last modified? * *Global permissions*: What are the access rights for particular groups? @@ -426,37 +425,14 @@ try (final InputStream stream = new FileInputStream("tinkerpop-modern.xml")) { } ---- -GraphML was a supported format in TinkerPop 2.x, but there were several issues that made it inconsistent with the -specification that were corrected for 3.x. As a result, attempting to read a GraphML file generated by 2.x with the -3.x `GraphMLReader` will result in error. To help with this problem, an XSLT file is provided as a resource in -`gremlin-core` which will transform 2.x GraphML to 3.x GraphML. It can be used as follows: - -[source,java] ----- -import javax.xml.parsers.DocumentBuilderFactory; -import javax.xml.transform.TransformerFactory; -import javax.xml.transform.dom.DOMSource; -import javax.xml.transform.stream.StreamSource; -import javax.xml.transform.stream.StreamResult; - -InputStream stylesheet = Thread.currentThread().getContextClassLoader().getResourceAsStream("tp2-to-tp3-graphml.xslt"); -File datafile = new File('/tmp/tp2-graphml.xml'); -File outfile = new File('/tmp/tp3-graphml.xml'); - -TransformerFactory tFactory = TransformerFactory.newInstance(); -StreamSource stylesource = new StreamSource(stylesheet); -Transformer transformer = tFactory.newTransformer(stylesource); - -StreamSource source = new StreamSource(datafile); -StreamResult result = new StreamResult(new FileWriter(outfile)); -transformer.transform(source, result); ----- +NOTE: If using GraphML generated from TinkerPop 2.x, you can read more about its incompatibilities in the +link:http://tinkerpop.apache.org/docs/x.y.z/upgrade/#graphml-format[Upgrade Documentation]. [[graphson-reader-writer]] === GraphSON Reader/Writer image:gremlin-graphson.png[width=350,float=left] GraphSON is a link:http://json.org/[JSON]-based format extended -from earlier versions of TinkerPop. It is important to note that TinkerPop3's GraphSON is not backwards compatible +from earlier versions of TinkerPop. It is important to note that TinkerPop's GraphSON is not backwards compatible with prior TinkerPop GraphSON versions. GraphSON has some support from graph-related application outside of TinkerPop, but it is generally best used in two cases: @@ -736,56 +712,8 @@ try (final InputStream stream = new FileInputStream("tinkerpop-modern.kryo")) { NOTE: The preferred extension for files names produced by Gryo is `.kryo`. -=== TinkerPop2 Data Migration - -image:data-migration.png[width=300,float=right] For those using TinkerPop2, migrating to TinkerPop3 will mean a number -of programming changes, but may also require a migration of the data depending on the graph implementation. For -example, trying to open `TinkerGraph` data from TinkerPop2 with TinkerPop3 code will not work, however opening a -TinkerPop2 `Neo4jGraph` with a TinkerPop3 `Neo4jGraph` should work provided there aren't Neo4j version compatibility -mismatches preventing the read. - -If such a situation arises that a particular TinkerPop2 `Graph` can not be read by TinkerPop3, a "legacy" data -migration approach exists. The migration involves writing the TinkerPop2 `Graph` to GraphSON, then reading it to -TinkerPop3 with the `LegacyGraphSONReader` (a limited implementation of the `GraphReader` interface). - -The following represents an example migration of the "classic" toy graph. In this example, the "classic" graph is -saved to GraphSON using TinkerPop2. - -[source,groovy] ----- -gremlin> Gremlin.version() -==>2.5.z -gremlin> graph = TinkerGraphFactory.createTinkerGraph() -==>tinkergraph[vertices:6 edges:6] -gremlin> GraphSONWriter.outputGraph(graph,'/tmp/tp2.json',GraphSONMode.EXTENDED) -==>null ----- - -The above console session uses the `gremlin-groovy` distribution from TinkerPop2. It is important to generate the -`tp2.json` file using the `EXTENDED` mode as it will include data types when necessary which will help limit -"lossiness" on the TinkerPop3 side when imported. Once `tp2.json` is created, it can then be imported to a TinkerPop3 -`Graph`. - -[source,groovy] ----- -gremlin> Gremlin.version() -==>x.y.z -gremlin> graph = TinkerGraph.open() -==>tinkergraph[vertices:0 edges:0] -gremlin> r = LegacyGraphSONReader.build().create() -==>org.apache.tinkerpop.gremlin.structure.io.graphson.LegacyGraphSONReader@64337702 -gremlin> r.readGraph(new FileInputStream('/tmp/tp2.json'), graph) -==>null -gremlin> g = graph.traversal() -==>graphtraversalsource[tinkergraph[vertices:6 edges:6], standard] -gremlin> g.E() -==>e[11][4-created->3] -==>e[12][6-created->3] -==>e[7][1-knows->2] -==>e[8][1-knows->4] -==>e[9][1-created->3] -==>e[10][4-created->5] ----- +NOTE: Data migrations from TinkerPop 2.x are discussed in the Appendix of the +link:http://tinkerpop.apache.org/docs/x.y.z/upgrade/#appendix[Upgrade Documentation]. == Namespace Conventions http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/reference/the-graphcomputer.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/the-graphcomputer.asciidoc b/docs/src/reference/the-graphcomputer.asciidoc index af599eb..4bf39d0 100644 --- a/docs/src/reference/the-graphcomputer.asciidoc +++ b/docs/src/reference/the-graphcomputer.asciidoc @@ -17,7 +17,7 @@ limitations under the License. [[graphcomputer]] = The GraphComputer -image:graphcomputer-puffers.png[width=350,float=right] TinkerPop3 provides two primary means of interacting with a +image:graphcomputer-puffers.png[width=350,float=right] TinkerPop provides two primary means of interacting with a graph: link:http://en.wikipedia.org/wiki/Online_transaction_processing[online transaction processing] (OLTP) and link:http://en.wikipedia.org/wiki/Online_analytical_processing[online analytical processing] (OLAP). OLTP-based graph systems allow the user to query the graph in real-time. However, typically, real-time performance is only @@ -39,7 +39,7 @@ walked by moving from vertex-to-vertex via incident edges. With Gremlin OLAP, al `VertexProgram`. The programs send messages to one another with the topological structure of the graph acting as the communication network (though random message passing possible). In many respects, the messages passed are like the OLTP traversers moving from vertex-to-vertex. However, all messages are moving independent of one another, in -parallel. Once a vertex program is finished computing, TinkerPop3's OLAP engine supports any number +parallel. Once a vertex program is finished computing, TinkerPop's OLAP engine supports any number link:http://en.wikipedia.org/wiki/MapReduce[`MapReduce`] jobs over the resultant graph. IMPORTANT: `GraphComputer` was designed from the start to be used within a multi-JVM, distributed environment -- @@ -87,7 +87,7 @@ g.V().valueMap() NOTE: This model of "vertex-centric graph computing" was made popular by Google's link:http://googleresearch.blogspot.com/2009/06/large-scale-graph-computing-at-google.html[Pregel] graph engine. In the open source world, this model is found in OLAP graph computing systems such as link:https://giraph.apache.org/[Giraph], -link:https://hama.apache.org/[Hama]. TinkerPop3 extends the +link:https://hama.apache.org/[Hama]. TinkerPop extends the popularized model with integrated post-processing <<mapreduce,MapReduce>> jobs over the vertex set. [[mapreduce]] @@ -97,7 +97,7 @@ The BSP model proposed by Pregel stores the results of the computation in a dist elements in the graph. In many situations, it is necessary to aggregate those resultant properties into a single result set (i.e. a statistic). For instance, assume a VertexProgram that computes a nominal cluster for each vertex (i.e. link:http://en.wikipedia.org/wiki/Community_structure[a graph clustering algorithm]). At the end of the -computation, each vertex will have a property denoting the cluster it was assigned to. TinkerPop3 provides the +computation, each vertex will have a property denoting the cluster it was assigned to. TinkerPop provides the ability to answer global questions about the clusters. For instance, in order to answer the following questions, `MapReduce` jobs are required: @@ -106,7 +106,7 @@ ability to answer global questions about the clusters. For instance, in order to * What is the average age of each vertex in each cluster? * What is the degree distribution of the vertices in each cluster? -A compressed representation of the `MapReduce` API in TinkerPop3 is provided below. The key idea is that the +A compressed representation of the `MapReduce` API in TinkerPop is provided below. The key idea is that the `map`-stage processes all vertices to emit key/value pairs. Those values are aggregated on their respective key for the `reduce`-stage to do its processing to ultimately yield more key/value pairs. @@ -155,14 +155,15 @@ result.memory().clusterPopulation result.memory().clusterCount ---- -IMPORTANT: The MapReduce model of TinkerPop3 does not support MapReduce chaining. Thus, the order in which the +IMPORTANT: The MapReduce model of TinkerPop does not support MapReduce chaining. Thus, the order in which the MapReduce jobs are executed is irrelevant. This is made apparent when realizing that the `map()`-stage takes a `Vertex` as its input and the `reduce()`-stage yields key/value pairs. Thus, the results of reduce can not fed back into a `map()`. == A Collection of VertexPrograms -TinkerPop3 provides a collection of VertexPrograms that implement common algorithms. This section discusses the various implementations. +TinkerPop provides a collection of VertexPrograms that implement common algorithms. This section discusses the various +implementations. IMPORTANT: The vertex programs presented are what are provided as of TinkerPop x.y.z. Over time, with future releases, more algorithms will be added. @@ -416,7 +417,7 @@ is provided in the SparkGraphComputer section. image:batch-graph.png[width=220,float=left] The `BulkLoaderVertexProgram` provides a generalized way for loading graphs of any size into a persistent `Graph`. It is especially useful for large graphs (i.e. hundreds of millions or billions of edges) as it can take advantage of the parallel processing offered by `GraphComputer` instances. The -input can be any existing `Graph` database supporting TinkerPop3 or any of the Hadoop GraphInputFormats (e.g. +input can be any existing `Graph` database supporting TinkerPop or any of the Hadoop GraphInputFormats (e.g. `GraphSONInputFormat`, `GryoInputFormat` or `ScriptInputFormat`). The following example demonstrates how to load data from one TinkerGraph to another: http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/reference/the-traversal.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc index 0132eab..d61da37 100644 --- a/docs/src/reference/the-traversal.asciidoc +++ b/docs/src/reference/the-traversal.asciidoc @@ -44,7 +44,7 @@ image::step-types.png[width=650] A `GraphTraversal<S,E>` is spawned from a `GraphTraversalSource`. It can also be spawned anonymously (i.e. empty) via `__`. A graph traversal is composed of an ordered list of steps. All the steps provided by `GraphTraversal` inherit from the more general forms diagrammed above. A list of all the steps (and their descriptions) are provided -in the TinkerPop3 link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html[GraphTraversal JavaDoc]. +in the TinkerPop link:http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html[GraphTraversal JavaDoc]. The following subsections will demonstrate the GraphTraversal steps using the <<gremlin-console,Gremlin Console>>. IMPORTANT: The basics for starting a traversal are described in <<the-graph-process,The Graph Process>> section as @@ -1024,8 +1024,8 @@ link:++http://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/grem image::inject-step.png[width=800] -One of the major features of TinkerPop3 is "injectable steps." This makes it possible to insert objects arbitrarily -into a traversal stream. In general, `inject()`-step (*sideEffect*) exists and a few examples are provided below. +The concept of "injectable steps" makes it possible to insert objects arbitrarily into a traversal stream. In general, +`inject()`-step (*sideEffect*) exists and a few examples are provided below. [gremlin-groovy,modern] ---- @@ -2809,7 +2809,7 @@ g.E().valueMap() ---- It is important to note that the map of a vertex maintains a list of values for each key. The map of an edge or -vertex-property represents a single property (not a list). The reason is that vertices in TinkerPop3 leverage +vertex-property represents a single property (not a list). The reason is that vertices in TinkerPop leverage <<vertex-properties,vertex properties>> which are support multiple values per key. Using the <<the-crew-toy-graph, "The Crew">> toy graph, the point is made explicit. @@ -2961,7 +2961,7 @@ g.V().as('a').out('knows').as('b'). WARNING: The anonymous traversal of `where()` processes the current object "locally". In OLAP, where the atomic unit of computing is the vertex and its local "star graph," it is important that the anonymous traversal does not leave the confines of the vertex's star graph. In other words, it can not traverse to an adjacent vertex's properties or -edges. Note that is only a temporary limitation that will be addressed in a future version of TinkerPop3 (see +edges. Note that is only a temporary limitation that will be addressed in a future version of TinkerPop (see link:https://issues.apache.org/jira/browse/TINKERPOP-693[TINKERPOP-693]). *Additional References* @@ -3157,7 +3157,7 @@ meets its criteria, can mutate it accordingly. Traversal strategies are executed of the Gremlin traversal machine's compiler. There are 5 categories of strategies which are itemized below: * There is an application-level feature that can be embedded into the traversal logic (*decoration*). - * There is a more efficient way to express the traversal at the TinkerPop3 level (*optimization*). + * There is a more efficient way to express the traversal at the TinkerPop level (*optimization*). * There is a more efficient way to express the traversal at the graph system/language/driver level (*provider optimization*). * There are some final adjustments/cleanups/analyses required before executing the traversal (*finalization*). * There are certain traversals that are not legal for the application or traversal engine (*verification*). @@ -3257,7 +3257,7 @@ public final class TinkerGraphStepStrategy extends AbstractTraversalStrategy<Tra The traversal is redefined by simply taking a chain of `has()`-steps after `g.V()` (`TinkerGraphStep`) and providing their `HasContainers` to `TinkerGraphStep`. Then its up to `TinkerGraphStep` to determine if an appropriate index exists. -Given that the strategy uses non-TinkerPop3 provided steps, it should go into the `ProviderOptimizationStrategy` category +Given that the strategy uses non-TinkerPop provided steps, it should go into the `ProviderOptimizationStrategy` category to ensure the added step does not interfere with the assumptions of the `OptimizationStrategy` strategies. [gremlin-groovy,modern] @@ -3269,11 +3269,11 @@ t.toString() ---- WARNING: The reason that `OptimizationStrategy` and `ProviderOptimizationStrategy` are two different categories is -that optimization strategies should only rewrite the traversal using TinkerPop3 steps. This ensures that the -optimizations executed at the end of the optimization strategy round are TinkerPop3 compliant. From there, provider +that optimization strategies should only rewrite the traversal using TinkerPop steps. This ensures that the +optimizations executed at the end of the optimization strategy round are TinkerPop compliant. From there, provider optimizations can analyze the traversal and rewrite the traversal as desired using graph system specific steps (e.g. replacing `GraphStep.HasStep...HasStep` with `TinkerGraphStep`). If provider optimizations use graph system specific -steps and implement `OptimizationStrategy`, then other TinkerPop3 optimizations may fail to optimize the traversal or +steps and implement `OptimizationStrategy`, then other TinkerPop optimizations may fail to optimize the traversal or mis-understand the graph system specific step behaviors (e.g. `ProviderVertexStep extends VertexStep`) and yield incorrect semantics. @@ -3305,7 +3305,7 @@ g.V().hasLabel('person'). <1> <8> `PathRetractionStrategy` will remove paths from the traversers and increase the likelihood of bulking as path data is not required after `select('b')`. <9> `AdjacentToIncidentStrategy` will turn `out()` into `outE()` to increase data access locality. -A collection of useful `DecorationStrategy` strategies are provided with TinkerPop3 and are generally useful to +A collection of useful `DecorationStrategy` strategies are provided with TinkerPop and are generally useful to end-users. The following sub-sections detail these strategies: === ElementIdStrategy http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/tutorials/the-gremlin-console/index.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/tutorials/the-gremlin-console/index.asciidoc b/docs/src/tutorials/the-gremlin-console/index.asciidoc index da8bac3..c1602e4 100644 --- a/docs/src/tutorials/the-gremlin-console/index.asciidoc +++ b/docs/src/tutorials/the-gremlin-console/index.asciidoc @@ -98,8 +98,8 @@ for all TinkerPop examples and test cases. * `createModern()` - The TinkerPop 3.x representation of the "classic" graph, where the main difference is that vertex labels are defined and the "weight" edge property is a `double` rather than a `float` (link:http://tinkerpop.apache.org/docs/x.y.z/images/tinkerpop-modern.png[diagram]). -* `createTheCrew()` - A graph that demonstrates usage of the new structural features of TinkerPop 3.x (as compared to -2.x) such as link:http://tinkerpop.apache.org/docs/x.y.z/reference/#vertex-properties[vertex properties and multi-properties] +* `createTheCrew()` - A graph that demonstrates usage of the new structural features of TinkerPop 3.x such as +link:http://tinkerpop.apache.org/docs/x.y.z/reference/#vertex-properties[vertex meta-properties and multi-properties] (link:http://tinkerpop.apache.org/docs/x.y.z/images/the-crew-graph.png[diagram]). [gremlin-groovy] http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/upgrade/appendix.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/upgrade/appendix.asciidoc b/docs/src/upgrade/appendix.asciidoc new file mode 100644 index 0000000..a9df0e4 --- /dev/null +++ b/docs/src/upgrade/appendix.asciidoc @@ -0,0 +1,113 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +//// + +[[appendix]] += Appendix + +== TinkerPop 2.x + +This section contains a few notes that reference differences between TinkerPop 2.x and 3.x. + +One of the major differences between TinkerPop 2.x and TinkerPop 3.x is that in TinkerPop 3.x, the Java convention of +using setters and getters was abandoned in favor of a syntax that is more aligned with the syntax of Gremlin-Groovy in +TinkerPop2. Given that Gremlin-Java8 and Gremlin-Groovy are nearly identical due to the inclusion of Java 8 lambdas, a +big effort was made to ensure that both languages were as similar as possible. + +In addition, TinkerPop2 and below made a sharp distinction between the various TinkerPop projects: Blueprints, Pipes, +Gremlin, Frames, Furnace, and Rexster. With TinkerPop 3.x, all of these projects have been merged and are generally +known as Gremlin. *Blueprints* -> Gremlin Structure API : *Pipes* -> `GraphTraversal` : *Frames* -> `Traversal` : +*Furnace* -> `GraphComputer` and `VertexProgram` : *Rexster* -> GremlinServer. + +[[graphml-format]] +=== GraphML Format + +GraphML was a supported format in TinkerPop 2.x, but there were several issues that made it inconsistent with the +specification that were corrected for 3.x. As a result, attempting to read a GraphML file generated by 2.x with the +3.x `GraphMLReader` will result in error. To help with this problem, an XSLT file is provided as a resource in +`gremlin-core` which will transform 2.x GraphML to 3.x GraphML. It can be used as follows: + +[source,java] +---- +import javax.xml.parsers.DocumentBuilderFactory; +import javax.xml.transform.TransformerFactory; +import javax.xml.transform.dom.DOMSource; +import javax.xml.transform.stream.StreamSource; +import javax.xml.transform.stream.StreamResult; + +InputStream stylesheet = Thread.currentThread().getContextClassLoader().getResourceAsStream("tp2-to-tp3-graphml.xslt"); +File datafile = new File('/tmp/tp2-graphml.xml'); +File outfile = new File('/tmp/tp3-graphml.xml'); + +TransformerFactory tFactory = TransformerFactory.newInstance(); +StreamSource stylesource = new StreamSource(stylesheet); +Transformer transformer = tFactory.newTransformer(stylesource); + +StreamSource source = new StreamSource(datafile); +StreamResult result = new StreamResult(new FileWriter(outfile)); +transformer.transform(source, result); +---- + +=== TinkerPop2 Data Migration + +image:data-migration.png[width=300,float=right] For those using TinkerPop 2.x, migrating to TinkerPop 3.x will mean a +number of programming changes, but may also require a migration of the data depending on the graph implementation. For +example, trying to open `TinkerGraph` data from TinkerPop 2.x with TinkerPop 3.x code will not work, however opening a +TinkerPop2 `Neo4jGraph` with a TinkerPop 3.x `Neo4jGraph` should work provided there aren't Neo4j version compatibility +mismatches preventing the read. + +If such a situation arises that a particular TinkerPop 2.x `Graph` can not be read by TinkerPop 3.x, a "legacy" data +migration approach exists. The migration involves writing the TinkerPop2 `Graph` to GraphSON, then reading it to +TinkerPop 3.x with the `LegacyGraphSONReader` (a limited implementation of the `GraphReader` interface). + +The following represents an example migration of the "classic" toy graph. In this example, the "classic" graph is +saved to GraphSON using TinkerPop 2.x. + +[source,groovy] +---- +gremlin> Gremlin.version() +==>2.5.z +gremlin> graph = TinkerGraphFactory.createTinkerGraph() +==>tinkergraph[vertices:6 edges:6] +gremlin> GraphSONWriter.outputGraph(graph,'/tmp/tp2.json',GraphSONMode.EXTENDED) +==>null +---- + +The above console session uses the `gremlin-groovy` distribution from TinkerPop2. It is important to generate the +`tp2.json` file using the `EXTENDED` mode as it will include data types when necessary which will help limit +"lossiness" on the TinkerPop 3.x side when imported. Once `tp2.json` is created, it can then be imported to a +TinkerPop 3.x `Graph`. + +[source,groovy] +---- +gremlin> Gremlin.version() +==>x.y.z +gremlin> graph = TinkerGraph.open() +==>tinkergraph[vertices:0 edges:0] +gremlin> r = LegacyGraphSONReader.build().create() +==>org.apache.tinkerpop.gremlin.structure.io.graphson.LegacyGraphSONReader@64337702 +gremlin> r.readGraph(new FileInputStream('/tmp/tp2.json'), graph) +==>null +gremlin> g = graph.traversal() +==>graphtraversalsource[tinkergraph[vertices:6 edges:6], standard] +gremlin> g.E() +==>e[11][4-created->3] +==>e[12][6-created->3] +==>e[7][1-knows->2] +==>e[8][1-knows->4] +==>e[9][1-created->3] +==>e[10][4-created->5] +---- \ No newline at end of file http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/docs/src/upgrade/index.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/upgrade/index.asciidoc b/docs/src/upgrade/index.asciidoc index 670ce31..65a1c88 100644 --- a/docs/src/upgrade/index.asciidoc +++ b/docs/src/upgrade/index.asciidoc @@ -41,3 +41,5 @@ include::release-3.2.x-incubating.asciidoc[] include::release-3.1.x-incubating.asciidoc[] include::release-3.0.x-incubating.asciidoc[] + +include::appendix.asciidoc[] http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/gremlin-dotnet/src/Gremlin.Net/Process/Traversal/GraphTraversal.cs ---------------------------------------------------------------------- diff --git a/gremlin-dotnet/src/Gremlin.Net/Process/Traversal/GraphTraversal.cs b/gremlin-dotnet/src/Gremlin.Net/Process/Traversal/GraphTraversal.cs index 9952455..bb3d5d8 100644 --- a/gremlin-dotnet/src/Gremlin.Net/Process/Traversal/GraphTraversal.cs +++ b/gremlin-dotnet/src/Gremlin.Net/Process/Traversal/GraphTraversal.cs @@ -1676,5 +1676,14 @@ namespace Gremlin.Net.Process.Traversal return Wrap<S, E>(this); } + /// <summary> + /// Adds the with step to this <see cref="GraphTraversal{SType, EType}" />. + /// </summary> + public GraphTraversal<S, E> With (StepConfiguration modulation) + { + Bytecode.AddStep("with", modulation); + return Wrap<S, E>(this); + } + } } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/process/graph-traversal.js ---------------------------------------------------------------------- diff --git a/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/process/graph-traversal.js b/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/process/graph-traversal.js index edeb2cb..901f9b0 100644 --- a/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/process/graph-traversal.js +++ b/gremlin-javascript/src/main/javascript/gremlin-javascript/lib/process/graph-traversal.js @@ -1132,6 +1132,16 @@ class GraphTraversal extends Traversal { return this; } + /** + * Graph traversal with method. + * @param {...Object} args + * @returns {GraphTraversal} + */ + with(...args) { + this.bytecode.addStep('with', args); + return this; + } + } function callOnEmptyTraversal(fnName, args) { http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/849349af/gremlin-python/src/main/jython/gremlin_python/process/graph_traversal.py ---------------------------------------------------------------------- diff --git a/gremlin-python/src/main/jython/gremlin_python/process/graph_traversal.py b/gremlin-python/src/main/jython/gremlin_python/process/graph_traversal.py index d5630c0..a492f9c 100644 --- a/gremlin-python/src/main/jython/gremlin_python/process/graph_traversal.py +++ b/gremlin-python/src/main/jython/gremlin_python/process/graph_traversal.py @@ -505,6 +505,10 @@ class GraphTraversal(Traversal): self.bytecode.add_step("where", *args) return self + def with(self, *args): + self.bytecode.add_step("with", *args) + return self + class __(object): graph_traversal = GraphTraversal
