Package org.apache.calcite.rel.hint

Class RelHint

java.lang.Object
org.apache.calcite.rel.hint.RelHint
public class RelHint extends Object
Hint attached to a relation expression.

A hint can be used to:

  • Enforce planner: there's no perfect planner, so it makes sense to implement hints to allow user better control the execution. For instance, "never merge this subquery with others", "treat those tables as leading ones" in the join ordering, etc.
  • Append meta data/statistics: Some statistics like “table index for scan” and “skew info of some shuffle keys” are somewhat dynamic for the query, it would be very convenient to config them with hints because our planning metadata from the planner is very often not that accurate.
  • Operator resource constraints: For many cases, we would give a default resource configuration for the execution operators, i.e. min parallelism or managed memory (resource consuming UDF) or special resource requirement (GPU or SSD disk) and so on, it would be very flexible to profile the resource with hints per query (instead of the Job).

In order to support hint override, each hint has a inheritPath (integers list) to record its propagate path from the root node, number `0` represents the hint was propagated along the first(left) child, number `1` represents the hint was propagated along the second(right) child. Given a relational expression tree with initial attached hints: 

            Filter (Hint1)
                |
               Join
              /    \
            Scan  Project (Hint2)
                     |
                    Scan2

The plan would have hints path as follows (assumes each hint can be propagated to all child nodes):

  • Filter → {Hint1[]}
  • Join → {Hint1[0]}
  • Scan → {Hint1[0, 0]}
  • Project → {Hint1[0,1], Hint2[]}
  • Scan2 → {[Hint1[0, 1, 0], Hint2[0]}

listOptions and kvOptions are supposed to contain the same information, they are mutually exclusive, that means, they can not both be non-empty.

RelHint is immutable.

  • Field Details

    • inheritPath

      public final com.google.common.collect.ImmutableList<Integer> inheritPath

    • hintName

      public final String hintName

    • listOptions

      public final List<String> listOptions

    • kvOptions

      public final Map<String,String> kvOptions

  • Method Details

    • builder

      public static RelHint.Builder builder(String hintName)
      Creates a hint builder with specified hint name.

    • copy

      public RelHint copy(List<Integer> inheritPath)
      Returns a copy of this hint with specified inherit path.
      Parameters:
      inheritPath - Hint path
      Returns:
      the new RelHint

    • equals

      public boolean equals(@Nullable Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object