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
commit 45bd9c67d74dad137ac8ae18e073747f89edc7c2 Author: stepmall <[email protected]> AuthorDate: Sat Jul 25 14:32:15 2026 +0000 Add expected output and explanatory callouts to values()-step docs The values()-step reference section listed three examples with no rendered output and only a single sentence of prose, leaving the behavior of the step hard to predict. Add an introductory explanation, numbered callouts on each example, and a note that result order is not guaranteed. The callouts clarify that a no-argument values() returns every property value across all keys, that the sample vertex has a multi-valued location property, and that properties('location').values() extracts meta-property values (startTime/endTime) rather than the city-name values returned by values('location'). The examples remain executable so their output is rendered at build time. Assisted-by: Kiro:claude-opus-4.8 --- docs/src/reference/the-traversal.asciidoc | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc index 8fcf078ec0..2ee333e435 100644 --- a/docs/src/reference/the-traversal.asciidoc +++ b/docs/src/reference/the-traversal.asciidoc @@ -5060,14 +5060,30 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre === Values Step The `values()`-step (*map*) extracts the values of properties from an `Element` in the traversal stream. +When called with one or more property keys it returns the values of just those properties, and when +called with no arguments it returns the values of every property on the element. A vertex property may +itself be multi-valued and may carry meta-properties, and those two cases produce results that are easy +to confuse. The examples below use the "TinkerPop Crew" toy graph, whose vertex `1` (marko) has a +multi-valued `location` property, to illustrate the difference. [gremlin-groovy,theCrew] ---- -g.V(1).values() -g.V(1).values('location') -g.V(1).properties('location').values() +g.V(1).values() <1> +g.V(1).values('location') <2> +g.V(1).properties('location').values() <3> ---- +<1> With no arguments, `values()` emits every property value on the vertex across all of its property +keys. Vertex `1` therefore yields its single `name` value together with each of its `location` values. +<2> Supplying a property key restricts the output to the values of that property. Because vertex `1` has +a multi-valued `location`, four city-name `String` values are returned. +<3> `properties('location')` first selects the `location` properties themselves, so the following +`values()` extracts their meta-property values, the `startTime` and `endTime` years. These are `Integer` +values and are distinct from the city-name `String` values produced by `values('location')` in the +previous line. + +The order in which property values are returned is not guaranteed. + *Additional References* link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#values(java.lang.String...)++[`values(String...)`]
