Package org.apache.tinkerpop.gremlin.gql

Class GqlMatchStep<S>

java.lang.Object

org.apache.tinkerpop.gremlin.process.traversal.step.util.AbstractStep<S,Map<String,Object>>

org.apache.tinkerpop.gremlin.process.traversal.step.map.DeclarativeMatchStep<S>

org.apache.tinkerpop.gremlin.gql.GqlMatchStep<S>

Type Parameters:

S - the traverser start type

All Implemented Interfaces:

Serializable, Cloneable, Iterator<Traverser.Admin<Map<String,Object>>>, Step<S,Map<String,Object>>, Configuring, Parameterizing

public final class GqlMatchStep<S>
extends DeclarativeMatchStep<S>

Concrete executable replacement for the generic DeclarativeMatchStep that runs TinkerGQL patterns via a GqlPlanner and GqlExecutor.

The planner and executor are normally supplied by GqlDeclarativeMatchStrategy, which caches one pair per graph instance so the planner's parse cache is shared across all traversals on the same graph. When the step is constructed without injected instances (e.g. in tests that use a substitute strategy), they are initialised lazily from the traversal's graph on the first call to processNextStart().

For each incoming traverser the plan is executed against the graph and one output traverser is emitted per result row. Each result row's named variable bindings are recorded in the emitted traverser's path so that downstream select() steps can retrieve them by name.

Only the "gql" query language is supported. If the step's query language is set to any other non-null value, UnsupportedOperationException is thrown.

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final String	SUPPORTED_QUERY_LANGUAGE	The query language identifier that this step accepts when set explicitly.

Fields inherited from class org.apache.tinkerpop.gremlin.process.traversal.step.map.DeclarativeMatchStep

parameters

Fields inherited from class org.apache.tinkerpop.gremlin.process.traversal.step.util.AbstractStep

id, labels, nextEnd, nextStep, previousStep, starts, traversal, traverserStepIdAndLabelsSetByChild

Constructor Summary

Constructors

Constructor	Description
GqlMatchStep(DeclarativeMatchStep<S> originalStep)	Constructs a GqlMatchStep without pre-injected planner or executor.
GqlMatchStep(DeclarativeMatchStep<S> originalStep, GqlPlanner planner, GqlExecutor executor)	Constructs a GqlMatchStep with pre-injected planner and executor.

Method Summary

Modifier and Type	Method	Description
GqlMatchStep<S>	clone()	Creates a clone with a fresh output queue and a null plan reference so the plan is re-fetched from the planner's cache on first use.
Set<TraverserRequirement>	getRequirements()	Declares TraverserRequirement.LABELED_PATH so that traversers track their path labels, enabling downstream select() steps to retrieve bound variables.
protected Traverser.Admin<Map<String,Object>>	processNextStart()	Returns the next output traverser.
void	reset()	Resets lazy row state.

Methods inherited from class org.apache.tinkerpop.gremlin.process.traversal.step.map.DeclarativeMatchStep

configure, getMatchQuery, getParameters, getParams, getQueryLanguage, isStart, toString

Methods inherited from class org.apache.tinkerpop.gremlin.process.traversal.step.util.AbstractStep

addLabel, addStart, addStarts, clearLabels, equals, getId, getLabels, getNextStep, getPreviousStep, getStarts, getTraversal, hashCode, hasNext, hasStarts, isTraverserStepIdAndLabelsSetByChild, next, prepareTraversalForNextStep, removeLabel, setId, setNextStep, setPreviousStep, setTraversal

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Iterator

forEachRemaining, remove

Methods inherited from interface org.apache.tinkerpop.gremlin.process.traversal.Step

equals

Field Details

SUPPORTED_QUERY_LANGUAGE

public static final String SUPPORTED_QUERY_LANGUAGE

The query language identifier that this step accepts when set explicitly. null is also accepted and is treated as a request to use this native language.

See Also:

• Constant Field Values

Constructor Details

GqlMatchStep

public GqlMatchStep(DeclarativeMatchStep<S> originalStep)

Constructs a GqlMatchStep without pre-injected planner or executor. Both are initialised lazily from the traversal's graph on the first processNextStart() call. Intended for use in tests where a substitute strategy replaces the placeholder step without access to the shared graph-level cache.

Parameters:

originalStep - the step being replaced by this concrete implementation

GqlMatchStep

public GqlMatchStep(DeclarativeMatchStep<S> originalStep,
 GqlPlanner planner,
 GqlExecutor executor)

Constructs a GqlMatchStep with pre-injected planner and executor. When planner and executor are non-null the plan cache is shared across all traversals that use the same objects — normally the per-graph-instance pair cached by GqlDeclarativeMatchStrategy.

Parameters:

originalStep - the step being replaced

planner - the planner to use, or null for lazy init

executor - the executor to use, or null for lazy init

Method Details

processNextStart

protected Traverser.Admin<Map<String,Object>> processNextStart()
                                                        throws NoSuchElementException

Returns the next output traverser.

On the first invocation (or after a clone()), if the planner was not injected it is initialised from the traversal's graph. The compiled GqlMatchPlan is always obtained from the planner's cache so identical query strings cost only a map lookup after the first compilation.

Overrides:

processNextStart in class DeclarativeMatchStep<S>

Throws:

UnsupportedOperationException - if the query language is non-null and not "gql"

NoSuchElementException

getRequirements

public Set<TraverserRequirement> getRequirements()

Declares TraverserRequirement.LABELED_PATH so that traversers track their path labels, enabling downstream select() steps to retrieve bound variables.

Specified by:

getRequirements in interface Step<S,Map<String,Object>>

Overrides:

getRequirements in class DeclarativeMatchStep<S>

Returns:

the set of requirements

clone

public GqlMatchStep<S> clone()

Creates a clone with a fresh output queue and a null plan reference so the plan is re-fetched from the planner's cache on first use. The planner and executor references are retained: when they are graph-level singletons (the normal path) the clone shares the plan cache; when they are per-step instances (test path) the clone will lazily re-create its own.

Specified by:

clone in interface Step<S,Map<String,Object>>

Overrides:

clone in class AbstractStep<S,Map<String,Object>>

Returns:

The cloned step

reset

public void reset()

Resets lazy row state. The planner and executor singletons are preserved so the QueryGraph parse cache survives a traversal reset, but the compiled GqlMatchPlan is cleared so that seed selection is recomputed from live label counts on the next execution — ensuring graph mutations between resets are reflected.

Specified by:

reset in interface Step<S,Map<String,Object>>

Overrides:

reset in class AbstractStep<S,Map<String,Object>>