org.apache.calcite.plan

Class RelOptRule

java.lang.Object

org.apache.calcite.plan.RelOptRule

Direct Known Subclasses:

AbstractConverter.ExpandConversionRule, AbstractJoinExtractFilterRule, AbstractMaterializedViewRule, AggregateExpandDistinctAggregatesRule, AggregateExtractProjectRule, AggregateFilterTransposeRule, AggregateJoinTransposeRule, AggregateProjectMergeRule, AggregateProjectPullUpConstantsRule, AggregateReduceFunctionsRule, AggregateRemoveRule, AggregateStarTableRule, AggregateUnionAggregateRule, AggregateUnionTransposeRule, AggregateValuesRule, Bindables.BindableTableScanRule, CalcMergeRule, CalcRemoveRule, CalcSplitRule, CoerceInputsRule, CommonRelSubExprRule, ConverterRule, DateRangeRules.FilterDateRangeRule, EnumerableFilterToCalcRule, EnumerableLimitRule, EnumerableProjectToCalcRule, FilterAggregateTransposeRule, FilterCalcMergeRule, FilterCorrelateRule, FilterJoinRule, FilterMergeRule, FilterMultiJoinMergeRule, FilterProjectTransposeRule, FilterRemoveIsNotDistinctFromRule, FilterSetOpTransposeRule, FilterTableFunctionTransposeRule, FilterTableScanRule, FilterToCalcRule, IntersectToDistinctRule, JoinAddRedundantSemiJoinRule, JoinAssociateRule, JoinCommuteRule, JoinProjectTransposeRule, JoinPushExpressionsRule, JoinPushThroughJoinRule, JoinPushTransitivePredicatesRule, JoinToCorrelateRule, JoinToMultiJoinRule, JoinUnionTransposeRule, LoptOptimizeJoinRule, MaterializedViewFilterScanRule, MultiJoinOptimizeBushyRule, ProjectCalcMergeRule, ProjectFilterTransposeRule, ProjectJoinTransposeRule, ProjectMergeRule, ProjectMultiJoinMergeRule, ProjectRemoveRule, ProjectSetOpTransposeRule, ProjectSortTransposeRule, ProjectTableScanRule, ProjectToCalcRule, ProjectToWindowRule, ProjectWindowTransposeRule, PruneEmptyRules.RemoveEmptySingleRule, ReduceDecimalsRule, ReduceExpressionsRule, RelDecorrelator.AdjustProjectForCountAggregateRule, RelDecorrelator.RemoveCorrelationForScalarAggregateRule, RelDecorrelator.RemoveCorrelationForScalarProjectRule, RelDecorrelator.RemoveSingleAggregateRule, SemiJoinFilterTransposeRule, SemiJoinJoinTransposeRule, SemiJoinProjectTransposeRule, SemiJoinRemoveRule, SemiJoinRule, SortJoinTransposeRule, SortProjectTransposeRule, SortRemoveRule, SortUnionTransposeRule, StreamRules.DeltaAggregateTransposeRule, StreamRules.DeltaFilterTransposeRule, StreamRules.DeltaJoinTransposeRule, StreamRules.DeltaProjectTransposeRule, StreamRules.DeltaSortTransposeRule, StreamRules.DeltaTableScanRule, StreamRules.DeltaTableScanToEmptyRule, StreamRules.DeltaUnionTransposeRule, SubQueryRemoveRule, SubstitutionVisitor.FilterOnProjectRule, TableScanRule, TraitMatchingRule, UnionEliminatorRule, UnionMergeRule, UnionPullUpConstantsRule, UnionToDistinctRule, ValuesReduceRule

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.apache.calcite.plan.RelOptRuleCall) on each of them.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	RelOptRule.ConverterRelOptRuleOperand Operand to an instance of the converter rule.

Field Summary

Fields

Modifier and Type	Field and Description
protected String	description Description of rule, must be unique within planner.
private RelOptRuleOperand	operand Root of operand tree.
List<RelOptRuleOperand>	operands Flattened list of operands.
RelBuilderFactory	relBuilderFactory Factory for a builder for relational expressions.

Constructor Summary

Constructors

Constructor and Description
RelOptRule(RelOptRuleOperand operand) Creates a rule.
RelOptRule(RelOptRuleOperand operand, RelBuilderFactory relBuilderFactory, String description) Creates a rule with an explicit description.
RelOptRule(RelOptRuleOperand operand, String description) Creates a rule with an explicit description.

Method Summary

