Github user vasia commented on a diff in the pull request:
https://github.com/apache/flink/pull/576#discussion_r28594064
--- Diff: docs/gelly_guide.md ---
@@ -269,7 +269,15 @@ Neighborhood Methods
Neighborhood methods allow vertices to perform an aggregation on their
first-hop neighborhood.
-`reduceOnEdges()` can be used to compute an aggregation on the neighboring
edges of a vertex, while `reduceOnNeighbors()` has access on both the
neighboring edges and vertices. The neighborhood scope is defined by the
`EdgeDirection` parameter, which takes the values `IN`, `OUT` or `ALL`. `IN`
will gather all in-coming edges (neighbors) of a vertex, `OUT` will gather all
out-going edges (neighbors), while `ALL` will gather all edges (neighbors).
+`groupReduceOnEdges()` can be used to compute an aggregation on the
neighboring edges of a vertex,
+while `groupReduceOnNeighbors()` has access to both the neighboring edges
and vertices. The neighborhood scope
+is defined by the `EdgeDirection` parameter, which takes the values `IN`,
`OUT` or `ALL`. `IN` will gather all in-coming edges (neighbors) of a vertex,
`OUT` will gather all out-going edges (neighbors), while `ALL` will gather all
edges (neighbors).
+
+The `groupReduceOnEdges()` and `groupReduceOnNeighbors()` methods return
zero, one or more values per vertex.
+When returning a single value per vertex, `reduceOnEdges()` or
`reduceOnNeighbors()` should be called
+as they are more efficient. Nevertheless, when the reduce on edges
modifies the value produced per vertex, for
+instance by multiplying it with a constant, `groupReduceOnEdges()` or
`groupReduceOnNeighbors()` must be used
+as illustrated in the third code snippet.
--- End diff --
I would rephrase this into something like the following: "when the
user-defined function to be applied on the neighborhood is associative and
commutative, it is highly advised to use the `reduceOnEdges()` and
`reduceOnNeighbors()` methods. These methods can exploit combiners internally
and significantly improve performance".
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
