Package org.apache.calcite.rel.hint

Defines hints interfaces and utilities for relational expressions.

See: Description

Interface Summary

Interface	Description
Hintable	Hintable is a kind of RelNode that can attach RelHints.
HintOptionChecker	A HintOptionChecker validates the options of a RelHint.
HintPredicate	A HintPredicate indicates whether a RelNode can apply the specified hint.

Class Summary

Class	Description
CompositeHintPredicate	A HintPredicate to combine multiple hint predicates into one.
HintPredicates	A collection of hint predicates.
HintStrategy	Represents a hint strategy entry of HintStrategyTable.
HintStrategy.Builder	Builder for HintStrategy.
HintStrategyTable	A collection of HintStrategys.
HintStrategyTable.Builder	Builder for HintStrategyTable.
HintStrategyTable.HintErrorLogger	Implementation of Litmus that returns a status code, it logs warnings for fail check and does not throw.
NodeTypeHintPredicate	A hint predicate that specifies which kind of relational expression the hint can be applied to.
RelHint	Hint attached to a relation expression.
RelHint.Builder	Builder for RelHint.

Enum Summary

Enum	Description
CompositeHintPredicate.Composition	How hint predicates are composed.

Package org.apache.calcite.rel.hint Description

Defines hints interfaces and utilities for relational expressions.

The Syntax

We support the Oracle style hint grammar for both query hint(right after the "SELECT" keyword) and the table hint(right after the table name reference). i.e.

   select /*+ NO_HASH_JOIN, RESOURCE(mem='128mb', parallelism='24') */
   from
     emp /*+ INDEX(idx1, idx2) */
     join
     dept /*+ PROPERTIES(k1='v1', k2='v2') */
     on emp.deptno=dept.deptno
 

Customize Hint Match Rules

Calcite implements a framework to define and propagate the hints. In order to make the hints propagate efficiently, every hint referenced in the sql statement needs to register the match rules for hints propagation.

A match rule is defined though HintPredicate. NodeTypeHintPredicate matches a relational expression by its node type; you can also define a custom instance with more complicated rules, i.e. JOIN with specified relations from the hint options.

Here is the code snippet to illustrate how to config the strategies:

       // Initialize a HintStrategyTable.
       HintStrategyTable strategies = HintStrategyTable.builder()
         .addHintStrategy("time_zone", HintPredicates.SET_VAR)
         .addHintStrategy("index", HintPredicates.TABLE_SCAN)
         .addHintStrategy("resource", HintPredicates.PROJECT)
         .addHintStrategy("use_hash_join",
             HintPredicates.and(HintPredicates.JOIN,
                 HintPredicates.explicit((hint, rel) -> {
                   ...
                 })))
         .hintStrategy("use_merge_join",
             HintStrategyTable.strategyBuilder(
                 HintPredicates.and(HintPredicates.JOIN, joinWithFixedTableName()))
                 .excludedRules(EnumerableRules.ENUMERABLE_JOIN_RULE).build())
         .build();
       // Config the strategies in the config.
       SqlToRelConverter.Config config = SqlToRelConverter.configBuilder()
         .withHintStrategyTable(strategies)
         .build();
       // Use the config to initialize the SqlToRelConverter.
   ...
 

Hints Propagation

There are two cases that need to consider the hints propagation:

• Right after a SqlNode tree is converted to RelNode tree, we would propagate the hints from the attaching node to its input(children) nodes. The hints are propagated recursively with a RelShuttle, see RelOptUtil#RelHintPropagateShuttle for how it works.
• During rule planning, in the transforming phrase of a RelOptRule, you should not copy the hints by hand. To ensure correctness, the hints copy work within planner rule is taken care of by Calcite; We make some effort to make the thing easier: right before the new relational expression was registered into the planner, the hints of the old relational expression was copied into the new expression sub-tree(by "new" we mean, the node was created just in the planner rule) if the nodes implement Hintable.

Design Doc

Calcite SQL and Planner Hints Design.