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 Summary

Constructors

Constructor and Description
HepProgramBuilder() Creates a new HepProgramBuilder with an initially empty program.

Method Summary

Methods

Modifier and Type	Method and Description
HepProgramBuilder	addCommonRelSubExprInstruction() Adds an instruction to attempt to match instances of CommonRelSubExprRule, but only in cases where vertices have more than one parent.
HepProgramBuilder	addConverters(boolean guaranteed) Adds an instruction to attempt to match instances of ConverterRule, but only where a conversion is actually required.
HepProgramBuilder	addGroupBegin() Adds an instruction to begin a group of rules.
HepProgramBuilder	addGroupEnd() Adds an instruction to end a group of rules, firing the group collectively.
HepProgramBuilder	addMatchLimit(int limit) Adds an instruction to limit the number of pattern matches for subsequent instructions.
HepProgramBuilder	addMatchOrder(HepMatchOrder order) Adds an instruction to change the order of pattern matching for subsequent instructions.
HepProgramBuilder	addRuleByDescription(String ruleDescription) Adds an instruction to attempt to match a specific rule identified by its unique description.
<R extends RelOptRule> HepProgramBuilder	addRuleClass(Class<R> ruleClass) Adds an instruction to attempt to match any rules of a given class.
HepProgramBuilder	addRuleCollection(Collection<RelOptRule> rules) Adds an instruction to attempt to match any rules in a given collection.
HepProgramBuilder	addRuleInstance(RelOptRule rule) Adds an instruction to attempt to match a specific rule object.
HepProgramBuilder	addSubprogram(HepProgram program) Adds an instruction to execute a subprogram.
HepProgram	build() Returns the constructed program, clearing the state of this program builder as a side-effect.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HepProgramBuilder

public HepProgramBuilder()

Creates a new HepProgramBuilder with an initially empty program. The program under construction has an initial match order of HepMatchOrder.ARBITRARY, and an initial match limit of HepProgram.MATCH_UNTIL_FIXPOINT.

Method Detail

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