You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by "FlorianHockmann (via GitHub)" <gi...@apache.org> on 2023/03/01 16:34:21 UTC
[GitHub] [tinkerpop] FlorianHockmann commented on a diff in pull request #1843: TINKERPOP-2824 Properties on response elements
FlorianHockmann commented on code in PR #1843:
URL: https://github.com/apache/tinkerpop/pull/1843#discussion_r1121982613
##########
docs/src/reference/gremlin-applications.asciidoc:
##########
@@ -2250,50 +2250,36 @@ to as "detached elements" and cases where properties are not included are "refer
With the type of request and detachment model in mind, it is now possible to discuss how best to consider element
properties in relation to them all in concert.
-By default, Gremlin Server sample configurations utilize `ReferenceElementStrategy` when creating the out-of-the-box
-`GraphTraversalSource`. As the name suggests, this means that elements will be detached by reference and will
-therefore not have properties included. The relevant configuration from the Gremlin Server initialization script looks
-like this:
+By default, Gremlin Server sample configurations return all properties.
+
+To manage properties for each request you can use <<configuration-steps-with,with()>> configuration option
+`materializeProperties`
[source,groovy]
----
-globals << [g : traversal().withEmbedded(graph).withStrategies(ReferenceElementStrategy)]
+g.with('materializeProperties', 'tokens').V()
----
-This configuration is global to Gremlin Server and therefore all methods of connection will always return elements
-without properties. If this strategy is not included, then there are other considerations to take into account such as
-the connection type (i.e. script or bytecode) and the serializer.
+The `tokens` value for the `materializeProperties` means that need to return only `id` and `label`. Another option
Review Comment:
```suggestion
The `tokens` value for the `materializeProperties` means that only `id` and `label` should be returned. Another option
```
##########
docs/src/reference/gremlin-applications.asciidoc:
##########
@@ -2250,50 +2250,36 @@ to as "detached elements" and cases where properties are not included are "refer
With the type of request and detachment model in mind, it is now possible to discuss how best to consider element
properties in relation to them all in concert.
-By default, Gremlin Server sample configurations utilize `ReferenceElementStrategy` when creating the out-of-the-box
-`GraphTraversalSource`. As the name suggests, this means that elements will be detached by reference and will
-therefore not have properties included. The relevant configuration from the Gremlin Server initialization script looks
-like this:
+By default, Gremlin Server sample configurations return all properties.
+
+To manage properties for each request you can use <<configuration-steps-with,with()>> configuration option
+`materializeProperties`
[source,groovy]
----
-globals << [g : traversal().withEmbedded(graph).withStrategies(ReferenceElementStrategy)]
+g.with('materializeProperties', 'tokens').V()
----
-This configuration is global to Gremlin Server and therefore all methods of connection will always return elements
-without properties. If this strategy is not included, then there are other considerations to take into account such as
-the connection type (i.e. script or bytecode) and the serializer.
+The `tokens` value for the `materializeProperties` means that need to return only `id` and `label`. Another option
+`all` used to indicate that all properties should be returned and is the default value.
Review Comment:
I think this needs to be:
> Another option, `all`, _can be_ used [...]
##########
docs/src/reference/gremlin-applications.asciidoc:
##########
@@ -2307,10 +2293,8 @@ List<Vertex> results = g.V().hasLabel("person").elementMap('name').toList();
Both of the above requests return a list of `Map` instances that contain the `id`, `label` and the "name" property.
-TIP: The example graph configurations pre-packaged with Gremlin Server utilize `ReferenceElementStrategy`
-which convert all graph elements to references by initializing "g" using
-`withStrategies(ReferenceElementStrategy.instance()`. Consider utilizing `ReferenceElementStrategy` whenever creating
-a `GraphTraversalSource` in Java to ensure the most portable Gremlin.
+TIP: Consider utilizing `ReferenceElementStrategy` whenever creating a `GraphTraversalSource` in Java to ensure
+the most portable Gremlin.
NOTE: For those interested, please see link:https://lists.apache.org/thread.html/e959e85d4f8b3d46d281f2742a6e574c7d27c54bfc52f802f7c04af3%40%3Cdev.tinkerpop.apache.org%3E[this post]
Review Comment:
I think we should remove this thread here or at least mention that it discusses the history of this and gives pros/cons, but it doesn't reflect the current situation any more as properties are now returned by default.
##########
docs/src/reference/gremlin-applications.asciidoc:
##########
@@ -2307,10 +2293,8 @@ List<Vertex> results = g.V().hasLabel("person").elementMap('name').toList();
Both of the above requests return a list of `Map` instances that contain the `id`, `label` and the "name" property.
-TIP: The example graph configurations pre-packaged with Gremlin Server utilize `ReferenceElementStrategy`
-which convert all graph elements to references by initializing "g" using
-`withStrategies(ReferenceElementStrategy.instance()`. Consider utilizing `ReferenceElementStrategy` whenever creating
-a `GraphTraversalSource` in Java to ensure the most portable Gremlin.
+TIP: Consider utilizing `ReferenceElementStrategy` whenever creating a `GraphTraversalSource` in Java to ensure
Review Comment:
Is this still a suggestion that we want to make? I'm not sure what is meant here by "portable Gremlin". Should it be easy to port a traversal to another GLV? In that case, we can remove the tip now as GLVs can now also deserialize properties.
Or portable between different graph providers? In that case, it might still be better to use `ReferenceElementStrategy` maybe, but I'm not sure how important this consideration is.
##########
docs/src/upgrade/release-3.7.x.asciidoc:
##########
@@ -29,6 +29,28 @@ Please see the link:https://github.com/apache/tinkerpop/blob/3.7.0/CHANGELOG.asc
=== Upgrading for Users
+==== Properties on Elements
+
+By default properties on Elements are now returned.
+If you don't need to get properties then you can do one of the following ways:
+
+* Configure server to not return properties, update groovy configuration file with `ReferenceElementStrategy`.
Review Comment:
I think _groovy configuration file_ isn't clear enough for users to understand which Groovy file they need to edit. Since it's named _Gremlin Server initialization script_ in the reference docs, I would also use that term here.
`server` should probably also be renamed to `Gremlin Server`. That way, users of graphs that don't include Gremlin Server know that this doesn't apply to them.
##########
docs/src/reference/gremlin-applications.asciidoc:
##########
@@ -2250,50 +2250,36 @@ to as "detached elements" and cases where properties are not included are "refer
With the type of request and detachment model in mind, it is now possible to discuss how best to consider element
properties in relation to them all in concert.
-By default, Gremlin Server sample configurations utilize `ReferenceElementStrategy` when creating the out-of-the-box
-`GraphTraversalSource`. As the name suggests, this means that elements will be detached by reference and will
-therefore not have properties included. The relevant configuration from the Gremlin Server initialization script looks
-like this:
+By default, Gremlin Server sample configurations return all properties.
+
+To manage properties for each request you can use <<configuration-steps-with,with()>> configuration option
+`materializeProperties`
[source,groovy]
----
-globals << [g : traversal().withEmbedded(graph).withStrategies(ReferenceElementStrategy)]
+g.with('materializeProperties', 'tokens').V()
----
-This configuration is global to Gremlin Server and therefore all methods of connection will always return elements
-without properties. If this strategy is not included, then there are other considerations to take into account such as
-the connection type (i.e. script or bytecode) and the serializer.
+The `tokens` value for the `materializeProperties` means that need to return only `id` and `label`. Another option
+`all` used to indicate that all properties should be returned and is the default value.
-For script-based requests, users should take care when returning graph elements. By default, elements will be returned
-as "detached elements" and depending on the serializer being used those detached elements may or may not have their
-properties carried with them. Gryo and GraphSON serializers will write all properties in the return payload in this
-case but GraphBinary will not. Therefore, script-based requests that use Gryo or GraphSON should definitely follow the
-best practice of only returning the data required by the application.
+In some cases it can be inconvenient to load vertices with properties due to fat data or for compatibility reasons.
+That can be solved by utilize `ReferenceElementStrategy` when creating the out-of-the-box `GraphTraversalSource`.
+As the name suggests, this means that elements will be detached by reference and will therefore not have properties
+included. The relevant configuration from the Gremlin Server initialization script looks like this:
-For bytecode-based requests, graph elements have reference detachment and thus only return the `id` and `label` of
-the elements. While this approach alleviates a potential performance problem that the script approach exposes, it is
-still important to follow the practice of being specific about the data that is required by the requesting application
-as it won't arrive on the client side without that declaration.
-
-Ultimately, the detachment model should have little impact to Gremlin usage if the best practice of specifying only
-the data required by the application is adhered to. In other words, while there may be a difference in the contents
-of return values for these traversals:
-
-[source,java]
+[source,groovy]
----
-// properties returned from g.V().hasLabel('person') because this is using the
-// Script API with full detachment
-Cluster cluster = Cluster.open();
-Client client = cluster.connect();
-ResultSet results = client.submit("g.V().hasLabel('person')");
-
-// no properties returned from g.V().hasLabel("person") because this is using
-// Bytecode API with reference detachment
-GraphTraversalSource g = traversal().withRemote('conf/remote-graph.properties');
-List<Vertex> results = g.V().hasLabel("person").toList();
+globals << [g : traversal().withEmbedded(graph).withStrategies(ReferenceElementStrategy)]
----
-There is no difference if re-written using the best practice of requesting only the data the application needs:
+This configuration is global to Gremlin Server and therefore all methods of connection will always return elements
+without properties. If this strategy is not included, then elements returned with properties.
Review Comment:
```suggestion
without properties. If this strategy is not included, then elements will be returned with properties.
```
##########
docs/src/reference/gremlin-applications.asciidoc:
##########
@@ -2250,50 +2250,36 @@ to as "detached elements" and cases where properties are not included are "refer
With the type of request and detachment model in mind, it is now possible to discuss how best to consider element
properties in relation to them all in concert.
-By default, Gremlin Server sample configurations utilize `ReferenceElementStrategy` when creating the out-of-the-box
-`GraphTraversalSource`. As the name suggests, this means that elements will be detached by reference and will
-therefore not have properties included. The relevant configuration from the Gremlin Server initialization script looks
-like this:
+By default, Gremlin Server sample configurations return all properties.
+
+To manage properties for each request you can use <<configuration-steps-with,with()>> configuration option
+`materializeProperties`
[source,groovy]
----
-globals << [g : traversal().withEmbedded(graph).withStrategies(ReferenceElementStrategy)]
+g.with('materializeProperties', 'tokens').V()
----
-This configuration is global to Gremlin Server and therefore all methods of connection will always return elements
-without properties. If this strategy is not included, then there are other considerations to take into account such as
-the connection type (i.e. script or bytecode) and the serializer.
+The `tokens` value for the `materializeProperties` means that need to return only `id` and `label`. Another option
+`all` used to indicate that all properties should be returned and is the default value.
-For script-based requests, users should take care when returning graph elements. By default, elements will be returned
-as "detached elements" and depending on the serializer being used those detached elements may or may not have their
-properties carried with them. Gryo and GraphSON serializers will write all properties in the return payload in this
-case but GraphBinary will not. Therefore, script-based requests that use Gryo or GraphSON should definitely follow the
-best practice of only returning the data required by the application.
+In some cases it can be inconvenient to load vertices with properties due to fat data or for compatibility reasons.
+That can be solved by utilize `ReferenceElementStrategy` when creating the out-of-the-box `GraphTraversalSource`.
Review Comment:
```suggestion
That can be solved by utilizing `ReferenceElementStrategy` when creating the out-of-the-box `GraphTraversalSource`.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tinkerpop.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org