| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc --> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>org.apache.calcite.rel.hint (Apache Calcite calcite API)</title> |
| <link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="Style"> |
| <script type="text/javascript" src="../../../../../script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="org.apache.calcite.rel.hint (Apache Calcite calcite API)"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../../overview-summary.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"> |
| <ul class="navList"> |
| <li><a href="../../../../../org/apache/calcite/rel/externalize/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../../org/apache/calcite/rel/logical/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../../index.html?org/apache/calcite/rel/hint/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="../../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 title="Package" class="title">Package org.apache.calcite.rel.hint</h1> |
| <div class="docSummary"> |
| <div class="block">Defines hints interfaces and utilities for relational expressions.</div> |
| </div> |
| <p>See: <a href="#package.description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Interface Summary table, listing interfaces, and an explanation"> |
| <caption><span>Interface Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Interface</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/Hintable.html" title="interface in org.apache.calcite.rel.hint">Hintable</a></td> |
| <td class="colLast"> |
| <div class="block"><a href="../../../../../org/apache/calcite/rel/hint/Hintable.html" title="interface in org.apache.calcite.rel.hint"><code>Hintable</code></a> is a kind of <a href="../../../../../org/apache/calcite/rel/RelNode.html" title="interface in org.apache.calcite.rel"><code>RelNode</code></a> that can attach <a href="../../../../../org/apache/calcite/rel/hint/RelHint.html" title="class in org.apache.calcite.rel.hint"><code>RelHint</code></a>s.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/HintOptionChecker.html" title="interface in org.apache.calcite.rel.hint">HintOptionChecker</a></td> |
| <td class="colLast"> |
| <div class="block">A <code>HintOptionChecker</code> validates the options of a <a href="../../../../../org/apache/calcite/rel/hint/RelHint.html" title="class in org.apache.calcite.rel.hint"><code>RelHint</code></a>.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/HintPredicate.html" title="interface in org.apache.calcite.rel.hint">HintPredicate</a></td> |
| <td class="colLast"> |
| <div class="block">A <code>HintPredicate</code> indicates whether a <a href="../../../../../org/apache/calcite/rel/RelNode.html" title="interface in org.apache.calcite.rel"><code>RelNode</code></a> |
| can apply the specified hint.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation"> |
| <caption><span>Class Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Class</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/CompositeHintPredicate.html" title="class in org.apache.calcite.rel.hint">CompositeHintPredicate</a></td> |
| <td class="colLast"> |
| <div class="block">A <a href="../../../../../org/apache/calcite/rel/hint/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"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/HintPredicates.html" title="class in org.apache.calcite.rel.hint">HintPredicates</a></td> |
| <td class="colLast"> |
| <div class="block">A collection of hint predicates.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/HintStrategy.html" title="class in org.apache.calcite.rel.hint">HintStrategy</a></td> |
| <td class="colLast"> |
| <div class="block">Represents a hint strategy entry of <a href="../../../../../org/apache/calcite/rel/hint/HintStrategyTable.html" title="class in org.apache.calcite.rel.hint"><code>HintStrategyTable</code></a>.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/HintStrategy.Builder.html" title="class in org.apache.calcite.rel.hint">HintStrategy.Builder</a></td> |
| <td class="colLast"> |
| <div class="block">Builder for <a href="../../../../../org/apache/calcite/rel/hint/HintStrategy.html" title="class in org.apache.calcite.rel.hint"><code>HintStrategy</code></a>.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/HintStrategyTable.html" title="class in org.apache.calcite.rel.hint">HintStrategyTable</a></td> |
| <td class="colLast"> |
| <div class="block">A collection of <a href="../../../../../org/apache/calcite/rel/hint/HintStrategy.html" title="class in org.apache.calcite.rel.hint"><code>HintStrategy</code></a>s.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/HintStrategyTable.Builder.html" title="class in org.apache.calcite.rel.hint">HintStrategyTable.Builder</a></td> |
| <td class="colLast"> |
| <div class="block">Builder for <code>HintStrategyTable</code>.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/HintStrategyTable.HintErrorLogger.html" title="class in org.apache.calcite.rel.hint">HintStrategyTable.HintErrorLogger</a></td> |
| <td class="colLast"> |
| <div class="block">Implementation of <a href="../../../../../org/apache/calcite/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"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/NodeTypeHintPredicate.html" title="class in org.apache.calcite.rel.hint">NodeTypeHintPredicate</a></td> |
| <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"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/RelHint.html" title="class in org.apache.calcite.rel.hint">RelHint</a></td> |
| <td class="colLast"> |
| <div class="block">Hint attached to a relation expression.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/RelHint.Builder.html" title="class in org.apache.calcite.rel.hint">RelHint.Builder</a></td> |
| <td class="colLast"> |
| <div class="block">Builder for <a href="../../../../../org/apache/calcite/rel/hint/RelHint.html" title="class in org.apache.calcite.rel.hint"><code>RelHint</code></a>.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Enum Summary table, listing enums, and an explanation"> |
| <caption><span>Enum Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Enum</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/calcite/rel/hint/CompositeHintPredicate.Composition.html" title="enum in org.apache.calcite.rel.hint">CompositeHintPredicate.Composition</a></td> |
| <td class="colLast"> |
| <div class="block">How hint predicates are composed.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| </ul> |
| <a name="package.description"> |
| <!-- --> |
| </a> |
| <h2 title="Package org.apache.calcite.rel.hint Description">Package org.apache.calcite.rel.hint Description</h2> |
| <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 /*+ 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 |
| </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="../../../../../org/apache/calcite/rel/hint/HintPredicate.html" title="interface in org.apache.calcite.rel.hint"><code>HintPredicate</code></a>. |
| <a href="../../../../../org/apache/calcite/rel/hint/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) -> { |
| ... |
| }))) |
| .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="../../../../../org/apache/calcite/rel/hint/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> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../../overview-summary.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"> |
| <ul class="navList"> |
| <li><a href="../../../../../org/apache/calcite/rel/externalize/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../../org/apache/calcite/rel/logical/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../../index.html?org/apache/calcite/rel/hint/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="../../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| <p class="legalCopy"><small>Copyright © 2012-2020 Apache Software Foundation. All Rights Reserved.</small></p> |
| </body> |
| </html> |