Modifier and Type	Method and Description
static RelOptRuleOperandChildren	any() Creates a list of child operands that signifies that the operand matches any number of child relational expressions.
private void	assignSolveOrder() Builds each operand's solve-order.
static RelNode	convert(RelNode rel, RelTrait toTrait) Converts one trait of a relational expression, if it does not already have that trait.
static RelNode	convert(RelNode rel, RelTraitSet toTraits) Converts a relation expression to a given set of traits, if it does not already have those traits.
protected static List<RelNode>	convertList(List<RelNode> rels, RelTrait trait) Converts a list of relational expressions.
protected static <R extends RelNode> RelOptRule.ConverterRelOptRuleOperand	convertOperand(Class<R> clazz, com.google.common.base.Predicate<? super R> predicate, RelTrait trait) Creates an operand for a converter rule.
boolean	equals(Object obj)
protected boolean	equals(RelOptRule that) Returns whether this rule is equal to another rule.
private List<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.
Convention	getOutConvention() Returns the 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 RelOptRuleOperandChildren	none() Creates an empty list of child operands.
abstract void	onMatch(RelOptRuleCall call) Receives notification about a rule match.
static <R extends RelNode> RelOptRuleOperand	operand(Class<R> clazz, RelOptRuleOperandChildren operandList) Creates an operand that matches a relational expression that has no children.
static <R extends RelNode> RelOptRuleOperand	operand(Class<R> clazz, RelOptRuleOperand first, RelOptRuleOperand... rest) Creates an operand that matches a relational expression with a given list of children.
static <R extends RelNode> RelOptRuleOperand	operand(Class<R> clazz, RelTrait trait, com.google.common.base.Predicate<? super R> predicate, RelOptRuleOperandChildren operandList) Creates an operand that matches a relational expression that has a particular trait and predicate.
static <R extends RelNode> RelOptRuleOperand	operand(Class<R> clazz, RelTrait trait, com.google.common.base.Predicate<? super R> predicate, RelOptRuleOperand first, RelOptRuleOperand... rest) Creates an operand that matches a relational expression that has no children.
static <R extends RelNode> RelOptRuleOperand	operand(Class<R> clazz, RelTrait trait, RelOptRuleOperandChildren operandList) Creates an operand that matches a relational expression that has no children.
static RelOptRuleOperandChildren	some(RelOptRuleOperand first, RelOptRuleOperand... rest) Creates a list of child operands that matches child relational expressions in the order they appear.
String	toString() Returns the description of this rule.
static RelOptRuleOperandChildren	unordered(RelOptRuleOperand first, RelOptRuleOperand... rest) Creates a list of child operands that matches child relational expressions in any order.

Methods inherited from class java.lang.Object

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

Field Detail

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.

relBuilderFactory

public final RelBuilderFactory relBuilderFactory

Factory for a builder for relational expressions.

The actual builder is available via RelOptRuleCall.builder().

operands

public final List<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

RelOptRule

public RelOptRule(RelOptRuleOperand operand,
                  RelBuilderFactory relBuilderFactory,
                  String description)

Creates a rule with an explicit description.

Parameters:

operand - root operand, must not be null

description - Description, or null to guess description

relBuilderFactory - Builder for relational expressions

Method Detail

operand

public static <R extends RelNode> RelOptRuleOperand operand(Class<R> clazz,
                                                            RelOptRuleOperandChildren operandList)

Creates an operand that matches a relational expression that has no children.

Type Parameters:

R - Class of relational expression to match

Parameters:

clazz - Class of relational expression to match (must not be null)

operandList - Child operands

Returns:

Operand that matches a relational expression that has no children

operand

public static <R extends RelNode> RelOptRuleOperand operand(Class<R> clazz,
                                                            RelTrait trait,
                                                            RelOptRuleOperandChildren operandList)

Creates an operand that matches a relational expression that has no children.

Type Parameters:

R - Class of relational expression to match

Parameters:

clazz - Class of relational expression to match (must not be null)

trait - Trait to match, or null to match any trait

operandList - Child operands

Returns:

Operand that matches a relational expression that has no children

operand

public static <R extends RelNode> RelOptRuleOperand operand(Class<R> clazz,
                                                            RelTrait trait,
                                                            com.google.common.base.Predicate<? super R> predicate,
                                                            RelOptRuleOperandChildren operandList)

Creates an operand that matches a relational expression that has a particular trait and predicate.

Type Parameters:

R - Class of relational expression to match

Parameters:

clazz - Class of relational expression to match (must not be null)

trait - Trait to match, or null to match any trait

predicate - Additional match predicate

operandList - Child operands

Returns:

