blob: ccbb8eebf8c228b153a5d05ea821b6c1978fb614 [file] [log] [blame]
<!DOCTYPE HTML>
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc -->
<title>org.apache.calcite.rel.hint (Apache Calcite calcite API)</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="description" content="declaration: package: org.apache.calcite.rel.hint">
<meta name="generator" content="javadoc/PackageWriterImpl">
<link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="Style">
<link rel="stylesheet" type="text/css" href="../../../../../script-dir/jquery-ui.css" title="Style">
<script type="text/javascript" src="../../../../../script.js"></script>
<script type="text/javascript" src="../../../../../script-dir/jszip/dist/jszip.min.js"></script>
<script type="text/javascript" src="../../../../../script-dir/jszip-utils/dist/jszip-utils.min.js"></script>
<!--[if IE]>
<script type="text/javascript" src="../../../../../script-dir/jszip-utils/dist/jszip-utils-ie.min.js"></script>
<![endif]-->
<script type="text/javascript" src="../../../../../script-dir/jquery-3.4.1.js"></script>
<script type="text/javascript" src="../../../../../script-dir/jquery-ui.js"></script>
</head>
<body class="package-declaration">
<script type="text/javascript">var pathtoroot = "../../../../../";
loadScripts(document, 'script');</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<div class="flexBox">
<header role="banner" class="flexHeader">
<nav role="navigation">
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a id="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a id="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../index.html">Overview</a></li>
<li class="navBarCell1Rev">Package</li>
<li>Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><b>Apache Calcite</b></div>
</div>
<div class="subNav">
<div class="navListSearch"><label for="search">SEARCH:</label>
<input type="text" id="search" value="search" disabled="disabled">
<input type="reset" id="reset" value="reset" disabled="disabled">
</div>
</div>
<!-- ========= END OF TOP NAVBAR ========= -->
<div class="skipNav"><a id="skip.navbar.top">
<!-- -->
</a></div>
</nav>
</header>
<div class="flexContent">
<main role="main">
<div class="header">
<h1 title="Package" class="title">Package&nbsp;org.apache.calcite.rel.hint</h1>
</div>
<div class="contentContainer">
<section class="packageDescription"><a id="package.description">
<!-- -->
</a>
<div class="block">Defines hints interfaces and utilities for relational expressions.
<h2>The Syntax</h2>
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.
<blockquote><pre>
select &#47;&#42;&#43; NO_HASH_JOIN, RESOURCE(mem='128mb', parallelism='24') &#42;&#47;
from
emp &#47;&#42;&#43; INDEX(idx1, idx2) &#42;&#47;
join
dept &#47;&#42;&#43; PROPERTIES(k1='v1', k2='v2') &#42;&#47;
on emp.deptno=dept.deptno
</pre></blockquote>
<h2>Customize Hint Match Rules</h2>
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.
<p>A match rule is defined though <a href="HintPredicate.html" title="interface in org.apache.calcite.rel.hint"><code>HintPredicate</code></a>.
<a href="NodeTypeHintPredicate.html" title="class in org.apache.calcite.rel.hint"><code>NodeTypeHintPredicate</code></a> 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.
<p>Here is the code snippet to illustrate how to config the strategies:
<pre>
// 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) -&gt; {
...
})))
.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.
...
</pre>
<h2>Hints Propagation</h2>
There are two cases that need to consider the hints propagation:
<ul>
<li>Right after a <code>SqlNode</code> tree is converted to <code>RelNode</code> tree, we would
propagate the hints from the attaching node to its input(children) nodes. The hints are
propagated recursively with a <code>RelShuttle</code>, see
RelOptUtil#RelHintPropagateShuttle for how it works.</li>
<li>During rule planning, in the transforming phrase of a <code>RelOptRule</code>,
you <strong>should not</strong> 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
<a href="Hintable.html" title="interface in org.apache.calcite.rel.hint"><code>Hintable</code></a>.</li>
</ul>
<h2>Design Doc</h2>
<a href="https://docs.google.com/document/d/1mykz-w2t1Yw7CH6NjUWpWqCAf_6YNKxSc59gXafrNCs/edit?usp=sharing">Calcite SQL and Planner Hints Design</a>.</div>
</section>
<section class="summary">
<ul class="blockList">
<li class="blockList">
<div class="typeSummary">
<table>
<caption><span>Interface Summary</span><span class="tabEnd">&nbsp;</span></caption>
<thead>
<tr>
<th class="colFirst" scope="col">Interface</th>
<th class="colLast" scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr class="altColor">
<th class="colFirst" scope="row"><a href="Hintable.html" title="interface in org.apache.calcite.rel.hint">Hintable</a></th>
<td class="colLast">
<div class="block"><a href="Hintable.html" title="interface in org.apache.calcite.rel.hint"><code>Hintable</code></a> is a kind of <a href="../RelNode.html" title="interface in org.apache.calcite.rel"><code>RelNode</code></a> that can attach <a href="RelHint.html" title="class in org.apache.calcite.rel.hint"><code>RelHint</code></a>s.</div>
</td>
</tr>
<tr class="rowColor">
<th class="colFirst" scope="row"><a href="HintOptionChecker.html" title="interface in org.apache.calcite.rel.hint">HintOptionChecker</a></th>
<td class="colLast">
<div class="block">A <code>HintOptionChecker</code> validates the options of a <a href="RelHint.html" title="class in org.apache.calcite.rel.hint"><code>RelHint</code></a>.</div>
</td>
</tr>
<tr class="altColor">
<th class="colFirst" scope="row"><a href="HintPredicate.html" title="interface in org.apache.calcite.rel.hint">HintPredicate</a></th>
<td class="colLast">
<div class="block">A <code>HintPredicate</code> indicates whether a <a href="../RelNode.html" title="interface in org.apache.calcite.rel"><code>RelNode</code></a>
can apply the specified hint.</div>
</td>
</tr>
</tbody>
</table>
</div>
</li>
<li class="blockList">
<div class="typeSummary">
<table>
<caption><span>Class Summary</span><span class="tabEnd">&nbsp;</span></caption>
<thead>
<tr>
<th class="colFirst" scope="col">Class</th>
<th class="colLast" scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr class="altColor">
<th class="colFirst" scope="row"><a href="CompositeHintPredicate.html" title="class in org.apache.calcite.rel.hint">CompositeHintPredicate</a></th>
<td class="colLast">
<div class="block">A <a href="HintPredicate.html" title="interface in org.apache.calcite.rel.hint"><code>HintPredicate</code></a> to combine multiple hint predicates into one.</div>
</td>
</tr>
<tr class="rowColor">
<th class="colFirst" scope="row"><a href="HintPredicates.html" title="class in org.apache.calcite.rel.hint">HintPredicates</a></th>
<td class="colLast">
<div class="block">A collection of hint predicates.</div>
</td>
</tr>
<tr class="altColor">
<th class="colFirst" scope="row"><a href="HintStrategy.html" title="class in org.apache.calcite.rel.hint">HintStrategy</a></th>
<td class="colLast">
<div class="block">Represents a hint strategy entry of <a href="HintStrategyTable.html" title="class in org.apache.calcite.rel.hint"><code>HintStrategyTable</code></a>.</div>
</td>
</tr>
<tr class="rowColor">
<th class="colFirst" scope="row"><a href="HintStrategy.Builder.html" title="class in org.apache.calcite.rel.hint">HintStrategy.Builder</a></th>
<td class="colLast">
<div class="block">Builder for <a href="HintStrategy.html" title="class in org.apache.calcite.rel.hint"><code>HintStrategy</code></a>.</div>
</td>
</tr>
<tr class="altColor">
<th class="colFirst" scope="row"><a href="HintStrategyTable.html" title="class in org.apache.calcite.rel.hint">HintStrategyTable</a></th>
<td class="colLast">
<div class="block">A collection of <a href="HintStrategy.html" title="class in org.apache.calcite.rel.hint"><code>HintStrategy</code></a>s.</div>
</td>
</tr>
<tr class="rowColor">
<th class="colFirst" scope="row"><a href="HintStrategyTable.Builder.html" title="class in org.apache.calcite.rel.hint">HintStrategyTable.Builder</a></th>
<td class="colLast">
<div class="block">Builder for <code>HintStrategyTable</code>.</div>
</td>
</tr>
<tr class="altColor">
<th class="colFirst" scope="row"><a href="HintStrategyTable.HintErrorLogger.html" title="class in org.apache.calcite.rel.hint">HintStrategyTable.HintErrorLogger</a></th>
<td class="colLast">
<div class="block">Implementation of <a href="../../util/Litmus.html" title="interface in org.apache.calcite.util"><code>Litmus</code></a> that returns
a status code, it logs warnings for fail check and does not throw.</div>
</td>
</tr>
<tr class="rowColor">
<th class="colFirst" scope="row"><a href="NodeTypeHintPredicate.html" title="class in org.apache.calcite.rel.hint">NodeTypeHintPredicate</a></th>
<td class="colLast">
<div class="block">A hint predicate that specifies which kind of relational
expression the hint can be applied to.</div>
</td>
</tr>
<tr class="altColor">
<th class="colFirst" scope="row"><a href="RelHint.html" title="class in org.apache.calcite.rel.hint">RelHint</a></th>
<td class="colLast">
<div class="block">Hint attached to a relation expression.</div>
</td>
</tr>
<tr class="rowColor">
<th class="colFirst" scope="row"><a href="RelHint.Builder.html" title="class in org.apache.calcite.rel.hint">RelHint.Builder</a></th>
<td class="colLast">
<div class="block">Builder for <a href="RelHint.html" title="class in org.apache.calcite.rel.hint"><code>RelHint</code></a>.</div>
</td>
</tr>
</tbody>
</table>
</div>
</li>
<li class="blockList">
<div class="typeSummary">
<table>
<caption><span>Enum Summary</span><span class="tabEnd">&nbsp;</span></caption>
<thead>
<tr>
<th class="colFirst" scope="col">Enum</th>
<th class="colLast" scope="col">Description</th>
</tr>
</thead>
<tbody>
<tr class="altColor">
<th class="colFirst" scope="row"><a href="CompositeHintPredicate.Composition.html" title="enum in org.apache.calcite.rel.hint">CompositeHintPredicate.Composition</a></th>
<td class="colLast">
<div class="block">How hint predicates are composed.</div>
</td>
</tr>
</tbody>
</table>
</div>
</li>
</ul>
</section>
</div>
</main>
<footer role="contentinfo">
<nav role="navigation">
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a id="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a id="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../index.html">Overview</a></li>
<li class="navBarCell1Rev">Package</li>
<li>Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage"><b>Apache Calcite</b></div>
</div>
<a id="skip.navbar.bottom">
<!-- -->
</a>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</nav>
<p class="legalCopy"><small>Copyright &copy; 2012-2020 Apache Software Foundation. All Rights Reserved.</small></p>
</footer>
</div>
</div>
</body>
</html>