diff --git a/docs/src/dev/provider/gremlin-semantics.asciidoc b/docs/src/dev/provider/gremlin-semantics.asciidoc index f2167c75c0c..1ef5dfe65dd 100644 --- a/docs/src/dev/provider/gremlin-semantics.asciidoc +++ b/docs/src/dev/provider/gremlin-semantics.asciidoc @@ -529,7 +529,7 @@ understand implementation expectations. *Description:* Filters array data from the Traversal Stream if all of the array's items match the supplied predicate. -*Syntax:* `all(Predicate)` +*Syntax:* `all(P predicate)` [width="100%",options="header"] |========================================================= @@ -539,7 +539,7 @@ understand implementation expectations. *Arguments:* -* `Predicate` - The predicate to use to test each value in the array data. +* `predicate` - The predicate to use to test each value in the array data. *Modulation:* @@ -562,7 +562,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#all-step[reference] *Description:* Filters array data from the Traversal Stream if any of the array's items match the supplied predicate. -*Syntax:* `any(Predicate)` +*Syntax:* `any(P predicate)` [width="100%",options="header"] |========================================================= @@ -572,7 +572,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#all-step[reference] *Arguments:* -* `Predicate` - The predicate to use to test each value in the array data. +* `predicate` - The predicate to use to test each value in the array data. *Modulation:* @@ -621,7 +621,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asDate-step[reference] *Description:* Returns the value of incoming traverser as strings, or if `Scope.local` is specified, returns each element inside incoming list traverser as string. -*Syntax:* `asString()` | `asString(Scope)` +*Syntax:* `asString()` | `asString(Scope scope)` [width="100%",options="header"] |========================================================= @@ -632,8 +632,8 @@ incoming list traverser as string. *Arguments:* * `scope` - Determines the type of traverser it operates on. Both scopes will operate on the level of individual traversers. -The `global` scope will operate on individual traverser, casting all (except null) to string. The `local` scope will behave like -`global` for everything except lists, where it will cast individual non-null elements inside the list into string and return a +The `global` scope will operate on individual traverser, casting all (except `null`) to string. The `local` scope will behave like +`global` for everything except lists, where it will cast individual non-`null` elements inside the list into string and return a list of string instead. Null values from the incoming traverser are not processed and remain as null when returned. @@ -641,7 +641,8 @@ Null values from the incoming traverser are not processed and remain as null whe *Exceptions* None -See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringStep.java[source], +See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsStringLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asString-step[reference] [[call-step]] @@ -649,7 +650,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asString-step[reference] *Description:* Provides support for provider-specific service calls. -*Syntax:* `call()` | `call(String, Map)` | `call(String, Traversal)` | `call(String, Map, Traversal)` +*Syntax:* `call()` | `call(String service, Map params)` | `call(String service, Traversal childTraversal)` | `call(String service, Map params, Traversal childTraversal)` [width="100%",options="header"] |========================================================= @@ -659,10 +660,10 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asString-step[reference] *Arguments:* -* `String` - The name of the service call. -* `Map` - A collection of static parameters relevant to the particular service call. Keys and values can be any +* `service` - The name of the service call. +* `params` - A collection of static parameters relevant to the particular service call. Keys and values can be any type currently supported by the Gremlin type system. -* `Traversal` - A traversal used to dynamically build at query time a collection of parameters relevant to the service +* `childTraversal` - A traversal used to dynamically build at query time a collection of parameters relevant to the service call. *Modulation:* @@ -734,7 +735,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#call-step[reference] *Description:* Appends one list to the other and returns the result to the Traversal Stream. -*Syntax:* `combine(Object)` +*Syntax:* `combine(Object values)` [width="100%",options="header"] |========================================================= @@ -744,7 +745,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#call-step[reference] *Arguments:* -* `Object` - A list of items (as an Iterable or an array) or a traversal that will produce a list of items. +* `values` - A list of items (as an Iterable or an array) or a traversal that will produce a list of items. *Modulation:* @@ -763,14 +764,14 @@ will cause exceptions to be thrown. See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/CombineStep.java[source], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#combine-step[reference], -link:https://tinkerpop.apache.org/docs/x.y.z/reference/#merge-step[merge() reference], +link:https://tinkerpop.apache.org/docs/x.y.z/reference/#merge-step[merge() reference] [[concat-step]] === concat() *Description:* Concatenates the incoming String traverser with the input String arguments, and return the joined String. -*Syntax:* `concat()` | `concat(String...)` | `concat(Traversal, Traversal...)` +*Syntax:* `concat()` | `concat(String... concatStrings)` | `concat(Traversal concatTraveral, Traversal... otherConcatTraverals)` [width="100%",options="header"] |========================================================= @@ -802,7 +803,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#concat-step[reference] *Description:* Increase value of input Date. -*Syntax:* `dateAdd(DT, Integer)` +*Syntax:* `dateAdd(DT dateToken, Integer value)` [width="100%",options="header"] |========================================================= @@ -812,8 +813,8 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#concat-step[reference] *Arguments:* -* `DT` - Date token enum. Supported values `second`, `minute`, `hour`, `day`. -* `Integer` - The number of units, specified by the DT Token, to add to the incoming values. May be negative for subtraction. +* `dateToken` - Date token enum. Supported values `second`, `minute`, `hour`, `day`. +* `value` - The number of units, specified by the DT Token, to add to the incoming values. May be negative for subtraction. *Exceptions* @@ -827,7 +828,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dateAdd-step[reference] *Description:* Returns the difference between two Dates in epoch time. -*Syntax:* `dateDiff(Date)` | `dateDiff(Traversal)` +*Syntax:* `dateDiff(Date value)` | `dateDiff(Traversal dateTraversal)` [width="100%",options="header"] |========================================================= @@ -837,8 +838,8 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dateAdd-step[reference] *Arguments:* -* `Date` - Date for subtraction. -* `Traversal` - The `Traversal` value must resolve to a `Date`. The first result returned from the traversal will be +* `value` - Date for subtraction. +* `dateTraversal` - The `Traversal` value must resolve to a `Date`. The first result returned from the traversal will be subtracted with the incoming traverser. If argument resolves as `null` then incoming date will not be changed. @@ -855,7 +856,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dateDiff-step[reference] *Description:* Removes repeatedly seen results from the Traversal Stream. -*Syntax:* `dedup()` | `dedup(labels)` +*Syntax:* `dedup()` | `dedup(String... labels)` | `dedup(Scope scope, String... labels)` [width="100%",options="header"] |========================================================= @@ -865,6 +866,10 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dateDiff-step[reference] *Arguments:* +* `scope` - Determines the scope in which `dedup` is applied. +The `global` scope will drop duplicate values across the global stream of traversers. The `local` scope operates at the +individual traverser level, and will remove duplicate values from within a collection. + * `labels` - If `dedup()` is provided a list of labels, then it will ensure that the de-duplication is not with respect to the current traverser object, but to the path history of the traverser. @@ -911,6 +916,7 @@ can return any of: `["Alex", "Bob"]`, `["Bob", "Alex"]`, `["Bob", "Chloe"]`, or `["Chloe", "Bob"]` See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/filter/DedupGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/DedupLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dedup-step[reference] [[difference-step]] @@ -918,7 +924,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dedup-step[reference] *Description:* Adds the difference of two lists to the Traversal Stream. -*Syntax:* `difference(Object)` +*Syntax:* `difference(Object values)` [width="100%",options="header"] |========================================================= @@ -928,7 +934,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dedup-step[reference] *Arguments:* -* `Object` - A list of items (as an Iterable or an array) or a traversal that will produce a list of items. +* `values` - A list of items (as an Iterable or an array) or a `Traversal` that will produce a list of items. *Modulation:* @@ -953,7 +959,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#difference-step[referenc *Description:* Adds the disjunct set to the Traversal Stream. -*Syntax:* `disjunct(Object)` +*Syntax:* `disjunct(Object values)` [width="100%",options="header"] |========================================================= @@ -963,8 +969,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#difference-step[referenc *Arguments:* -* `Object` - A list of items (as an Iterable or an array). -* `Traversal` - A traversal that will produce a list of items. +* `values` - A list of items (as an Iterable or an array) or a `Traversal` that will produce a list of items. *Modulation:* @@ -1009,17 +1014,17 @@ None *Description:* a mid-traversal step which will handle result formatting to string values. -*Syntax:* `format(String)` +*Syntax:* `format(String formatString)` [width="100%",options="header"] |========================================================= |Start Step |Mid Step |Modulated |Domain |Range -|N |Y |Y |`any` |`String` +|N |Y |`by()` |`any` |`String` |========================================================= *Arguments:* -Format string. Variables can be represented with `%{variable_name}` notation. +* `formatString` - Variables can be represented with `%{variable_name}` notation. Positional arguments can be used as `%{_}` token. Can be used multiple times. The variable values are used in the order that the first one will be found: Element properties, then Scope values. If value for some variable was not found, then the result is filtered out. @@ -1042,7 +1047,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#format-step[reference] *Description:* Returns the length of the incoming string or list, if `Scope.local` is specified, returns the length of each string elements inside incoming list traverser. -*Syntax:* `length()` | `length(Scope)` +*Syntax:* `length()` | `length(Scope scope)` [width="100%",options="header"] |========================================================= @@ -1061,7 +1066,8 @@ Null values from the incoming traverser are not processed and remain as null whe * For `Scope.global` or parameterless function calls, if the incoming traverser is a non-String value then an `IllegalArgumentException` will be thrown. * For `Scope.local`, if the incoming traverser is not a string or a list of strings then an `IllegalArgumentException` will be thrown. -See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/LengthStep.java[source], +See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/LengthGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/LengthLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#length-step[reference] [[intersect-step]] @@ -1069,7 +1075,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#length-step[reference] *Description:* Adds the intersection to the Traversal Stream. -*Syntax:* `intersect(Object)` +*Syntax:* `intersect(Object values)` [width="100%",options="header"] |========================================================= @@ -1079,7 +1085,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#length-step[reference] *Arguments:* -* `Object` - A list of items (as an Iterable or an array) or a traversal that will produce a list of items. +* `values` - A list of items (as an Iterable or an array) or a `Traversal` that will produce a list of items. *Modulation:* @@ -1104,7 +1110,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#intersect-step[reference *Description:* Joins every element in a list together into a String. -*Syntax:* `conjoin(String)` +*Syntax:* `conjoin(String delimiter)` [width="100%",options="header"] |========================================================= @@ -1114,7 +1120,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#intersect-step[reference *Arguments:* -* `String` - A delimiter to use to join the elements together. Can't be null. +* `delimiter` - A delimiter to use to join the elements together. Can't be null. *Modulation:* @@ -1122,9 +1128,9 @@ None *Considerations:* -Every element in the list (except null) is converted to a String. Null values are ignored. The delimiter is inserted +Every element in the list (except `null`) is converted to a String. Null values are ignored. The delimiter is inserted between neighboring elements to form the final result. This step only applies to list types which means that -non-iterable types (including null) will cause exceptions to be thrown. +non-iterable types (including `null`) will cause exceptions to be thrown. *Exceptions* @@ -1139,7 +1145,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#conjoin-step[reference] *Description:* Returns a string with leading whitespace removed. -*Syntax:* `lTrim()` +*Syntax:* `lTrim()` | `lTrim(Scope scope)` [width="100%",options="header"] |========================================================= @@ -1158,7 +1164,8 @@ Null values from the incoming traverser are not processed and remain as null whe * For `Scope.global` or parameterless function calls, if the incoming traverser is a non-String value then an `IllegalArgumentException` will be thrown. * For `Scope.local`, if the incoming traverser is not a string or a list of strings then an `IllegalArgumentException` will be thrown. -See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/LTrimStep.java[source], +See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/LTrimGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/LTrimLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#lTrim-step[reference] [[merge-step]] @@ -1166,7 +1173,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#lTrim-step[reference] *Description:* Adds the union of two sets (or two maps) to the Traversal Stream. -*Syntax:* `merge(Object)` +*Syntax:* `merge(Object values)` [width="100%",options="header"] |========================================================= @@ -1176,7 +1183,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#lTrim-step[reference] *Arguments:* -* `Object` - A list of items (as an Iterable or an array), a map, or a traversal that will produce a list of items. +* `values` - A list of items (as an `Iterable` or an array), a `Map`, or a `Traversal` that will produce a list of items. *Modulation:* @@ -1202,7 +1209,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#merge-step[reference] *Description:* Provides upsert-like functionality for edges. -*Syntax:* `mergeE()` | `mergeE(Map)` | `mergeE(Traversal)` +*Syntax:* `mergeE()` | `mergeE(Map searchCreate)` | `mergeE(Traversal searchCreate)` [width="100%",options="header"] |========================================================= @@ -1280,7 +1287,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#mergee-step[reference] *Description:* Provides upsert-like functionality for vertices. -*Syntax:* `mergeV()` | `mergeV(Map)` | `mergeV(Traversal)` +*Syntax:* `mergeV()` | `mergeV(Map searchCreate)` | `mergeV(Traversal searchCreate)` [width="100%",options="header"] |========================================================= @@ -1344,7 +1351,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#mergev-step[reference] *Description:* Adds the cartesian product to the Traversal Stream. -*Syntax:* `product(Object)` +*Syntax:* `product(Object values)` [width="100%",options="header"] |========================================================= @@ -1354,7 +1361,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#mergev-step[reference] *Arguments:* -* `Object` - A list of items (as an Iterable or an array) or a traversal that will produce a list of items. +* `values` - A list of items (as an `Iterable` or an array) or a `Traversal` that will produce a list of items. *Modulation:* @@ -1378,7 +1385,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#product-step[reference] *Description:* Returns a string with the specified characters in the original string replaced with the new characters. -*Syntax:* `replace(String, String)` | `replace(Scope, String, String)` +*Syntax:* `replace(String oldChar, String newChar)` | `replace(Scope scope, String oldChar, String newChar)` [width="100%",options="header"] |========================================================= @@ -1401,7 +1408,8 @@ Null values from the incoming traverser are not processed and remain as null whe * For `Scope.global` or parameterless function calls, if the incoming traverser is a non-String value then an `IllegalArgumentException` will be thrown. * For `Scope.local`, if the incoming traverser is not a string or a list of strings then an `IllegalArgumentException` will be thrown. -See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/ReplaceStep.java[source], +See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/ReplaceGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/ReplaceLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#replace-step[reference] [[reverse-step]] @@ -1437,7 +1445,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#reverse-step[reference] *Description:* Returns a string with trailing whitespace removed. -*Syntax:* `rTrim()` +*Syntax:* `rTrim()` | `rTrim(Scope scope)` [width="100%",options="header"] |========================================================= @@ -1456,7 +1464,8 @@ Null values from the incoming traverser are not processed and remain as null whe * For `Scope.global` or parameterless function calls, if the incoming traverser is a non-String value then an `IllegalArgumentException` will be thrown. * For `Scope.local`, if the incoming traverser is not a string or a list of strings then an `IllegalArgumentException` will be thrown. -See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/RTrimStep.java[source], +See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/RTrimGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/RTrimLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#rTrim-step[reference] [[split-step]] @@ -1464,7 +1473,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#rTrim-step[reference] *Description:* Returns a list of strings created by splitting the incoming string traverser around the matches of the given separator. -*Syntax:* `split(String)` | `split(Scope, String)` +*Syntax:* `split(String separator)` | `split(Scope scope, String separator)` [width="100%",options="header"] |========================================================= @@ -1485,7 +1494,8 @@ Null values from the incoming traverser are not processed and remain as null whe * For `Scope.global` or parameterless function calls, if the incoming traverser is a non-String value then an `IllegalArgumentException` will be thrown. * For `Scope.local`, if the incoming traverser is not a string or a list of strings then an `IllegalArgumentException` will be thrown. -See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/SplitStep.java[source], +See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/SplitGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/SplitLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#split-step[reference] [[substring-step]] @@ -1493,7 +1503,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#split-step[reference] *Description:* Returns a substring of the incoming string traverser with a 0-based start index (inclusive) and end index (exclusive). -*Syntax:* `substring(int, int)` | `substring(Scope, int, int)` +*Syntax:* `substring(int startIndex, int endIndex)` | `substring(Scope scope, int startIndex, int endIndex)` [width="100%",options="header"] |========================================================= @@ -1516,7 +1526,8 @@ Null values from the incoming traverser are not processed and remain as null whe * For `Scope.global` or parameterless function calls, if the incoming traverser is a non-String value then an `IllegalArgumentException` will be thrown. * For `Scope.local`, if the incoming traverser is not a string or a list of strings then an `IllegalArgumentException` will be thrown. -See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/SubstringStep.java[source], +See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/SubstringGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/SubstringLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#substring-step[reference] [[toLower-step]] @@ -1525,7 +1536,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#substring-step[reference *Description:* Returns the lowercase representation of incoming string traverser, or if `Scope.local` is specified, returns the lowercase representation of each string elements inside incoming list traverser. -*Syntax:* `toLower()` | `toLower(Scope)` +*Syntax:* `toLower()` | `toLower(Scope scope)` [width="100%",options="header"] |========================================================= @@ -1544,7 +1555,8 @@ Null values from the incoming traverser are not processed and remain as null whe * For `Scope.global` or parameterless function calls, if the incoming traverser is a non-String value then an `IllegalArgumentException` will be thrown. * For `Scope.local`, if the incoming traverser is not a string or a list of strings then an `IllegalArgumentException` will be thrown. -See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/ToLowerStep.java[source], +See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/ToLowerGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/ToLowerLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#toLower-step[reference] [[toUpper-step]] @@ -1553,7 +1565,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#toLower-step[reference] *Description:* Returns the uppercase representation of incoming string traverser, or if `Scope.local` is specified, returns the uppercase representation of each string elements inside incoming list traverser. -*Syntax:* `toUpper()` | `toUpper(Scope)` +*Syntax:* `toUpper()` | `toUpper(Scope scope)` [width="100%",options="header"] |========================================================= @@ -1572,7 +1584,8 @@ Null values from the incoming traverser are not processed and remain as null whe * For `Scope.global` or parameterless function calls, if the incoming traverser is a non-String value then an `IllegalArgumentException` will be thrown. * For `Scope.local`, if the incoming traverser is not a string or a list of strings then an `IllegalArgumentException` will be thrown. -See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/ToUpperStep.java[source], +See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/ToUpperGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/ToUpperLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#toUpper-step[reference] [[trim-step]] @@ -1580,7 +1593,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#toUpper-step[reference] *Description:* Returns a string with leading and trailing whitespace removed. -*Syntax:* `trim()` +*Syntax:* `trim()` | `trim(Scope scope)` [width="100%",options="header"] |========================================================= @@ -1599,5 +1612,6 @@ Null values from the incoming traverser are not processed and remain as null whe * For `Scope.global` or parameterless function calls, if the incoming traverser is a non-String value then an `IllegalArgumentException` will be thrown. * For `Scope.local`, if the incoming traverser is not a string or a list of strings then an `IllegalArgumentException` will be thrown. -See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/TrimStep.java[source], +See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/TrimGlobalStep.java[source], +link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/TrimLocalStep.java[source (local)], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#trim-step[reference] diff --git a/docs/src/reference/the-traversal.asciidoc b/docs/src/reference/the-traversal.asciidoc index 5acfe2d4c5d..d20352dcff1 100644 --- a/docs/src/reference/the-traversal.asciidoc +++ b/docs/src/reference/the-traversal.asciidoc @@ -803,10 +803,11 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre [[asDate-step]] === AsDate Step -The `asDate()`-step (*map*) converts string or numeric input to Date. -For string input only ISO-8601 format is supported. -For numbers, the value is considered as the number of the milliseconds since "the epoch" (January 1, 1970, 00:00:00 GMT). -Date input passed without changes. +The `asDate()`-step (*map*) converts string or numeric input to Date. + +For string input only ISO-8601 format is supported. For numbers, the value is considered as the number of the +milliseconds since "the epoch" (January 1, 1970, 00:00:00 GMT). Date input is passed without changes. + If the incoming traverser is not a string, number or Date then an `IllegalArgumentException` will be thrown. [gremlin-groovy,modern] @@ -822,8 +823,7 @@ g.inject(datetime("2023-08-24T00:00:00Z")).asDate() <3> *Additional References* -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#asDate-- -++[`asDate()`] +link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#asDate()++[`asDate()`] [[barrier-step]] === Barrier Step @@ -1148,8 +1148,8 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre The `combine()`-step (*map*) combines the elements of the incoming list traverser and the provided list argument into one list. This is also known as appending or concatenating. This step only expects list data (array or Iterable) and -will throw an `IllegalArgumentException` if any other type is encountered (including null). This differs from the -`merge` step in that it allows duplicates to exist. +will throw an `IllegalArgumentException` if any other type is encountered (including `null`). This differs from the +`merge()`-step in that it allows duplicates to exist. [gremlin-groovy,modern] ---- @@ -1159,7 +1159,7 @@ g.V().values("name").fold().combine(__.constant("stephen").fold()) *Additional References* -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#combine-Object++[`combine(Object)`] +link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#combine(java.lang.Object)++[`combine(Object)`] link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#combine-step++[`Semantics`] [[concat-step]] @@ -1215,7 +1215,7 @@ link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#concat-step++[`Sema The `conjoin()`-step (*map*) joins together the elements in the incoming list traverser together with the provided argument as a delimiter. The resulting `String` is added to the Traversal Stream. This step only expects list data (array or Iterable) in the incoming traverser and will throw an `IllegalArgumentException` if any other type is encountered -(including null). Null values are skipped and not included in the result. +(including `null`). Null values are skipped and not included in the result. [gremlin-groovy,modern] ---- @@ -1224,7 +1224,7 @@ g.V().values("name").fold().conjoin("+") *Additional References* -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#conjoin-String++[`conjoin(String)`] +link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#conjoin(java.lang.String)++[`conjoin(String)`] link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#conjoin-step++[`Semantics`] [[connectedcomponent-step]] @@ -1361,8 +1361,7 @@ g.inject(["2023-08-02T00:00:00Z", "2023-08-03T00:00:00Z"]).unfold().asDate().dat *Additional References* -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#dateAdd-- -++[`dateAdd()`] +link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#dateAdd()++[`dateAdd()`] [[dateDiff-step]] === DateDiff Step @@ -1379,8 +1378,7 @@ g.inject("2023-08-02T00:00:00Z").asDate().dateDiff(constant("2023-08-03T00:00:00 *Additional References* -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#dateDiff-- -++[`dateDiff()`] +link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#dateDiff()++[`dateDiff()`] [[dedup-step]] === Dedup Step @@ -1437,7 +1435,7 @@ link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#dedup-step++[`Seman The `difference()`-step (*map*) calculates the difference between the incoming list traverser and the provided list argument. More specifically, this provides the set operation A-B where A is the traverser and B is the argument. This step only expects list data (array or Iterable) and will throw an `IllegalArgumentException` if any other type is -encountered (including null). +encountered (including `null`). [gremlin-groovy,modern] ---- @@ -1447,7 +1445,7 @@ g.V().values("name").fold().difference(__.V().limit(2).values("name").fold()) *Additional References* -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#difference-Object++[`difference(Object)`] +link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#difference(java.lang.Object)++[`difference(Object)`] link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#difference-step++[`Semantics`] [[disjunct-step]] @@ -1455,7 +1453,7 @@ link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#difference-step++[` The `disjunct()`-step (*map*) calculates the disjunct set between the incoming list traverser and the provided list argument. This step only expects list data (array or Iterable) and will throw an `IllegalArgumentException` if any other -type is encountered (including null). +type is encountered (including `null`). [gremlin-groovy,modern] ---- @@ -1467,7 +1465,7 @@ g.V().values("name").fold().disjunct(__.V().limit(3).values("name").fold()) *Additional References* -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#disjunct-Object++[`disjunct(Object)`] +link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#disjunct(java.lang.Object)++[`disjunct(Object)`] link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#disjunct-step++[`Semantics`] [[drop-step]] @@ -1650,9 +1648,8 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre [[format-step]] === Format Step -This step is designed to simplify some string operations. -In general, it is similar to the string formatting function available in many programming languages. -Variable values can be picked up from Element properties, maps and scope variables. +This step is designed to simplify some string operations. In general, it is similar to the string formatting function +available in many programming languages. Variable values can be picked up from Element properties, maps and scope variables. [gremlin-groovy,modern] ---- @@ -1998,7 +1995,7 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre The `intersect()`-step (*map*) calculates the intersection between the incoming list traverser and the provided list argument. This step only expects list data (array or Iterable) and will throw an `IllegalArgumentException` if any other -type is encountered (including null). +type is encountered (including `null`). [gremlin-groovy,modern] ---- @@ -2008,7 +2005,7 @@ g.V().values("name").fold().intersect(__.V().limit(2).values("name").fold()) *Additional References* -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#intersect-Object++[`intersect(Object)`] +link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#intersect(java.lang.Object)++[`intersect(Object)`] link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#intersect-step++[`Semantics`] anchor:_gremlin_i_o[] @@ -2766,8 +2763,8 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre The `merge()`-step (*map*) merges the elements of the incoming list traverser and the provided list argument into one list. This is also known as the union operation. This step only expects list data (array or Iterable) and will throw -an `IllegalArgumentException` if any other type is encountered (including null). This differs from the `combine` -step in that it doesn't allow duplicates. +an `IllegalArgumentException` if any other type is encountered (including `null`). This differs from the `combine()`-step +in that it doesn't allow duplicates. [gremlin-groovy,modern] ---- @@ -2777,8 +2774,7 @@ g.V().values("name").fold().merge(__.constant("james").fold()) *Additional References* -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#merge-Object++[`merge(Object)`] -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#merge-Traversal++[`merge(Traversal)`] +link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#merge(java.lang.Object)++[`merge(Object)`] link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#merge-step++[`Semantics`] [[mergeedge-step]] @@ -3519,7 +3515,7 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre The `product()`-step (*map*) calculates the cartesian product between the incoming list traverser and the provided list argument. This step only expects list data (array or Iterable) and will throw an `IllegalArgumentException` if any -other type is encountered (including null). +other type is encountered (including `null`). [gremlin-groovy,modern] ---- @@ -3529,7 +3525,7 @@ g.V().values("name").fold().product(__.V().has("age").limit(1).values("age").fol *Additional References* -link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#product-Object++[`product(Object)`] +link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#product(java.lang.Object)++[`product(Object)`] link:++https://tinkerpop.apache.org/docs/x.y.z/dev/provider/#product-step++[`Semantics`] [[profile-step]] @@ -3926,7 +3922,7 @@ link:++https://tinkerpop.apache.org/docs/x.y.z/recipes/#looping[`Looping Recipes The `replace()`-step (*map*) returns a string with the specified characters in the original string replaced with the new characters. Any null arguments will be a no-op and the original string is returned. Null values from the incoming traversers are not processed and remain as null when returned. If the incoming traverser is a non-String value then -an IllegalArgumentException will be thrown. +an `IllegalArgumentException` will be thrown. [gremlin-groovy,modern] ---- @@ -3947,7 +3943,7 @@ link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gre [[reverse-step]] === Reverse Step -The `reverse()`-step (*map*) returns a reversed of the incoming list traverser. Single values (including null) are not +The `reverse()`-step (*map*) returns the reverse of the incoming list traverser. Single values (including `null`) are not processed and are added back to the Traversal Stream unchanged. If the incoming traverser is a String value then the reversed String will be returned. diff --git a/docs/src/upgrade/release-3.7.x.asciidoc b/docs/src/upgrade/release-3.7.x.asciidoc index 5f9d2ae5c78..5b48e0bde59 100644 --- a/docs/src/upgrade/release-3.7.x.asciidoc +++ b/docs/src/upgrade/release-3.7.x.asciidoc @@ -30,9 +30,10 @@ complete list of all the modifications that are part of this release. === Upgrading for Users ==== String Manipulation Steps -Modifications to the concat() step as well as additional String manipulation steps have been added to this version. +This version introduces the following new string manipulation steps `asString()`, `length()`, `toLower()`, `toUpper()`, `trim()`, +`lTrim()`, `rTrim()`, `reverse()`, `replace()`, `split()`, `substring()`, and `format()`, as well as modifications to the `concat()` step introduced in 3.7.0. -===== Updates to concat(): +===== Updates to String Step concat(): Concat has been modified to take traversal varargs instead of a single traversal. Users no longer have to chain concat() steps together to concatenate multiple traversals: [source,text] @@ -59,9 +60,9 @@ gremlin> g.inject("a").concat(constant("b")) ==>ab ---- -link:https://tinkerpop.apache.org/docs/x.y.z/reference/#concat-step[concat()-step], +link:https://tinkerpop.apache.org/docs/x.y.z/reference/#concat-step[concat()-step] -===== String Steps asString(), length(), toLower(), toUpper(): +===== New String Steps asString(), length(), toLower(), toUpper(): The following example demonstrates the use of a closure to perform the above functions: [source,text] @@ -133,7 +134,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#length-step[length()-ste link:https://tinkerpop.apache.org/docs/x.y.z/reference/#toLower-step[toLower()-step], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#toUpper-step[toUpper()-step] -===== String Steps trim(), lTrim(), rTrim(), reverse(): +===== New String Steps trim(), lTrim(), rTrim(), reverse(): The following example demonstrates the use of a closure to reverse and trim strings (concatenated with a string for demonstration): @@ -181,13 +182,13 @@ gremlin> g.inject([" hello ", " world "]).trim(Scope.local) ==>[hello,world] ---- -See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#trim-step[trim()-step] -See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#lTrim-step[lTrim()-step] -See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#rTrim-step[rTrim()-step] -See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#reverse-step[reverse()-step] -See: link:https://issues.apache.org/jira/browse/TINKERPOP-2672[TINKERPOP-2672] +See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#trim-step[trim()-step], +link:https://tinkerpop.apache.org/docs/x.y.z/reference/#lTrim-step[lTrim()-step], +link:https://tinkerpop.apache.org/docs/x.y.z/reference/#rTrim-step[rTrim()-step], +link:https://tinkerpop.apache.org/docs/x.y.z/reference/#reverse-step[reverse()-step], +link:https://issues.apache.org/jira/browse/TINKERPOP-2672[TINKERPOP-2672] -===== String Steps replace(), split(), substring() +===== New String Steps replace(), split(), substring() The following example demonstrates the use of a closure to perform `replace()` and `split()` functions: [source,text] @@ -255,15 +256,14 @@ gremlin> g.V().hasLabel("person").values("name").substring(-2) ==>er ---- -See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#replace-step[replace()-step] -See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#split-step[split()-step] -See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#substring-step[substring()-step] -See: link:https://issues.apache.org/jira/browse/TINKERPOP-2672[TINKERPOP-2672] +See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#replace-step[replace()-step], +link:https://tinkerpop.apache.org/docs/x.y.z/reference/#split-step[split()-step], +link:https://tinkerpop.apache.org/docs/x.y.z/reference/#substring-step[substring()-step], +link:https://issues.apache.org/jira/browse/TINKERPOP-2672[TINKERPOP-2672] -===== Format Step -This step is designed to simplify some string operations. -In general, it is similar to the string formatting function available in many programming languages. -Variable values can be picked up from Element properties, maps and scope variables. +===== New String Step format() +This step is designed to simplify some string operations. In general, it is similar to the string formatting function +available in many programming languages. Variable values can be picked up from Element properties, maps and scope variables. [source,text] ---- @@ -282,7 +282,7 @@ gremlin> g.V(1).format("%{name} has %{_} connections").by(bothE().count()) See: link:https://issues.apache.org/jira/browse/TINKERPOP-2334[TINKERPOP-2334], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#format-step[format()-step] -==== List Traverser based Steps +==== List Manipulation Steps Additional List manipulation/filter steps have been added to replace the use of closures: `any()`, `all()`, `product()`, `merge()`, `intersect()`, `combine()`, `conjoin()`, `difference()`,`disjunct()` and `reverse()`. @@ -323,7 +323,7 @@ link:https://tinkerpop.apache.org/docs/x.y.z/reference/#conjoin-step[conjoin()-s link:https://tinkerpop.apache.org/docs/x.y.z/reference/#difference-step[difference()-step], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#disjunct-step[disjunct()-step] -==== Date manipulation functions +==== Date Manipulation Steps Date manipulations in Gremlin queries were only possible using closures, which may or may not be supported by different providers. In 3.7.1, we introduce the `asDate()`, `dateAdd` and `dateDiff` steps aimed to replace the usage of closure. @@ -341,7 +341,7 @@ See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dateAdd-step[dateAd See: link:https://tinkerpop.apache.org/docs/x.y.z/reference/#dateDiff-step[dateDiff()-step] See: link:https://issues.apache.org/jira/browse/TINKERPOP-2979[TINKERPOP-2979] -===== `datetime()` for current server time +===== `datetime()` for Current Server Time Function `datetime()` extended to return current server time when used without argument. @@ -364,6 +364,8 @@ feature. In an effort to better allow graphs to support one feature or the other been split into two tags: `@MultiProperties` and `@MetaProperties`. The original `@MultiMetaProperties` tag has been removed. +===== InsertionOrderingRequired Test Tag + Added a new `@InsertionOrderingRequired` tag which signifies Gherkin feature tests which are reliant on the graph system predictably returning results (vertices, edges, properties) in the same order in which they were inserted into the graph. These tests should be skipped by any graph which does not guarantee such ordering. ==== Graph Driver Providers