RelOptPlanner (Apache Calcite API)

All Known Implementing Classes:

AbstractRelOptPlanner, HepPlanner, VolcanoPlanner
```
public interface RelOptPlanner
```
A RelOptPlanner is a query optimizer: it transforms a relational expression into a semantically equivalent relational expression, according to a given set of rules and a cost model.

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static class`	`RelOptPlanner.CannotPlanException` Thrown by `findBestExp()`.
`static interface`	`RelOptPlanner.Executor` Deprecated. Use `RexExecutor`

Field Summary

Fields
Modifier and Type Field and Description

static org.slf4j.Logger LOGGER

Fields
Modifier and Type	Field and Description
`static org.slf4j.Logger`	`LOGGER`

Method Summary

All Methods Instance Methods Abstract Methods Deprecated 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.
`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 registered rules, materialized views, and lattices.
`void`	`clearRelTraitDefs()` Clear all the registered RelTraitDef.
`RelTraitSet`	`emptyTraitSet()` Creates an empty trait set.
`RelNode`	`ensureRegistered(RelNode rel, @Nullable RelNode equivRel)` Registers a relational expression if it is not already registered.
`RelNode`	`findBestExp()` Finds the most efficient expression to implement this query.
`Context`	`getContext()` Provides the Context created when this planner was constructed.
`@Nullable RelOptCost`	`getCost(RelNode rel)` Deprecated. Use `getCost(RelNode, RelMetadataQuery)` or, better, call `RelMetadataQuery.getCumulativeCost(RelNode)`.
`@Nullable RelOptCost`	`getCost(RelNode rel, RelMetadataQuery mq)` Computes the cost of a RelNode.
`RelOptCostFactory`	`getCostFactory()` Returns the factory that creates `RelOptCost`s.
`@Nullable RexExecutor`	`getExecutor()` Returns the executor used to evaluate constant expressions.
`@Nullable RelOptLattice`	`getLattice(RelOptTable table)` Retrieves a lattice, given its star table.
`List<RelOptMaterialization>`	`getMaterializations()` Returns the materializations that have been registered with the planner.
`long`	`getRelMetadataTimestamp(RelNode rel)` Deprecated.
`List<RelTraitDef>`	`getRelTraitDefs()` Returns the list of active trait types.
`@Nullable RelNode`	`getRoot()` Returns the root node of this query.
`List<RelOptRule>`	`getRules()` Returns the list of all registered rules.
`boolean`	`isRegistered(RelNode rel)` Determines whether a relational expression has been registered.
`void`	`onCopy(RelNode rel, RelNode newRel)` Called when a relational expression is copied to a similar expression.
`void`	`prune(RelNode rel)` Prunes a node from the planner.
`RelNode`	`register(RelNode rel, @Nullable RelNode equivRel)` Registers a relational expression in the expression bank.
`void`	`registerClass(RelNode node)` Registers a class of RelNode.
`void`	`registerMetadataProviders(List<RelMetadataProvider> list)` Deprecated.
`void`	`registerSchema(RelOptSchema schema)` Tells this planner that a schema exists.
`boolean`	`removeRule(RelOptRule rule)` Removes a rule.
`void`	`setCancelFlag(CancelFlag cancelFlag)` Deprecated. Previously, this method installed the cancellation-checking flag for this planner, but is now deprecated. Now, you should add a `CancelFlag` to the `Context` passed to the constructor.
`void`	`setExecutor(@Nullable RexExecutor executor)` Sets the object that can execute scalar expressions.
`void`	`setRoot(RelNode rel)` Sets the root node of this query.
`void`	`setRuleDescExclusionFilter(@Nullable Pattern exclusionFilter)` Sets the exclusion filter to use for this planner.

- Field Detail
  - LOGGER
```
static final org.slf4j.Logger LOGGER
```
- Method Detail
  - setRoot
```
void setRoot(RelNode rel)
```
    Sets the root node of this query.
    
    Parameters:
    
    rel - Relational expression
  - getRoot
```
@Nullable RelNode getRoot()
```
    Returns the root node of this query.
    
    Returns:
    
    Root node
  - addRelTraitDef
```
boolean addRelTraitDef(RelTraitDef relTraitDef)
```
    Registers a rel trait definition. If the RelTraitDef has already been registered, does nothing.
    
    Returns:
    
    whether the RelTraitDef was added, as per Collection.add(E)
  - clearRelTraitDefs
```
void clearRelTraitDefs()
```
    Clear all the registered RelTraitDef.
  - getRelTraitDefs
```
List<RelTraitDef> getRelTraitDefs()
```
    Returns the list of active trait types.
  - clear
```
void clear()
```
    Removes all internal state, including all registered rules, materialized views, and lattices.
  - getRules
```
List<RelOptRule> getRules()
```
    Returns the list of all registered rules.
  - addRule
```
boolean addRule(RelOptRule rule)
```
    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
```
boolean removeRule(RelOptRule rule)
```
    Removes a rule.
    
    Returns:
    
    true if the rule was present, as per Collection.remove(Object)
  - getContext
```
Context getContext()
```
    Provides the Context created when this planner was constructed.
    
    Returns:
    
    Never null; either an externally defined context, or a dummy context that returns null for each requested interface
  - setRuleDescExclusionFilter
