match() with TinkerGQL

CHANGELOG.asciidoc

@@ -60,6 +60,11 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 * Added string parameter parsing to `GremlinServer` to prevent traversal injection and excessive nesting depths.
 * Modified all GLVs to detect unsupported types in `GremlinLang` and throw consistent error for that case.
 * Added GraphBinary 4.0 `Graph` (`0x10`) serializer/deserializer to `gremlin-javascript`, `gremlin-dotnet`, and `gremlin-go` so that `subgraph()` results are returned as a detached `Graph` data container.
+* Added `match(string)` and `match(string, IDictionary)` overloads for declarative pattern matching.
+* Deprecated the traversal-based `match(Traversal[])` in favor of the new string-based API.
+* Added the `gql-gremlin` module containing the TinkerGQL engine, a `MATCH`-pattern executor implementing a deliberate minimal subset of ISO GQL, usable by any graph provider.
+* Added `Graph.countVerticesByLabel(String)`, `Graph.countEdgesByLabel(String)`, and the `Graph.Index` nested interface as performance-hint extension points for the TinkerGQL engine.
+* Added GQL support to TinkerGraph with `gql-gremlin`,
 
 [[release-4-0-0-beta-2]]
 === TinkerPop 4.0.0-beta.2 (April 1, 2026)
@@ -90,7 +95,7 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 * Replace `WebSocket` with `HTTP` (non-streaming) in `gremlin-dotnet`.
 * Added `MimeType` to `IMessageSerializer` and split client option to allow separate request and response serialization in `gremlin-dotnet`.
 * Added `RequestInterceptor` to `gremlin-dotnet` with `auth` reference implementations.
-* Added streaming deserialization to `gremlin-dotnet`, results are now deserialized incrementally from the HTTP response stream via `IAsyncEnumerable<T>`. 
+* Added streaming deserialization to `gremlin-dotnet`, results are now deserialized incrementally from the HTTP response stream via `IAsyncEnumerable<T>`.
 * Target framework for `gremlin-dotnet` updated to `net8.0`.
 * Bumped minimum Node.js version for `gremlin-javascript` from 20 to 22.
 * Removed `mimeType` connection option in `gremlin-javascript` in favor of direct use of `reader` and `writer` options.

docs/src/dev/developer/for-committers.asciidoc

@@ -665,6 +665,10 @@ tries to reference inaccessible properties that are on elements only available b
 the traversal does not mind the star graph limitation.
 * `@GremlinGroovyNotSupported` - The scenario uses `gremlin-lang` syntax which is incompatible with `gremlin-groovy` and
 cannot be resolved with the groovy translator. This is typically for scenarios using ambiguously-types `null` parameters.
+* `@TinkerGQL` - The scenario uses `match(String)` with GQL MATCH syntax and requires a graph that supports the
+TinkerGQL engine (i.e. has `GqlDeclarativeMatchStrategy` registered). Graph providers that do not support
+`match(String)` should add `and not @TinkerGQL` to their `@CucumberOptions` tag filter. TinkerGraph includes
+TinkerGQL support out of the box and runs these scenarios without any additional configuration.
 * `@InsertionOrderingRequired` - The scenario is reliant on the graph system predictably returning results (vertices,
 edges, properties) in the same order in which they were inserted into the graph.
 * `@MetaProperties` - The scenario makes use of meta-properties.

docs/src/dev/future/proposal-3-remove-closures.asciidoc

@@ -16,11 +16,12 @@ KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 ////
-== Proposal 3 - Removing the Need for Closures/Lambda in Gremlin
 
-=== Status
+image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"]
 
-This proposal has been accepted through a post to the TinkerPop Dev List and is ready to begin implementaion.
+*Proposal 3*
+
+== Removing the Need for Closures/Lambda in Gremlin
 
 === Motivation
 

docs/src/dev/future/proposal-arrow-flight-2.asciidoc

@@ -18,7 +18,7 @@ under the License.
 ////
 image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"]
 
-*x.y.z - Proposal 2*
+*Proposal 2*
 
 = Gremlin Arrow Flight
 

docs/src/dev/future/proposal-asbool-step-7.asciidoc

@@ -19,7 +19,7 @@ under the License.
 
 image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"]
 
-*x.y.z - Proposal 7*
+*Proposal 7*
 
 == asBool() Step
 

docs/src/dev/future/proposal-asnumber-step-6.asciidoc

@@ -19,7 +19,7 @@ under the License.
 
 image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"]
 
-*x.y.z - Proposal 6*
+*Proposal 6*
 
 == asNumber() Step
 

