Package org.apache.calcite.plan.hep

Class HepProgramBuilder

java.lang.Object
org.apache.calcite.plan.hep.HepProgramBuilder
public class HepProgramBuilder extends Object
HepProgramBuilder creates instances of HepProgram.

  • Constructor Details

  • Method Details

    • addRuleClass

      public <R extends RelOptRule> HepProgramBuilder addRuleClass(Class<R> ruleClass)
      Adds an instruction to attempt to match any rules of a given class. The order in which the rules within a class will be attempted is arbitrary, so if more control is needed, use addRuleInstance instead.

      Note that when this method is used, it is also necessary to add the actual rule objects of interest to the planner via RelOptPlanner.addRule(org.apache.calcite.plan.RelOptRule). If the planner does not have any rules of the given class, this instruction is a nop.

      TODO: support classification via rule annotations.

      Parameters:
      ruleClass - class of rules to fire, e.g. ConverterRule.class

    • addRuleCollection

      public HepProgramBuilder addRuleCollection(Collection<RelOptRule> rules)
      Adds an instruction to attempt to match any rules in a given collection. The order in which the rules within a collection will be attempted is arbitrary, so if more control is needed, use addRuleInstance instead. The collection can be "live" in the sense that not all rule instances need to have been added to it at the time this method is called. The collection contents are reevaluated for each execution of the program.

      Note that when this method is used, it is NOT necessary to add the rules to the planner via RelOptPlanner.addRule(org.apache.calcite.plan.RelOptRule); the instances supplied here will be used. However, adding the rules to the planner redundantly is good form since other planners may require it.

      Parameters:
      rules - collection of rules to fire

    • addRuleInstance

      public HepProgramBuilder addRuleInstance(RelOptRule rule)
      Adds an instruction to attempt to match a specific rule object.

      Note that when this method is used, it is NOT necessary to add the rule to the planner via RelOptPlanner.addRule(org.apache.calcite.plan.RelOptRule); the instance supplied here will be used. However, adding the rule to the planner redundantly is good form since other planners may require it.

      Parameters:
      rule - rule to fire

    • addRuleByDescription

      public HepProgramBuilder addRuleByDescription(String ruleDescription)
      Adds an instruction to attempt to match a specific rule identified by its unique description.

      Note that when this method is used, it is necessary to also add the rule object of interest to the planner via RelOptPlanner.addRule(org.apache.calcite.plan.RelOptRule). This allows for some decoupling between optimizers and plugins: the optimizer only knows about rule descriptions, while the plugins supply the actual instances. If the planner does not have a rule matching the description, this instruction is a nop.

      Parameters:
      ruleDescription - description of rule to fire

    • addGroupBegin

      public HepProgramBuilder addGroupBegin()
      Adds an instruction to begin a group of rules. All subsequent rules added (until the next endRuleGroup) will be collected into the group rather than firing individually. After addGroupBegin has been called, only addRuleXXX methods may be called until the next addGroupEnd.

    • addGroupEnd

      public HepProgramBuilder addGroupEnd()
      Adds an instruction to end a group of rules, firing the group collectively. The order in which the rules within a group will be attempted is arbitrary. Match order and limit applies to the group as a whole.

    • addConverters

      public HepProgramBuilder addConverters(boolean guaranteed)
      Adds an instruction to attempt to match instances of ConverterRule, but only where a conversion is actually required.
      Parameters:
      guaranteed - if true, use only guaranteed converters; if false, use only non-guaranteed converters

    • addCommonRelSubExprInstruction

      public HepProgramBuilder addCommonRelSubExprInstruction()
      Adds an instruction to attempt to match instances of CommonRelSubExprRule, but only in cases where vertices have more than one parent.

    • addMatchOrder

      public HepProgramBuilder addMatchOrder(HepMatchOrder order)
      Adds an instruction to change the order of pattern matching for subsequent instructions. The new order will take effect for the rest of the program (not counting subprograms) or until another match order instruction is encountered.
      Parameters:
      order - new match direction to set

    • addMatchLimit

      public HepProgramBuilder addMatchLimit(int limit)
      Adds an instruction to limit the number of pattern matches for subsequent instructions. The limit will take effect for the rest of the program (not counting subprograms) or until another limit instruction is encountered.
      Parameters:
      limit - limit to set; use HepProgram.MATCH_UNTIL_FIXPOINT to remove limit

    • addSubprogram

      public HepProgramBuilder addSubprogram(HepProgram program)
      Adds an instruction to execute a subprogram. Note that this is different from adding the instructions from the subprogram individually. When added as a subprogram, the sequence will execute repeatedly until a fixpoint is reached, whereas when the instructions are added individually, the sequence will only execute once (with a separate fixpoint for each instruction).

      The subprogram has its own state for match order and limit (initialized to the defaults every time the subprogram is executed) and any changes it makes to those settings do not affect the parent program.

      Parameters:
      program - subProgram to execute

    • build

      public HepProgram build()
      Returns the constructed program, clearing the state of this program builder as a side-effect.
      Returns:
      immutable program