Package org.apache.tinkerpop.gremlin.process.traversal.dsl.graph

Class GraphTraversalSource

java.lang.Object
org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource
All Implemented Interfaces:
AutoCloseable, Cloneable, TraversalSource
Direct Known Subclasses:
CredentialTraversalSourceDsl
public class GraphTraversalSource extends Object implements TraversalSource
A GraphTraversalSource is the primary DSL of the Gremlin traversal machine. It provides access to all the configurations and steps for Turing complete graph computing. Any DSL can be constructed based on the methods of both GraphTraversalSource and GraphTraversal.
Author:
Marko A. Rodriguez (http://markorodriguez.com), Stephen Mallette (http://stephen.genoprime.com)

  • Field Details

  • Constructor Details

    • GraphTraversalSource

      public GraphTraversalSource(Graph graph, TraversalStrategies traversalStrategies)

    • GraphTraversalSource

      public GraphTraversalSource(Graph graph)

    • GraphTraversalSource

      public GraphTraversalSource(RemoteConnection connection)

  • Method Details

    • getAnonymousTraversalClass

      public Optional<Class<?>> getAnonymousTraversalClass()
      Specified by:
      getAnonymousTraversalClass in interface TraversalSource

    • getStrategies

      public TraversalStrategies getStrategies()
      Description copied from interface: TraversalSource
      Get the TraversalStrategies associated with this traversal source.
      Specified by:
      getStrategies in interface TraversalSource
      Returns:
      the traversal strategies of the traversal source

    • getGraph

      public Graph getGraph()
      Description copied from interface: TraversalSource
      Get the Graph associated with this traversal source.
      Specified by:
      getGraph in interface TraversalSource
      Returns:
      the graph of the traversal source

    • getGremlinLang

      public GremlinLang getGremlinLang()
      Description copied from interface: TraversalSource
      Get the GremlinLang associated with the current state of this traversal source.
      Specified by:
      getGremlinLang in interface TraversalSource
      Returns:
      the traversal source byte code

    • clone

      public GraphTraversalSource clone()
      Description copied from interface: TraversalSource
      The clone-method should be used to create immutable traversal sources with each call to a configuration "withXXX"-method. The clone-method should clone the GremlinLang, TraversalStrategies, mutate the cloned strategies accordingly, and then return the cloned traversal source leaving the original unaltered.
      Specified by:
      clone in interface TraversalSource
      Overrides:
      clone in class Object
      Returns:
      the cloned traversal source

    • with

      public GraphTraversalSource with(String key)
      Provides a configuration to a traversal in the form of a key which is the same as with(key, true). The key of the configuration must be graph provider specific and therefore a configuration could be supplied that is not known to be valid until execution.
      Specified by:
      with in interface TraversalSource
      Parameters:
      key - the key of the configuration to apply to a traversal
      Returns:
      a new traversal source with the included configuration

    • with

      public GraphTraversalSource with(String key, Object value)
      Provides a configuration to a traversal in the form of a key value pair. The key of the configuration must be graph provider specific and therefore a configuration could be supplied that is not known to be valid until execution. This is a handy shortcut for building an OptionsStrategy manually and then add with TraversalSource.withStrategies(TraversalStrategy[]).
      Specified by:
      with in interface TraversalSource
      Parameters:
      key - the key of the configuration to apply to a traversal
      value - the value of the configuration to apply to a traversal
      Returns:
      a new traversal source with the included configuration

    • withStrategies

      public GraphTraversalSource withStrategies(TraversalStrategy... traversalStrategies)
      Add an arbitrary collection of TraversalStrategy instances to the traversal source.
      Specified by:
      withStrategies in interface TraversalSource
      Parameters:
      traversalStrategies - a collection of traversal strategies to add
      Returns:
      a new traversal source with updated strategies

    • withoutStrategies

      public GraphTraversalSource withoutStrategies(Class<? extends TraversalStrategy>... traversalStrategyClasses)
      Remove an arbitrary collection of TraversalStrategy classes from the traversal source.
      Specified by:
      withoutStrategies in interface TraversalSource
      Parameters:
      traversalStrategyClasses - a collection of traversal strategy classes to remove
      Returns:
      a new traversal source with updated strategies

    • withComputer

      public GraphTraversalSource withComputer(Computer computer)
      Add a Computer that will generate a GraphComputer from the Graph that will be used to execute the traversal. This adds a VertexProgramStrategy to the strategies.
      Specified by:
      withComputer in interface TraversalSource
      Parameters:
      computer - a builder to generate a graph computer from the graph
      Returns:
      a new traversal source with updated strategies

    • withComputer

      public GraphTraversalSource withComputer(Class<? extends GraphComputer> graphComputerClass)
      Add a GraphComputer class used to execute the traversal. This adds a VertexProgramStrategy to the strategies.
      Specified by:
      withComputer in interface TraversalSource
      Parameters:
      graphComputerClass - the graph computer class
      Returns:
      a new traversal source with updated strategies

    • withComputer

      public GraphTraversalSource withComputer()
      Add the standard GraphComputer of the graph that will be used to execute the traversal. This adds a VertexProgramStrategy to the strategies.
      Specified by:
      withComputer in interface TraversalSource
      Returns:
      a new traversal source with updated strategies

    • withSideEffect

      public <A> GraphTraversalSource withSideEffect(String key, Supplier<A> initialValue, BinaryOperator<A> reducer)
      Add a sideEffect to be used throughout the life of a spawned Traversal. This adds a SideEffectStrategy to the strategies.
      Specified by:
      withSideEffect in interface TraversalSource
      Parameters:
      key - the key of the sideEffect
      initialValue - a supplier that produces the initial value of the sideEffect
      reducer - a reducer to merge sideEffect mutations into a single result
      Returns:
      a new traversal source with updated strategies

    • withSideEffect

      public <A> GraphTraversalSource withSideEffect(String key, A initialValue, BinaryOperator<A> reducer)
      Add a sideEffect to be used throughout the life of a spawned Traversal. This adds a SideEffectStrategy to the strategies.
      Specified by:
      withSideEffect in interface TraversalSource
      Parameters:
      key - the key of the sideEffect
      initialValue - the initial value of the sideEffect
      reducer - a reducer to merge sideEffect mutations into a single result
      Returns:
      a new traversal source with updated strategies

    • withSideEffect

      public <A> GraphTraversalSource withSideEffect(String key, A initialValue)
      Add a sideEffect to be used throughout the life of a spawned Traversal. This adds a SideEffectStrategy to the strategies.
      Specified by:
      withSideEffect in interface TraversalSource
      Parameters:
      key - the key of the sideEffect
      initialValue - the initial value of the sideEffect
      Returns:
      a new traversal source with updated strategies

    • withSideEffect

      public <A> GraphTraversalSource withSideEffect(String key, Supplier<A> initialValue)
      Add a sideEffect to be used throughout the life of a spawned Traversal. This adds a SideEffectStrategy to the strategies.
      Specified by:
      withSideEffect in interface TraversalSource
      Parameters:
      key - the key of the sideEffect
      initialValue - a supplier that produces the initial value of the sideEffect
      Returns:
      a new traversal source with updated strategies

    • withSack

      public <A> GraphTraversalSource withSack(Supplier<A> initialValue, UnaryOperator<A> splitOperator, BinaryOperator<A> mergeOperator)
      Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.
      Specified by:
      withSack in interface TraversalSource
      Parameters:
      initialValue - a supplier that produces the initial value of the sideEffect
      splitOperator - the sack split operator
      mergeOperator - the sack merge operator
      Returns:
      a new traversal source with updated strategies

    • withSack

      public <A> GraphTraversalSource withSack(A initialValue, UnaryOperator<A> splitOperator, BinaryOperator<A> mergeOperator)
      Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.
      Specified by:
      withSack in interface TraversalSource
      Parameters:
      initialValue - the initial value of the sideEffect
      splitOperator - the sack split operator
      mergeOperator - the sack merge operator
      Returns:
      a new traversal source with updated strategies

    • withSack

      public <A> GraphTraversalSource withSack(A initialValue)
      Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.
      Specified by:
      withSack in interface TraversalSource
      Parameters:
      initialValue - the initial value of the sideEffect
      Returns:
      a new traversal source with updated strategies

    • withSack

      public <A> GraphTraversalSource withSack(Supplier<A> initialValue)
      Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.
      Specified by:
      withSack in interface TraversalSource
      Parameters:
      initialValue - a supplier that produces the initial value of the sideEffect
      Returns:
      a new traversal source with updated strategies

    • withSack

      public <A> GraphTraversalSource withSack(Supplier<A> initialValue, UnaryOperator<A> splitOperator)
      Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.
      Specified by:
      withSack in interface TraversalSource
      Parameters:
      initialValue - a supplier that produces the initial value of the sideEffect
      splitOperator - the sack split operator
      Returns:
      a new traversal source with updated strategies

    • withSack

      public <A> GraphTraversalSource withSack(A initialValue, UnaryOperator<A> splitOperator)
      Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.
      Specified by:
      withSack in interface TraversalSource
      Parameters:
      initialValue - the initial value of the sideEffect
      splitOperator - the sack split operator
      Returns:
      a new traversal source with updated strategies

    • withSack

      public <A> GraphTraversalSource withSack(Supplier<A> initialValue, BinaryOperator<A> mergeOperator)
      Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.
      Specified by:
      withSack in interface TraversalSource
      Parameters:
      initialValue - a supplier that produces the initial value of the sideEffect
      mergeOperator - the sack merge operator
      Returns:
      a new traversal source with updated strategies

    • withSack

      public <A> GraphTraversalSource withSack(A initialValue, BinaryOperator<A> mergeOperator)
      Add a sack to be used throughout the life of a spawned Traversal. This adds a SackStrategy to the strategies.
      Specified by:
      withSack in interface TraversalSource
      Parameters:
      initialValue - the initial value of the sideEffect
      mergeOperator - the sack merge operator
      Returns:
      a new traversal source with updated strategies

    • withBulk

      public GraphTraversalSource withBulk(boolean useBulk)

    • withPath

      public GraphTraversalSource withPath()

    • addV

      public GraphTraversal<Vertex,Vertex> addV(String label, String... additionalLabels)
      Spawns a GraphTraversal by adding a vertex with one or more labels.
      Parameters:
      label - the first (or only) vertex label
      additionalLabels - additional labels (may be empty for single-label)
      Returns:
      the traversal with the vertex added
      Since:
      3.1.0-incubating

    • addV

      public GraphTraversal<Vertex,Vertex> addV(Traversal<?,?> label, Traversal<?,?>... additionalLabels)
      Spawns a GraphTraversal by adding a Vertex with one or more labels each determined by a Traversal. Each traversal is iterated for a single result only. If exactly one Traversal is provided, and it produces a Collection<String>, the collection will be automatically unfolded.
      Parameters:
      label - the first (or only) label traversal
      additionalLabels - additional label traversals (may be empty for single-traversal behavior)
      Since:
      4.0.0

    • addV

      public GraphTraversal<Vertex,Vertex> addV()
      Spawns a GraphTraversal by adding a vertex with the default label.
      Since:
      3.1.0-incubating

    • addV

      @SafeVarargs public final GraphTraversal<Vertex,Vertex> addV(GValue<String> label, GValue<String>... additionalLabels)
      Spawns a GraphTraversal by adding a vertex with one or more specified labels. If the label is null then it will default to Vertex.DEFAULT_LABEL.
      Parameters:
      label - the first (or only) label
      additionalLabels - additional labels. May be empty for single-label)
      Returns:
      the traversal with the vertex added
      Since:
      4.0.0

    • addE

      public GraphTraversal<Edge,Edge> addE(String label)
      Spawns a GraphTraversal by adding an edge with the specified label.
      Since:
      3.1.0-incubating

    • addE

      public GraphTraversal<Edge,Edge> addE(Traversal<?,String> edgeLabelTraversal)
      Spawns a GraphTraversal by adding a edge with a label as specified by the provided Traversal.
      Since:
      3.3.1

    • addE

      public GraphTraversal<Edge,Edge> addE(GValue<String> label)
      Spawns a GraphTraversal by adding an edge with the specified label.
      Since:
      3.8.0

    • mergeV

      public GraphTraversal<Vertex,Vertex> mergeV(Map<Object,Object> searchCreate)
      Spawns a GraphTraversal by doing a merge (i.e. upsert) style operation for an Vertex using a Map as an argument. The Map represents search criteria and will match each of the supplied key/value pairs where the keys may be String property values or a value of T. If a match is not made it will use that search criteria to create the new Vertex.
      Parameters:
      searchCreate - This Map can have a key of T or a String.
      Since:
      3.6.0

    • mergeV

      public <S> GraphTraversal<S,Vertex> mergeV(Traversal<?,Map<Object,Object>> searchCreate)
      Spawns a GraphTraversal by doing a merge (i.e. upsert) style operation for an Vertex using a Map as an argument. The Map represents search criteria and will match each of the supplied key/value pairs where the keys may be String property values or a value of T. If a match is not made it will use that search criteria to create the new Vertex.
      Parameters:
      searchCreate - This anonymous Traversal must produce a Map that may have a keys of T or a String.
      Since:
      3.6.0

    • mergeV

      public GraphTraversal<Vertex,Vertex> mergeV(GValue<Map<?,?>> searchCreate)
      Spawns a GraphTraversal by doing a merge (i.e. upsert) style operation for an Vertex using a Map as an argument. The Map represents search criteria and will match each of the supplied key/value pairs where the keys may be String property values or a value of T. If a match is not made it will use that search criteria to create the new Vertex.
      Parameters:
      searchCreate - This Map can have a key of T or a String.
      Since:
      3.8.0

    • mergeE

      public GraphTraversal<Edge,Edge> mergeE(Map<Object,Object> searchCreate)
      Spawns a GraphTraversal by doing a merge (i.e. upsert) style operation for an Edge using a Map as an argument.
      Parameters:
      searchCreate - This Map can have a key of T Direction or a String.
      Since:
      3.6.0

    • mergeE

      public GraphTraversal<Edge,Edge> mergeE(Traversal<?,Map<Object,Object>> searchCreate)
      Spawns a GraphTraversal by doing a merge (i.e. upsert) style operation for an Edge using a Map as an argument.
      Parameters:
      searchCreate - This Map can have a key of T Direction or a String.
      Since:
      3.6.0

    • mergeE

      public GraphTraversal<Edge,Edge> mergeE(GValue<Map<Object,Object>> searchCreate)
      Spawns a GraphTraversal by doing a merge (i.e. upsert) style operation for an Edge using a Map as an argument.
      Parameters:
      searchCreate - This Map can have a key of T Direction or a String.
      Since:
      3.8.0

    • inject

      public <S> GraphTraversal<S,S> inject(S... starts)
      Spawns a GraphTraversal starting it with arbitrary values.

    • V

      public GraphTraversal<Vertex,Vertex> V(Object... vertexIds)
      Spawns a GraphTraversal starting with all vertices or some subset of vertices as specified by their unique identifier.
      Since:
      3.0.0-incubating

    • V

      public GraphTraversal<Vertex,Vertex> V(Traversal<?,?> traversal)
      Spawns a GraphTraversal starting with vertices whose IDs are resolved from a child traversal. As a start step, a synthetic traverser is generated to seed the child traversal evaluation, consistent with how mergeV(traversal) handles start steps. The child traversal should be self-contained (e.g., __.V(1).id()) rather than dependent on an incoming traverser.
      Parameters:
      traversal - the child traversal that produces vertex IDs
      Since:
      4.0.0

    • E

      public GraphTraversal<Edge,Edge> E(Object... edgeIds)
      Spawns a GraphTraversal starting with all edges or some subset of edges as specified by their unique identifier.
      Since:
      3.0.0-incubating

    • E

      public GraphTraversal<Edge,Edge> E(Traversal<?,?> traversal)
      Spawns a GraphTraversal starting with edges whose IDs are resolved from a child traversal. As a start step, a synthetic traverser is generated to seed the child traversal evaluation, consistent with how mergeE(traversal) handles start steps. The child traversal should be self-contained (e.g., __.V(1).outE().id()) rather than dependent on an incoming traverser.
      Parameters:
      traversal - the child traversal that produces edge IDs
      Since:
      4.0.0

    • call

      public <S> GraphTraversal<S,S> call()
      Spawns a GraphTraversal starting with a list of available services.
      Since:
      3.6.0

    • call

      public <S> GraphTraversal<S,S> call(String service)
      Spawns a GraphTraversal starting with values produced by the specified service call with no parameters.
      Parameters:
      service - the name of the service call
      Since:
      3.6.0

    • call

      public <S> GraphTraversal<S,S> call(String service, Map params)
      Spawns a GraphTraversal starting with values produced by the specified service call with the specified static parameters.
      Parameters:
      service - the name of the service call
      params - static parameter map (no nested traversals)
      Since:
      3.6.0

    • call

      public <S> GraphTraversal<S,S> call(String service, Traversal<S,Map> childTraversal)
      Spawns a GraphTraversal starting with values produced by the specified service call with dynamic parameters produced by the specified child traversal.
      Parameters:
      service - the name of the service call
      childTraversal - a traversal that will produce a Map of parameters for the service call when invoked.
      Since:
      3.6.0

    • call

      public <S> GraphTraversal<S,S> call(String service, Map params, Traversal<S,Map> childTraversal)
      Spawns a GraphTraversal starting with values produced by the specified service call with both static and dynamic parameters produced by the specified child traversal. These parameters will be merged at execution time per the provider implementation. Reference implementation merges dynamic into static (dynamic will overwrite static).
      Parameters:
      service - the name of the service call
      params - static parameter map (no nested traversals)
      childTraversal - a traversal that will produce a Map of parameters for the service call when invoked.
      Since:
      3.6.0

    • call

      public <S> GraphTraversal<S,S> call(String service, GValue<Map<?,?>> params)
      Spawns a GraphTraversal starting with values produced by the specified service call with the specified static parameters.
      Parameters:
      service - the name of the service call
      params - static parameter map (no nested traversals)
      Since:
      3.8.0

    • call

      public <S> GraphTraversal<S,S> call(String service, GValue<Map<?,?>> params, Traversal<S,Map<?,?>> childTraversal)
      Spawns a GraphTraversal starting with values produced by the specified service call with the specified static parameters.
      Parameters:
      service - the name of the service call
      params - static parameter map (no nested traversals)
      Since:
      3.8.0

    • match

      public <S> GraphTraversal<S,Map<String,Object>> match(String matchQuery)
      Spawns a GraphTraversal by executing a declarative pattern match query. The query language is not prescribed or implemented by the framework; it defaults to null, meaning the graph provider will use its native query language. Use .with("queryLanguage", value) to specify a language explicitly. Consult the graph system you are using to determine what query language you can give to this step.
      Parameters:
      matchQuery - the declarative query string
      Returns:
      the traversal with an appended DeclarativeMatchStep.
      Since:
      4.0.0

    • match

      public <S> GraphTraversal<S,Map<String,Object>> match(String matchQuery, Map<String,Object> params)
      Spawns a GraphTraversal by executing a declarative pattern match query. The query language is not prescribed or implemented by the framework; it defaults to null, meaning the graph provider will use its native query language. Use .with("queryLanguage", value) to specify a language explicitly. Consult the graph system you are using to determine what query language you can give to this step.
      Parameters:
      matchQuery - the declarative query string
      params - the query parameters (may be null)
      Returns:
      the traversal with an appended DeclarativeMatchStep.
      Since:
      4.0.0

    • union

      public <S> GraphTraversal<S,S> union(Traversal<?,S>... unionTraversals)
      Merges the results of an arbitrary number of traversals.
      Parameters:
      unionTraversals - the traversals to merge
      Since:
      3.7.0
      See Also:

    • io

      public <S> GraphTraversal<S,S> io(String file)
      Performs a read or write based operation on the Graph backing this GraphTraversalSource. This step can be accompanied by the GraphTraversal.with(String, Object) modulator for further configuration and must be accompanied by a GraphTraversal.read() or GraphTraversal.write() modulator step which will terminate the traversal.
      Parameters:
      file - the name of file for which the read or write will apply - note that the context of how this parameter is used is wholly dependent on the implementation
      Returns:
      the traversal with the IoStep added
      Since:
      3.4.0
      See Also:

    • tx

      public Transaction tx()
      Proxies calls through to the underlying Graph.tx() or to the RemoteConnection.tx().

      When a remote connection is present, this method delegates to the connection's RemoteConnection.tx() method, which returns an appropriate transaction implementation for the remote connection type (e.g., HttpRemoteTransaction for HTTP-based connections).

      Returns:
      A Transaction for managing transactional operations

    • executeInTx

      public void executeInTx(Consumer<GraphTraversalSource> txWork)
      Runs the supplied unit of work inside a single transaction, managing the transaction lifecycle automatically.

      This is the no-return (action) form of evaluateInTx(Function). It is a thin convenience wrapper that obtains a Transaction via tx(), begins it, invokes txWork with the transaction-bound GraphTraversalSource (gtx), and then commits on normal completion. If txWork throws, the transaction is rolled back and the original error is re-thrown unchanged. Because the lifecycle is driven through tx(), the underlying transaction semantics (embedded thread-bound vs. remote server session) are whatever the underlying begin()/commit()/rollback() provide.

      This is a single-shot operation - exactly one attempt is made, with no automatic retry. The lambda receives the transactional gtx and should issue its traversals against that source only.

      Parameters:
      txWork - the unit of work to run against the transaction-bound GraphTraversalSource
      See Also:

    • evaluateInTx

      public <T> T evaluateInTx(Function<GraphTraversalSource,T> txWork)
      Runs the supplied unit of work inside a single transaction, managing the transaction lifecycle automatically, and returns the value the work produces.

      This wrapper obtains a Transaction via tx(), begins it, invokes txWork with the transaction-bound GraphTraversalSource (gtx), and then commits on normal completion, returning the value computed by txWork. Error handling:

      • If txWork throws, the transaction is rolled back and the exact original error is re-thrown to the caller. If that rollback itself fails, the rollback failure is attached to the original error via Throwable.addSuppressed(Throwable) and a warning is logged, but the original error still propagates as the primary error.
      • If commit fails, a rollback is attempted afterward (to avoid leaving transaction resources tied up on the server), and the commit error is re-thrown as the primary error. If the follow-up rollback also fails, the rollback failure is attached to the commit error via Throwable.addSuppressed(Throwable) and a warning is logged.

      This is a single-shot operation - exactly one attempt is made, with no automatic retry. The lambda receives the transactional gtx and should issue its traversals against that source only. Because the lifecycle is driven through tx(), the underlying transaction semantics (embedded thread-bound vs. remote server session) are whatever the underlying begin()/commit()/rollback() provide.

      Type Parameters:
      T - the type of value produced by txWork
      Parameters:
      txWork - the unit of work to run against the transaction-bound GraphTraversalSource
      Returns:
      the value produced by txWork
      See Also:

    • close

      public void close() throws Exception
      If there is an underlying RemoteConnection it will be closed by this method.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface TraversalSource
      Throws:
      Exception

    • toString

      public String toString()
      Overrides:
      toString in class Object