Errors in Gremlin-Javascript documentation

[Kevin Connor]

I'm new to Gremlin, and I was pulling my hair out trying to get things to work via Javascript, when I finally decided to dig into the Javascript files installed for Gremlin by npm. Based on my reading of the code, it seems that most of my problems stemmed from inaccuracies and omissions in the official Gremlin reference documentation.

Specifically, the key problems are here: http://tinkerpop.apache.org/docs/current/reference/#_common_imports_2

Most of these suggested imports are listed as "gremlin.process.traversal..." when they should actually just be "gremlin.process...". For example, this doesn't work:

const pop = gremlin.process.traversal.pop

but this does:

const pop = gremlin.process.pop

I tried changing all of these in my own imports, and it seems to work fine.

As for omissions, this documentation fails to include any mention that I could find of how you need to reference these objects in writing your Gremlin code in Javascript. So, for example, it was only through reading through the Gremlin Javascript files that I was able to figure out that the Gremlin query "select(all, 'a')" needed to be written in Javascript as "select(pop.all, 'a')".

I'll also note that the listing of "Common Imports" didn't list all of the imports I needed for my own Gremlin queries. Specifically, there was no import for "withOptions", so I just added the line "const withOptions = gremlin.process.withOptions".

I'm not a full-time coder/engineer, so it's certainly possible I've got some of this wrong. Thus, I was hesitant to try to propose any changes in the documentation directly via a pull request, but let me know if you think I should.

(Oh, as a side note, I'm using Gremlin on Amazon Neptune, but I don't believe that changes any of the basic facts here.)

[Stephen Mallette]

Sorry for the confusion and thanks for reporting the problem. Mistakes in the documentation are possible. If you'd like to submit a PR to help fix some of those things that would be appreciated. Certainly, if "Common Imports" are not right or has omissions then that should be corrected. As for

> it was only through reading through the Gremlin Javascript files that I was able to figure out that the Gremlin query "select(all, 'a')" needed to be written in Javascript as "select(pop.all, 'a')".

I imagine that could be unclear if you're just getting started. As an explanation into the thinking for why the documentation is as it is, I will note that it makes some assumption that users of Gremlin Language Variants (i.e.  javascript, python, .NET) have some familiarity with Gremlin and its style. So, we assume that folks are familiar with the forms of select() and that there is a select() overload that takes Pop and that could be written in Java as:

select(Pop.all, "a")

We'd then make the assumption that users are comfortable with the Gremlin style of short-forming to:

select(all, "a")

by way of statically importing Pop.all. If you know that much and you're familiar with your programming language then you'd know to organize your code to write your Gremlin that way - thus for Javascript, rather than a static import you would just do this assignment:

const all = gremlin.process.pop.all

so that you could write your Gremlin with the short-form. 

Perhaps that's too many assumptions for newcomers who don't start with Gremlin in the console with some TinkerGraph and just head straight to other graph systems with GLVs. I'd be open to ideas and pull requests that make improvements for such folks. I guess I'd just want to be sure we were not duplicating documentation over and over again across languages. 

i will keep an eye open for your PR around the Common Imports section. Please target the 3.3-dev branch with your change. It comes in good time as well because we intend to release in the next couple of weeks. Thanks!

--
You received this message because you are subscribed to the Google Groups "Gremlin-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to gremlin-user...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/gremlin-users/8e5bfd48-30d1-4b71-b02e-463b7bda6f4b%40googlegroups.com.

[Kevin Connor]

I actually hadn't looked at the 3.3 version of the documentation before, as I had assumed that the 3.4.6 version would be the most accurate and up-to-date. It turns out that the Javascript sections for 3.3 and 3.4.6 are substantially different, with the 3.3 version being the better one. It doesn't include the full list of "common imports", but the imports it does include are referenced correctly. There's also a "Static Enums and Methods" section in the 3.3 version that says a little about how the Gremlin tokens are represented as objects. This section is missing from the 3.4.6 version. I think if I had started with the 3.3 version of the documentation I might have sorted this out faster!

I don't see any immediate corrections needed in the 3.3 version on GitHub, either, so I'm not going to submit any pull requests at this time.

One last question while I've got you, though: In using valueMap().with_(withOptions.tokens, withOptions.ids) in Javascript, I find I'm getting *both* the label and the ID back, even though my understanding is that only should give the ID. In addition, rather than just providing the strings "id" and "label" as keys, it's returning a full EnumValue object for each key, which includes the "id" or "label" string as the elementName. Is that the expected behavior, or did I likely do something wrong?

