Package org.apache.tinkerpop.gremlin.gql

Interface GqlPlanner

All Known Implementing Classes:
DefaultGqlPlanner
public interface GqlPlanner
Compiles a GQL MATCH string into an executable GqlMatchPlan.

DefaultGqlPlanner is the reference implementation. It parses the GQL MATCH expression into a QueryGraph, selects a seed vertex by lowest cardinality (via Graph.countVerticesByLabel(String)), and orders extension steps by edge-label density (via Graph.countEdgesByLabel(String)) through a BFS traversal of the query graph. The parsed QueryGraph is cached by query string; seed selection and step ordering are recomputed on each call from live counts so that graph mutations are always reflected.

When to implement this interface

Most providers do not need to implement GqlPlanner. The statistics that drive planning — label cardinalities and index counts — are already surfaced as default methods on Graph (countVerticesByLabel, countEdgesByLabel, and Graph.Index); overriding those methods is all that is needed to improve plan quality in most cases, and DefaultGqlPlanner consults them automatically.

A custom GqlPlanner is warranted only when a provider needs a fundamentally different join strategy — for example, a cost-based optimizer backed by richer statistics than label counts. Note that producing a valid GqlMatchPlan requires constructing ExtensionStep objects, building a variable index map, and satisfying all other invariants of that concrete class — non-trivial work that is roughly comparable in effort to writing a custom executor. At that level of investment, consider whether replacing both planner and executor, or bypassing gql-gremlin entirely by implementing a TraversalStrategy.ProviderOptimizationStrategy that claims DeclarativeMatchStep directly, is the cleaner approach.

The more common advanced customization is to keep DefaultGqlPlanner and replace only the executor. See GqlExecutor for details.

Implementations are encouraged to cache the parsed QueryGraph keyed on the query string; seed selection should be recomputed on each call so that graph mutations are reflected in subsequent executions.

  • Method Summary

    Modifier and Type
    Method
    Description
    GqlMatchPlan
    plan(String gqlMatchString)
    Compiles the given GQL MATCH expression into an executable plan.

  • Method Details

    • plan

      GqlMatchPlan plan(String gqlMatchString)
      Compiles the given GQL MATCH expression into an executable plan.
      Parameters:
      gqlMatchString - a GQL MATCH expression (e.g. "MATCH (a:Person)-[:KNOWS]->(b)")
      Returns:
      the compiled execution plan
      Throws:
      IllegalArgumentException - if the string cannot be parsed