| <!DOCTYPE HTML> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc (17) --> |
| <title>org.apache.calcite.rel.hint (Apache Calcite API)</title> |
| <meta name="viewport" content="width=device-width, initial-scale=1"> |
| <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.min.css" title="Style"> |
| <link rel="stylesheet" type="text/css" href="../../../../../jquery-ui.overrides.css" title="Style"> |
| <script type="text/javascript" src="../../../../../script.js"></script> |
| <script type="text/javascript" src="../../../../../script-dir/jquery-3.5.1.min.js"></script> |
| <script type="text/javascript" src="../../../../../script-dir/jquery-ui.min.js"></script> |
| </head> |
| <body class="package-declaration-page"> |
| <script type="text/javascript">var evenRowColor = "even-row-color"; |
| var oddRowColor = "odd-row-color"; |
| var tableTab = "table-tab"; |
| var activeTableTab = "active-table-tab"; |
| var pathtoroot = "../../../../../"; |
| loadScripts(document, 'script');</script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <div class="flex-box"> |
| <header role="banner" class="flex-header"> |
| <nav role="navigation"> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="top-nav" id="navbar-top"> |
| <div class="skip-nav"><a href="#skip-navbar-top" title="Skip navigation links">Skip navigation links</a></div> |
| <div class="about-language"><b>Apache Calcite</b></div> |
| <ul id="navbar-top-firstrow" class="nav-list" title="Navigation"> |
| <li><a href="../../../../../index.html">Overview</a></li> |
| <li class="nav-bar-cell1-rev">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#package">Help</a></li> |
| </ul> |
| </div> |
| <div class="sub-nav"> |
| <div> |
| <ul class="sub-nav-list"> |
| <li>Package: </li> |
| <li><a href="#package-description">Description</a> | </li> |
| <li><a href="#related-package-summary">Related Packages</a> | </li> |
| <li><a href="#class-summary">Classes and Interfaces</a></li> |
| </ul> |
| </div> |
| <div class="nav-list-search"><label for="search-input">SEARCH:</label> |
| <input type="text" id="search-input" value="search" disabled="disabled"> |
| <input type="reset" id="reset-button" value="reset" disabled="disabled"> |
| </div> |
| </div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <span class="skip-nav" id="skip-navbar-top"></span></nav> |
| </header> |
| <div class="flex-content"> |
| <main role="main"> |
| <div class="header"> |
| <h1 title="Package org.apache.calcite.rel.hint" class="title">Package org.apache.calcite.rel.hint</h1> |
| </div> |
| <hr> |
| <div class="package-signature">package <span class="element-name">org.apache.calcite.rel.hint</span></div> |
| <section class="package-description" id="package-description"> |
| <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="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) -> { |
| ... |
| }))) |
| .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="summary-list"> |
| <li> |
| <div id="related-package-summary"> |
| <div class="caption"><span>Related Packages</span></div> |
| <div class="summary-table two-column-summary"> |
| <div class="table-header col-first">Package</div> |
| <div class="table-header col-last">Description</div> |
| <div class="col-first even-row-color"><a href="../package-summary.html">org.apache.calcite.rel</a></div> |
| <div class="col-last even-row-color"> |
| <div class="block">Defines relational expressions.</div> |
| </div> |
| </div> |
| </div> |
| </li> |
| <li> |
| <div id="class-summary"> |
| <div class="table-tabs" role="tablist" aria-orientation="horizontal"><button id="class-summary-tab0" role="tab" aria-selected="true" aria-controls="class-summary.tabpanel" tabindex="0" onkeydown="switchTab(event)" onclick="show('class-summary', 'class-summary', 2)" class="active-table-tab">All Classes and Interfaces</button><button id="class-summary-tab1" role="tab" aria-selected="false" aria-controls="class-summary.tabpanel" tabindex="-1" onkeydown="switchTab(event)" onclick="show('class-summary', 'class-summary-tab1', 2)" class="table-tab">Interfaces</button><button id="class-summary-tab2" role="tab" aria-selected="false" aria-controls="class-summary.tabpanel" tabindex="-1" onkeydown="switchTab(event)" onclick="show('class-summary', 'class-summary-tab2', 2)" class="table-tab">Classes</button><button id="class-summary-tab3" role="tab" aria-selected="false" aria-controls="class-summary.tabpanel" tabindex="-1" onkeydown="switchTab(event)" onclick="show('class-summary', 'class-summary-tab3', 2)" class="table-tab">Enums</button></div> |
| <div id="class-summary.tabpanel" role="tabpanel"> |
| <div class="summary-table two-column-summary" aria-labelledby="class-summary-tab0"> |
| <div class="table-header col-first">Class</div> |
| <div class="table-header col-last">Description</div> |
| <div class="col-first even-row-color class-summary class-summary-tab2"><a href="CompositeHintPredicate.html" title="class in org.apache.calcite.rel.hint">CompositeHintPredicate</a></div> |
| <div class="col-last even-row-color class-summary class-summary-tab2"> |
| <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> |
| </div> |
| <div class="col-first odd-row-color class-summary class-summary-tab3"><a href="CompositeHintPredicate.Composition.html" title="enum in org.apache.calcite.rel.hint">CompositeHintPredicate.Composition</a></div> |
| <div class="col-last odd-row-color class-summary class-summary-tab3"> |
| <div class="block">How hint predicates are composed.</div> |
| </div> |
| <div class="col-first even-row-color class-summary class-summary-tab1"><a href="Hintable.html" title="interface in org.apache.calcite.rel.hint">Hintable</a></div> |
| <div class="col-last even-row-color class-summary class-summary-tab1"> |
| <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> |
| </div> |
| <div class="col-first odd-row-color class-summary class-summary-tab1"><a href="HintOptionChecker.html" title="interface in org.apache.calcite.rel.hint">HintOptionChecker</a></div> |
| <div class="col-last odd-row-color class-summary class-summary-tab1"> |
| <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> |
| </div> |
| <div class="col-first even-row-color class-summary class-summary-tab1"><a href="HintPredicate.html" title="interface in org.apache.calcite.rel.hint">HintPredicate</a></div> |
| <div class="col-last even-row-color class-summary class-summary-tab1"> |
| <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> |
| </div> |
| <div class="col-first odd-row-color class-summary class-summary-tab2"><a href="HintPredicates.html" title="class in org.apache.calcite.rel.hint">HintPredicates</a></div> |
| <div class="col-last odd-row-color class-summary class-summary-tab2"> |
| <div class="block">A collection of hint predicates.</div> |
| </div> |
| <div class="col-first even-row-color class-summary class-summary-tab2"><a href="HintStrategy.html" title="class in org.apache.calcite.rel.hint">HintStrategy</a></div> |
| <div class="col-last even-row-color class-summary class-summary-tab2"> |
| <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> |
| </div> |
| <div class="col-first odd-row-color class-summary class-summary-tab2"><a href="HintStrategy.Builder.html" title="class in org.apache.calcite.rel.hint">HintStrategy.Builder</a></div> |
| <div class="col-last odd-row-color class-summary class-summary-tab2"> |
| <div class="block">Builder for <a href="HintStrategy.html" title="class in org.apache.calcite.rel.hint"><code>HintStrategy</code></a>.</div> |
| </div> |
| <div class="col-first even-row-color class-summary class-summary-tab2"><a href="HintStrategyTable.html" title="class in org.apache.calcite.rel.hint">HintStrategyTable</a></div> |
| <div class="col-last even-row-color class-summary class-summary-tab2"> |
| <div class="block">A collection of <a href="HintStrategy.html" title="class in org.apache.calcite.rel.hint"><code>HintStrategy</code></a>s.</div> |
| </div> |
| <div class="col-first odd-row-color class-summary class-summary-tab2"><a href="HintStrategyTable.Builder.html" title="class in org.apache.calcite.rel.hint">HintStrategyTable.Builder</a></div> |
| <div class="col-last odd-row-color class-summary class-summary-tab2"> |
| <div class="block">Builder for <code>HintStrategyTable</code>.</div> |
| </div> |
| <div class="col-first even-row-color class-summary class-summary-tab2"><a href="HintStrategyTable.HintErrorLogger.html" title="class in org.apache.calcite.rel.hint">HintStrategyTable.HintErrorLogger</a></div> |
| <div class="col-last even-row-color class-summary class-summary-tab2"> |
| <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> |
| </div> |
| <div class="col-first odd-row-color class-summary class-summary-tab2"><a href="NodeTypeHintPredicate.html" title="class in org.apache.calcite.rel.hint">NodeTypeHintPredicate</a></div> |
| <div class="col-last odd-row-color class-summary class-summary-tab2"> |
| <div class="block">A hint predicate that specifies which kind of relational |
| expression the hint can be applied to.</div> |
| </div> |
| <div class="col-first even-row-color class-summary class-summary-tab2"><a href="RelHint.html" title="class in org.apache.calcite.rel.hint">RelHint</a></div> |
| <div class="col-last even-row-color class-summary class-summary-tab2"> |
| <div class="block">Hint attached to a relation expression.</div> |
| </div> |
| <div class="col-first odd-row-color class-summary class-summary-tab2"><a href="RelHint.Builder.html" title="class in org.apache.calcite.rel.hint">RelHint.Builder</a></div> |
| <div class="col-last odd-row-color class-summary class-summary-tab2"> |
| <div class="block">Builder for <a href="RelHint.html" title="class in org.apache.calcite.rel.hint"><code>RelHint</code></a>.</div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </li> |
| </ul> |
| </section> |
| </main> |
| <footer role="contentinfo"> |
| <hr> |
| <p class="legal-copy"><small>Copyright © 2012-2023 Apache Software Foundation. All Rights Reserved.</small></p> |
| </footer> |
| </div> |
| </div> |
| </body> |
| </html> |
