[tinkerpop] branch 3.6-dev updated: Adds additional docs for dedup step (#1933)

[xi...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

xiazcy pushed a commit to branch 3.6-dev
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git


The following commit(s) were added to refs/heads/3.6-dev by this push:
     new a47da0b8b0 Adds additional docs for dedup step (#1933)
a47da0b8b0 is described below

commit a47da0b8b0b7a19c5c95a5fbfebc2b9e885d05dc
Author: Cole Greer <11...@users.noreply.github.com>
AuthorDate: Wed Jan 11 11:45:54 2023 -0800

    Adds additional docs for dedup step (#1933)
    
    Adds a section in the gremlin-semantics docs for the dedup step.
    
    Main purpose of this is to highlight some extra considerations with
    dedup implementation which are somewhat beyond the scope of the
    reference docs.
---
 docs/src/dev/provider/gremlin-semantics.asciidoc | 49 +++++++++++++++++++++++-
 docs/src/reference/the-traversal.asciidoc        |  3 +-
 2 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/docs/src/dev/provider/gremlin-semantics.asciidoc b/docs/src/dev/provider/gremlin-semantics.asciidoc
index 0557f1fa6a..4acd384c7e 100644
--- a/docs/src/dev/provider/gremlin-semantics.asciidoc
+++ b/docs/src/dev/provider/gremlin-semantics.asciidoc
@@ -730,4 +730,51 @@ resolve to a `Map`.
 * As is common to Gremlin, it is expected that `Traversal` arguments may utilize `sideEffect()` steps.
 
 See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/MergeVertexStep.java[source],
-link:https://tinkerpop.apache.org/docs/x.y.z/reference/#mergev-step[reference]
\ No newline at end of file
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#mergev-step[reference]
+
+=== dedup()
+
+*Description:* Removes repeatedly seen results from the Traversal Stream.
+
+*Syntax:* `dedup()` | `dedup(labels)`
+
+[width="100%",options="header"]
+|=========================================================
+|Start Step |Mid Step |Modulated |Domain |Range
+|N |Y |`by()` |`any` |`any`
+|=========================================================
+
+*Arguments:*
+
+* `labels` - If dedup() is provided a list of labels, then it will ensure that the de-duplication
+is not with respect to the current traverser object, but to the path history of the traverser.
+For Example:
+`g.V().as('a').out('created').as('b').in('created').as('c').dedup('a','b').select('a','b','c')`
+will filter out any such `a` and `b` pairs which have previously been seen.
+
+*Modulation:*
+
+* `by()` - Performs dedup according to the property specified in the by modulation. For example:
+`g.V().dedup().by("name")` will filter out vertices with duplicate names.
+
+*Considerations:*
+
+* There is no guarantee that ordering of results will be preserved across a dedup step.
+* There is no guarantee which element is selected as the survivor when filtering duplicates.
+
+For Example, Given a graph with the following 3 vertices:
+
+[width="100%",options="header"]
+|=========================================================
+|name |age
+|Alex |38
+|Bob |45
+|Chloe |38
+|=========================================================
+
+`g.V().order().by("name", Order.asc).barrier().dedup().by("age").values("name")` can return any of
+`["Alex", "Bob"]`, `["Bob", "Alex"]`, `["Bob", "Chloe"]`, or `["Chloe", "Bob"]`
+
+
+See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/filter/DedupGlobalStep.java[source],
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dedup-step[reference]
\ No newline at end of file
diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc
index e3943ac18b..1ac796ae86 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -1211,7 +1211,8 @@ g.V().as('a').both().as('b').both().as('c').
 
 link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#dedup-org.apache.tinkerpop.gremlin.process.traversal.Scope-java.lang.String...-++[`dedup(Scope,String...)`],
 link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#dedup-java.lang.String...-++[`dedup(String...)`],
-link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/Scope.html++[`Scope`]
+link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/Scope.html++[`Scope`],
+link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#_dedup++[`Semantics`]
 
 [[drop-step]]
 === Drop Step