<html>
<head>
<base href="https://docs.jboss.org/author">
<link rel="stylesheet" href="/author/s/en/2172/19/5/_/styles/combined.css?spaceKey=TEIID&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://docs.jboss.org/author/display/TEIID/Query+Plans">Query Plans</a></h2>
<h4>Page <b>edited</b> by <a href="https://docs.jboss.org/author/display/~shawkins">Steven Hawkins</a>
</h4>
<br/>
<h4>Changes (2)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >- If the KEEP ALIASES option is used either for the general hint or on the applicable source specific hint, then the table/view aliases from the user query and any nested views will be preserved in the push-down query. This is useful in situations where the source hint may need to reference aliases and the user does not wish to rely on the generated aliases (which can be seen in the query plan in the relevant source queries - see above). However in some situations this may result in an invalid source query if the preserved alias names are not valid for the source or result in a name collision. If the usage of KEEP ALIASES results in an error, the query could be modified by preventing view removal with the NO_UNNEST hint, the aliases modified, or the KEEP ALIASES option could be removed and the query plan used to determine the generated alias names. <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{code:SQL|title=Sample Source Hint}SELECT /*+ sh:'general hint' my-oracle:'oracle hint' */ ... {code}. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{code:SQL|title=Sample Source Hints}SELECT /*+ sh:'general hint' */ ... <br> <br>SELECT /*+ sh KEEP ALIASES:'general hint' my-oracle:'oracle hint' */ ... <br>{code} <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<p>When integrating information using a federated query planner, it is useful to be able to view the query plans that are created, to better understand how information is being accessed and processed, and to troubleshoot problems.</p>
<p>A query plan is a set of instructions created by a query engine for executing a command submitted by a user or application. The purpose of the query plan is to execute the user's query in as efficient a way as possible.</p>
<h1><a name="QueryPlans-GettingaQueryPlan"></a>Getting a Query Plan</h1>
<p>You can get a query plan any time you execute a command. The SQL options available are as follows:</p>
<p><b>SHOWPLAN [ON|DEBUG]</b>- Returns the plan or the plan and the full planner debug log.<br/>
With the above options, the query plan is available from the Statement object by casting to the <tt>org.teiid.jdbc.TeiidStatement</tt> interface.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Retrieving a Query Plan</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
statement.execute("set showplan on");
ResultSet rs = statement.executeQuery("select ...");
TeiidStatement tstatement = statement.unwrap(TeiidStatement.class);
PlanNode queryPlan = tstatement.getPlanDescription();
System.out.println(queryPlan);
</pre>
</div></div>
<p>The query plan is made available automatically in several of Teiid's tools.</p>
<h1><a name="QueryPlans-AnalyzingaQueryPlan"></a>Analyzing a Query Plan</h1>
<p>Once a query plan has been obtained you will most commonly be looking for:</p>
<ul>
<li>Source pushdown -- what parts of the query that got pushed to each source</li>
</ul>
<ul>
<li>Join ordering</li>
</ul>
<ul>
<li>Join algorithm used - merge or nested loop.</li>
</ul>
<ul>
<li>Presence of federated optimizations, such as dependent joins.</li>
</ul>
<ul>
<li>Join criteria type mismatches.</li>
</ul>
<p>All of these issues presented above will be present subsections of the plan that are specific to relational queries. If you are executing a procedure or generating an XML document, the overall query plan will contain additional information related the surrounding procedural execution.</p>
<p>A query plan consists of a set of nodes organized in a tree structure. As with the above example, you will typically be interested in analyzing the textual form of the plan.</p>
<p>In a procedural context the ordering of child nodes implies the order of execution. In most other situation, child nodes may be executed in any order even in parallel. Only in specific optimizations, such as dependent join, will the children of a join execute serially.</p>
<h1><a name="QueryPlans-RelationalPlans"></a>Relational Plans</h1>
<p>Relational plans represent the actually processing plan that is composed of nodes that are the basic building blocks of logical relational operations. Physical relational plans differ from logical relational plans in that they will contain additional operations and execution specifics that were chosen by the optimizer.</p>
<p>The nodes for a relational query plan are:</p>
<ul>
<li>Access - Access a source. A source query is sent to the connection factory associated with the source. [For a dependent join, this node is called Dependent Select.]</li>
</ul>
<ul>
<li>Project - Defines the columns returned from the node. This does not alter the number of records returned. [When there is a subquery in the Select clause, this node is called Dependent Project.]</li>
</ul>
<ul>
<li>Project Into - Like a normal project, but outputs rows into a target table.</li>
</ul>
<ul>
<li>Select - Select is a criteria evaluation filter node (WHERE / HAVING). [When there is a subquery in the criteria, this node is called Dependent Select.]</li>
</ul>
<ul>
<li>Join - Defines the join type, join criteria, and join strategy (merge or nested loop).</li>
</ul>
<ul>
<li>Union - There are no properties for this node, it just passes rows through from it's children</li>
<li>Sort - Defines the columns to sort on, the sort direction for each column, and whether to remove duplicates or not.</li>
</ul>
<ul>
<li>Dup Removal - Same properties as for Sort, but the removeDups property is set to true</li>
</ul>
<ul>
<li>Group - Groups sets of rows into groups and evaluates aggregate functions.</li>
</ul>
<ul>
<li>Null - A node that produces no rows. Usually replaces a Select node where the criteria is always false (and whatever tree is underneath). There are no properties for this node.</li>
<li>Plan Execution - Executes another sub plan.</li>
</ul>
<ul>
<li>Limit - Returns a specified number of rows, then stops processing. Also processes an offset if present.</li>
</ul>
<h2><a name="QueryPlans-NodeStatistics"></a>Node Statistics</h2>
<p>Every node has a set of statistics that are output. These can be used to determine the amount of data flowing through the node.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Statistic </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Units </th>
</tr>
<tr>
<td class='confluenceTd'> Node Output Rows </td>
<td class='confluenceTd'> Number of records output from the node </td>
<td class='confluenceTd'> count </td>
</tr>
<tr>
<td class='confluenceTd'> Node Process Time </td>
<td class='confluenceTd'> Time processing in this node only </td>
<td class='confluenceTd'> millisec </td>
</tr>
<tr>
<td class='confluenceTd'> Node Cumulative Process Time </td>
<td class='confluenceTd'> Elapsed time from beginning of processing to end </td>
<td class='confluenceTd'> millisec </td>
</tr>
<tr>
<td class='confluenceTd'> Node Cumulative Next Batch Process Time </td>
<td class='confluenceTd'> Time processing in this node + child nodes </td>
<td class='confluenceTd'> millisec </td>
</tr>
<tr>
<td class='confluenceTd'> Node Next Batch Calls </td>
<td class='confluenceTd'> Number of times a node was called for processing </td>
<td class='confluenceTd'> count </td>
</tr>
<tr>
<td class='confluenceTd'> Node Blocks </td>
<td class='confluenceTd'> Number of times a blocked exception was thrown by this node or a child </td>
<td class='confluenceTd'> count </td>
</tr>
</tbody></table>
</div>
<p>In addition to node statistics, some nodes display cost estimates computed at the node.</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Cost Estimates </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Units </th>
</tr>
<tr>
<td class='confluenceTd'> Estimated Node Cardinality </td>
<td class='confluenceTd'> Estimated number of records that will be output from the node; -1 if unknown </td>
<td class='confluenceTd'> count </td>
</tr>
</tbody></table>
</div>
<h1><a name="QueryPlans-SourceHints"></a>Source Hints</h1>
<p>Teiid user and transformation queries can contain a meta source hint that can provide additional information to source queries. The source hint has the form:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">/*+ sh[[ KEEP ALIASES]:'arg'] source-name[ KEEP ALIASES]:'arg1' ... */</pre>
</div></div>
<ul class="alternate" type="square">
<li>The source hint is expected to appear after the query (SELECT, INSERT, UPDATE, DELETE) keyword.</li>
<li>The sh arg is optional and is passed to all source queries via the <tt>ExecutionContext.getGeneralHint</tt> method. The additional args should have a source-name that matches the source name assigned to the translator in the VDB. If the source-name matches, the hint value will be supplied via the <tt>ExecutionContext.getSourceHint</tt> method. See the <a href="/author/display/TEIID/Developer%27s+Guide" title="Developer's Guide">Developer's Guide</a> for more on using an ExecutionContext.</li>
<li>Each of the arg values has the form of a string literal - it must be surrounded in single quotes and a single quote can be escaped with another single quote. Only the Oracle translator does anything with source hints by default. The Oracle translator will use either the source hint or the general hint (in that order) if available to form an Oracle hint enclosed in /*+ ... */. Source hints in views will not be passed to the source if the view is used as a pushdown subquery, is joined, or is in a set operation.</li>
<li>If the KEEP ALIASES option is used either for the general hint or on the applicable source specific hint, then the table/view aliases from the user query and any nested views will be preserved in the push-down query. This is useful in situations where the source hint may need to reference aliases and the user does not wish to rely on the generated aliases (which can be seen in the query plan in the relevant source queries - see above). However in some situations this may result in an invalid source query if the preserved alias names are not valid for the source or result in a name collision. If the usage of KEEP ALIASES results in an error, the query could be modified by preventing view removal with the NO_UNNEST hint, the aliases modified, or the KEEP ALIASES option could be removed and the query plan used to determine the generated alias names.</li>
</ul>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Sample Source Hints</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: sql; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">SELECT /*+ sh:'general hint' */ ...
SELECT /*+ sh KEEP ALIASES:'general hint' my-oracle:'oracle hint' */ ...
</pre>
</div></div>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://docs.jboss.org/author/users/removespacenotification.action?spaceKey=TEIID">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://docs.jboss.org/author/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://docs.jboss.org/author/display/TEIID/Query+Plans">View Online</a>
|
<a href="https://docs.jboss.org/author/pages/diffpagesbyversion.action?pageId=18646297&revisedVersion=4&originalVersion=3">View Changes</a>
|
<a href="https://docs.jboss.org/author/display/TEIID/Query+Plans?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>