Operand that matches a relational expression that has a particular trait and predicate

operand

public static <R extends RelNode> RelOptRuleOperand operand(Class<R> clazz,
                                                            RelTrait trait,
                                                            com.google.common.base.Predicate<? super R> predicate,
                                                            RelOptRuleOperand first,
                                                            RelOptRuleOperand... rest)

Creates an operand that matches a relational expression that has no children.

Type Parameters:

R - Class of relational expression to match

Parameters:

clazz - Class of relational expression to match (must not be null)

trait - Trait to match, or null to match any trait

predicate - Additional match predicate

first - First operand

rest - Rest operands

Returns:

Operand

operand

public static <R extends RelNode> RelOptRuleOperand operand(Class<R> clazz,
                                                            RelOptRuleOperand first,
                                                            RelOptRuleOperand... rest)

Creates an operand that matches a relational expression with a given list of children.

Shorthand for operand(clazz, some(...)).

If you wish to match a relational expression that has no children (that is, a leaf node), write operand(clazz, none())

.

If you wish to match a relational expression that has any number of children, write operand(clazz, any())

.

Type Parameters:

R - Class of relational expression to match

Parameters:

clazz - Class of relational expression to match (must not be null)

first - First operand

rest - Rest operands

Returns:

Operand that matches a relational expression with a given list of children

convertOperand

protected static <R extends RelNode> RelOptRule.ConverterRelOptRuleOperand convertOperand(Class<R> clazz,
                                                                                          com.google.common.base.Predicate<? super R> predicate,
                                                                                          RelTrait trait)

Creates an operand for a converter rule.

Parameters:

clazz - Class of relational expression to match (must not be null)

trait - Trait to match, or null to match any trait

predicate - Predicate to apply to relational expression

some

public static RelOptRuleOperandChildren some(RelOptRuleOperand first,
                                             RelOptRuleOperand... rest)

Creates a list of child operands that matches child relational expressions in the order they appear.

Parameters:

first - First child operand

rest - Remaining child operands (may be empty)

Returns:

List of child operands that matches child relational expressions in the order

unordered

public static RelOptRuleOperandChildren unordered(RelOptRuleOperand first,
                                                  RelOptRuleOperand... rest)

Creates a list of child operands that matches child relational expressions in any order.

This is useful when matching a relational expression which can have a variable number of children. For example, the rule to eliminate empty children of a Union would have operands

Operand(Union, true, Operand(Empty))

and given the relational expressions

Union(LogicalFilter, Empty, LogicalProject)

would fire the rule with arguments

{Union, Empty}

It is up to the rule to deduce the other children, or indeed the position of the matched child.

Parameters:

first - First child operand

rest - Remaining child operands (may be empty)

Returns:

List of child operands that matches child relational expressions in any order

none

public static RelOptRuleOperandChildren none()

Creates an empty list of child operands.

Returns:

Empty list of child operands

any

public static RelOptRuleOperandChildren any()

Creates a list of child operands that signifies that the operand matches any number of child relational expressions.

Returns:

List of child operands that signifies that the operand matches any number of child relational expressions

flattenOperands

private List<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.

Parameters:

that - Another rule

Returns:

Whether this rule is equal to another rule

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.apache.calcite.rel.RelNode, java.util.Map<org.apache.calcite.rel.RelNode, org.apache.calcite.rel.RelNode>) to register the expression.

Parameters:

call - Rule call

See Also:

matches(RelOptRuleCall)

getOutConvention

public Convention getOutConvention()

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

Returns:

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.

Returns:

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

toString

public final String toString()

Returns the description of this rule.

It must be unique (for rules that are not equal) and must consist of only the characters A-Z, a-z, 0-9, '_', '.', '(', ')'. It must start with a letter.

Overrides:

toString in class Object

convert

public static RelNode convert(RelNode rel,
                              RelTraitSet toTraits)

Converts a relation expression to a given set of traits, if it does not already have those traits.

Parameters:

rel - Relational expression to convert

toTraits - desired traits

Returns:

a relational expression with the desired traits; never null

convert

public static RelNode convert(RelNode rel,
                              RelTrait toTrait)

Converts one trait of a relational expression, if it does not already have that trait.

Parameters:

rel - Relational expression to convert

toTrait - Desired trait

Returns:

a relational expression with the desired trait; never null

convertList

protected static List<RelNode> convertList(List<RelNode> rels,
                                           RelTrait trait)

Converts a list of relational expressions.

Parameters:

rels - Relational expressions

trait - Trait to add to each relational expression

Returns:

List of converted relational expressions, never null

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