This is an automated email from the ASF dual-hosted git repository.
Cole-Greer pushed a commit to branch multi-label-toy-graph
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/multi-label-toy-graph by this
push:
new b2a2f43098 Convert read-only multi-label doc examples to use the zoo
graph
b2a2f43098 is described below
commit b2a2f43098150b1232658d55deb3051979d6dab4
Author: Cole Greer <[email protected]>
AuthorDate: Tue Jul 7 19:44:15 2026 -0700
Convert read-only multi-label doc examples to use the zoo graph
Converts 7 of the 14 executable gremlin-groovy examples added for
multi-label support in the-traversal.asciidoc to use [gremlin-groovy,theZoo]
instead of hand-building a single-vertex TinkerGraph inline:
- By Step: group().by(label) vs by(labels().fold())
- Choose Step: choose(T.label) non-determinism
- ElementMap: with("multilabel") example
- Has Step: chained hasLabel() AND/OR semantics
- Label Step
- Labels Step
- ValueMap: with("multilabel") example
Each converted example is read-only after the block's own setup, so there
is no risk of mutation leaking across examples: the docs preprocessor opens
a fresh TinkerFactory.createTheZoo() graph for every [gremlin-groovy,theZoo]
block. Kept the AddLabel, DropLabel, and mergeV examples on hand-built empty
graphs since they depend on precise, narrative-driven mutation sequences or
a LabelCardinality.ONE case the zoo graph can't represent.
Assisted-by: Kiro:claude-sonnet-5
---
docs/src/reference/the-traversal.asciidoc | 104 ++++++++++--------------------
1 file changed, 34 insertions(+), 70 deletions(-)
diff --git a/docs/src/reference/the-traversal.asciidoc
b/docs/src/reference/the-traversal.asciidoc
index ebff11d799..ec2d4649cb 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -1112,23 +1112,17 @@ multi-label vertex returns only one label chosen
non-deterministically. Steps li
`dedup()`, `order()`, `path()`, `simplePath()`, and `tree()` that modulate
`by(label)` will therefore behave
unpredictably on multi-label vertices.
-[gremlin-groovy]
+[gremlin-groovy,theZoo]
----
-conf = new BaseConfiguration()
-conf.setProperty("gremlin.tinkergraph.vertexLabelCardinality", "ZERO_OR_MORE")
-graph = TinkerGraph.open(conf)
-g = traversal().with(graph)
-g.addV('person','employee').property('name','marko')
-g.addV('person').property('name','vadas')
g.V().group().by(label).by(values('name').fold()) <1>
g.V().group().by(labels().fold()).by(values('name').fold()) <2>
----
-<1> marko has both the "person" and "employee" labels, but is grouped under
only one of them, chosen
-non-deterministically, so this grouping is not reliable for multi-label
vertices.
-<2> Grouping by the full set of labels instead keeps marko under `[person,
employee]`, distinct from vadas under
-`[person]`, regardless of which order the labels were assigned in. Prefer this
pattern with the
-<<labels-step,`labels()`>> step over `by(label)` for graphs that support
multiple labels per vertex.
+<1> `atlas` carries the "animal", "reptile", "aquatic", and "endangered"
labels, but is grouped under only one of
+them, chosen non-deterministically, so this grouping is not reliable for
multi-label vertices.
+<2> Grouping by the full set of labels instead keeps each animal under its own
distinct combination of labels.
+Prefer this pattern with the <<labels-step,`labels()`>> step over `by(label)`
for graphs that support multiple
+labels per vertex.
*Additional References*
@@ -1323,22 +1317,17 @@ On the "modern" graph, that works reliably because each
vertex has exactly one l
tells a different story, since `choose(T.label)` still selects a branch based
on a single label chosen
non-deterministically from the full set:
-[gremlin-groovy]
+[gremlin-groovy,theZoo]
----
-conf = new BaseConfiguration()
-conf.setProperty("gremlin.tinkergraph.vertexLabelCardinality", "ZERO_OR_MORE")
-graph = TinkerGraph.open(conf)
-g = traversal().with(graph)
-g.addV('person','employee').property('name','marko')
-g.V().has('name','marko').choose(T.label).
- option('person', constant('routed as a person')).
- option('employee', constant('routed as an employee')) <1>
+g.V().has('name','tux').choose(T.label).
+ option('bird', constant('routed as a bird')).
+ option('aquatic', constant('routed as aquatic')) <1>
----
-<1> marko carries both the "person" and "employee" labels, so which `option()`
branch is taken depends on which
-label the graph happens to return from `label()` and is not guaranteed to be
consistent. Filtering with
-<<has-step,`hasLabel()`>> beforehand, or restructuring the choice around
`labels()`, gives predictable results for
-multi-label vertices.
+<1> `tux` carries the "animal", "bird", "aquatic", and "endangered" labels, so
which `option()` branch is taken
+depends on which label the graph happens to return from `label()` and is not
guaranteed to be consistent. Filtering
+with <<has-step,`hasLabel()`>> beforehand, or restructuring the choice around
`labels()`, gives predictable results
+for multi-label vertices.
The `Pick` enum was introduced in an example earlier to handle non-matching
scenarios. The following `Pick` options may
be used with `choose()`:
@@ -1954,18 +1943,13 @@ as the `id` is the only available data to the star
graph.
For multi-label graphs, `elementMap()` returns labels as a single string by
default. To receive all labels as a
set, use `with("multilabel")` either per-traversal or on a persistent source:
-[gremlin-groovy]
+[gremlin-groovy,theZoo]
----
-conf = new BaseConfiguration()
-conf.setProperty("gremlin.tinkergraph.vertexLabelCardinality", "ZERO_OR_MORE")
-graph = TinkerGraph.open(conf)
-g = traversal().with(graph)
-g.addV('person').property('name','marko').addLabel('employee').addLabel('manager').iterate()
-g.V().has('name','marko').elementMap() <1>
-g.with("multilabel").V().has('name','marko').elementMap() <2>
+g.V().has('name','tux').elementMap() <1>
+g.with("multilabel").V().has('name','tux').elementMap() <2>
gml = g.with("multilabel")
-gml.V().has('name','marko').elementMap() <3>
-gml.V().has('name','marko').valueMap(true) <4>
+gml.V().has('name','tux').elementMap() <3>
+gml.V().has('name','tux').valueMap(true) <4>
----
<1> Without `"multilabel"`, the label entry is a single string.
@@ -2326,20 +2310,15 @@ the key,value pairs for those vertices.
Chained `hasLabel()` calls requires that a vertex carry all of the specified
labels, which matters in cases
where a vertex can have more than one label:
-[gremlin-groovy]
+[gremlin-groovy,theZoo]
----
-conf = new BaseConfiguration()
-conf.setProperty("gremlin.tinkergraph.vertexLabelCardinality", "ZERO_OR_MORE")
-graph = TinkerGraph.open(conf)
-g = traversal().with(graph)
-g.addV('person','employee').property('name','marko')
-g.addV('person').property('name','vadas')
-g.V().hasLabel('person','employee').values('name') <1>
-g.V().hasLabel('person').hasLabel('employee').values('name') <2>
+g.V().hasLabel('bird','reptile').values('name') <1>
+g.V().hasLabel('bird').hasLabel('aquatic').values('name') <2>
----
-<1> OR semantics: matches both marko and vadas, since each has at least one of
"person" or "employee".
-<2> Chaining `hasLabel()` calls requires both labels to be present, matching
only marko.
+<1> OR semantics: matches `tux`, `atlas`, and `monty`, since each has at least
one of "bird" or "reptile".
+<2> Chaining `hasLabel()` calls requires both labels to be present, matching
only `tux`, which has both "bird" and
+"aquatic".
*Additional References*
@@ -2732,19 +2711,14 @@ g.V(1).properties().label()
For elements that carry exactly one label, as in the "modern" graph above,
`label()` behaves as expected. A
multi-label vertex complicates matters, since `label()` still returns only a
single `String`:
-[gremlin-groovy]
+[gremlin-groovy,theZoo]
----
-conf = new BaseConfiguration()
-conf.setProperty("gremlin.tinkergraph.vertexLabelCardinality", "ZERO_OR_MORE")
-graph = TinkerGraph.open(conf)
-g = traversal().with(graph)
-g.addV('person','employee').property('name','marko')
-g.V().has('name','marko').label() <1>
-g.V().has('name','marko').labels() <2>
+g.V().has('name','tux').label() <1>
+g.V().has('name','tux').labels() <2>
----
-<1> marko carries both the "person" and "employee" labels, but `label()`
returns only one of them, chosen
-non-deterministically.
+<1> `tux` carries the "animal", "bird", "aquatic", and "endangered" labels,
but `label()` returns only one of them,
+chosen non-deterministically.
<2> Use the <<labels-step,`labels()`>> step instead to reliably retrieve every
label a vertex carries.
*Additional References*
@@ -2757,13 +2731,8 @@
link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre
The `labels()`-step (*flatMap*) takes an `Element` and emits each of its
labels as a separate traverser. For elements
with a single label this behaves identically to `label()`. For multi-label
elements, it emits one traverser per label.
-[gremlin-groovy]
+[gremlin-groovy,theZoo]
----
-conf = new BaseConfiguration()
-conf.setProperty("gremlin.tinkergraph.vertexLabelCardinality", "ZERO_OR_MORE")
-graph = TinkerGraph.open(conf)
-g = traversal().with(graph)
-g.addV('person').property('name','marko').addLabel('employee').iterate()
g.V().labels()
g.V().labels().count()
----
@@ -5685,15 +5654,10 @@
g.V().hasLabel('person').properties('location').valueMap().with(WithOptions.toke
For multi-label graphs, the label value in the map is a single string by
default. Use `with("multilabel")` to
receive all labels as a set:
-[gremlin-groovy]
+[gremlin-groovy,theZoo]
----
-conf = new BaseConfiguration()
-conf.setProperty("gremlin.tinkergraph.vertexLabelCardinality", "ZERO_OR_MORE")
-graph = TinkerGraph.open(conf)
-g = traversal().with(graph)
-g.addV('person').property('name','marko').addLabel('employee').iterate()
-g.V().has('name','marko').valueMap(true) <1>
-g.with("multilabel").V().has('name','marko').valueMap(true) <2>
+g.V().has('name','tux').valueMap(true) <1>
+g.with("multilabel").V().has('name','tux').valueMap(true) <2>
----
<1> Without `"multilabel"`, the label entry is a single string.
