You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2025/08/06 12:08:27 UTC

(tinkerpop) branch master updated (8fc5b9be3b -> d3a6421790)

This is an automated email from the ASF dual-hosted git repository.

spmallette pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git


    from 8fc5b9be3b Merge branch '3.8-dev'
     add 6b29a6659e Backported 62a3935152354eea54f2cfadc39edf10ebe2005d  from 4.x
     add 343eef4a85 Backported e8b9532fc0ec811460e97ebf5e00b8b9ec9192ac from 4.x
     add 8e26f77d55 Backported more discard() steps from 4.x
     new f57584be9a Merge branch '3.8-dev'
     new d3a6421790 Minor text changes after merge of discard/none backport to 3.8 CTR

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 CHANGELOG.asciidoc                                 |  2 ++
 docs/src/dev/provider/gremlin-semantics.asciidoc   |  6 ++---
 docs/src/reference/the-traversal.asciidoc          | 28 +++++++++++++++-------
 docs/src/upgrade/release-3.8.x.asciidoc            | 13 ++++++++++
 .../traversal/dsl/graph/GraphTraversal.java        |  2 +-
 5 files changed, 38 insertions(+), 13 deletions(-)


(tinkerpop) 02/02: Minor text changes after merge of discard/none backport to 3.8 CTR

Posted by sp...@apache.org.
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 d3a6421790ce819dd7794cb1bc1b8bb6b4e639b4
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Wed Aug 6 08:07:35 2025 -0400

    Minor text changes after merge of discard/none backport to 3.8 CTR
---
 CHANGELOG.asciidoc                                 |  2 ++
 docs/src/dev/provider/gremlin-semantics.asciidoc   |  6 ++---
 docs/src/reference/the-traversal.asciidoc          | 28 +++++++++++++++-------
 docs/src/upgrade/release-3.8.x.asciidoc            | 13 ++++++++++
 .../traversal/dsl/graph/GraphTraversal.java        |  2 +-
 5 files changed, 38 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
index 6b31f04dfb..6135c3271b 100644
--- a/CHANGELOG.asciidoc
+++ b/CHANGELOG.asciidoc
@@ -95,6 +95,8 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 This release also includes changes from <<release-3-7-XXX, 3.7.XXX>>.
 
 * Removed Vertex/ReferenceVertex from grammar. Use vertex id in traversals now instead.
+* Renamed `none()` step to `discard()`.
+* Repurposed `none()` step as a list filtering step with the signature `none(P)`.
 * Modified mathematical operators to prevent overflows in steps such as `sum()` and 'sack()' to prefer promotion to the next highest number type.
 * Added `DateTime` ontop of the existing 'datetime' grammar.
 * Added `UUID()` and `UUID(value)` to grammar.
diff --git a/docs/src/dev/provider/gremlin-semantics.asciidoc b/docs/src/dev/provider/gremlin-semantics.asciidoc
index 979d44874a..14fa9a37af 100644
--- a/docs/src/dev/provider/gremlin-semantics.asciidoc
+++ b/docs/src/dev/provider/gremlin-semantics.asciidoc
@@ -1835,7 +1835,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#mergev-step[reference]
 [[none-step]]
 === none()
 
-*Description:* Filters array data from the Traversal Stream if none of the array's items match the supplied predicate.
+*Description:* Filters array data from the traversal stream if none of the array's items match the supplied predicate.
 
 *Syntax:* `none(P predicate)`
 
@@ -1847,7 +1847,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#mergev-step[reference]
 
 *Arguments:*
 
-* `predicate` - The predicate to use to test each value in the array data.
+* `predicate` - The predicate used to test each value in the array data.
 
 *Modulation:*
 
@@ -1856,7 +1856,7 @@ None
 *Considerations:*
 
 Each value will be tested using the supplied predicate. Empty lists always pass through and null/non-list traversers
-will be filtered out of the Traversal Stream.
+will be filtered out of the traversal stream.
 
 *Exceptions*
 
diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc
index c2fb12d633..b105ecac42 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -1515,12 +1515,23 @@ link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#difference-step++[`
 [[discard-step]]
 === Discard Step
 
