VolcanoPlanner (Calcite Core 1.2.0-incubating API)

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.

Nested Class Summary
- Nested classes/interfaces inherited from interface org.apache.calcite.plan.RelOptPlanner
  RelOptPlanner.CannotPlanException, RelOptPlanner.Executor

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`ambitious` If true, the planner keeps applying rules as long as they continue to reduce the cost.
`protected static double`	`COST_IMPROVEMENT`
`protected boolean`	`impatient` If true, and if `ambitious` is true, the planner waits a finite number of iterations for the cost to improve.
`protected RelSubset`	`root`
`protected Set<RelOptRule>`	`ruleSet` Set of all registered rules.

Fields inherited from class org.apache.calcite.plan.AbstractRelOptPlanner
context, costFactory

Fields inherited from interface org.apache.calcite.plan.RelOptPlanner
LOGGER

Constructor Summary

Constructors
Constructor and Description
`VolcanoPlanner()` Creates a uninitialized `VolcanoPlanner`.
`VolcanoPlanner(Context externalContext)` Creates a uninitialized `VolcanoPlanner`.
`VolcanoPlanner(RelOptCostFactory costFactory, Context externalContext)` Creates a `VolcanoPlanner` with a given cost factory.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addLattice(RelOptLattice lattice)` Defines a lattice.
`void`	`addListener(RelOptListener newListener)` Adds a listener to this planner.
`void`	`addMaterialization(RelOptMaterialization materialization)` Defines a pair of relational expressions that are equivalent.
`boolean`	`addRelTraitDef(RelTraitDef relTraitDef)` Registers a rel trait definition.
`boolean`	`addRule(RelOptRule rule)` Registers a rule.
`boolean`	`canConvert(RelTraitSet fromTraits, RelTraitSet toTraits)`
`RelNode`	`changeTraits(RelNode rel, RelTraitSet toTraits)` Changes a relational expression to an equivalent one with a different set of traits.
`RelOptPlanner`	`chooseDelegate()` Negotiates an appropriate planner to deal with distributed queries.
`void`	`clear()` Removes all internal state, including all rules.
`void`	`clearRelTraitDefs()` Clear all the registered RelTraitDef.
`void`	`dump(PrintWriter pw)` Dumps the internal state of this VolcanoPlanner to a writer.
`RelTraitSet`	`emptyTraitSet()` Creates an empty trait set.
`RelSubset`	`ensureRegistered(RelNode rel, RelNode equivRel)` Registers a relational expression if it is not already registered.
`void`	`ensureRegistered(RelNode rel, RelNode equivRel, VolcanoRuleCall ruleCall)`
`RelNode`	`findBestExp()` Finds the most efficient expression to implement the query given via `RelOptPlanner.setRoot(org.apache.calcite.rel.RelNode)`.
`RelOptCost`	`getCost(RelNode rel)` Computes the cost of a RelNode.
`RelOptLattice`	`getLattice(RelOptTable table)` Retrieves a lattice, given its star table.
`protected VolcanoPlannerPhaseRuleMappingInitializer`	`getPhaseRuleMappingInitializer()`
`long`	`getRelMetadataTimestamp(RelNode rel)` Gets a timestamp for a given rel's metadata.
`List<RelTraitDef>`	`getRelTraitDefs()` Returns the list of active trait types.
`RelNode`	`getRoot()` Returns the root node of this query.
`org.apache.calcite.plan.volcano.RelSet`	`getSet(RelNode rel)` Finds an expression's equivalence set.
`RelSubset`	`getSubset(RelNode rel)` Returns the subset that a relational expression belongs to.
`RelSubset`	`getSubset(RelNode rel, RelTraitSet traits)`
`RelSubset`	`getSubset(RelNode rel, RelTraitSet traits, boolean createIfMissing)`
`boolean`	`isRegistered(RelNode rel)` Determines whether a relational expression has been registered.
`static String`	`normalizePlan(String plan)` Normalizes references to subsets within the string representation of a plan.
`protected void`	`onNewClass(RelNode node)` Called when a new class of `RelNode` is seen.
`RelSubset`	`register(RelNode rel, RelNode equivRel)` Registers a relational expression in the expression bank.
`void`	`registerAbstractRelationalRules()`
`void`	`registerMetadataProviders(List<RelMetadataProvider> list)` Gives this planner a chance to register one or more `RelMetadataProvider`s in the chain which will be used to answer metadata queries.
`void`	`registerSchema(RelOptSchema schema)` Tells this planner that a schema exists.
`boolean`	`removeRule(RelOptRule rule)` Removes a rule.
`void`	`setImportance(RelNode rel, double importance)` Sets the importance of a relational expression.
`void`	`setLocked(boolean locked)` Sets whether this planner is locked.
`void`	`setRoot(RelNode rel)` Sets the root node of this query.
`protected void`	`validate()` Checks internal consistency.

Methods inherited from class org.apache.calcite.plan.AbstractRelOptPlanner
checkCancel, fireRule, getContext, getCostFactory, getExecutor, getListener, getRuleByDescription, isRuleExcluded, mapRuleDescription, notifyChosen, notifyDiscard, notifyEquivalence, notifyTransformation, onCopy, registerClass, setCancelFlag, setExecutor, setRuleDescExclusionFilter, subClasses, unmapRuleDescription

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - COST_IMPROVEMENT
```
protected static final double COST_IMPROVEMENT
```
    See Also:
    Constant Field Values
  - root
```
protected RelSubset root
```
  - ambitious
```
protected boolean ambitious
```
    If true, the planner keeps applying rules as long as they continue to reduce the cost. If false, the planner terminates as soon as it has found any implementation, no matter how expensive. The default is false due to unresolved bugs with various rules.
  - impatient
```
protected boolean impatient
```
    If true, and if ambitious is true, the planner waits a finite number of iterations for the cost to improve.
    The number of iterations K is equal to the number of iterations required to get the first finite plan. After the first finite plan, it continues to fire rules to try to improve it. The planner sets a target cost of the current best cost multiplied by COST_IMPROVEMENT. If it does not meet that cost target within K steps, it quits, and uses the current best plan. If it meets the cost, it sets a new, lower target, and has another K iterations to meet it. And so forth.
    If false, the planner continues to fire rules until the rule queue is empty.
  - ruleSet
```
protected final Set<RelOptRule> ruleSet
```
    Set of all registered rules.
- Constructor Detail
  - 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(RelOptCostFactory costFactory,
              Context externalContext)
```
    Creates a VolcanoPlanner with a given cost factory.
