You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by ok...@apache.org on 2015/03/20 20:49:43 UTC
incubator-tinkerpop git commit: added AddVertex, fixed up AddEdge,
and added AddProperty to the docs.
Repository: incubator-tinkerpop
Updated Branches:
refs/heads/master 7b922831c -> 07e13a480
added AddVertex, fixed up AddEdge, and added AddProperty to the docs.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/commit/07e13a48
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/07e13a48
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/07e13a48
Branch: refs/heads/master
Commit: 07e13a4802e16d6c8e0a795b6a6fb639f953ccdb
Parents: 7b92283
Author: Marko A. Rodriguez <ok...@gmail.com>
Authored: Fri Mar 20 13:49:39 2015 -0600
Committer: Marko A. Rodriguez <ok...@gmail.com>
Committed: Fri Mar 20 13:49:39 2015 -0600
----------------------------------------------------------------------
docs/src/the-graph.asciidoc | 10 +++---
docs/src/the-traversal.asciidoc | 64 ++++++++++++++++++++++++++++++------
2 files changed, 59 insertions(+), 15 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/07e13a48/docs/src/the-graph.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/the-graph.asciidoc b/docs/src/the-graph.asciidoc
index 775903e..f08e77f 100644
--- a/docs/src/the-graph.asciidoc
+++ b/docs/src/the-graph.asciidoc
@@ -131,9 +131,6 @@ g.V().has('name','gremlin').inE('uses').
order().by('skill',incr).as('a').
outV().as('b').
select().by('skill').by('name') // rank the users of gremlin by their skill level
-graph.variables() // access the global graph variables
-graph.variables().get('creator')
-graph.variables().get('creator').get()
----
Graph Variables
@@ -145,7 +142,7 @@ TinkerPop3 introduces the concept of `Graph.Variables`. Variables are key/value
* *Global permissions*: What are the access rights for particular groups?
* *System user information*: Who are the admins of the system?
-An example of graph variables in use is presented below in Gremlin-Groovy:
+An example of graph variables in use is presented below:
[gremlin-groovy]
----
@@ -160,6 +157,8 @@ graph.variables().remove('systemAdmins')
graph.variables().keys()
----
+:IMPORTANT Graph variables are not intended to be subject to heavy, concurrent mutation nor to be used in complex computations. The intention is to have a location to store data about the graph for administrative purposes.
+
[[transactions]]
Graph Transactions
------------------
@@ -700,6 +699,7 @@ gremlin> r = LegacyGraphSONReader.build().create()
gremlin> r.readGraph(new FileInputStream('/tmp/tp2.json'),graph)
==>null
gremlin> g = graph.traversal(standard)
+==>graphtraversalsource[tinkergraph[vertices:6 edges:6], standard]
gremlin> g.E()
==>e[11][4-created->3]
==>e[12][6-created->3]
@@ -712,7 +712,7 @@ gremlin> g.E()
Namespace Conventions
---------------------
-End users, <<implementations,vendors>>, <<graphstrategy,strategy>> developers, <<graphcomputer,`GraphComputer`>> algorithm designers, <<gremlin-plugins,GremlinPlugin>> creators, etc. all leverages properties on elements to store information. There are a few conventions that should be respected when naming property keys to ensure that conflicts between these stakeholders do not conflict.
+End users, <<implementations,vendors>>, <<graphstrategy,strategy>> developers, <<graphcomputer,`GraphComputer`>> algorithm designers, <<gremlin-plugins,GremlinPlugin>> creators, etc. all leverage properties on elements to store information. There are a few conventions that should be respected when naming property keys to ensure that conflicts between these stakeholders do not conflict.
* End users are granted the _flat namespace_ (e.g. `name`, `age`, `location`) to key their properties and label their elements.
* Vendors are granted the _hidden namespace_ (e.g. `~metadata`) to to key their properties and labels. Data key'd as such is only accessible via the vendor implementation code and no other stakeholders are granted read nor write access to data prefixed with "~" (see `Graph.Hidden`). Test coverage and exceptions exist to ensure that vendors respect this hard boundary.
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/07e13a48/docs/src/the-traversal.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/the-traversal.asciidoc b/docs/src/the-traversal.asciidoc
index 720b0ed..5dad569 100644
--- a/docs/src/the-traversal.asciidoc
+++ b/docs/src/the-traversal.asciidoc
@@ -23,12 +23,14 @@ image::gremlin-running.png[width=125]
At the most general level there is `Traversal<S,E>` which implements `Iterator<E>`, where the `S` stands for start and the `E` stands for end. A traversal is composed of four primary components:
. `Step<S,E>`: an individual function applied to `S` to yield `E`. Steps are chained within a traversal.
- . `TraversalStrategy`: interceptor methods to alter the execution of the traversal (i.e. query re-writing typically used only by vendors).
+ . `TraversalStrategy`: interceptor methods to alter the execution of the traversal (e.g. query re-writing).
. `TraversalSideEffects`: key/value pairs that can be used to store global information about the traversal.
. `Traverser<T>`: the object propagating through the `Traversal` currently representing an object of type `T`.
The classic notion of a graph traversal is provided by `GraphTraversal<S,E>` which extends `Traversal<S,E>`. GraphTraversal provides an interpretation of the graph data in terms of vertices, edges, etc. and thus, a graph traversal link:http://en.wikipedia.org/wiki/Domain-specific_language[DSL].
+:IMPORTANT The underlying `Step` implementations provided by TinkerPop should encompass most of the functionality required by a DSL author. It is important that DSL authors leverage the provided steps as then the common optimization and decoration strategies can reason on the underlying traversal sequence. If new steps are introduced, then common traversal strategies may not function properly.
+
[[graph-traversal-steps]]
Graph Traversal Steps
---------------------
@@ -41,6 +43,8 @@ A `GraphTraversal<S,E>` can be spawned off of a Graph, Vertex, Edge, or VertexPr
Lambda Steps
~~~~~~~~~~~~
+CAUTION: Lambda steps are presented for educational purposes as they represent the foundational constructs of the Gremlin language. In practice, lambda steps should be avoided and traversal verification strategies exist to disallow their use unless explicitly "turned off." For more information on the problems with lambdas, please read <<a-note-on-lambdas,A Note on Lambdas>>.
+
There are four generic steps by which all other specific steps described later extend.
[width="100%",cols="10,12",options="header"]
@@ -64,8 +68,6 @@ The `Traverser<S>` object provides access to:
. The side-effects associated with the traversal -- `Traverser.sideEffects()`.
.. A helper shorthand to get a particular side-effect -- `Traverser.sideEffect(String) == Traverser.sideEffects().get(String)`.
-IMPORTANT: If a specific traversal step can do the necessary step-computation, use it. Lambda steps can not be optimized by the Gremlin <<traversalstrategy,traversal strategies>> and should only be used when the requisite computation does not have a corresponding standard Gremlin step. For example, instead of `filter{it.get().property('name').isPresent()}` use `has('name')`.
-
image:map-lambda.png[width=150,float=right]
[gremlin-groovy,modern]
----
@@ -115,24 +117,66 @@ g.V().choose(has('name','marko'),
AddEdge Step
~~~~~~~~~~~~
+It is possible to mutate the graph within a traversal. The typical mutations are adding/removing vertices, edges, and properties. To add edges, there are a collection of `addE()`-steps (*map*/*sideEffect*).
+
+[gremlin-groovy,modern]
+----
+g.V(1).addOutE('co-worker',g.V(2),'year',2009) <1>
+g.V(4).addInE('createdBy',g.V(3,5)) <2>
+g.V(1).addOutE('livesNear',g.V(2),'year',2009).inV().inE('livesNear').values('year') <3>
+g.V(1).out('livesNear')
+----
+
+<1> Add an outgoing co-worker edge from the marko-vertex to the vadas-vertex with a year property of value 2009.
+<2> Add incoming createdBy edges from the josh-vertex to the lop- and ripple-vertices.
+<3> The newly created edge is a traversable object.
+
image::addedge-step.png[width=450]
-link:http://en.wikipedia.org/wiki/Automated_reasoning[Reasoning] is the process of making explicit in the data was is implicit in the data. What is explicit in a graph are the objects of the graph -- i.e. vertices and edges. What is implicit in the graph is the traversal. In other words, traversals expose meaning where the meaning is defined by the traversal description. For example, take the concept of a "co-developer." Two people are co-developers if they have worked on the same project together. This concept can be represented as a traversal and thus, the concept of "co-developers" can be derived. This is made possible with `addE()`-step (*sideEffect*).
+link:http://en.wikipedia.org/wiki/Automated_reasoning[Reasoning] is the process of making explicit in the data was is implicit in the data. What is explicit in a graph are the objects of the graph -- i.e. vertices and edges. What is implicit in the graph is the traversal. In other words, traversals expose meaning where the meaning is defined by the traversal description. For example, take the concept of a "co-developer." Two people are co-developers if they have worked on the same project together. This concept can be represented as a traversal and thus, the concept of "co-developers" can be derived.
[gremlin-groovy,modern]
----
g.V(1).as('a').out('created')
g.V(1).as('a').out('created').in('created')
g.V(1).as('a').out('created').in('created').except('a') <1>
-g.V(1).as('a').out('created').in('created').except('a').addInE('co-developer','a')
+g.V(1).as('a').out('created').in('created').except('a').
+ addOutE('co-developer','a').outV().
+ addInE('co-developer','a')
g.V(1).out('co-developer').values('name')
-g.V(1).out('co-developer').in('co-developer')
+g.V(1).in('co-developer').values('name')
----
<1> Marko can't be a co-developer with himself.
-Note that it is possible to add an arbitrary number of key/value pairs (i.e. Object var args) to the `addE` steps to have those attached as properties to the created edges.
+[[addvertex-step]]
+AddVertex Step
+~~~~~~~~~~~~~~
+
+The `addV()`-step is used to add vertices to the graph (*map*/*sideEffect*). For every incoming object, a vertex is created. Moreover, `GraphTraversalSource` maintains an `addV()` method.
+[gremlin-groovy,modern]
+----
+g.addV(label,'person','name','stephen')
+g.V().values('name')
+g.V().outE('knows').addV('name','nothing')
+g.V().has('name','nothing')
+g.V().has('name','nothing').bothE()
+----
+
+[[addproperty-step]]
+AddProperty Step
+~~~~~~~~~~~~~~~~
+
+The `property()`-step is used to add properties to the elements of the graph (*sideEffect*). Unlike `addV()` and `addE()`, `property()` is a full sideEffect step in that it does not return the property it created, but the element that streamed into it.
+
+[gremlin-groovy,modern]
+----
+g.V(1).property('country','usa')
+g.V(1).property('city','santa fe').property('state','new mexico').valueMap()
+g.V(1).property(list,'age',35)
+g.V(1).valueMap()
+----
[[aggregate-step]]
Aggregate Step
@@ -1401,9 +1445,9 @@ image:lambda.png[width=150,float=right] A link:http://en.wikipedia.org/wiki/Anon
[gremlin-groovy,modern]
----
-g.V().filter {it.get().value('name') == 'marko'}.out('created').map {
- it.get().value('name')
-} <1>
+g.V().filter{it.get().value('name') == 'marko'}.
+ flatMap{it.get().vertices('created')}.
+ map {it.get().value('name')} <1>
g.V().has('name','marko').out('created').values('name') <2>
----