org.eigenbase.relopt
Class RelOptRule

java.lang.Object
  org.eigenbase.relopt.RelOptRule

Direct Known Subclasses:

AbstractConverter.ExpandConversionRule, AddFilterToQueryRule, AddProjectToQueryRule, AddRedundantSemiJoinRule, CoerceInputsRule, CombineUnionsRule, CommonRelSubExprRule, ConverterRule, ConvertMultiJoinRule, ExtractJoinFilterRule, FarragoAutoCalcRule, FarragoJavaUdxRule, FarragoMultisetSplitterRule, FarragoReduceExpressionsRule, FarragoReduceValuesRule, FennelAggRule, FennelBernoulliSamplingRule, FennelCartesianJoinRule, FennelCollectRule, FennelCorrelatorRule, FennelDistinctSortRule, FennelNestedLoopJoinRule, FennelRemoveRedundantSortRule, FennelRenameRule, FennelReshapeRule, FennelSortRule, FennelUncollectRule, FennelWindowRule, FilterToCalcRule, FtrsIndexBuilderRule, FtrsIndexJoinRule, FtrsRemoveRedundantSortRule, FtrsScanToSearchRule, FtrsTableModificationRule, LcsAddDeletionScanRule, LcsIndexAccessRule, LcsIndexAggRule, LcsIndexBuilderRule, LcsIndexOnlyAccessRule, LcsIndexSemiJoinRule, LcsRemoveRidExprRule, LcsSamplingRowScanRule, LcsTableAlterRule, LcsTableAppendRule, LcsTableDeleteRule, LcsTableMergeRule, LhxAggRule, LhxIntersectRule, LhxJoinRule, LhxMinusRule, LhxSemiJoinRule, LoptIterCalcRule, LoptModifyRemovableSelfJoinRule, LoptOptimizeJoinRule, LoptRemoveSelfJoinRule, MedAbstractFennelProjectionRule, MedJdbcAggPushDownRule, MedJdbcPushDownRule, MedMdrJoinRule, MedMockTableModificationRule, MedMqlPushDownRule, MergeCalcRule, MergeFilterOntoCalcRule, MergeFilterRule, MergeProjectOntoCalcRule, MergeProjectRule, NestedLoopsJoinRule, ProjectToCalcRule, PullConstantsThroughAggregatesRule, PullUpAggregateAboveUnionRule, PullUpProjectsAboveJoinRule, PushAggregateThroughUnionRule, PushAggThroughUnionAllRule, PushFilterIntoMultiJoinRule, PushFilterPastJoinRule, PushFilterPastProjectRule, PushFilterPastSetOpRule, PushProjectIntoMultiJoinRule, PushProjectPastFilterRule, PushProjectPastJoinRule, PushProjectPastSetOpRule, PushSemiJoinPastFilterRule, PushSemiJoinPastJoinRule, PushSemiJoinPastProjectRule, ReduceAggregatesRule, ReduceDecimalsRule, RelDecorrelator.AdjustProjectForCountAggregateRule, RelDecorrelator.RemoveCorrelationForScalarAggregateRule, RelDecorrelator.RemoveCorrelationForScalarProjectRule, RelDecorrelator.RemoveSingleAggregateRule, RemoveDistinctAggregateRule, RemoveDistinctRule, RemoveEmptyRule, RemoveIsNotDistinctFromRule, RemoveSemiJoinRule, RemoveTrivialCalcRule, RemoveTrivialProjectRule, SwapJoinRule, TableAccessRule, TraitMatchingRule, UnionEliminatorRule, UnionToDistinctRule, VolcanoPlannerTest.GoodRemoveSingleRule, VolcanoPlannerTest.GoodSingleRule, VolcanoPlannerTest.PhysLeafRule, VolcanoPlannerTest.PhysProjectRule, VolcanoPlannerTest.ReformedRemoveSingleRule, VolcanoPlannerTest.ReformedSingleRule, VolcanoPlannerTraitTest.IterSingleRule, VolcanoPlannerTraitTest.IterSingleRule2, VolcanoPlannerTraitTest.PhysLeafRule, WindowedAggSplitterRule

public abstract class RelOptRule
extends Object

A RelOptRule transforms an expression into another. It has a list of RelOptRuleOperands, which determine whether the rule can be applied to a particular section of the tree.

