org.eigenbase.relopt
Interface RelOptPlanner

All Known Subinterfaces:

FarragoSessionPlanner

All Known Implementing Classes:

AbstractRelOptPlanner, FarragoDefaultHeuristicPlanner, FarragoDefaultPlanner, FarragoMiniplanPersonalityFactory.FarragoVolcanoMiniplanner, FarragoTestPlanner, HepPlanner, LucidDbSessionPersonality.LucidDbPlanner, MockRelOptPlanner, 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.

Field Summary

static Logger

tracer

Method Summary

void	addListener(RelOptListener newListener) Adds a listener to this planner.
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.
RelNode	ensureRegistered(RelNode rel, RelNode equivRel) Registers a relational expression if it is not already registered.
RelNode	findBestExp() Finds the most efficient expression to implement this query.
RelOptCost	getCost(RelNode rel) Computes the cost of a RelNode.
JavaRelImplementor	getJavaRelImplementor(RelNode rel) Retrieves an implementor appropriate for the context in which this planner was created.
long	getRelMetadataTimestamp(RelNode rel) Gets a timestamp for a given rel's metadata.
RelNode	getRoot() Returns the root node of this query.
boolean	isRegistered(RelNode rel) Determines whether a relational expression has been registered.
RelOptCost	makeCost(double dRows, double dCpu, double dIo) Creates a cost object.
RelOptCost	makeHugeCost() Creates a cost object representing an enormous non-infinite cost.
RelOptCost	makeInfiniteCost() Creates a cost object representing infinite cost.
RelOptCost	makeTinyCost() Creates a cost object representing a small positive cost.
RelOptCost	makeZeroCost() Creates a cost object representing zero cost.
RelNode	register(RelNode rel, RelNode equivRel) Registers a relational expression in the expression bank.
void	registerMetadataProviders(ChainedRelMetadataProvider chain) Gives this planner a chance to register one or more RelMetadataProviders 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	setCancelFlag(CancelFlag cancelFlag) Installs the cancellation-checking flag for this planner.
void	setImportance(RelNode rel, double importance) Sets the importance of a relational expression.
void	setRoot(RelNode rel) Sets the root node of this query.
void	setRuleDescExclusionFilter(Pattern exclusionFilter) Sets the exclusion filter to use for this planner.

Field Detail

tracer

static final Logger tracer

Method Detail

setRoot

void setRoot(RelNode rel)

Sets the root node of this query.

Parameters:

rel - Relational expression

getRoot

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)

addRule

boolean addRule(RelOptRule rule)

Registers a rule. If the rule has already been registered, does nothing. This method should determine 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)

setRuleDescExclusionFilter

void setRuleDescExclusionFilter(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

void setCancelFlag(CancelFlag cancelFlag)

Installs the cancellation-checking flag for this planner. The planner should periodically check this flag and terminate the planning process if it sees a cancellation request.

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

toTraits - Trait set to convert relational expression to

Returns:

Relational expression with desired traits. Never null, but may be abstract

"Precondition:"

!rel.getTraits().equals(toTraits)

"Postcondition:"

return != null

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.

findBestExp

RelNode findBestExp()

Finds the most efficient expression to implement this query.

makeCost

RelOptCost makeCost(double dRows,
                    double dCpu,
                    double dIo)

Creates a cost object.

makeHugeCost

RelOptCost makeHugeCost()

Creates a cost object representing an enormous non-infinite cost.

makeInfiniteCost

RelOptCost makeInfiniteCost()

Creates a cost object representing infinite cost.

makeTinyCost

RelOptCost makeTinyCost()

Creates a cost object representing a small positive cost.

makeZeroCost

RelOptCost makeZeroCost()

Creates a cost object representing zero cost.

getCost

RelOptCost getCost(RelNode rel)

Computes the cost of a RelNode. In most cases, this just dispatches to RelMetadataQuery.getCumulativeCost(org.eigenbase.rel.RelNode).

Parameters:

rel - expression of interest

Returns:

estimated cost

register

RelNode register(RelNode rel,
                 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

"Precondition:"

!isRegistered(rel)

ensureRegistered

RelNode ensureRegistered(RelNode rel,
                         RelNode equivRel)

Registers a relational expression if it is not already registered.

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.

getJavaRelImplementor

JavaRelImplementor getJavaRelImplementor(RelNode rel)

Retrieves an implementor appropriate for the context in which this planner was created.

addListener

void addListener(RelOptListener newListener)

Adds a listener to this planner.

Parameters:

newListener - new listener to be notified of events

registerMetadataProviders

void registerMetadataProviders(ChainedRelMetadataProvider chain)

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:

chain - receives planner's custom providers, if any

getRelMetadataTimestamp

long getRelMetadataTimestamp(RelNode rel)

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

setImportance

void setImportance(RelNode rel,
                   double importance)

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.

Parameters:

rel - Relational expression

importance - Importance