docs/src/dev/future/proposal-declarative-match-step-9.asciidoc

@@ -17,6 +17,10 @@ specific language governing permissions and limitations
 under the License.
 ////
 
+image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"]
+
+*Proposal 8*
+
 == *Specification for the declarative `match()` step*
 
 This document outlines the specification for a new, declarative

docs/src/dev/future/proposal-equality-1.asciidoc

@@ -18,7 +18,7 @@ under the License.
 ////
 image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"]
 
-*x.y.z - Proposal 1*
+*Proposal 1*
 
 = Equality, Equivalence, Comparability and Orderability Semantics
 

docs/src/dev/future/proposal-scoping-5.asciidoc

@@ -18,7 +18,7 @@ under the License.
 ////
 image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"]
 
-*x.y.z - Proposal 5*
+*Proposal 5*
 
 == Lazy vs. Eager Evaluation in TP4 ==
 

docs/src/dev/future/proposal-transaction-4.asciidoc

@@ -18,7 +18,7 @@ under the License.
 ////
 image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"]
 
-*x.y.z - Proposal 4*
+*Proposal 4*
 
 == TinkerGraph Transaction Support
 

docs/src/dev/future/proposal-type-predicate-8.asciidoc

@@ -19,7 +19,7 @@ under the License.
 
 image::apache-tinkerpop-logo.png[width=500,link="https://tinkerpop.apache.org"]
 
-*x.y.z - Proposal 8*
+*Proposal 8*
 
 == Type Predicate
 

docs/src/dev/provider/gremlin-semantics.asciidoc

@@ -1796,6 +1796,59 @@ See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/j
 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]
 
+[[match-step]]
+=== match()
+
+*Description:* Executes a declarative pattern match query against the graph using a provider-supported query
+string. The query string format is provider-specific; providers may use TinkerPop's optional `gql-gremlin` module
+(which implements the <<tinkergql,TinkerGQL>> dialect) or supply their own engine. Users should consult their
+graph system's documentation to determine what format is supported. The second argument, when provided, supplies
+bound parameters to the query; how (and whether) these are used is left to the provider.
+
+*Syntax:*
+
+* `match(String matchQuery)` +
+* `match(String matchQuery, Map<String, Object> params)`
+
+[width="100%",options="header"]
+|=========================================================
+|Start Step |Mid Step |Modulated |Domain |Range
+|Y |Y |Y (via `with()`) |`any` |`Map<String, Object>`
+|=========================================================
+
+*Arguments:*
+
+* `matchQuery` - An opaque query string evaluated by the graph provider. For example, a GQL MATCH expression:
+  `"MATCH (a:person)-[:knows]->(b:person)"`.
+* `params` - Optional bound parameters passed to the provider alongside the query string. May be `null` or empty.
+
+*Modulation:*
+
+`with("queryLanguage", value)` - specifies which query language the provider should use to evaluate the string.
+When omitted, the provider uses its native or default language.
+
+*Considerations:*
+
+* The step is a provider-delegation point. `gremlin-core` supplies only the placeholder `DeclarativeMatchStep`;
+graph providers replace it with their own implementation via a `TraversalStrategy`.
+* The traverser value emitted by the step is a `Map<String, Object>` containing one entry per named variable in
+the matched pattern, keyed by variable name. Providers must set this map as the traverser value for each result
+row.
+* Each named variable is also recorded as a labeled entry in the traverser's path, so results remain retrievable
+by name via `select()` when downstream steps require individual values.
+* Anonymous elements in the pattern (those without a variable name) are not exposed in the map or path and cannot be
+referenced by `select()`.
+* When used as a spawn step on `GraphTraversalSource`, no upstream traversers are consumed; the provider
+executes the query once and emits one traverser per result row.
+
+*Exceptions*
+
+* If the step is reached and no supporting strategy has replaced the placeholder, an `UnsupportedOperationException` is
+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/DeclarativeMatchStep.java[source],
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#match-step[reference]
+
 [[merge-step]]
 === merge()
 

docs/src/dev/provider/index.asciidoc

@@ -623,6 +623,200 @@ from TinkerPop using the link:https://tinkerpop.apache.org/docs/x.y.z/reference/
 Simply provide a `InputFormat` and `OutputFormat` that can be referenced by a `HadoopGraph` instance as discussed
 in the link:https://tinkerpop.apache.org/docs/x.y.z/reference/#clonevertexprogram[Reference Documentation].
 