The optimizer figures out which rules are applicable, then calls onMatch(org.eigenbase.relopt.RelOptRuleCall) on each of them.

Field Summary

static RelOptRuleOperand.Dummy	ANY Shorthand for RelOptRuleOperand.Dummy.ANY.
protected String	description Description of rule, must be unique within planner.
private RelOptRuleOperand	operand Root of operand tree.
RelOptRuleOperand[]	operands Flattened list of operands.

Constructor Summary

RelOptRule(RelOptRuleOperand operand)
Creates a rule.

RelOptRule(RelOptRuleOperand operand, String description)
Creates a rule with an explicit description.

Method Summary

private void	assignSolveOrder() Builds each operand's solve-order.
static RelNode	convert(RelNode rel, RelTraitSet toTraits) Converts a relation expression to a give set of traits, if it does not already have those traits.
boolean	equals(Object obj)
protected boolean	equals(RelOptRule that) Returns whether this rule is equal to another rule.
private RelOptRuleOperand[]	flattenOperands(RelOptRuleOperand rootOperand) Creates a flattened list of this operand and its descendants in prefix order.
private void	flattenRecurse(List<RelOptRuleOperand> operandList, RelOptRuleOperand parentOperand) Adds the operand and its descendants to the list in prefix order.
RelOptRuleOperand	getOperand() Returns the root operand of this rule
List<RelOptRuleOperand>	getOperands() Returns a flattened list of operands of this rule.
CallingConvention	getOutConvention() Returns the calling convention of the result of firing this rule, null if not known.
RelTrait	getOutTrait() Returns the trait which will be modified as a result of firing this rule, or null if the rule is not a converter rule.
(package private) static String	guessDescription(String className) Deduces a name for a rule by taking the name of its class and returning the segment after the last '.' or '$'.
int	hashCode()
boolean	matches(RelOptRuleCall call) Returns whether this rule could possibly match the given operands.
static RelNode	mergeTraitsAndConvert(RelTraitSet baseTraits, RelTrait newTrait, RelNode rel) Creates a new RelTraitSet based on the given traits and converts the relational expression to that trait set.
static RelNode	mergeTraitsAndConvert(RelTraitSet baseTraits, RelTraitSet newTraits, RelNode rel) Creates a new RelTraitSet based on the given traits and converts the relational expression to that trait set.
abstract void	onMatch(RelOptRuleCall call) Receives notification about a rule match.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ANY

public static final RelOptRuleOperand.Dummy ANY

Shorthand for RelOptRuleOperand.Dummy.ANY.

description

protected final String description

Description of rule, must be unique within planner. Default is the name of the class sans package name, but derived classes are encouraged to override.

operand

private final RelOptRuleOperand operand

Root of operand tree.

operands

public RelOptRuleOperand[] operands

Flattened list of operands.

Constructor Detail

RelOptRule

public RelOptRule(RelOptRuleOperand operand)

Creates a rule.

Parameters:

operand - root operand, must not be null

RelOptRule

public RelOptRule(RelOptRuleOperand operand,
                  String description)

Creates a rule with an explicit description.

Parameters:

operand - root operand, must not be null

description - Description, or null to guess description

Method Detail

flattenOperands

private RelOptRuleOperand[] flattenOperands(RelOptRuleOperand rootOperand)

Creates a flattened list of this operand and its descendants in prefix order.

Parameters:

rootOperand - Root operand

Returns:

Flattened list of operands

flattenRecurse

private void flattenRecurse(List<RelOptRuleOperand> operandList,
                            RelOptRuleOperand parentOperand)

Adds the operand and its descendants to the list in prefix order.

Parameters:

operandList - Flattened list of operands

parentOperand - Parent of this operand

assignSolveOrder

private void assignSolveOrder()

Builds each operand's solve-order. Start with itself, then its parent, up to the root, then the remaining operands in prefix order.

getOperand

public RelOptRuleOperand getOperand()

Returns the root operand of this rule

Returns:

the root operand of this rule

getOperands

public List<RelOptRuleOperand> getOperands()

Returns a flattened list of operands of this rule.

Returns:

flattened list of operands

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

equals

protected boolean equals(RelOptRule that)

Returns whether this rule is equal to another rule.