```
void setRuleDescExclusionFilter(@Nullable Pattern exclusionFilter)
```
    Sets the exclusion filter to use for this planner. Rules which match the given pattern will not be fired regardless of whether or when they are added to the planner.
    
    Parameters:
    
    exclusionFilter - pattern to match for exclusion; null to disable filtering
  - setCancelFlag
```
@Deprecated
void setCancelFlag(CancelFlag cancelFlag)
```
    Deprecated. Previously, this method installed the cancellation-checking flag for this planner, but is now deprecated. Now, you should add a CancelFlag to the Context passed to the constructor.
    
    Does nothing.
    
    Parameters:
    
    cancelFlag - flag which the planner should periodically check
  - changeTraits
```
RelNode changeTraits(RelNode rel,
                     RelTraitSet toTraits)
```
    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
```
RelOptPlanner chooseDelegate()
```
    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.
  - addMaterialization
```
void addMaterialization(RelOptMaterialization materialization)
```
    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.
  - getMaterializations
```
List<RelOptMaterialization> getMaterializations()
```
    Returns the materializations that have been registered with the planner.
  - addLattice
```
void addLattice(RelOptLattice lattice)
```
    Defines a lattice.
    The lattice may have materializations; it is not necessary to call addMaterialization(org.apache.calcite.plan.RelOptMaterialization) for these; they are registered implicitly.
  - getLattice
```
@Nullable RelOptLattice getLattice(RelOptTable table)
```
    Retrieves a lattice, given its star table.
  - findBestExp
```
RelNode findBestExp()
```
    Finds the most efficient expression to implement this query.
    
    Throws:
    
    RelOptPlanner.CannotPlanException - if cannot find a plan
  - getCostFactory
```
RelOptCostFactory getCostFactory()
```
    Returns the factory that creates RelOptCosts.
  - getCost
```
@Nullable RelOptCost getCost(RelNode rel,
                             RelMetadataQuery mq)
```
    Computes the cost of a RelNode. In most cases, this just dispatches to RelMetadataQuery.getCumulativeCost(org.apache.calcite.rel.RelNode).
    
    Parameters:
    
    rel - Relational expression of interest
    
    mq - Metadata query
    
    Returns:
    
    estimated cost
  - getCost
```
@Deprecated
@Nullable RelOptCost getCost(RelNode rel)
```
    Deprecated. Use getCost(RelNode, RelMetadataQuery) or, better, call RelMetadataQuery.getCumulativeCost(RelNode).
  - register
```
RelNode register(RelNode rel,
                 @Nullable RelNode equivRel)
```
    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 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
```
RelNode ensureRegistered(RelNode rel,
                         @Nullable RelNode equivRel)
```
    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
  - isRegistered
```
boolean isRegistered(RelNode rel)
```
    Determines whether a relational expression has been registered.
    
    Parameters:
    
    rel - expression to test
    
    Returns:
    
    whether rel has been registered
  - registerSchema
```
void registerSchema(RelOptSchema schema)
```
    Tells this planner that a schema exists. This is the schema's chance to tell the planner about all of the special transformation rules.
  - addListener
```
void addListener(RelOptListener newListener)
```
    Adds a listener to this planner.
    
    Parameters:
    
    newListener - new listener to be notified of events
  - registerMetadataProviders
```
@Deprecated
void registerMetadataProviders(List<RelMetadataProvider> list)
```
    Deprecated.
    
    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.
    
    Parameters:
    
    list - receives planner's custom providers, if any
  - getRelMetadataTimestamp
```
@Deprecated
long getRelMetadataTimestamp(RelNode rel)
```
    Deprecated.
    
    Gets a timestamp for a given rel's metadata. This timestamp is used by CachingRelMetadataProvider to decide whether cached metadata has gone stale.
    
    Parameters:
    
    rel - rel of interest
    
    Returns:
    
    timestamp of last change which might affect metadata derivation
  - prune
```
void prune(RelNode rel)
```
    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.
    
    Parameters:
    
    rel - the node to prune.
  - registerClass
```
void registerClass(RelNode node)
```
    Registers a class of RelNode. If this class of RelNode has been seen before, does nothing.
    
    Parameters:
    
    node - Relational expression
  - emptyTraitSet
```
RelTraitSet emptyTraitSet()
```
    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.
    
    Returns:
    
    Empty trait set
  - setExecutor
```
void setExecutor(@Nullable RexExecutor executor)
```
    Sets the object that can execute scalar expressions.
  - getExecutor
```
@Nullable RexExecutor getExecutor()
```
    Returns the executor used to evaluate constant expressions.
  - onCopy
```
void onCopy(RelNode rel,
            RelNode newRel)
```
    Called when a relational expression is copied to a similar expression.

Interface RelOptPlanner

Nested Class Summary

Field Summary

Method Summary

Field Detail

LOGGER

Method Detail

setRoot

getRoot

addRelTraitDef

clearRelTraitDefs

getRelTraitDefs

clear

getRules

addRule

removeRule

getContext

setRuleDescExclusionFilter

setCancelFlag

changeTraits

chooseDelegate

addMaterialization

getMaterializations

addLattice

getLattice

findBestExp

getCostFactory

getCost

getCost

register

ensureRegistered

isRegistered

registerSchema

addListener

registerMetadataProviders

getRelMetadataTimestamp

prune

registerClass

emptyTraitSet

setExecutor

getExecutor

onCopy