From commits-return-40491-archive-asf-public=cust-asf.ponee.io@tinkerpop.apache.org Wed Sep 2 15:12:42 2020 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mailroute1-lw-us.apache.org (mailroute1-lw-us.apache.org [207.244.88.153]) by mx-eu-01.ponee.io (Postfix) with ESMTPS id 9517718065D for ; Wed, 2 Sep 2020 17:12:42 +0200 (CEST) Received: from mail.apache.org (localhost [127.0.0.1]) by mailroute1-lw-us.apache.org (ASF Mail Server at mailroute1-lw-us.apache.org) with SMTP id C5563121985 for ; Wed, 2 Sep 2020 15:12:41 +0000 (UTC) Received: (qmail 19964 invoked by uid 500); 2 Sep 2020 15:12:41 -0000 Mailing-List: contact commits-help@tinkerpop.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@tinkerpop.apache.org Delivered-To: mailing list commits@tinkerpop.apache.org Received: (qmail 19941 invoked by uid 99); 2 Sep 2020 15:12:41 -0000 Received: from ec2-52-202-80-70.compute-1.amazonaws.com (HELO gitbox.apache.org) (52.202.80.70) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 02 Sep 2020 15:12:41 +0000 Received: by gitbox.apache.org (ASF Mail Server at gitbox.apache.org, from userid 33) id 75C9D8088C; Wed, 2 Sep 2020 15:12:41 +0000 (UTC) Date: Wed, 02 Sep 2020 15:12:42 +0000 To: "commits@tinkerpop.apache.org" Subject: [tinkerpop] 01/01: Merge branch '3.4-dev' MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit From: spmallette@apache.org In-Reply-To: <159905956108.18090.12456008899078403540@gitbox.apache.org> References: <159905956108.18090.12456008899078403540@gitbox.apache.org> X-Git-Host: gitbox.apache.org X-Git-Repo: tinkerpop X-Git-Refname: refs/heads/master X-Git-Reftype: branch X-Git-Rev: 486bc5dfd16e4cbb1a99f35be7991748c4102b18 X-Git-NotificationType: diff X-Git-Multimail-Version: 1.5.dev Auto-Submitted: auto-generated Message-Id: <20200902151241.75C9D8088C@gitbox.apache.org> This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git commit 486bc5dfd16e4cbb1a99f35be7991748c4102b18 Merge: 1290265 92b89b6 Author: Stephen Mallette AuthorDate: Wed Sep 2 11:12:22 2020 -0400 Merge branch '3.4-dev' docs/src/reference/gremlin-variants.asciidoc | 80 ++++++++++++++++++++-- gremlin-dotnet/README.md | 24 +++++-- gremlin-dotnet/src/Gremlin.Net/Gremlin.Net.csproj | 18 +++-- gremlin-dotnet/src/index.md | 24 +++++-- .../main/javascript/gremlin-javascript/README.md | 71 +++++++++++-------- gremlin-python/src/main/python/README.rst | 72 +++++++++++++++++-- 6 files changed, 234 insertions(+), 55 deletions(-) diff --cc docs/src/reference/gremlin-variants.asciidoc index 8d42ca7,b9e4944..7696bfd --- a/docs/src/reference/gremlin-variants.asciidoc +++ b/docs/src/reference/gremlin-variants.asciidoc @@@ -979,10 -1031,11 +980,14 @@@ is detected during deserialization, th results within a collection across different languages. If a `Set` is needed then convert `List` results 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. +does not support that at a language level. Using GraphSON 3.0 or GraphBinary (after 3.5.0) makes it possible to return +such results. In all other cases, Gremlin that returns such results will need to be re-written to avoid that sort of +key. + * 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 The TinkerPop source code contains a simple Python script that shows a basic example of how gremlinpython works. It @@@ -1176,28 -1229,57 +1181,76 @@@ and then it can be called from the appl include::../../../gremlin-dotnet/test/Gremlin.Net.IntegrationTest/Docs/Reference/GremlinVariantsDslTests.cs[tags=dslExamples] ---- - [[gremlin-dotnet-differences]] + [[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 is 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("name"); + ---- + +Gremlin allows for `Map` instances to include `null` keys, but `null` keys in C# `Dictionary` instances are not allowed. +It is therefore necessary to rewrite a traversal such as: + +[source,javascript] +---- +g.V().groupCount().by('age') +---- + +where "age" is not a valid key for all vertices in a way that will remove the need for a `null` to be returned. + +[source,javascript] +---- +g.V().has('age').groupCount().by('age') +g.V().hasLabel('person').groupCount().by('age') +---- + +Either of the above two options accomplishes the desired goal as both prevent `groupCount()` from having to process +the possibility of `null`. + + [[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 @@@ -1408,38 -1490,9 +1472,44 @@@ bits of conflicting Gremlin get an unde *Steps* - <>, <>, <> +Gremlin allows for `Map` instances to include `null` keys, but `null` keys in Javascript have some interesting behavior +as in: + +[source,text] +---- +> var a = { null: 'something', 'b': 'else' }; +> JSON.stringify(a) +'{"null":"something","b":"else"}' +> JSON.parse(JSON.stringify(a)) +{ null: 'something', b: 'else' } +> a[null] +'something' +> a['null'] +'something' +---- + +This behavior needs to be considered when using Gremlin to return such results. A typical situation where this might +happen is with `group()` or `groupCount()` as in: + +[source,javascript] +---- +g.V().groupCount().by('age') +---- + +where "age" is not a valid key for all vertices. In these cases, it will return `null` for that key and group on that. +It may bet better in Javascript to filter away those vertices to avoid the return of `null` in the returned `Map`: + +[source,javascript] +---- +g.V().has('age').groupCount().by('age') +g.V().hasLabel('person').groupCount().by('age') +---- + +Either of the above two options accomplishes the desired goal as both prevent `groupCount()` from having to process - the possibility of `null`. ++the possibility of `null`. + [[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.