The base implementation checks that the rules have the same class and that the operands are equal; derived classes can override.

matches

public boolean matches(RelOptRuleCall call)

Returns whether this rule could possibly match the given operands.

This method is an opportunity to apply side-conditions to a rule. The RelOptPlanner calls this method after matching all operands of the rule, and before calling onMatch(RelOptRuleCall).

In implementations of RelOptPlanner which may queue up a matched RelOptRuleCall for a long time before calling onMatch(RelOptRuleCall), this method is beneficial because it allows the planner to discard rules earlier in the process.

The default implementation of this method returns true. It is acceptable for any implementation of this method to give a false positives, that is, to say that the rule matches the operands but have onMatch(RelOptRuleCall) subsequently not generate any successors.

The following script is useful to identify rules which commonly produce no successors. You should override this method for these rules:

awk '
 /Apply rule/ {rule=$4; ruleCount[rule]++;}
 /generated 0 successors/ {ruleMiss[rule]++;}
 END {
   printf "%-30s %s %s\n", "Rule", "Fire", "Miss";
   for (i in ruleCount) {
     printf "%-30s %5d %5d\n", i, ruleCount[i], ruleMiss[i];
   }
 } ' FarragoTrace.log

Parameters:

call - Rule call which has been determined to match all operands of this rule

Returns:

whether this RelOptRule matches a given RelOptRuleCall

onMatch

public abstract void onMatch(RelOptRuleCall call)

Receives notification about a rule match. At the time that this method is called, call.rels holds the set of relational expressions which match the operands to the rule; call.rels[0] is the root expression.

Typically a rule would check that the nodes are valid matches, creates a new expression, then calls back RelOptRuleCall.transformTo(org.eigenbase.rel.RelNode) to register the expression.

Parameters:

call - Rule call

See Also:

matches(RelOptRuleCall)

"Precondition:"

matches(call)

getOutConvention

public CallingConvention getOutConvention()

Returns the calling convention of the result of firing this rule, null if not known.

getOutTrait

public RelTrait getOutTrait()

Returns the trait which will be modified as a result of firing this rule, or null if the rule is not a converter rule.

toString

public String toString()

Overrides:

toString in class Object

convert

public static RelNode convert(RelNode rel,
                              RelTraitSet toTraits)

Converts a relation expression to a give set of traits, if it does not already have those traits. If the conversion is not possible, returns null.

Parameters:

rel - Relexp to convert

toTraits - desired traits

Returns:

a relational expression with the desired traits, or null if no conversion is possible

"Postcondition:"

return == null || return.getTraits().matches(toTraits)

mergeTraitsAndConvert

public static RelNode mergeTraitsAndConvert(RelTraitSet baseTraits,
                                            RelTraitSet newTraits,
                                            RelNode rel)

Creates a new RelTraitSet based on the given traits and converts the relational expression to that trait set. Clones baseTraits and merges newTraits with the cloned set, then converts rel to that set. Normally, during a rule call, baseTraits are the traits of the rel's parent and newTraits are the traits that the rule wishes to guarantee.

Parameters:

baseTraits - base traits for converted rel

newTraits - altered traits

rel - the rel to convert

Returns:

converted rel or null if conversion could not be made

mergeTraitsAndConvert

public static RelNode mergeTraitsAndConvert(RelTraitSet baseTraits,
                                            RelTrait newTrait,
                                            RelNode rel)

Creates a new RelTraitSet based on the given traits and converts the relational expression to that trait set. Clones baseTraits and merges newTrait with the cloned set, then converts rel to that set. Normally, during a rule call, baseTraits are the traits of the rel's parent and newTrait is the trait that the rule wishes to guarantee.

Parameters:

baseTraits - base traits for converted rel

newTrait - altered trait

rel - the rel to convert

Returns:

converted rel or null if conversion could not be made

guessDescription

static String guessDescription(String className)

Deduces a name for a rule by taking the name of its class and returning the segment after the last '.' or '$'.

Examples:

• "com.foo.Bar" yields "Bar";
• "com.flatten.Bar$Baz" yields "Baz";
• "com.foo.Bar$1" yields "1" (which as an integer is an invalid name, and writer of the rule is encouraged to give it an explicit name).

Parameters:

className - Name of the rule's class

Returns:

Last segment of the class