This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch 3.7-dev
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/3.7-dev by this push:
new bdf7a218bc Explain properties()-step stream transformation and
meta-properties
bdf7a218bc is described below
commit bdf7a218bcda0a35280d68134f40afa824a0b3dd
Author: Stephen Mallette <[email protected]>
AuthorDate: Mon Jul 27 12:35:25 2026 +0000
Explain properties()-step stream transformation and meta-properties
The properties()-step reference section showed three examples against The
Crew graph but never explained that properties() changes the traversal
stream from Vertex to VertexProperty elements, nor that a VertexProperty is
itself an Element that can carry its own properties (meta-properties). As a
result it was not clear why has('endTime') and valueMap() applied after
properties('location') filter and read the meta-properties of each vertex
property rather than the vertex's own properties.
Expand the prose to describe the stream transformation and the meta-property
concept, cross-reference the vertex-properties and Crew-graph sections, and
annotate the three examples so the four-rows-to-three-rows filtering is
explained alongside the live output.
Assisted-by: Kiro:claude-opus-4.8
---
docs/src/reference/the-traversal.asciidoc | 24 ++++++++++++++++++++----
1 file changed, 20 insertions(+), 4 deletions(-)
diff --git a/docs/src/reference/the-traversal.asciidoc
b/docs/src/reference/the-traversal.asciidoc
index 8ba5f8a78f..e93333cfef 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -3782,15 +3782,31 @@ g.V().hasLabel('person').
[[properties-step]]
=== Properties Step
-The `properties()`-step (*map*) extracts properties from an `Element` in the
traversal stream.
+The `properties()`-step (*map*) extracts properties from an `Element` in the
traversal stream. Unlike
+`values()`, which emits the raw property values, `properties()` transforms the
stream so that it contains
+`VertexProperty` elements rather than the original `Vertex` elements. A
`VertexProperty` is itself an
+`Element`, which means it can carry its own properties — called
meta-properties (see
+<<vertex-properties,vertex properties>>) — and can therefore be traversed
further with steps like `has()`
+and `valueMap()`. The examples below use the <<the-crew-toy-graph,"TinkerPop
Crew">> toy graph, whose
+vertex `1` (marko) has a multi-valued `location` property whose values carry
`startTime` and `endTime`
+meta-properties.
[gremlin-groovy,theCrew]
----
-g.V(1).properties()
-g.V(1).properties('location').valueMap()
-g.V(1).properties('location').has('endTime').valueMap()
+g.V(1).properties() <1>
+g.V(1).properties('location').valueMap() <2>
+g.V(1).properties('location').has('endTime').valueMap() <3>
----
+<1> With no arguments, `properties()` emits a `VertexProperty` for every
property on vertex `1`.
+<2> Supplying the `location` key emits one `VertexProperty` per value, so the
stream now holds four
+`VertexProperty` elements. Because those elements are the `location` vertex
properties themselves,
+`valueMap()` returns the meta-properties (`startTime` and `endTime`) of each
one — four rows — rather than
+the vertex's own properties.
+<3> Since the elements in the stream are `VertexProperty` objects,
`has('endTime')` filters on their
+meta-properties: only the three `location` values that carry an `endTime`
meta-property pass, so
+`valueMap()` reports three rows.
+
*Additional References*
link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#properties(java.lang.String...)++[`properties(String...)`]
