From 1971abec4280788b4d89801deb27f3282122f9a7 Mon Sep 17 00:00:00 2001 From: Stephen Mallette Date: Thu, 23 Jan 2025 08:12:50 -0500 Subject: [PATCH] Added translator section. --- book/Section-Beyond-Basic-Queries.adoc | 73 ++++++++++++++++++++++++++ book/Section-Getting-Started.adoc | 21 +++++--- 2 files changed, 87 insertions(+), 7 deletions(-) diff --git a/book/Section-Beyond-Basic-Queries.adoc b/book/Section-Beyond-Basic-Queries.adoc index b4f28f0..cbae835 100644 --- a/book/Section-Beyond-Basic-Queries.adoc +++ b/book/Section-Beyond-Basic-Queries.adoc @@ -6174,6 +6174,79 @@ your own. One of the pre configured Vertex Programs is Page Rank. Let's take a look next at one way it can be used. +[[translators]] +Translating Gremlin to different programming languages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This book mostly focuses on writing Gremln in its Groovy syntax where it is easy to +run inside of the Gremlin Console, which is a great convenience when learning or just +trying to work out a query. The Groovy syntax is actually quite close to the native +form of the Gremlin language. As most developers tend to write Gremlin in the +language they are most comfortable, it isn't always well known that Gremlin has its +own grammar that is used for parsing queries. For historical reasons, particularly +where Gremlin long ago was wholly built on top of Groovy in versions prior to +TinkerPop 3, the grammar for native Gremlin matches quite closely to Groovy's +grammar. We refer to this native form of gremlin as 'gremlin-lang'. + +The only time that you might encounter gremlin-lang is with Gremlin Server, which +uses the grammar by default to process queries. The grammar may also be used +internally to TinkerPop-enabled graph systems that support the Gremlin Server +protocols. Even in those cases, the Gremlin drivers hide that syntax away by +translating the Gremlin you write in your programming language to the form expected +by the grammar. If you are not using the drivers and are instead using raw HTTP +requests, then you must write gremlin-lang yourself as a string to send to the +server. When sending direct HTTP requests, it would be possible to use the drivers to +write Gremlin in your favorite programming langugage, get the gremlin-lang form and +then manually submit that as a direct HTTP request, but it's hard to say what the +benefit of that approach would be since the drivers are designed to hide that +complexity from the application. + +If you want to see the gremlin-lang form, you can get it from the traversal itself. +In the following example, we write our Gremlin in Groovy and then use its +'gremlinLang' property (which is a shorthand for Java's 'getGremlinLang()') to get +the Gremlin native form after giving it the "g" representing the alias for the +'GraphTraversalSource': + +[source,groovy] +---- +t = g.V().outE('knows');[] +t.gremlinLang.getGremlin("g") + +g.V().outE("knows") +---- + +You can see in the prior example that gremlin-lang is not so different than Groovy. +The only difference is that the translation has normalized the single quotes to +double quotes to define a string. That said, gremlin-lang can also equally accept +single quotes for it string representation. The influence from Groovy on gremlin-lang +is evident here. We can see where the divergence from Groovy though with a slightly +longer example: + +[source,groovy] +---- +t = g.V().outE('knows').has('weight', 1 as byte);[] +t.gremlinLang.getGremlin("g") + + +g.V().outE("knows").has("weight",1B) +---- + +In Groovy, we define a 'byte' using the 'as' keyword. You can see in the translation +that gremlin-lang allows for a shorthand of a capital "B" suffix to the number to +define a 'byte'. + +If you have gremlin-lang compliant Gremlin, you can translate it to any of the +programming languages that TinkerPop supports using the 'GremlinTranslator'. This can +be helpful if you find an example written in a language you aren't familiar with and +wish to convert it to one that you are. + +[source,groovy] +---- +GremlinTranslator.translate("g.V().outE(\"knows\")", Translator.GO) + +g.V().OutE("knows") +---- + [[pagerank]] Experiments with Page Rank ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/book/Section-Getting-Started.adoc b/book/Section-Getting-Started.adoc index 2cffaad..6d374a8 100644 --- a/book/Section-Getting-Started.adoc +++ b/book/Section-Getting-Started.adoc @@ -54,10 +54,17 @@ this book we will be working within the Gremlin console with a local graph. Howe in Chapters 7 and 8 we take a look at Gremlin Server and some other TinkerPop enabled environments. Most of Apache TinkerPop has been developed using Java but there are also bindings available for many other programming languages such as Groovy, Python, -Go, Javascript, and C#. Parts of TinkerPop are themselves developed in Groovy, most -notably the Gremlin Console. The nice thing about that is that we can use Groovy -syntax along with Gremlin when entering queries into the Console or sending them via -REST API to a Gremlin Server. All of these topics are covered in detail. +Go, Javascript, and C#. These bindings help make Gremlin feel comfortable to you as +you can work with Gremlin in the idioms of the programming language that you are most +familiar with. + +Even though this book focuses on Gremlin written with Groovy, you should remember +that whatever examples you see in Groovy can easily be converted to any other +supported programming language. You just need to understand the idioms of the the +language you are using and converting should be straightforward. For example, Python +prefers snake case compared to Groovy preferring camel-case. Therefore a Groovy query +of 'g.addV("person")' just converts to 'g.add_v("person")' in Python. You will read +more about Gremlin translation in the "<>" section. The queries used as examples in this book have been tested with Apache TinkerPop version {tpvercheck} as well as some prior releases where appropriate. Tests were @@ -251,9 +258,9 @@ One thing that is not at all obvious or apparent is that the Gremlin console qui imports a large number of Java Classes and Enums on your behalf as it starts up. This makes writing queries within the console simpler. However, as we shall explore in the "<>" section later, once you start writing standalone programs in Java -or other languages, you need to actually know what the console did on your behalf. As -a teaser for what comes later, try typing ':show imports' when using the Gremlin -Console and see what it returns. +or other languages, you need to actually know what the console did on your behalf. +Reading through that section will help familiarize you with the classes you need to +import to your application code. [[gremlinsave]] Saving output from the console to a file