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 2015/11/10 13:50:41 UTC
incubator-tinkerpop git commit: Tweaks to spelling/grammar and minor
additional content in the getting started tutorial.
Repository: incubator-tinkerpop
Updated Branches:
refs/heads/master a9efe6542 -> 2714ff029
Tweaks to spelling/grammar and minor additional content in the getting started tutorial.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/commit/2714ff02
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/2714ff02
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/2714ff02
Branch: refs/heads/master
Commit: 2714ff029ccc6f553084290523ac2940d2f09b09
Parents: a9efe65
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Tue Nov 10 07:49:51 2015 -0500
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Tue Nov 10 07:49:51 2015 -0500
----------------------------------------------------------------------
docs/src/tutorials-getting-started.asciidoc | 86 +++++++++++++-----------
1 file changed, 45 insertions(+), 41 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/2714ff02/docs/src/tutorials-getting-started.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/tutorials-getting-started.asciidoc b/docs/src/tutorials-getting-started.asciidoc
index e890eab..28f4aba 100644
--- a/docs/src/tutorials-getting-started.asciidoc
+++ b/docs/src/tutorials-getting-started.asciidoc
@@ -19,15 +19,15 @@ Getting Started
===============
link:http://tinkerpop.com[Apache TinkerPop] is an open source Graph Computing Framework. Within itself, TinkerPop
-represents a large collection of capabilities and technologies and in its wider ecosystem an additionally extended
+represents a large collection of capabilities and technologies and, in its wider ecosystem, an additionally extended
world of link:http://tinkerpop.incubator.apache.org/#graph-systems[third-party contributed] graph libraries and
systems. TinkerPop's ecosystem can appear complex to newcomers of all experience, especially when glancing at the
link:http://tinkerpop.incubator.apache.org/docs/x.y.z/index.html[reference documentation] for the first time.
So, where do you get started with TinkerPop? How do you dive in quickly and get productive? Well - Gremlin, the
most recognizable citizen of The TinkerPop, is here to help with this thirty minute tutorial. That's right - in just
-thirty short minutes, you too can be fit to start building graph applications with TinkerPop. Welcome to _The Gremlin
-TinkerPop - by Gremlin_!
+thirty short minutes, you too can be fit to start building graph applications with TinkerPop. Welcome to _The
+TinkerPop Workout - by Gremlin_!
image::gremlin-gym.png[width=1024]
@@ -43,7 +43,7 @@ Gremlin helps you navigate the vertices and edges of a graph. He is essentially
databases, as link:http://sql2gremlin.com/[SQL] is the query language to relational databases. To tell Gremlin how
he should "traverse" the graph (i.e. what you want your query to do) you need a way to provide him commands in the
language he understands - and, of course, that language is called "Gremlin". For this task, you need one of
-TinkerPop's most important tools: the link:http://tinkerpop.incubator.apache.org/docs/x.y.z/#gremlin-console[Gremlin Console].
+TinkerPop's most important tools: link:http://tinkerpop.incubator.apache.org/docs/x.y.z/#gremlin-console[The Gremlin Console].
Download the console, unpackage it and start it:
@@ -75,19 +75,20 @@ To get Gremlin to traverse a graph, you need a `Graph` instance, which holds the
link:http://tinkerpop.incubator.apache.org/docs/x.y.z/#_the_graph_structure[structure] and data of the
graph. TinkerPop is a graph abstraction layer over different graph databases and different graph processors, so there
are many `Graph` instances you can choose from to instantiate in the console. The best `Graph` instance to start with
-however, is link:http://tinkerpop.incubator.apache.org/docs/x.y.z/#tinkergraph-gremlin[TinkerGraph]. TinkerGraph
+however is link:http://tinkerpop.incubator.apache.org/docs/x.y.z/#tinkergraph-gremlin[TinkerGraph]. TinkerGraph
is a fast, in-memory graph database with a small handful of configuration options, making it a good choice for beginners.
TIP: TinkerGraph is not just a toy for beginners. It is useful in analyzing subgraphs taken from a large graph,
-trying out, working with a static graph that doesn't change much, unit tests and other use cases where the graph
+working with a small static graph that doesn't change much, writing unit tests and other use cases where the graph
can fit in memory.
TIP: Resist the temptation to "get started" with more complex databases like link:http://thinkaurelius.github.io/titan/[Titan]
or to delve into how to get link:http://tinkerpop.incubator.apache.org/docs/x.y.zg/#gremlin-server[Gremlin Server]
-working properly. Focusing on the basics builds a good foundation for all the other things TinkerPop offers.
+working properly. Focusing on the basics, presented in this guide, builds a good foundation for all the other things
+TinkerPop offers.
-To make your process even easier, start with one of TinkerPop's toy graphs. These are "small" graphs designed to
-provide a quick start into querying. It is good to get familiar with them as almost all TinkerPop documentation is based
+To make your process even easier, start with one of TinkerPop's "toy" graphs. These are "small" graphs designed to
+provide a quick start into querying. It is good to get familiar with them, as almost all TinkerPop documentation is based
on them and when you need help and have to come to the link:http://groups.google.com/group/gremlin-users[mailing list],
a failing example put in the context of the toy graphs can usually get you a fast answer to your problem.
@@ -106,9 +107,9 @@ g = graph.traversal()
The first command creates a `Graph` instance named `graph`, which thus provides a reference to the data you want
Gremlin to traverse. Unfortunately, just having `graph` doesn't provide Gremlin enough context to do his job. You
also need something called a `TraversalSource`, which is generated by the second command. The `TraversalSource`
-provides additional information (such as link:http://tinkerpop.incubator.apache.org/docs/x.y.z/#traversalstrategy[traversal strategies]
-and link:http://tinkerpop.incubator.apache.org/docs/x.y.z/#graphcomputer[traversal engine]) to Gremlin with respect
-to how he should execute his trip around the `Graph`.
+provides additional information to Gremlin (such as the link:http://tinkerpop.incubator.apache.org/docs/x.y.z/#traversalstrategy[traversal strategies]
+to apply and the link:http://tinkerpop.incubator.apache.org/docs/x.y.z/#graphcomputer[traversal engine] to use) which
+provides him guidance on how to execute his trip around the `Graph`.
With your `TraversalSource` `g` available it is now possible to ask Gremlin to traverse the `Graph`:
@@ -132,23 +133,22 @@ g.V(1).out('knows').has('age', gt(30)).values('name') <7>
(similar to `inE().inV()` and `in` for incoming edges).
<7> Get the names of the people vertex "1" knows who are over the age of 30.
-In this first five minutes with Gremlin, you've gotten the Gremlin Console installed, instantiated a `Graph`, wrote
-some traversals and hopefully learned something about TinkerPop in general. You've only scratched the surface of
-what there is to know, but those accomplishments will help enable understanding of the more detailed tutorials to
-come.
+In this first five minutes with Gremlin, you've gotten the Gremlin Console installed, instantiated a `Graph` and
+`TraversalSource`, wrote some traversals and hopefully learned something about TinkerPop in general. You've only
+scratched the surface of what there is to know, but those accomplishments will help enable your understanding of the
+detailed sections to come.
The Next Fifteen Minutes
------------------------
-In the first five minutes of getting started with TinkerPop, you learned some basics for telling Gremlin how to
-traverse a graph. Of course, there wasn't much discussion about what a graph is. A graph is a collection of
-vertices (i.e. nodes, dots) and edges (i.e. relationships, lines), where a vertex is an entity which
-represents some domain object (e.g. a person, a place, etc.) and an edge represents the relationship between two
-vertices.
+In the first five minutes of _The TinkerPop Workout - by Gremlin_, you learned some basics for traversing graphs. Of
+course, there wasn't much discussion about what a graph is. A graph is a collection of vertices (i.e. nodes, dots)
+and edges (i.e. relationships, lines), where a vertex is an entity which represents some domain object (e.g. a person,
+a place, etc.) and an edge represents the relationship between two vertices.
image:modern-edge-1-to-3-1.png[width=300]
-The above example shows a graph with two vertices, one with a unique identifier of "1" and another with a unique
+The diagram above shows a graph with two vertices, one with a unique identifier of "1" and another with a unique
identifier of "3". There is a edge connecting the two with a unique identifier of "9". It is important to consider
that the edge has a direction which goes _out_ from vertex "1" and _in_ to vertex "3'.
@@ -187,6 +187,10 @@ v2 = g.addV(id, 3, label, "software", "name", "lop", "lang", "java").next()
v1.addEdge("created", v2, id, 9, "weight", 0.4)
----
+IMPORTANT: The `TraversalSource` is a Java `Iterator`. It does *nothing* until it is _iterated_, by calling some
+form of `next()`. Therefore, a line of code like `x = g.addV()` does not "add a vertex" and assign that vertex to
+the variable `x`. It creates a `Traversal` and assigns that value to `x`.
+
There are a number of important things to consider in the above code. First, why didn't we use `graph.addVertex()`?
Couldn't that just as easily performed the same function? Yes - it could have, however, TinkerPop encourages
end-users to utilizes the methods of the `TraversalSource` rather than `Graph`. The `Graph` methods are considered
@@ -200,10 +204,10 @@ creation method are statically imported to the console. You would normally refer
NOTE: The fully qualified name for `T` is `org.apache.tinkerpop.gremlin.structure.T`.
Third, don't forget that you are working with TinkerGraph and so identifier assignment is allowed. That is _not_ the
-case with most graph databases (don't bother to try with Neo4j).
+case with most graph databases (for example, don't bother to try with Neo4j or Titan).
Finally, the label for an `Edge` is required and is thus part of the method signature of `addEdge()`. It is the first
-parameter supplied, followed by `Vertex` to which `v1` should be connected. Therefore, this usage of `addEdge` is
+parameter supplied, followed by the `Vertex` to which `v1` should be connected. Therefore, this usage of `addEdge` is
creating an edge that goes _out_ of `v1` and into `v2` with a label of "created".
Graph Traversal - Staying Simple
@@ -243,7 +247,7 @@ When Gremlin is on a vertex or an edge, he has access to all the properties that
IMPORTANT: The above query iterates all the vertices in the graph to get its answer. That's fine for our little example,
but for multi-million or billion edge graphs that is a big problem. To solve this problem, you should look to use
indices. TinkerPop does not provide an abstraction for index management. You should consult the documentation of the
-graph you have chosen and utilize its native API to create indices that will speed up these types of lookups. Your
+graph you have chosen and utilize its native API to create indices which will then speed up these types of lookups. Your
traversals will remain unchanged however, as the indices will be used transparently at execution time.
Now that Gremlin has found "marko", he can now consider the next step in the traversal where we ask him to "walk"
@@ -281,7 +285,7 @@ g.V().has('name','marko').out('created')
----
Finally, now that Gremlin has reached the "software that Marko created", he has access to the properties of the
-"software" vertex and you can therefore ask Gremlin to extract the "name" property as follows:
+"software" vertex and you can therefore ask Gremlin to extract the value of the "name" property as follows:
[gremlin-groovy,modern]
----
@@ -295,9 +299,9 @@ on your understanding of these basic concepts.
Graph Traversal - Increasing Complexity
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Armed with the knowledge from the previous section, let's ask Gremlin to do some more complex things. There's not much
-more that can be done with the "baby" graph we had, so let's return to the "modern" toy graph from the "five
-minutes section". Recall that you can create this `Graph` and establish a `TraversalSource` with:
+Armed with the knowledge from the previous section, let's ask Gremlin to perform some more difficult traversal tasks.
+There's not much more that can be done with the "baby" graph we had, so let's return to the "modern" toy graph from
+the "five minutes section". Recall that you can create this `Graph` and establish a `TraversalSource` with:
[gremlin-groovy]
----
@@ -314,7 +318,7 @@ use the `within` comparator with `has()` as follows:
g.V().has('name',within('vadas','marko')).values('age')
----
-It is worth noting that `within` is statically imported to the Gremlin Console (much like `T` is, as described
+It is worth noting that `within` is statically imported from `P` to the Gremlin Console (much like `T` is, as described
earlier).
NOTE: The fully qualified name for `P` is `org.apache.tinkerpop.gremlin.process.traversal.P`.
@@ -335,11 +339,11 @@ step. We know how to find the "software" that "marko" created:
g.V().has('name','marko').out('created')
----
-image:gremlin-on-software-vertex.png[width=300,float=right] Let's extend on that to try to learn who "marko"
-collaborates with. In other words, let's try to answer the question of: "Who are the people that "marko" develops
-"software" with?" To do that, we should first picture Gremlin standing on the "software" vertex. To find out who
-"created" that "software" we need to have Gremlin traverse back _in_ along the "created" edges to find the "person"
-vertices tied to it.
+image:gremlin-on-software-vertex.png[width=350,float=right] Let's extend on that query to try to learn who "marko"
+collaborates with when it comes to the software he created. In other words, let's try to answer the question of: "Who
+are the people that marko develops software with?" To do that, we should first picture Gremlin where we left him in
+the previous query. He was standing on the "software" vertex. To find out who "created" that "software", we need to
+have Gremlin traverse back _in_ along the "created" edges to find the "person" vertices tied to it.
[gremlin-groovy,modern]
----
@@ -358,8 +362,8 @@ g.V().has('name','marko').as('exclude').out('created').in('created').where(neq('
We made two additions to the traversal to make it exclude "marko" from the results. First, we added the
link:http://tinkerpop.incubator.apache.org/docs/x.y.z/#as-step[as()] step. The `as()` step is not really a "step",
but a "step modulator" - something that adds features to a step or the traversal. Here, the `as('exclude')` labels
-the `has()` step with "exclude" and all values that pass through that step are held in that "label" for later use. In
-this case, the "marko" vertex is the only vertex to pass through that point, so it is held in "exclude".
+the `has()` step with the name "exclude" and all values that pass through that step are held in that label for later
+use. In this case, the "marko" vertex is the only vertex to pass through that point, so it is held in "exclude".
The other addition that was made was the `where()` step which is a filter step like `has()`. The `where()` is
positioned after the `in()` step that has "person" vertices, which means that the `where()` filter is occurring
@@ -399,14 +403,14 @@ g.V().group().by(label).by('name')
----
In this section, you have learned a bit more about what property graphs are and how Gremlin interacts with them.
-You also learned how to envision Gremlin moving about a graph and how to use some of the more complex but commonly
+You also learned how to envision Gremlin moving about a graph and how to use some of the more complex, but commonly
utilized traversal steps. You are now ready to think about TinkerPop in terms of its wider applicability to
graph computing.
The Final Ten Minutes
---------------------
-These final ten minutes of _The TinkerPop Workout - by Gremlin_ we'll look at TinkerPop from a higher level and
+In these final ten minutes of _The TinkerPop Workout - by Gremlin_ we'll look at TinkerPop from a higher level and
introduce different features of the stack in order to orient you with what it offers. In this way, you can
identify areas of interest and dig into the details from there.
@@ -423,8 +427,8 @@ are thus afforded options in their architecture and development because:
* They can try different implementations using the same code to decide which is best for their environment.
* They can grow into a particular implementation if they so desire - start with a graph that is designed to scale
within a single machine and then later switch to a graph that is designed to scale horizontally.
-* They can feel more confident in a technology choices, as advances in the state of different provider implementations
-are behind TinkerPop APIs, which open the possibility to switch providers with limited impact.
+* They can feel more confident in graph technology choices, as advances in the state of different provider
+implementations are behind TinkerPop APIs, which open the possibility to switch providers with limited impact.
TinkerPop has always had the vision of being an abstraction over different graph databases. That much
is not new and dates back to TinkerPop 1.x. It is in TinkerPop 3.x however that we see the introduction of the notion