Package 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.

  • Field Details

    • 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 Details

    • 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
      relBuilderFactory - Builder for relational expressions
      description - Description, or null to guess description

  • Method Details

    • 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)
      predicate - Predicate to apply to relational expression
      trait - Trait to match, or null to match any trait

    • 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:

    • 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(RelOptPlanner planner, RelNode rel, RelTraitSet toTraits)

    • 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

    • convert

      public static RelNode convert(RelOptPlanner planner, RelNode rel, @Nullable RelTrait toTrait)

    • 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