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 2020/08/31 15:21:31 UTC
[tinkerpop] 01/01: TINKERPOP-2392 Improved GLV starting docs
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch TINKERPOP-2392
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 457af63b3052a24ac2ddce50b2d8add532c4efe5
Author: Stephen Mallette <sp...@genoprime.com>
AuthorDate: Mon Aug 31 11:18:58 2020 -0400
TINKERPOP-2392 Improved GLV starting docs
This issue was about javascript but really might have applied to all GLVs. With the recent change of ae95dbe9c33b380555ee32716e56ec12b56c3f6c it seemed to make sense to expand this change to all GLVs and to improve upon it.
---
docs/src/reference/gremlin-variants.asciidoc | 73 ++++++++++++++++++++++
gremlin-dotnet/README.md | 18 +++++-
gremlin-dotnet/src/Gremlin.Net/Gremlin.Net.csproj | 12 +++-
gremlin-dotnet/src/index.md | 18 +++++-
.../main/javascript/gremlin-javascript/README.md | 61 +++++++++++-------
gremlin-python/src/main/jython/README.rst | 63 ++++++++++++++++++-
6 files changed, 213 insertions(+), 32 deletions(-)
diff --git a/docs/src/reference/gremlin-variants.asciidoc b/docs/src/reference/gremlin-variants.asciidoc
index 764d86c..1e9488c 100644
--- a/docs/src/reference/gremlin-variants.asciidoc
+++ b/docs/src/reference/gremlin-variants.asciidoc
@@ -1012,6 +1012,7 @@ bits of conflicting Gremlin get an underscore appended as a suffix:
*Tokens* - <<a-note-on-scopes,Scope.global_>>
+[[gremlin-python-limitations]]
=== Limitations
* Traversals that return a `Set` *might* be coerced to a `List` in Python. In the case of Python, number equality
@@ -1021,6 +1022,9 @@ results within a collection across different languages. If a `Set` is needed the
to `Set` manually.
* Gremlin is capable of returning `Dictionary` results that use non-hashable keys (e.g. Dictionary as a key) and Python
does not support that at a language level. Gremlin that returns such results will need to be re-written to avoid that.
+* The `subgraph()`-step is not supported by any variant that is not running on the Java Virtual Machine as there is
+no `Graph` instance to deserialize a result into on the client-side. A workaround is to replace the step with `store()`
+and then convert those results to something the client can use locally.
=== Application Examples
@@ -1215,6 +1219,57 @@ and then it can be called from the application as follows:
include::../../../gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Reference/GremlinVariantsDslTests.cs[tags=dslExamples]
----
+[[gremlin-net-differences]]
+=== Differences
+
+The biggest difference between Gremlin in .NET and the canonical version in Java is the casing of steps. Canonical
+Gremlin utilizes `camelCase` as is typical in Java for function names, but C# utilizes `PascalCase` as it more typical
+in that language. Therefore, when viewing a typical Gremlin example written in Gremlin Console, the conversion to
+C# usually just requires capitalization of the first letter in the step name, thus the following example in Groovy:
+
+[source,groovy]
+----
+g.V().has('person','name','marko').
+ out('knows').
+ elementMap().toList()
+----
+
+would become the following in C#:
+
+[source,csharp]
+----
+g.V().Has("Person","name","marko").
+ Out("knows").
+ ElementMap().ToList();
+----
+
+In addition to the uppercase change, also note the conversion of the single quotes to double quotes as is expected for
+declaring string values in C# and the addition of the semi-colon at the end of the line. In short, don't forget to
+apply the common syntax expectations for C# when trying to convert an example of Gremlin from a different language.
+
+Another common conversion issues lies in having to explicitly define generics, which can make canonical Gremlin appear
+much more complex in C# where type erasure is not a feature of the language. For example, the following example in
+Groovy:
+
+[source,groovy]
+----
+g.V().repeat(__.out()).times(2).values('name')
+----
+
+must be written as:
+
+[source,csharp]
+----
+g.V().Repeat(__.Out()).Times(2).Values<string>("name");
+----
+
+[[gremlin-net-limitations]]
+=== Limitations
+
+* The `subgraph()`-step is not supported by any variant that is not running on the Java Virtual Machine as there is
+no `Graph` instance to deserialize a result into on the client-side. A workaround is to replace the step with `store()`
+and then convert those results to something the client can use locally.
+
anchor:gremlin-dotnet-template[]
[[dotnet-application-examples]]
=== Application Examples
@@ -1313,6 +1368,16 @@ const scope = gremlin.process.scope
const t = gremlin.process.t
----
+By defining these imports it becomes possible to write Gremlin in the more shorthand, canonical style that is
+demonstrated in most examples found here in the documentation:
+
+[source,javascript]
+----
+const { P: { gt } } = gremlin.process;
+const { order: { desc } } = gremlin.process;
+g.V().hasLabel('person').has('age',gt(30)).order().by('age',desc).toList()
+----
+
=== Submitting Scripts
WARNING: TinkerPop does not recommend submitting script-based requests and generally continues to support this feature
@@ -1406,6 +1471,7 @@ g.person('marko').aged(29).values('name').toList().
then(names => console.log(names));
----
+[[javascript-differences]]
[[gremlin-javascript-differences]]
=== Differences
@@ -1413,3 +1479,10 @@ In situations where Javascript reserved words and global functions overlap with
bits of conflicting Gremlin get an underscore appended as a suffix:
*Steps* - <<from-step,from_()>>, <<in-step,in_()>>, <<with-step,with_()>>
+
+[[gremlin-javascript-limitations]]
+=== Limitations
+
+* The `subgraph()`-step is not supported by any variant that is not running on the Java Virtual Machine as there is
+no `Graph` instance to deserialize a result into on the client-side. A workaround is to replace the step with `store()`
+and then convert those results to something the client can use locally.
diff --git a/gremlin-dotnet/README.md b/gremlin-dotnet/README.md
index de80335..09aaffe 100644
--- a/gremlin-dotnet/README.md
+++ b/gremlin-dotnet/README.md
@@ -33,8 +33,22 @@ operating systems and with different .NET frameworks, such as .NET Framework and
nuget install Gremlin.Net
```
-Please see the [reference documentation][docs] at Apache TinkerPop for more information.
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that
+cover a wide body of features. The [Reference Documentation][steps] describes these functions and other aspects of the
+TinkerPop ecosystem including some specifics on [Gremlin in .NET][docs] itself. Most of the examples found in the
+documentation use Groovy language syntax in the [Gremlin Console][console]. For the most part, these examples
+should generally translate to C# with [some logical modification][differences]. Given the strong correspondence
+between canonical Gremlin in Java and its variants like C#, there is a limited amount of C#-specific
+documentation and examples. This strong correspondence among variants ensures that the general Gremlin reference
+documentation is applicable to all variants and that users moving between development languages can easily adopt the
+Gremlin variant for that language.
+
+**NOTE** that versions suffixed with "-rc" are considered release candidates (i.e. pre-alpha, alpha, beta, etc.) and thus
+for early testing purposes only.
[tk]: http://tinkerpop.apache.org
[gremlin]: http://tinkerpop.apache.org/gremlin.html
-[docs]: http://tinkerpop.apache.org/docs/current/reference/#gremlin-DotNet
\ No newline at end of file
+[docs]: http://tinkerpop.apache.org/docs/current/reference/#gremlin-dotnet
+[console]: https://tinkerpop.apache.org/docs/current/tutorials/the-gremlin-console/
+[steps]: https://tinkerpop.apache.org/docs/current/reference/#graph-traversal-steps
+[differences]: https://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript-differences
\ No newline at end of file
diff --git a/gremlin-dotnet/src/Gremlin.Net/Gremlin.Net.csproj b/gremlin-dotnet/src/Gremlin.Net/Gremlin.Net.csproj
index 33ad0a6..f6ff345 100644
--- a/gremlin-dotnet/src/Gremlin.Net/Gremlin.Net.csproj
+++ b/gremlin-dotnet/src/Gremlin.Net/Gremlin.Net.csproj
@@ -42,10 +42,20 @@ http://tinkerpop.apache.org/docs/current/reference/#gremlin-server
or a remote graph provider that exposes protocols by which Gremlin.Net can connect.
-Please see the reference documentation of Apache TinkerPop for more information on usage: https://s.apache.org/pgbwu
+Please see the Reference Documentation of Apache TinkerPop for more information on usage: http://tinkerpop.apache.org/docs/current/reference
and use our Google Group gremlin-users if there are any questions: https://s.apache.org/c8hru
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that cover a wide body of features. The Reference Documentation describes these functions and other aspects of the TinkerPop ecosystem including some specifics on Gremlin in .NET itself:
+
+https://s.apache.org/pgbwu
+
+Most of the examples found in the documentation use Groovy language syntax in the Gremlin Console. For the most part, these examples should generally translate to C# with some logical modification:
+
+https://s.apache.org/10v91
+
+Given the strong correspondence between canonical Gremlin in Java and its variants like C#, there is a limited amount of C#-specific documentation and examples. This strong correspondence among variants ensures that the general Gremlin reference documentation is applicable to all variants and that users moving between development languages can easily adopt the Gremlin variant for that language.
+
NOTE that versions suffixed with "-rc" are considered release candidates (i.e. pre-alpha, alpha, beta, etc.) and thus for early testing purposes only.</Description>
<AssemblyOriginatorKeyFile>../../build/tinkerpop.snk</AssemblyOriginatorKeyFile>
<SignAssembly>true</SignAssembly>
diff --git a/gremlin-dotnet/src/index.md b/gremlin-dotnet/src/index.md
index de80335..09aaffe 100644
--- a/gremlin-dotnet/src/index.md
+++ b/gremlin-dotnet/src/index.md
@@ -33,8 +33,22 @@ operating systems and with different .NET frameworks, such as .NET Framework and
nuget install Gremlin.Net
```
-Please see the [reference documentation][docs] at Apache TinkerPop for more information.
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that
+cover a wide body of features. The [Reference Documentation][steps] describes these functions and other aspects of the
+TinkerPop ecosystem including some specifics on [Gremlin in .NET][docs] itself. Most of the examples found in the
+documentation use Groovy language syntax in the [Gremlin Console][console]. For the most part, these examples
+should generally translate to C# with [some logical modification][differences]. Given the strong correspondence
+between canonical Gremlin in Java and its variants like C#, there is a limited amount of C#-specific
+documentation and examples. This strong correspondence among variants ensures that the general Gremlin reference
+documentation is applicable to all variants and that users moving between development languages can easily adopt the
+Gremlin variant for that language.
+
+**NOTE** that versions suffixed with "-rc" are considered release candidates (i.e. pre-alpha, alpha, beta, etc.) and thus
+for early testing purposes only.
[tk]: http://tinkerpop.apache.org
[gremlin]: http://tinkerpop.apache.org/gremlin.html
-[docs]: http://tinkerpop.apache.org/docs/current/reference/#gremlin-DotNet
\ No newline at end of file
+[docs]: http://tinkerpop.apache.org/docs/current/reference/#gremlin-dotnet
+[console]: https://tinkerpop.apache.org/docs/current/tutorials/the-gremlin-console/
+[steps]: https://tinkerpop.apache.org/docs/current/reference/#graph-traversal-steps
+[differences]: https://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript-differences
\ No newline at end of file
diff --git a/gremlin-javascript/src/main/javascript/gremlin-javascript/README.md b/gremlin-javascript/src/main/javascript/gremlin-javascript/README.md
index fbfd021..bd3e4fe 100644
--- a/gremlin-javascript/src/main/javascript/gremlin-javascript/README.md
+++ b/gremlin-javascript/src/main/javascript/gremlin-javascript/README.md
@@ -58,7 +58,17 @@ const names = await g.V().hasLabel('person').values('name').toList();
console.log(names);
```
-# Main Operations
+# Sample Traversals
+
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that
+cover a wide body of features. The [Reference Documentation][steps] describes these functions and other aspects of the
+TinkerPop ecosystem including some specifics on [Gremlin in Javascript][docs] itself. Most of the examples found in the
+documentation use Groovy language syntax in the [Gremlin Console][console]. For the most part, these examples
+should generally translate to Javascript with [little modification][differences]. Given the strong correspondence
+between canonical Gremlin in Java and its variants like Javascript, there is a limited amount of Javascript-specific
+documentation and examples. This strong correspondence among variants ensures that the general Gremlin reference
+documentation is applicable to all variants and that users moving between development languages can easily adopt the
+Gremlin variant for that language.
## Create Vertex
@@ -68,36 +78,23 @@ const { t: { id } } = gremlin.process;
const { cardinality: { single } } = gremlin.process;
/**
- * create a new vertex with Id, Label and properties
- * @param {String,Number} vertexId Vertex Id
- * @param {String} label Vertex Label
+ * Create a new vertex with Id, Label and properties
+ * @param {String,Number} vertexId Vertex Id (assuming the graph database allows id assignment)
+ * @param {String} vlabel Vertex Label
*/
-const createVertex = async (vertexId, label) => {
- const vertex = await g.addV(label)
+const createVertex = async (vertexId, vlabel) => {
+ const vertex = await g.addV(vlabel)
.property(id, vertexId)
.property(single, 'name', 'Apache')
- .property(single, 'lastname', 'Tinkerpop')
+ .property('lastname', 'Tinkerpop') // default database cardinality
.next();
return vertex.value;
};
```
-## Find Vertex
-
-```javascript
-/**
- * find unique vertex with id and label
- * @param {String,Number} vertexId
- * @param {String} label
- */
-const findVertex = async (vertexId, label) => {
- const vertex = await g.V(vertexId).hasLabel(label).elementMap().next();
- return vertex.value;
-};
-```
+## Find Vertices
-## Listing Vertexes
```javascript
/**
* List all vertexes in db
@@ -106,6 +103,22 @@ const findVertex = async (vertexId, label) => {
const listAll = async (limit = 500) => {
return g.V().limit(limit).elementMap().toList();
};
+/**
+ * Find unique vertex with id
+ * @param {Object} vertexId Vertex Id
+ */
+const findVertex = async (vertexId) => {
+ const vertex = await g.V(vertexId).elementMap().next();
+ return vertex.value;
+};
+/**
+ * Find vertices by label and 'name' property
+ * @param {String} vlabel Vertex label
+ * @param {String} name value of 'name' property
+ */
+const listByLabelAndName = async (vlabel, name) => {
+ return g.V().has(vlabel, 'name', name).elementMap().toList();
+};
```
## Update Vertex
@@ -115,7 +128,6 @@ const { cardinality: { single } } = gremlin.process;
/**
* Update Vertex Properties
* @param {String,Number} vertexId Vertex Id
- * @param {String} label Vertex Label
* @param {String} name Vertex Name Property
*/
const updateVertex = async (vertexId, label, name) => {
@@ -124,8 +136,6 @@ const updateVertex = async (vertexId, label, name) => {
};
```
-Please see the [reference documentation][docs] at Apache TinkerPop for more information.
-
NOTE that versions suffixed with "-rc" are considered release candidates (i.e. pre-alpha, alpha, beta, etc.) and
thus for early testing purposes only.
@@ -134,3 +144,6 @@ thus for early testing purposes only.
[docs]: http://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript
[gs]: http://tinkerpop.apache.org/docs/current/reference/#gremlin-server
[rgp]: http://tinkerpop.apache.org/docs/current/reference/#connecting-rgp
+[console]: https://tinkerpop.apache.org/docs/current/tutorials/the-gremlin-console/
+[steps]: https://tinkerpop.apache.org/docs/current/reference/#graph-traversal-steps
+[differences]: https://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript-differences
\ No newline at end of file
diff --git a/gremlin-python/src/main/jython/README.rst b/gremlin-python/src/main/jython/README.rst
index c5d84e1..428d09c 100644
--- a/gremlin-python/src/main/jython/README.rst
+++ b/gremlin-python/src/main/jython/README.rst
@@ -54,8 +54,65 @@ remote graph:
>>> g.V().both().name.toList()
[lop, vadas, josh, marko, marko, josh, peter, ripple, lop, marko, josh, lop]
-Please see the `reference documentation <http://tinkerpop.apache.org/docs/current/reference/#gremlin-python>`_
-at Apache TinkerPop for more information on usage.
+-----------------
+Sample Traversals
+-----------------
+
+The Gremlin language allows users to write highly expressive graph traversals and has a broad list of functions that
+cover a wide body of features. The `Reference Documentation <https://tinkerpop.apache.org/docs/current/reference/#graph-traversal-steps>`_
+describes these functions and other aspects of the TinkerPop ecosystem including some specifics on
+`Gremlin in Python <http://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript>`_ itself. Most of the
+examples found in the documentation use Groovy language syntax in the
+`Gremlin Console <https://tinkerpop.apache.org/docs/current/tutorials/the-gremlin-console/>`_.
+For the most part, these examples should generally translate to Python with
+`some modification <https://tinkerpop.apache.org/docs/current/reference/#gremlin-python-differences>`_. Given the
+strong correspondence between canonical Gremlin in Java and its variants like Python, there is a limited amount of
+Python-specific documentation and examples. This strong correspondence among variants ensures that the general
+Gremlin reference documentation is applicable to all variants and that users moving between development languages can
+easily adopt the Gremlin variant for that language.
+
+Create Vertex
+^^^^^^^^^^^^^
+
+.. code:: python
+
+ from gremlin_python.process.traversal import T
+ from gremlin_python.process.traversal import Cardinality
+
+ id = T.id
+ single = Cardinality.single
+
+ def create_vertex(self, vid, vlabel):
+ g.addV(vlabel).property(id, vid). \
+ property(single, 'name', 'Apache'). \
+ property('lastname', 'Tinkerpop'). \ # default database cardinality
+ next()
+
+Find Vertices
+^^^^^^^^^^^^^
+
+.. code:: python
+
+ def list_all(self, limit=500):
+ g.V().limit(limit).elementMap().toList()
+
+ def find_vertex(self, vid):
+ g.V(vid).elementMap().next()
+
+ def list_by_label_name(self, vlabel, name):
+ g.V().has(vlabel, 'name', name).elementMap().toList()
+
+Update Vertex
+^^^^^^^^^^^^^
+
+.. code:: python
+
+ from gremlin_python.process.traversal import Cardinality
+
+ single = Cardinality.single
+
+ def update_vertex(self, vid, name):
+ g.V(vid).property(single, 'name', name).next()
NOTE that versions suffixed with "rc" are considered release candidates (i.e. pre-alpha, alpha, beta, etc.) and
-thus for early testing purposes only.
+thus for early testing purposes only.
\ No newline at end of file