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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RelHint.Builder Builder for RelHint.

Field Summary

Fields

Modifier and Type	Field and Description
String	hintName
com.google.common.collect.ImmutableList<Integer>	inheritPath
Map<String,String>	kvOptions
List<String>	listOptions

Method Summary

Modifier and Type	Method and Description
static RelHint.Builder	builder(String hintName) Creates a hint builder with specified hint name.
RelHint	copy(List<Integer> inheritPath) Returns a copy of this hint with specified inherit path.
boolean	equals(@Nullable Object o)
int	hashCode()
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

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 Detail

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