-The `discard()`-step (*filter*) filters all objects from a traversal stream. It is especially useful for traversals
-that are executed remotely where returning results is not useful and the traversal is only meant to generate
-side-effects. Choosing not to return results saves in serialization and network costs as the objects are filtered on
-the remote end and not returned to the client side. Typically, this step does not need to be used directly and is
-quietly used by the `iterate()` terminal step which appends `discard()` to the traversal before actually cycling through
-results.
+The `discard()`-step (*filter*) filters all objects from a traversal stream. It is helpful with <<branch-step>> types
+of steps where a particular branch of code should "throw away" traversers. In the following example, traversers that
+don't match are filtered out of the traversal stream.
+
+[gremlin-groovy,modern]
+----
+g.V().choose(T.label).
+        option("person", __.out("knows").values("name")).
+        option("bleep", __.out("created").values("name")).
+        option(none, discard())
+----
+
+It is also useful for traversals that are executed remotely where returning results is not useful and the traversal is
+only meant to generate side-effects. Choosing not to return results saves in serialization and network costs as the
+objects are filtered on the remote end and not returned to the client side. Typically, this step does not need to be
+used directly and is quietly used by the `iterate()` terminal step which appends `discard()` to the traversal before
+actually cycling through results.
 
 *Additional References*
 
@@ -3242,9 +3253,8 @@ the supplied predicate and if none of the items pass then the traverser is passe
 filtered. Empty lists are passed along but null or non-iterable traversers are filtered out.
 
 
-NOTE: Prior to release 4.0.0, `none()` was a traversal discarding step primarily used by <<iterate-step,`iterate()`>>. This step has
-since been renamed to <<discard-step,`discard()`>>
-
+NOTE: Prior to release 3.8.0, `none()` was a traversal discarding step primarily used by <<iterate-step,`iterate()`>>.
+This step has since been renamed to <<discard-step,`discard()`>>
 
 [gremlin-groovy,modern]
 ----
diff --git a/docs/src/upgrade/release-3.8.x.asciidoc b/docs/src/upgrade/release-3.8.x.asciidoc
index 85c8b495d4..0363f70bb7 100644
--- a/docs/src/upgrade/release-3.8.x.asciidoc
+++ b/docs/src/upgrade/release-3.8.x.asciidoc
@@ -58,6 +58,13 @@ gremlin> g.V().sack(assign).by(__.hasLabel('person').count().asBool()).sack(and)
 See: link:https://tinkerpop.apache.org/docs/3.8.0/reference/#asBool-step[asBool()-step]
 See: link:https://issues.apache.org/jira/browse/TINKERPOP-3175[TINKERPOP-3175]
 
+==== none() and discard()
+
+There is a complicated relationship with the `none()` and `discard()` steps that begs some discussion. Prior to this
+version, the `none()` step was used to "throw away" all traversers that passed into it. In 3.8.0, that step has been
+renamed to `discard()`. The `discard()` step with its verb tone arguably makes for a better name for that feature, but
+it also helped make room for `none()` to be repurposed as `none(P)` which is a complement to `any(P)` and `all(P) steps.
+
 ==== Set minimum Java version to 11
 
 TinkerPop 3.8 requires a minimum of Java 11 for building and running. Support for Java 1.8 has been dropped.
@@ -438,6 +445,12 @@ link:https://issues.apache.org/jira/browse/TINKERPOP-2974[TINKERPOP-2974]
 
 ==== Graph System Providers
 
+===== NoneStep Renaming
+
+The `DiscardStep` is now renamed to `DiscardStep`. Providers who developed strategies or other optimizations around
+`DiscardStep` should switch to `DiscardStep`. Note that `DiscardStep` has been repurposed as `none(P)` for filtering
+collections as a complement to `any(P)` and `all(P)`.
+
 ==== Set minimum Java version to 11
 
 TinkerPop 3.8 requires a minimum of Java 11 for building and running. Support for Java 1.8 has been dropped.
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.java
index 131d2b72e1..52976537f1 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.java
@@ -3581,7 +3581,7 @@ public interface GraphTraversal<S, E> extends Traversal<S, E> {
      * @param predicate the filter to apply
      * @return the traversal with an appended {@link NoneStep}
      * @see <a href="http://tinkerpop.apache.org/docs/${project.version}/reference/#none-step" target="_blank">Reference Documentation - None Step</a>
-     * @since 4.0.0
+     * @since 3.8.0
      */
     public default <S2> GraphTraversal<S, E> none(final P<S2> predicate) {
         this.asAdmin().getGremlinLang().addStep(Symbols.none, predicate);


(tinkerpop) 01/02: Merge branch '3.8-dev'

Posted by sp...@apache.org.
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 f57584be9a096124b15478ffea9b70e29ec72561
Merge: 8fc5b9be3b 8e26f77d55
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Wed Aug 6 07:32:53 2025 -0400

    Merge branch '3.8-dev'