+[[tinkerpop-providers-tinkergql]]
+==== Supporting Declarative Pattern Matching (TinkerGQL)
+
+Graph providers can offer declarative pattern matching via the `match(String)` step by integrating the
+link:https://tinkerpop.apache.org/docs/x.y.z/reference/#tinkergql[TinkerGQL] engine shipped in the optional
+`gql-gremlin` module. TinkerGQL handles GQL `MATCH` parsing, query planning, and execution against any `Graph`
+implementation through a thin set of default interface methods, so most providers can get working `match()` support
+with only a few lines of wiring code.
+
+===== Maven Dependency
+
+Add `gql-gremlin` alongside your provider's existing TinkerPop dependencies:
+
+[source,xml]
+----
+<dependency>
+    <groupId>org.apache.tinkerpop</groupId>
+    <artifactId>gql-gremlin</artifactId>
+    <version>x.y.z</version>
+</dependency>
+----
+
+===== Registering the Strategy
+
+Register `GqlDeclarativeMatchStrategy.instance()` in the global strategy cache from a static initializer on your
+graph class. This is exactly how TinkerGraph registers TinkerGQL support:
+
+[source,java]
+----
+import org.apache.tinkerpop.gremlin.gql.GqlDeclarativeMatchStrategy;
+import org.apache.tinkerpop.gremlin.process.traversal.TraversalStrategies;
+import org.apache.tinkerpop.gremlin.structure.Graph;
+
+public class AcmeGraph implements Graph {
+
+    static {
+        TraversalStrategies.GlobalCache.registerStrategies(
+                AcmeGraph.class,
+                TraversalStrategies.GlobalCache.getStrategies(Graph.class).clone()
+                        .addStrategies(GqlDeclarativeMatchStrategy.instance()));  // <1>
+    }
+    // ...
+}
+----
+
+<1> `instance()` is a singleton. On first use against a given graph it lazily creates one `DefaultGqlPlanner`
+    and one `DefaultGqlExecutor` for that graph instance and caches them. All traversals on the same graph
+    reuse that pair, so the planner's query parse cache is shared automatically.
+
+Providers should also evict the cached pair when the graph is closed to avoid retaining it in memory:
+
+[source,java]
+----
+@Override
+public void close() {
+    GqlDeclarativeMatchStrategy.evict(this);  // <1>
+    // ... other cleanup
+}
+----
+
+<1> Removes the per-graph `DefaultGqlPlanner` / `DefaultGqlExecutor` pair from the singleton cache.
+    `AbstractTinkerGraph.close()` does this automatically for TinkerGraph-based implementations.
+
+===== Performance Hints (Optional, but strongly recommended)
+
+Without these overrides the TinkerGQL planner has no cardinality information. It treats every label count as
+unknown (`Long.MAX_VALUE`), which causes it to pick the seed vertex arbitrarily and order extension steps without
+regard to label density. On any graph of meaningful size this produces unnecessarily large intermediate result
+sets and slow query execution. The fix is two method overrides.
+
+The most common customization — and the one that requires the least code — is telling the planner about your
+graph's label cardinalities. Overriding these two methods on your `Graph` implementation is all that is needed
+for the planner to make better join-ordering decisions:
+
+[source,java]
+----
+@Override
+public long countVerticesByLabel(final String label) {
+    return myLabelIndex.getCount(label);  // <1>
+}
+
+@Override
+public long countEdgesByLabel(final String label) {
+    return myEdgeLabelIndex.getCount(label);
+}
+----
+
+<1> Return `Long.MAX_VALUE` if the count is unknown. The planner uses these values only for relative comparison
+    when choosing a seed vertex and ordering extension steps — approximate counts are fine.
+
+These hooks feed directly into `DefaultGqlPlanner`'s seed-selection and step-ordering logic, so no planner
+replacement is needed to benefit from them.
+
+===== Property Index Integration (Optional, but strongly recommended)
+
+Without this override every `MATCH` query performs a full scan of all vertices regardless of any inline property
+filters in the pattern. A query like `MATCH (p:Person {name: $n})` will iterate every vertex in the graph and
+test each one against the predicate, even if your graph has a `name` index that could satisfy it in a single
+lookup. The planner is also unable to use index cardinalities to refine seed selection, so join ordering
+degrades to label-count-only heuristics.
+
+If your graph maintains property indexes, expose them by returning a custom `Graph.Index` from `Graph.index()`.
+When a `MATCH` pattern includes an inline property filter and the executor finds an index for that key, it
+replaces the full vertex scan with a targeted index lookup. The planner also uses index cardinalities to
+refine seed selection:
+
+[source,java]
+----
+@Override
+public Graph.Index index() {
+    return new Graph.Index() {
+
+        @Override
+        public Iterator<Vertex> queryVertexIndex(final String key, final Object value) {
+            return myVertexIndex.lookup(key, value);  // <1>
+        }
+
+        @Override
+        public long countVertexIndex(final String key, final Object value) {
+            return myVertexIndex.isIndexed(key)
+                    ? myVertexIndex.count(key, value)
+                    : Long.MAX_VALUE;  // <2>
+        }
+    };
+}
+----
+
+<1> Return an empty iterator (not `null`) when the key is not indexed or no match exists.
+<2> Returning `Long.MAX_VALUE` for an un-indexed key signals both the planner and executor to fall back to a
+    full vertex scan. Any value less than `Long.MAX_VALUE` — including `0` — means "the index was consulted
+    and returned this count."
+
+===== Custom Executor (Native Engine Integration, Optional)
+
+For providers whose graph has a native traversal API, the most practical advanced customization is replacing
+only the *executor* while keeping `DefaultGqlPlanner`. This lets a provider get free GQL parsing and
+cardinality-guided join ordering from the default planner, then translate the resulting `GqlMatchPlan` into
+native queries rather than running `DefaultGqlExecutor`'s DFS over `Graph.vertices()`.
+
+[source,java]
+----
+public class AcmeGraph implements Graph {
+
+    private final GqlPlanner gqlPlanner = new DefaultGqlPlanner(this);  // <1>
+    private final GqlExecutor gqlExecutor = new AcmeGqlExecutor(this);  // <2>
+
+    @Override
+    public GraphTraversalSource traversal() {
+        return super.traversal()
+                .withStrategies(GqlDeclarativeMatchStrategy.create(gqlPlanner, gqlExecutor));  // <3>
+    }
+    // ...
+}
+----
+
+<1> The default planner is reused: it handles GQL MATCH parsing, BFS join ordering, and seed selection using
+    the `countVerticesByLabel`, `countEdgesByLabel`, and `Graph.index()` overrides already in place.
+<2> `AcmeGqlExecutor` receives a `GqlMatchPlan` and translates each `ExtensionStep` to a native traversal
+    or query rather than calling `Graph.vertices()`.
+<3> Instances are held as fields and reused so the parse cache is shared across traversals.
+
+The contract for a `GqlExecutor` implementation is: for each seed vertex matching the plan's seed label and
+predicates, extend through each `ExtensionStep` in an order that keeps every step's anchor variable bound
+before that step executes, and emit one `Element[]` per complete match. Each array's indices must match
+`GqlMatchPlan.getVariables()`, with the seed variable at index 0. See `DefaultGqlExecutor` for a reference
+implementation.
+
+NOTE: Replacing only the *planner* is rarely worthwhile. Producing a valid `GqlMatchPlan` requires
+      constructing `ExtensionStep` objects, assigning variable index maps, and satisfying all other
+      invariants of that concrete class — effort comparable to writing a full executor anyway. The
+      `Graph` method hooks described above (`countVerticesByLabel`, `countEdgesByLabel`, `Graph.index()`)
+      are the right way to improve plan quality because `DefaultGqlPlanner` already consults them when
+      selecting the seed and ordering steps. A custom planner is only warranted when a provider needs a
+      fundamentally different join strategy (such as a cost-based optimizer backed by richer statistics
+      than label counts). At that level of investment, consider whether replacing both planner and
+      executor — or bypassing `gql-gremlin` entirely via the `DeclarativeMatchStep` pattern described
+      below — is the cleaner path.
+
+===== Implementing a Different Declarative Language
+
+The `GqlDeclarativeMatchStrategy` pattern is not TinkerGQL-specific. Providers that want to support a different
+declarative language over the `match(String)` step, for example openCypher, SPARQL, or a proprietary query language,
+can follow the same pattern:
+
+. Implement `TraversalStrategy.ProviderOptimizationStrategy` and in its `apply()` method locate all
+  `DeclarativeMatchStep` instances in the traversal using `TraversalHelper.getStepsOfClass()`.
+. Replace each `DeclarativeMatchStep` with a custom step that parses the query string and executes it
+  against the graph, emitting binding maps in the same form as `GqlMatchStep`.
+. Register the strategy in the global cache from a static initializer, exactly as shown above for TinkerGQL.
+
+`DeclarativeMatchStep` is the placeholder step inserted by the `match(String)` overload. The first registered
+`ProviderOptimizationStrategy` to claim all `DeclarativeMatchStep` instances in a traversal wins; providers do not
+need to interact with `gql-gremlin` at all if they supply their own end-to-end implementation.
+
 [[validating-with-gremlin-test]]
 === Validating with Gremlin-Test