org.apache.calcite.plan

Class RelOptRule

java.lang.Object

org.apache.calcite.plan.RelOptRule

Direct Known Subclasses:

RelRule

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
protected 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.
List<RelOptRuleOperand>	operands Flattened list of operands.
RelBuilderFactory	relBuilderFactory Factory for a builder for relational expressions.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
static RelOptRuleOperandChildren	any() Deprecated. Use RelRule.OperandDetailBuilder.anyInputs()
static RelNode	convert(RelNode rel, @Nullable 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, Predicate<? super R> predicate, RelTrait trait) Deprecated.
protected static <R extends RelNode> RelOptRule.ConverterRelOptRuleOperand	convertOperand(Class<R> clazz, com.google.common.base.Predicate<? super R> predicate, RelTrait trait) Deprecated. Use convertOperand(Class, Predicate, RelTrait).
boolean	equals(@Nullable Object obj)
protected boolean	equals(RelOptRule that) Returns whether this rule is equal to another rule.
RelOptRuleOperand	getOperand() Returns the root operand of this rule.
List<RelOptRuleOperand>	getOperands() Returns a flattened list of operands of this rule.
@Nullable Convention	getOutConvention() Returns the convention of the result of firing this rule, null if not known.
@Nullable 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.
int	hashCode()
boolean	matches(RelOptRuleCall call) Returns whether this rule could possibly match the given operands.
static RelOptRuleOperandChildren	none() Deprecated. Use RelRule.OperandDetailBuilder.noInputs()
abstract void	onMatch(RelOptRuleCall call) Receives notification about a rule match.
static <R extends RelNode> RelOptRuleOperand	operand(Class<R> clazz, RelOptRuleOperandChildren operandList) Deprecated. Use RelRule.OperandBuilder.operand(Class)
static <R extends RelNode> RelOptRuleOperand	operand(Class<R> clazz, RelOptRuleOperand first, RelOptRuleOperand... rest) Deprecated. Use RelRule.OperandBuilder.operand(Class)
static <R extends RelNode> RelOptRuleOperand	operand(Class<R> clazz, RelTrait trait, com.google.common.base.Predicate<? super R> predicate, RelOptRuleOperandChildren operandList) Deprecated. Use operandJ(java.lang.Class<R>, org.apache.calcite.plan.RelTrait, java.util.function.Predicate<? super R>, org.apache.calcite.plan.RelOptRuleOperandChildren)
static <R extends RelNode> RelOptRuleOperand	operand(Class<R> clazz, RelTrait trait, com.google.common.base.Predicate<? super R> predicate, RelOptRuleOperand first, RelOptRuleOperand... rest) Deprecated.
static <R extends RelNode> RelOptRuleOperand	operand(Class<R> clazz, RelTrait trait, RelOptRuleOperandChildren operandList) Deprecated. Use RelRule.OperandBuilder.operand(Class)
static <R extends RelNode> RelOptRuleOperand	operandJ(Class<R> clazz, RelTrait trait, Predicate<? super R> predicate, RelOptRuleOperandChildren operandList) Deprecated. Use RelRule.OperandBuilder.operand(Class)
static <R extends RelNode> RelOptRuleOperand	operandJ(Class<R> clazz, RelTrait trait, Predicate<? super R> predicate, RelOptRuleOperand first, RelOptRuleOperand... rest) Deprecated. Use RelRule.OperandBuilder.operand(Class)
static RelOptRuleOperandChildren	some(RelOptRuleOperand first, RelOptRuleOperand... rest) Deprecated. Use RelRule.OperandDetailBuilder.inputs(org.apache.calcite.plan.RelRule.OperandTransform...)
String	toString() Returns the description of this rule.
static RelOptRuleOperandChildren	unordered(RelOptRuleOperand first, RelOptRuleOperand... rest) Deprecated.

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.

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

protected RelOptRule(RelOptRuleOperand operand)

Creates a rule.

Parameters:

operand - root operand, must not be null

RelOptRule

protected 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

protected RelOptRule(RelOptRuleOperand operand,
                     RelBuilderFactory relBuilderFactory,
                     @Nullable 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

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

Deprecated. Use RelRule.OperandBuilder.operand(Class)

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

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

Deprecated. Use RelRule.OperandBuilder.operand(Class)

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

operandJ

@Deprecated
public static <R extends RelNode> RelOptRuleOperand operandJ(Class<R> clazz,
                                                                         RelTrait trait,
                                                                         Predicate<? super R> predicate,
                                                                         RelOptRuleOperandChildren operandList)

Deprecated. Use RelRule.OperandBuilder.operand(Class)

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

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

Deprecated. Use operandJ(java.lang.Class<R>, org.apache.calcite.plan.RelTrait, java.util.function.Predicate<? super R>, org.apache.calcite.plan.RelOptRuleOperandChildren)

operandJ

@Deprecated
public static <R extends RelNode> RelOptRuleOperand operandJ(Class<R> clazz,
                                                                         RelTrait trait,
                                                                         Predicate<? super R> predicate,
                                                                         RelOptRuleOperand first,
                                                                         RelOptRuleOperand... rest)

Deprecated. Use RelRule.OperandBuilder.operand(Class)

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

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

Deprecated.

operand

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

Deprecated. Use RelRule.OperandBuilder.operand(Class)

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

@Deprecated
protected static <R extends RelNode> RelOptRule.ConverterRelOptRuleOperand convertOperand(Class<R> clazz,
                                                                                                      Predicate<? super R> predicate,
                                                                                                      RelTrait trait)

Deprecated.

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

convertOperand

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

Deprecated. Use convertOperand(Class, Predicate, RelTrait).

some

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

Deprecated. Use RelRule.OperandDetailBuilder.inputs(org.apache.calcite.plan.RelRule.OperandTransform...)

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

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

Deprecated.

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

@Deprecated
public static RelOptRuleOperandChildren none()

Deprecated. Use RelRule.OperandDetailBuilder.noInputs()

Creates an empty list of child operands.

Returns:

Empty list of child operands

any

@Deprecated
public static RelOptRuleOperandChildren any()

Deprecated. Use RelRule.OperandDetailBuilder.anyInputs()

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

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(@Nullable 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>, org.apache.calcite.plan.RelHintsPropagator) to register the expression.

Parameters:

call - Rule call

See Also:

matches(RelOptRuleCall)

getOutConvention

public @Nullable 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 @Nullable 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,
                              @Nullable 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