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
The following commit(s) were added to refs/heads/master by this push:
new b0c84720d6 Clarify disjunct() set semantics in the Gremlin semantics
docs
b0c84720d6 is described below
commit b0c84720d6bdc187207cc184cf1e8121fe2cbcb2
Author: Stephen Mallette <[email protected]>
AuthorDate: Fri Sep 11 17:10:20 2026 +0000
Clarify disjunct() set semantics in the Gremlin semantics docs
Expand the disjunct() Considerations to describe the symmetric difference
result as an unordered set with no duplicates, explain that membership is
decided by value and type so numerically equal values of different numeric
types are distinct members, and clarify that the null or non-iterable error
applies only to a whole traverser or argument while a NULL element inside an
otherwise valid list is a legal member. This mirrors the recently clarified
difference() step.
Assisted-by: Kiro:claude-opus-4.8
---
docs/src/dev/provider/gremlin-semantics.asciidoc | 17 +++++++++++++++--
1 file changed, 15 insertions(+), 2 deletions(-)
diff --git a/docs/src/dev/provider/gremlin-semantics.asciidoc
b/docs/src/dev/provider/gremlin-semantics.asciidoc
index 986598eab5..1f7a80b96c 100644
--- a/docs/src/dev/provider/gremlin-semantics.asciidoc
+++ b/docs/src/dev/provider/gremlin-semantics.asciidoc
@@ -1762,8 +1762,21 @@ None
*Considerations:*
-A set is returned after the disjunct operation is applied so there won't be
duplicates. This step only applies to list
-types which means that non-iterable types (including null) will cause
exceptions to be thrown.
+The disjunct operation is the symmetric difference of two lists. The result
contains the members that appear in the
+incoming traverser or in the provided argument but not in both. The operation
is symmetric, so exchanging the incoming
+traverser and the argument does not change the result. The result is a `SET`,
so it contains no duplicates, and its
+iteration order is unspecified. In particular the result does not preserve the
order of either input list, so a
+traversal that depends on a particular member order orders the result
explicitly.
+
+Membership of the result is decided by comparing members by value and by type.
Numerically equal values of different
+numeric types, such as an `INT` and a `LONG` of the same magnitude, are
treated as distinct members. A `NULL` is a
+legal member of either list and is compared in the same way, so a `NULL` is
excluded from the result only when it
+appears in both inputs.
+
+This step only applies to lists. An error is raised when the incoming
traverser or the argument is itself `NULL` or is
+not iterable, while a `NULL` that appears as an element of an otherwise
iterable list is permitted and behaves as
+described above. When the argument is supplied as a `Traversal`, that
traversal produces the comparison list as a
+single result rather than as a stream of separate results.
*Exceptions:*