- Method Detail
  - getPhaseRuleMappingInitializer
```
protected VolcanoPlannerPhaseRuleMappingInitializer getPhaseRuleMappingInitializer()
```
  - 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
```
public RelNode getRoot()
```
    Description copied from interface: RelOptPlanner
    
    Returns the root node of this query.
    
    Returns:
    Root node
  - 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 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
  - getSet
```
public 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 rules.
    
    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.
    
    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.
    
    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
  - canConvert
```
public boolean canConvert(RelTraitSet fromTraits,
                 RelTraitSet toTraits)
```
  - 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).
    The algorithm executes repeatedly in a series of phases. In each phase the exact rules that may be fired varies. The mapping of phases to rule sets is maintained in the ruleQueue.
    In each phase, the planner sets the initial importance of the existing RelSubSets (setInitialImportance()). The planner then iterates over the rule matches presented by the rule queue until:
    1. The rule queue becomes empty.
    2. For ambitious planners: No improvements to the plan have been made recently (specifically within a number of iterations that is 10% of the number of iterations necessary to first reach an implementable plan or 25 iterations whichever is larger).
    3. For non-ambitious planners: When an implementable plan is found.
    Furthermore, after every 10 iterations without an implementable plan, RelSubSets that contain only logical RelNodes are given an importance boost via injectImportanceBoost(). Once an implementable plan is found, the artificially raised importance values are cleared (see clearImportanceBoost()).
    Returns:
    the most efficient RelNode tree found for implementing the given query
  - register
```
public RelSubset register(RelNode rel,
                 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,
                         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
  - validate
```
protected void validate()
```
    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
  - getCost
```
public RelOptCost getCost(RelNode rel)
```
    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 - expression of interest
    
    Returns:
    estimated cost
  - getSubset
```
public 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
  - getSubset
```
public RelSubset getSubset(RelNode rel,
                  RelTraitSet traits)
```
  - getSubset
```
public RelSubset getSubset(RelNode rel,
                  RelTraitSet traits,
                  boolean createIfMissing)
```
  - setImportance
```
public void setImportance(RelNode rel,
                 double importance)
```
    Description copied from interface: RelOptPlanner
    
    Sets the importance of a relational expression.
    An important use of this method is when a RelOptRule has created a relational expression which is indisputably better than the original relational expression. The rule set the original relational expression's importance to zero, to reduce the search space. Pending rule calls are cancelled, and future rules will not fire.
    
    Specified by:
    
    setImportance in interface RelOptPlanner
    
    Overrides:
    
    setImportance in class AbstractRelOptPlanner
    
    Parameters:
    rel - Relational expression
    importance - Importance
  - dump
```
public void dump(PrintWriter pw)
```
    Dumps the internal state of this VolcanoPlanner to a writer.
    
    Parameters:
    pw - Print writer
    See Also:
    normalizePlan(String)
  - addListener
```
public void addListener(RelOptListener newListener)
```
    Description copied from interface: RelOptPlanner
    
    Adds a listener to this planner.
    
    Specified by:
    
    addListener in interface RelOptPlanner
    
    Overrides:
    
    addListener in class AbstractRelOptPlanner
    
    Parameters:
    newListener - new listener to be notified of events
  - registerMetadataProviders
```
public void registerMetadataProviders(List<RelMetadataProvider> list)
```
    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
```
public long getRelMetadataTimestamp(RelNode rel)
```
    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 String normalizePlan(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])
    
    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
  - ensureRegistered
```
public void ensureRegistered(RelNode rel,
                    RelNode equivRel,
                    VolcanoRuleCall ruleCall)
```

Class VolcanoPlanner

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.calcite.plan.RelOptPlanner

Field Summary

Fields inherited from class org.apache.calcite.plan.AbstractRelOptPlanner

Fields inherited from interface org.apache.calcite.plan.RelOptPlanner

Constructor Summary

Method Summary

Methods inherited from class org.apache.calcite.plan.AbstractRelOptPlanner

Methods inherited from class java.lang.Object

Field Detail

COST_IMPROVEMENT

root

ambitious

impatient

ruleSet

Constructor Detail

VolcanoPlanner

VolcanoPlanner

VolcanoPlanner

Method Detail

getPhaseRuleMappingInitializer

isRegistered

setRoot

getRoot

addMaterialization

addLattice

getLattice

getSet

addRelTraitDef

clearRelTraitDefs

getRelTraitDefs

emptyTraitSet

clear

addRule

removeRule

onNewClass

canConvert

changeTraits

chooseDelegate

findBestExp

register

ensureRegistered

validate

registerAbstractRelationalRules

registerSchema

getCost

getSubset

getSubset

getSubset

setImportance

dump

addListener

registerMetadataProviders

getRelMetadataTimestamp

normalizePlan

setLocked

ensureRegistered