Package org.apache.calcite.plan.volcano

Class VolcanoPlanner

java.lang.Object
org.apache.calcite.plan.AbstractRelOptPlanner
org.apache.calcite.plan.volcano.VolcanoPlanner
All Implemented Interfaces:
RelOptPlanner
public class VolcanoPlanner extends AbstractRelOptPlanner
VolcanoPlanner optimizes queries by transforming expressions selectively according to a dynamic programming algorithm.

  • Field Details

    • root

      protected @MonotonicNonNull RelSubset root

  • Constructor Details

    • VolcanoPlanner

      public VolcanoPlanner()
      Creates a uninitialized VolcanoPlanner. To fully initialize it, the caller must register the desired set of relations, rules, and calling conventions.

    • VolcanoPlanner

      public VolcanoPlanner(Context externalContext)
      Creates a uninitialized VolcanoPlanner. To fully initialize it, the caller must register the desired set of relations, rules, and calling conventions.

    • VolcanoPlanner

      public VolcanoPlanner(@Nullable RelOptCostFactory costFactory, @Nullable Context externalContext)
      Creates a VolcanoPlanner with a given cost factory.

  • Method Details

    • setTopDownOpt

      public void setTopDownOpt(boolean value)
      Enable or disable top-down optimization.

      Note: Enabling top-down optimization will automatically enable top-down trait propagation.

    • isRegistered

      public boolean isRegistered(RelNode rel)
      Description copied from interface: RelOptPlanner
      Determines whether a relational expression has been registered.
      Parameters:
      rel - expression to test
      Returns:
      whether rel has been registered

    • setRoot

      public void setRoot(RelNode rel)
      Description copied from interface: RelOptPlanner
      Sets the root node of this query.
      Parameters:
      rel - Relational expression

    • getRoot

      @Pure public @Nullable RelNode getRoot()
      Description copied from interface: RelOptPlanner
      Returns the root node of this query.
      Returns:
      Root node

    • getMaterializations

      public List<RelOptMaterialization> getMaterializations()
      Description copied from interface: RelOptPlanner
      Returns the materializations that have been registered with the planner.
      Specified by:
      getMaterializations in interface RelOptPlanner
      Overrides:
      getMaterializations in class AbstractRelOptPlanner

    • addMaterialization

      public void addMaterialization(RelOptMaterialization materialization)
      Description copied from interface: RelOptPlanner
      Defines a pair of relational expressions that are equivalent.

      Typically tableRel is a LogicalTableScan representing a table that is a materialized view and queryRel is the SQL expression that populates that view. The intention is that tableRel is cheaper to evaluate and therefore if the query being optimized uses (or can be rewritten to use) queryRel as a sub-expression then it can be optimized by using tableRel instead.

      Specified by:
      addMaterialization in interface RelOptPlanner
      Overrides:
      addMaterialization in class AbstractRelOptPlanner

    • addLattice

      public void addLattice(RelOptLattice lattice)
      Description copied from interface: RelOptPlanner
      Defines a lattice.

      The lattice may have materializations; it is not necessary to call RelOptPlanner.addMaterialization(org.apache.calcite.plan.RelOptMaterialization) for these; they are registered implicitly.

      Specified by:
      addLattice in interface RelOptPlanner
      Overrides:
      addLattice in class AbstractRelOptPlanner

    • getLattice

      public @Nullable RelOptLattice getLattice(RelOptTable table)
      Description copied from interface: RelOptPlanner
      Retrieves a lattice, given its star table.
      Specified by:
      getLattice in interface RelOptPlanner
      Overrides:
      getLattice in class AbstractRelOptPlanner

    • registerMaterializations

      protected void registerMaterializations()

    • getSet

      public @Nullable org.apache.calcite.plan.volcano.RelSet getSet(RelNode rel)
      Finds an expression's equivalence set. If the expression is not registered, returns null.
      Parameters:
      rel - Relational expression
      Returns:
      Equivalence set that expression belongs to, or null if it is not registered

    • addRelTraitDef

      public boolean addRelTraitDef(RelTraitDef relTraitDef)
      Description copied from interface: RelOptPlanner
      Registers a rel trait definition. If the RelTraitDef has already been registered, does nothing.
      Specified by:
      addRelTraitDef in interface RelOptPlanner
      Overrides:
      addRelTraitDef in class AbstractRelOptPlanner
      Returns:
      whether the RelTraitDef was added, as per Collection.add(E)

    • clearRelTraitDefs

      public void clearRelTraitDefs()
      Description copied from interface: RelOptPlanner
      Clear all the registered RelTraitDef.
      Specified by:
      clearRelTraitDefs in interface RelOptPlanner
      Overrides:
      clearRelTraitDefs in class AbstractRelOptPlanner

    • getRelTraitDefs

      public List<RelTraitDef> getRelTraitDefs()
      Description copied from interface: RelOptPlanner
      Returns the list of active trait types.
      Specified by:
      getRelTraitDefs in interface RelOptPlanner
      Overrides:
      getRelTraitDefs in class AbstractRelOptPlanner

    • emptyTraitSet

      public RelTraitSet emptyTraitSet()
      Description copied from interface: RelOptPlanner
      Creates an empty trait set. It contains all registered traits, and the default values of any traits that have them.

      The empty trait set acts as the prototype (a kind of factory) for all subsequently created trait sets.

      Specified by:
      emptyTraitSet in interface RelOptPlanner
      Overrides:
      emptyTraitSet in class AbstractRelOptPlanner
      Returns:
      Empty trait set

    • clear

      public void clear()
      Description copied from interface: RelOptPlanner
      Removes all internal state, including all registered rules, materialized views, and lattices.
      Specified by:
      clear in interface RelOptPlanner
      Overrides:
      clear in class AbstractRelOptPlanner

    • addRule

      public boolean addRule(RelOptRule rule)
      Description copied from interface: RelOptPlanner
      Registers a rule.

      If the rule has already been registered, does nothing. This method determines if the given rule is a ConverterRule and pass the ConverterRule to all registered RelTraitDef instances.

      Specified by:
      addRule in interface RelOptPlanner
      Overrides:
      addRule in class AbstractRelOptPlanner
      Returns:
      whether the rule was added, as per Collection.add(E)

    • removeRule

      public boolean removeRule(RelOptRule rule)
      Description copied from interface: RelOptPlanner
      Removes a rule.
      Specified by:
      removeRule in interface RelOptPlanner
      Overrides:
      removeRule in class AbstractRelOptPlanner
      Returns:
      true if the rule was present, as per Collection.remove(Object)

    • onNewClass

      protected void onNewClass(RelNode node)
      Description copied from class: AbstractRelOptPlanner
      Called when a new class of RelNode is seen.
      Overrides:
      onNewClass in class AbstractRelOptPlanner

    • changeTraits

      public RelNode changeTraits(RelNode rel, RelTraitSet toTraits)
      Description copied from interface: RelOptPlanner
      Changes a relational expression to an equivalent one with a different set of traits.
      Parameters:
      rel - Relational expression (may or may not have been registered; must not have the desired traits)
      toTraits - Trait set to convert the relational expression to
      Returns:
      Relational expression with desired traits. Never null, but may be abstract

    • chooseDelegate

      public RelOptPlanner chooseDelegate()
      Description copied from interface: RelOptPlanner
      Negotiates an appropriate planner to deal with distributed queries. The idea is that the schemas decide among themselves which has the most knowledge. Right now, the local planner retains control.
      Specified by:
      chooseDelegate in interface RelOptPlanner
      Overrides:
      chooseDelegate in class AbstractRelOptPlanner

    • findBestExp

      public RelNode findBestExp()
      Finds the most efficient expression to implement the query given via RelOptPlanner.setRoot(org.apache.calcite.rel.RelNode).
      Returns:
      the most efficient RelNode tree found for implementing the given query

    • checkCancel

      public void checkCancel()
      Description copied from class: AbstractRelOptPlanner
      Checks to see whether cancellation has been requested, and if so, throws an exception.
      Overrides:
      checkCancel in class AbstractRelOptPlanner

    • register

      public RelSubset register(RelNode rel, @Nullable RelNode equivRel)
      Description copied from interface: RelOptPlanner
      Registers a relational expression in the expression bank.

      After it has been registered, you may not modify it.

      The expression must not already have been registered. If you are not sure whether it has been registered, call RelOptPlanner.ensureRegistered(RelNode, RelNode).

      Parameters:
      rel - Relational expression to register (must not already be registered)
      equivRel - Relational expression it is equivalent to (may be null)
      Returns:
      the same expression, or an equivalent existing expression

    • ensureRegistered

      public RelSubset ensureRegistered(RelNode rel, @Nullable RelNode equivRel)
      Description copied from interface: RelOptPlanner
      Registers a relational expression if it is not already registered.

      If equivRel is specified, rel is placed in the same equivalence set. It is OK if equivRel has different traits; rel will end up in a different subset of the same set.

      It is OK if rel is a subset.

      Parameters:
      rel - Relational expression to register
      equivRel - Relational expression it is equivalent to (may be null)
      Returns:
      Registered relational expression

    • isValid

      protected boolean isValid(Litmus litmus)
      Checks internal consistency.

    • registerAbstractRelationalRules

      public void registerAbstractRelationalRules()

    • registerSchema

      public void registerSchema(RelOptSchema schema)
      Description copied from interface: RelOptPlanner
      Tells this planner that a schema exists. This is the schema's chance to tell the planner about all of the special transformation rules.
      Specified by:
      registerSchema in interface RelOptPlanner
      Overrides:
      registerSchema in class AbstractRelOptPlanner

    • setNoneConventionHasInfiniteCost

      public void setNoneConventionHasInfiniteCost(boolean infinite)
      Sets whether this planner should consider rel nodes with Convention.NONE to have infinite cost or not.
      Parameters:
      infinite - Whether to make none convention rel nodes infinite cost

    • getCost

      public @Nullable RelOptCost getCost(RelNode rel, RelMetadataQuery mq)
      Description copied from interface: RelOptPlanner
      Computes the cost of a RelNode. In most cases, this just dispatches to RelMetadataQuery.getCumulativeCost(org.apache.calcite.rel.RelNode).
      Specified by:
      getCost in interface RelOptPlanner
      Overrides:
      getCost in class AbstractRelOptPlanner
      Parameters:
      rel - Relational expression of interest
      mq - Metadata query
      Returns:
      estimated cost

    • getSubset

      public @Nullable RelSubset getSubset(RelNode rel)
      Returns the subset that a relational expression belongs to.
      Parameters:
      rel - Relational expression
      Returns:
      Subset it belongs to, or null if it is not registered

    • getSubsetNonNull

      @API(since="1.26", status=EXPERIMENTAL) public RelSubset getSubsetNonNull(RelNode rel)
      Returns the subset that a relational expression belongs to.
      Parameters:
      rel - Relational expression
      Returns:
      Subset it belongs to, or null if it is not registered
      Throws:
      AssertionError - in case subset is not found

    • getSubset

      public @Nullable RelSubset getSubset(RelNode rel, RelTraitSet traits)

    • prune

      public void prune(RelNode rel)
      Description copied from interface: RelOptPlanner
      Prunes a node from the planner.

      When a node is pruned, the related pending rule calls are cancelled, and future rules will not fire. This can be used to reduce the search space.

      Specified by:
      prune in interface RelOptPlanner
      Overrides:
      prune in class AbstractRelOptPlanner
      Parameters:
      rel - the node to prune.

    • dump

      public void dump(PrintWriter pw)
      Dumps the internal state of this VolcanoPlanner to a writer.
      Parameters:
      pw - Print writer
      See Also:

    • toDot

      public String toDot()

    • registerMetadataProviders

      @Deprecated public void registerMetadataProviders(List<RelMetadataProvider> list)
      Deprecated.
      Description copied from interface: RelOptPlanner
      Gives this planner a chance to register one or more RelMetadataProviders in the chain which will be used to answer metadata queries.

      Planners which use their own relational expressions internally to represent concepts such as equivalence classes will generally need to supply corresponding metadata providers.

      Specified by:
      registerMetadataProviders in interface RelOptPlanner
      Overrides:
      registerMetadataProviders in class AbstractRelOptPlanner
      Parameters:
      list - receives planner's custom providers, if any

    • getRelMetadataTimestamp

      @Deprecated public long getRelMetadataTimestamp(RelNode rel)
      Deprecated.
      Description copied from interface: RelOptPlanner
      Gets a timestamp for a given rel's metadata. This timestamp is used by CachingRelMetadataProvider to decide whether cached metadata has gone stale.
      Specified by:
      getRelMetadataTimestamp in interface RelOptPlanner
      Overrides:
      getRelMetadataTimestamp in class AbstractRelOptPlanner
      Parameters:
      rel - rel of interest
      Returns:
      timestamp of last change which might affect metadata derivation

    • normalizePlan

      public static @PolyNull String normalizePlan(@PolyNull String plan)
      Normalizes references to subsets within the string representation of a plan.

      This is useful when writing tests: it helps to ensure that tests don't break when an extra rule is introduced that generates a new subset and causes subsequent subset numbers to be off by one.

      For example,

      FennelAggRel.FENNEL_EXEC(child=Subset#17.FENNEL_EXEC,groupCount=1, EXPR$1=COUNT())
        FennelSortRel.FENNEL_EXEC(child=Subset#2.FENNEL_EXEC, key=[0], discardDuplicates=false)
          FennelCalcRel.FENNEL_EXEC( child=Subset#4.FENNEL_EXEC, expr#0..8={inputs}, expr#9=3456, DEPTNO=$t7, $f0=$t9)
            MockTableImplRel.FENNEL_EXEC( table=[CATALOG, SALES, EMP])

      becomes

      FennelAggRel.FENNEL_EXEC(child=Subset#{0}.FENNEL_EXEC, groupCount=1, EXPR$1=COUNT())
        FennelSortRel.FENNEL_EXEC(child=Subset#{1}.FENNEL_EXEC, key=[0], discardDuplicates=false)
          FennelCalcRel.FENNEL_EXEC( child=Subset#{2}.FENNEL_EXEC,expr#0..8={inputs},expr#9=3456,DEPTNO=$t7, $f0=$t9)
            MockTableImplRel.FENNEL_EXEC( table=[CATALOG, SALES, EMP])

      Returns null if and only if plan is null.

      Parameters:
      plan - Plan
      Returns:
      Normalized plan

    • setLocked

      public void setLocked(boolean locked)
      Sets whether this planner is locked. A locked planner does not accept new rules. addRule(org.apache.calcite.plan.RelOptRule) will do nothing and return false.
      Parameters:
      locked - Whether planner is locked

    • isLogical

      @API(since="1.24", status=EXPERIMENTAL) public boolean isLogical(RelNode rel)
      Decide whether a rule is logical or not.
      Parameters:
      rel - The specific rel node
      Returns:
      True if the relnode is a logical node

    • isSubstituteRule

      @API(since="1.24", status=EXPERIMENTAL) protected boolean isSubstituteRule(VolcanoRuleCall match)
      Checks whether a rule match is a substitution rule match.
      Parameters:
      match - The rule match to check
      Returns:
      True if the rule match is a substitution rule match

    • isTransformationRule

      @API(since="1.24", status=EXPERIMENTAL) protected boolean isTransformationRule(VolcanoRuleCall match)
      Checks whether a rule match is a transformation rule match.
      Parameters:
      match - The rule match to check
      Returns:
      True if the rule match is a transformation rule match

    • getLowerBound

      @API(since="1.24", status=EXPERIMENTAL) protected RelOptCost getLowerBound(RelNode rel)
      Gets the lower bound cost of a relational operator.
      Parameters:
      rel - The rel node
      Returns:
      The lower bound cost of the given rel. The value is ensured NOT NULL.

    • upperBoundForInputs

      @API(since="1.24", status=EXPERIMENTAL) protected RelOptCost upperBoundForInputs(RelNode mExpr, RelOptCost upperBound)
      Gets the upper bound of its inputs. Allow users to overwrite this method as some implementations may have different cost model on some RelNodes, like Spool.