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:29 UTC
(tinkerpop) 02/02: Minor text changes after merge of discard/none backport to 3.8 CTR
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);