spmallette commented on code in PR #3458:
URL: https://github.com/apache/tinkerpop/pull/3458#discussion_r3443715013
##########
docs/src/upgrade/release-4.x.x.asciidoc:
##########
@@ -101,6 +70,51 @@ partial work is discarded if the user forgets to call
`commit()`. In Java (both
can still be overridden via `tx.onClose(Transaction.CLOSE_BEHAVIOR.COMMIT)`.
The non-Java GLVs do not support
configuring close behavior and always rollback.
+==== Expanding Dynamic Arguments to Additional Steps
+
+Prior to 4.0, comparing a traverser's value against a dynamically computed
reference required verbose workarounds with
+`where()`, `select()`, and labeled steps. For example, finding all people
older than "marko" previously required:
+
+[source,groovy]
+----
+// Old way: label marko's age, compare via where()
+g.V(1).values("age").as("markosAge").
+ V().hasLabel("person").as("p").
+ values("age").as("otherAge").
+ where("otherAge", gt("markosAge")).
+ select("p").values("name")
+----
+
+This pattern was unintuitive and could not easily compose with other
predicates. With traversal-accepting arguments,
+the same query becomes a single, readable step:
+
+[source,groovy]
+----
+// New way: traversal inside the predicate
+g.V().has("age", P.gt(__.V(1).values("age"))).values("name")
+----
+
+Steps and predicates that previously only accepted literal values now accept
child traversals resolved per-traverser
+at runtime. Affected steps: `has()`, `hasId()`, `hasKey()`, `hasLabel()`,
`hasValue()`, `V()`, `E()`, `property()`,
+`is()`, `where(P)`, and all `P` and `TextP` predicates.
+
+[source,groovy]
+----
+// Multi-source filtering with within()
+g.V().has("name", P.within(__.V(1).out("knows").values("name").fold(),
__.constant("peter")))
+
+// Set multiple properties from a computed Map
+g.V(4).property(__.V(1).project("friendCount").by(__.out("knows").count()))
+----
+
Review Comment:
This needs a summarizing finish of some sort, not to mention a description
of patterns folks should be looking to replace. I would think a lot of `where`
usage is obvious from the first example, but I think it is worth being
explicit. Perhaps consider my comment here:
https://github.com/apache/tinkerpop/pull/3458#issuecomment-4723691197 and see
what might change elsewhere in our docs and then use that to inform what
patterns we should advise about.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
