Package org.apache.calcite.plan

Class RelOptRule

    • Field Detail

      • description

        protected final java.lang.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.

      • operands

        public final java.util.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,
                  java.lang.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,
                  java.lang.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​(java.lang.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​(java.lang.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

      • operandJ

        public static <R extends RelNode> RelOptRuleOperand operandJ​(java.lang.Class<R> clazz,
                                                             RelTrait trait,
                                                             java.util.function.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

      • operandJ

        public static <R extends RelNode> RelOptRuleOperand operandJ​(java.lang.Class<R> clazz,
                                                             RelTrait trait,
                                                             java.util.function.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​(java.lang.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​(java.lang.Class<R> clazz,
                                                                                          java.util.function.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 java.util.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​(java.util.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 java.util.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 java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.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

      • 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 java.lang.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 java.lang.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 java.util.List<RelNode> convertList​(java.util.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 java.lang.String guessDescription​(java.lang.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