Thanks!

To unsubscribe from this group and stop receiving emails from it, send an email to gremli...@googlegroups.com.

[Stephen Mallette]

I pushed a fix for the 3.4-dev docs. 

> One last question while I've got you, though: In using valueMap().with_(withOptions.tokens, withOptions.ids) in Javascript, I find I'm getting *both* the label and the ID back, even though my understanding is that only should give the ID. In addition, rather than just providing the strings "id" and "label" as keys, it's returning a full EnumValue object for each key, which includes the "id" or "label" string as the elementName. Is that the expected behavior, or did I likely do something wrong?

If you asked for tokes/ids i wouldn't expect label:

gremlin> g.V().valueMap().with(WithOptions.tokens,WithOptions.ids)
==>[id:1,name:[marko],age:[29]]
==>[id:2,name:[vadas],age:[27]]
==>[id:3,name:[lop],lang:[java]]
==>[id:4,name:[josh],age:[32]]
==>[id:5,name:[ripple],lang:[java]]
==>[id:6,name:[peter],age:[35]]

I do expect the id however to not be a string but instead an actual enum object:

gremlin> x = g.V().valueMap().with(WithOptions.tokens,WithOptions.ids).next()
==>id=1
==>name=[marko]
==>age=[29]
gremlin> x[T.id]
==>1

What graph database are you using?

To unsubscribe from this group and stop receiving emails from it, send an email to gremlin-user...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/gremlin-users/445249f8-8380-42be-9837-c30e811a9017%40googlegroups.com.

[Kevin Connor]

Thanks for the clarification on the enum objects. Regarding the label token, when I perform this query in the Gremlin Console (using Groovy), I *only* get the ID back. When I do the same query in Javascript, however, I get both label and ID. That's why I wondered if it was possible that I had made some mistake in how I was referencing the objects. 

I'm performing all of these queries on an Amazon Neptune database.

To view this discussion on the web visit https://groups.google.com/d/msgid/gremlin-users/445249f8-8380-42be-9837-c30e811a9017%40googlegroups.com.

[Stephen Mallette]

I just added an explicit test for this scenario and it passes across all programming languges:

https://github.com/apache/tinkerpop/blob/3bfe50bfaf8a04d6dbfa3cd3dd7d4569ebfc3b1c/gremlin-test/features/map/ValueMap.feature#L132-L146  

I sense this might be a problem with Neptune. Perhaps Kelvin will notice this and try to confirm on his end. 

To unsubscribe from this group and stop receiving emails from it, send an email to gremlin-user...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/gremlin-users/724be4aa-a3e3-4d44-bcad-0b7328a37233%40googlegroups.com.

[Kelvin Lawrence]

I will take a look.

Cheers

Kelvin

To view this discussion on the web visit https://groups.google.com/d/msgid/gremlin-users/724be4aa-a3e3-4d44-bcad-0b7328a37233%40googlegroups.com.

[Kelvin Lawrence]

This is what I get back using the 3.4.4 Gremlin JavaScript client when run using Node 8.15 and Neptune. This code...

    let trv = g.V('1').valueMap().with_(withOptions.tokens,withOptions.ids);
    const result = await trv.toList();
    console.log(result);

Yields this result...

[

 Map {
    'country' => [ 'US' ],
    EnumValue { typeName: 'T', elementName: 'id' } => '1',
    'code' => [ 'ATL' ],
    'longest' => [ 12390 ],
    'city' => [ 'Atlanta' ],
    'lon' => [ -84.4281005859375 ],
    'type' => [ 'airport' ],
    'mySet' => [ 1, 2, 3 ],
    'elev' => [ 1026 ],
    'icao' => [ 'KATL' ],
    'runways' => [ 5 ],
    'region' => [ 'US-GA' ],
    'lat' => [ 33.6366996765137 ],
    'desc' => [ 'Hartsfield - Jackson Atlanta International Airport' ] } ]

[Kevin Connor]

Sorry I missed your reply on this, Kelvin, but I thought I'd follow up just to resolve any uncertainty. As you might have concluded, this was user error. As I took a closer look, I realized there was a difference between my test query in the Gremlin console and the query I ultimately wrote in Javascript. As I was trying to debug my Javascript, I had inserted the "true" parameter into my valueMap step, so that's what resulted in the Label being returned.

Thanks for looking into this.