spmallette commented on code in PR #3232: URL: https://github.com/apache/tinkerpop/pull/3232#discussion_r2413541113
########## docs/src/dev/future/proposal-declarative-match-step.asciidoc: ########## @@ -0,0 +1,163 @@ +//// +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +//// + +== *Specification for the declarative `match()` step* + +This document outlines the specification for a new, declarative +`match()` step in Gremlin. This step is designed to replace the existing +imperative `match()` step, which has proven difficult for providers to +optimize and for users to utilize effectively. The new step leverages +familiar declarative graph pattern matching syntax to provide a more +powerful, intuitive, and optimizable query experience. + +=== 1. Motivation + +The current `match()` step in Gremlin is imperative, which requires +graph providers to translate complex traversal logic into an optimizable +form, a notoriously difficult task. Consequently, its adoption is low, +and its performance is often suboptimal. + +The proposed solution introduces a new `match()` step that accepts a +query string from a standard declarative graph query language. This +allows the underlying database to use its native query planner and +optimizer to execute the pattern match efficiently, while Gremlin +retains its role in composing the declarative query with broader +imperative traversals. + +''''' + +=== 2. Core Concept + +The `match()` step introduces a declarative pattern matching clause into +a Gremlin traversal. The variables bound within the pattern are not +returned directly but are added to the traversal’s path history, making +them accessible to subsequent steps like `select()`. + +The `match()` step can be used as both a start step on a +`GraphTraversalSource` and as a mid-traversal step. + +=== 3. Declarative Language + +The `match()` step is language-agnostic by design, but it will +standardize on a default language to ensure portability. + +* *Default Language:* A restricted, read-only subset of *GQL* will be +the default language. This subset will primarily support `MATCH` and +`WHERE` clauses. The `RETURN` clause will *not* be supported in the +default implementation (see Section 6). A provider implementing the +default GQL does not need to be specified via a modulator. +** Example: +`g.match("MATCH (p:Person WHERE p.name = 'Stephen')-[:knows]->(friend)")` +* *Provider-Specific Languages:* Providers may support other declarative +languages (e.g., Cypher, GSQL, SQL++) via the `queryLanguage` modulator. +** Example: `g.match("...").with("queryLanguage", "GSQL")` + +To aid vendors, the TinkerPop project should consider providing a +reference ANTLR4 grammar for the default GQL dialect. + +''''' + +=== 4. Parameterization + +To prevent query injection and improve performance by enabling query +plan caching, parameterized queries are supported. Parameters are +supplied using the existing `with()` modulator with a special key Review Comment: for consistency with a steps like `math` i think we'd prefer `by` rather than `with`. That also removes the conflict with configurations for `match` like the aforementioned: `with("queryLanguage", "GSQL")`` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
