<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/Translator+Capabilities">Translator Capabilities</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" >| AdvancedOlapOperations | ElementaryOlapOperations | Translator supports aggregate conditions. | <br>| OnlyFormatLiterals | function support for a parse/format function and an implementation of the supportsFormatLiteral method. | Translator supports only literal format patterns that must be validated by the supportsFormatLiteral method. | <br></td></tr>
<tr><td class="diff-changed-lines" >| <span class="diff-changed-words">FormatLitera<span class="diff-added-chars"style="background-color: #dfd;">l</span>(String</span> literal, Format type) | OnlyFormatLiterals | Translator supports the given literal format string. | <br></td></tr>
<tr><td class="diff-unchanged" >| ArrayType \\ | | Translator supports the push down of array values. \\ | <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">| OnlyCorrelatedSubqueries\\ | CorrelatedSubqueries\\ | Translator ONLY supports correlated subqueries.&nbsp; Uncorrelated scalar and exists subqueries will be pre-evaluated prior to push-down.\\ | <br></td></tr>
<tr><td class="diff-unchanged" > <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<p>The <tt>ExecutionFactory</tt> class defines all the methods that describe the capabilities of a Translator. These are used by the Connector Manager to determine what kinds of commands the translator is capable of executing. A base <tt>ExecutionFactory</tt> class implements all the basic capabilities methods, which says your translator does not support any capabilities. Your extended <tt>ExecutionFactory</tt> class must override the the necessary methods to specify which capabilities your translator supports. You should consult the debug log of query planning (set showplan debug) to see if desired pushdown requires additional capabilities.</p>
<h2><a name="TranslatorCapabilities-CapabilityScope"></a>Capability Scope</h2>
<p>Note that if your capabilities will remain unchanged for the lifetime of the translator, since the engine will cache them for reuse by all instances of that translator. Capabilities based on connection/user are not supported.</p>
<h2><a name="TranslatorCapabilities-Capabilities"></a>Capabilities</h2>
<p>The following table lists the capabilities that can be specified in the <tt>ExecutionFactory</tt> class.</p>
<p><b>Available Capabilities</b>
<br class="atl-forced-newline" /></p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Capability </th>
<th class='confluenceTh'> Requires </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> SelectDistinct </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support SELECT DISTINCT in queries. </td>
</tr>
<tr>
<td class='confluenceTd'> SelectExpression </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support SELECT of more than just column references. </td>
</tr>
<tr>
<td class='confluenceTd'> AliasedTable </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support Tables in the FROM clause that have an alias. </td>
</tr>
<tr>
<td class='confluenceTd'> InnerJoins </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support inner and cross joins </td>
</tr>
<tr>
<td class='confluenceTd'> SelfJoins </td>
<td class='confluenceTd'> AliasedGroups and at least on of the join type supports. </td>
<td class='confluenceTd'> Translator can support a self join between two aliased versions of the same Table. </td>
</tr>
<tr>
<td class='confluenceTd'> OuterJoins </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support LEFT and RIGHT OUTER JOIN. </td>
</tr>
<tr>
<td class='confluenceTd'> FullOuterJoins </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support FULL OUTER JOIN. </td>
</tr>
<tr>
<td class='confluenceTd'> DependentJoins </td>
<td class='confluenceTd'> Base join and criteria support </td>
<td class='confluenceTd'> Translator supports dependent join pushdown. See <a href="/author/display/TEIID/Dependent+Join+Pushdown" title="Dependent Join Pushdown">Dependent Join Pushdown</a>. When set the MaxDependentInPredicates and MaxInCriteriaSize values are not used by the engine, rather all independent values are made available to the pushdown command. </td>
</tr>
<tr>
<td class='confluenceTd'> SubqueryInOn </td>
<td class='confluenceTd'> Join and base subquery support, such as ExistsCriteria </td>
<td class='confluenceTd'> Translator can support subqueries in the ON clause. Defaults to true. </td>
</tr>
<tr>
<td class='confluenceTd'> InlineViews </td>
<td class='confluenceTd'> AliasedTable </td>
<td class='confluenceTd'> Translator can support a named subquery in the FROM clause. </td>
</tr>
<tr>
<td class='confluenceTd'> BetweenCriteria </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Not currently used - between criteria is rewriten as compound comparisions. </td>
</tr>
<tr>
<td class='confluenceTd'> CompareCriteriaEquals </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support comparison criteria with the operator "=". </td>
</tr>
<tr>
<td class='confluenceTd'> CompareCriteriaOrdered </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support comparison criteria with the operator ">" or "<". </td>
</tr>
<tr>
<td class='confluenceTd'> LikeCriteria </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support LIKE criteria. </td>
</tr>
<tr>
<td class='confluenceTd'> LikeCriteriaEscapeCharacter </td>
<td class='confluenceTd'> LikeCriteria </td>
<td class='confluenceTd'> Translator can support LIKE criteria with an ESCAPE character clause. </td>
</tr>
<tr>
<td class='confluenceTd'> SimilarTo </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support SIMILAR TO criteria. </td>
</tr>
<tr>
<td class='confluenceTd'> LikeRegexCriteria </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support LIKE_REGEX criteria. </td>
</tr>
<tr>
<td class='confluenceTd'> InCriteria </td>
<td class='confluenceTd'> MaxInCriteria </td>
<td class='confluenceTd'> Translator can support IN predicate criteria. </td>
</tr>
<tr>
<td class='confluenceTd'> InCriteriaSubquery </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support IN predicate criteria where values are supplied by a subquery. </td>
</tr>
<tr>
<td class='confluenceTd'> IsNullCriteria </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support IS NULL predicate criteria. </td>
</tr>
<tr>
<td class='confluenceTd'> OrCriteria </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the OR logical criteria. </td>
</tr>
<tr>
<td class='confluenceTd'> NotCriteria </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the NOT logical criteria. IMPORTANT: This capability also applies to negation of predicates, such as specifying IS NOT NULL, "<=" (not ">"), ">=" (not "<"), etc. </td>
</tr>
<tr>
<td class='confluenceTd'> ExistsCriteria </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support EXISTS predicate criteria. </td>
</tr>
<tr>
<td class='confluenceTd'> QuantifiedCompareCriteriaAll </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support a quantified comparison criteria using the ALL quantifier. </td>
</tr>
<tr>
<td class='confluenceTd'> QuantifiedCompareCriteriaSome </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support a quantified comparison criteria using the SOME or ANY quantifier. </td>
</tr>
<tr>
<td class='confluenceTd'> OnlyLiteralComparison </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator if only Literal comparisons (equality, ordered, like, etc.) are supported for non-join conditions. </td>
</tr>
<tr>
<td class='confluenceTd'> Convert(int fromType, int toType) </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Used for fine grained control of convert/cast pushdown. The <tt>ExecutionFactory.getSupportedFunctions()</tt> should contain <tt>SourceSystemFunctions.CONVERT</tt>. This method can then return false to indicate a lack of specific support. See <tt>TypeFacility.RUNTIME_CODES</tt> for the possible type codes. The engine will does not care about an unnecessary conversion where fromType == toType. By default lob conversion is disabled. </td>
</tr>
<tr>
<td class='confluenceTd'> OrderBy </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the ORDER BY clause in queries. </td>
</tr>
<tr>
<td class='confluenceTd'> OrderByUnrelated </td>
<td class='confluenceTd'> OrderBy </td>
<td class='confluenceTd'> Translator can support ORDER BY items that are not directly specified in the select clause. </td>
</tr>
<tr>
<td class='confluenceTd'> OrderByNullOrdering </td>
<td class='confluenceTd'> OrderBy </td>
<td class='confluenceTd'> Translator can support ORDER BY items with NULLS FIRST/LAST. </td>
</tr>
<tr>
<td class='confluenceTd'> GroupBy </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support an explict GROUP BY clause. </td>
</tr>
<tr>
<td class='confluenceTd'> Having </td>
<td class='confluenceTd'> GroupBy </td>
<td class='confluenceTd'> Translator can support the HAVING clause. </td>
</tr>
<tr>
<td class='confluenceTd'> AggregatesAvg </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the AVG aggregate function. </td>
</tr>
<tr>
<td class='confluenceTd'> AggregatesCount </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the COUNT aggregate function. </td>
</tr>
<tr>
<td class='confluenceTd'> AggregatesCountStar </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the COUNT(*) aggregate function. </td>
</tr>
<tr>
<td class='confluenceTd'> AggregatesDistinct </td>
<td class='confluenceTd'> At least one of the aggregate functions. </td>
<td class='confluenceTd'> Translator can support the keyword DISTINCT inside an aggregate function. This keyword indicates that duplicate values within a group of rows will be ignored. </td>
</tr>
<tr>
<td class='confluenceTd'> AggregatesMax </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the MAX aggregate function. </td>
</tr>
<tr>
<td class='confluenceTd'> AggregatesMin </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the MIN aggregate function. </td>
</tr>
<tr>
<td class='confluenceTd'> AggregatesSum </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the SUM aggregate function. </td>
</tr>
<tr>
<td class='confluenceTd'> AggregatesEnhancedNumeric </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the VAR_SAMP, VAR_POP, STDDEV_SAMP, STDDEV_POP aggregate functions. </td>
</tr>
<tr>
<td class='confluenceTd'> ScalarSubqueries </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the use of a subquery in a scalar context (wherever an expression is valid). </td>
</tr>
<tr>
<td class='confluenceTd'> CorrelatedSubqueries </td>
<td class='confluenceTd'> At least one of the subquery pushdown capabilities. </td>
<td class='confluenceTd'> Translator can support a correlated subquery that refers to an element in the outer query. </td>
</tr>
<tr>
<td class='confluenceTd'> CaseExpressions </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Not currently used - simple case is rewriten as searched case. </td>
</tr>
<tr>
<td class='confluenceTd'> SearchedCaseExpressions </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support "searched" CASE expressions anywhere that expressions are accepted. </td>
</tr>
<tr>
<td class='confluenceTd'> Unions </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator support UNION and UNION ALL </td>
</tr>
<tr>
<td class='confluenceTd'> Intersect </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator supports INTERSECT </td>
</tr>
<tr>
<td class='confluenceTd'> Except </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator supports Except </td>
</tr>
<tr>
<td class='confluenceTd'> SetQueryOrderBy </td>
<td class='confluenceTd'> Unions, Intersect, or Except </td>
<td class='confluenceTd'> Translator supports set queries with an ORDER BY </td>
</tr>
<tr>
<td class='confluenceTd'> RowLimit </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the limit portion of the limit clause </td>
</tr>
<tr>
<td class='confluenceTd'> RowOffset </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator can support the offset portion of the limit clause </td>
</tr>
<tr>
<td class='confluenceTd'> FunctionsInGroupBy </td>
<td class='confluenceTd'> GroupBy </td>
<td class='confluenceTd'> Translator can support non-column reference grouping expressions. </td>
</tr>
<tr>
<td class='confluenceTd'> InsertWithQueryExpression </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator supports INSERT statements with values specified by an QueryExpression. </td>
</tr>
<tr>
<td class='confluenceTd'> BatchedUpdates </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator supports a batch of INSERT, UPDATE and DELETE commands to be executed together. </td>
</tr>
<tr>
<td class='confluenceTd'> BulkUpdate </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator supports updates with multiple value sets </td>
</tr>
<tr>
<td class='confluenceTd'> CommonTableExpressions </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator supports the WITH clause. </td>
</tr>
<tr>
<td class='confluenceTd'> ElementaryOlapOperations </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator supports window functions and analytic functions RANK, DENSE_RANK, and ROW_NUMBER. </td>
</tr>
<tr>
<td class='confluenceTd'> WindowOrderByWithAggregates </td>
<td class='confluenceTd'> ElementaryOlapOperations </td>
<td class='confluenceTd'> Translator supports windowed aggregates with a window order by clause. </td>
</tr>
<tr>
<td class='confluenceTd'> WindowDistinctAggregates </td>
<td class='confluenceTd'> ElementaryOlapOperations, AggregatesDistinct </td>
<td class='confluenceTd'> Translator supports windowed distinct aggregates. </td>
</tr>
<tr>
<td class='confluenceTd'> AdvancedOlapOperations </td>
<td class='confluenceTd'> ElementaryOlapOperations </td>
<td class='confluenceTd'> Translator supports aggregate conditions. </td>
</tr>
<tr>
<td class='confluenceTd'> OnlyFormatLiterals </td>
<td class='confluenceTd'> function support for a parse/format function and an implementation of the supportsFormatLiteral method. </td>
<td class='confluenceTd'> Translator supports only literal format patterns that must be validated by the supportsFormatLiteral method. </td>
</tr>
<tr>
<td class='confluenceTd'> FormatLiteral(String literal, Format type) </td>
<td class='confluenceTd'> OnlyFormatLiterals </td>
<td class='confluenceTd'> Translator supports the given literal format string. </td>
</tr>
<tr>
<td class='confluenceTd'> ArrayType <br class="atl-forced-newline" /> </td>
<td class='confluenceTd'> </td>
<td class='confluenceTd'> Translator supports the push down of array values. <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td class='confluenceTd'> OnlyCorrelatedSubqueries<br class="atl-forced-newline" /> </td>
<td class='confluenceTd'> CorrelatedSubqueries<br class="atl-forced-newline" /> </td>
<td class='confluenceTd'> Translator ONLY supports correlated subqueries. Uncorrelated scalar and exists subqueries will be pre-evaluated prior to push-down.<br class="atl-forced-newline" /> </td>
</tr>
</tbody></table>
</div>
<p>Note that any pushdown subquery must itself be compliant with the Translator capabilities.</p>
<h2><a name="TranslatorCapabilities-CommandForm"></a>Command Form</h2>
<p>The method <tt>ExecutionFactory.useAnsiJoin()</tt> should return true if the Translator prefers the use of ANSI style join structure for join trees that contain only INNER and CROSS joins.</p>
<p>The method <tt>ExecutionFactory.requiresCriteria()</tt> should return true if the Translator requires criteria for any Query, Update, or Delete. This is a replacement for the model support property "Where All".</p>
<h2><a name="TranslatorCapabilities-ScalarFunctions"></a>Scalar Functions</h2>
<p>The method <tt>ExecutionFactory.getSupportedFunctions()</tt> can be used to specify which system/user defined scalar and user defined aggregate functions the Translator supports. The constants interface <tt>org.teiid.translator.SourceSystemFunctions</tt> contains the string names of all possible built-in pushdown functions, which includes the four standard math operators: +, -, *, and /.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/author/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Not all system functions appear in SourceSystemFunctions, since some system functions will always be evaluated in Teiid, are simple aliases to other functions, or are rewritten to a more standard expression.</td></tr></table></div>
<p>This documentation for system functions can be found at <a href="/author/display/TEIID/Scalar+Functions" title="Scalar Functions">Scalar Functions</a>. If the Translator states that it supports a function, it must support all type combinations and overloaded forms of that function.</p>
<p>A translator may also indicate support for scalar functions that are intended for pushdown evaluation by that translator, but are not registered as user defined functions via a model/schema. These pushdown functions are reported to the engine via the <tt>ExecutionFactory.getPushDownFunctions()</tt> list as <tt>FunctionMethod</tt> metadata objects. The <tt>FuncitonMethod</tt> representation allow the translator to control all of the metadata related to the function, including type signature, determinism, varargs, etc. The simplest way to add a pushdown function is with a call to <tt>ExecutionFactory.addPushDownFunction</tt>:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">FunctionMethod addPushDownFunction(String qualifier, String name, String returnType, String...paramTypes)</pre>
</div></div>
<p>This resulting function will be known as sys.qualifier.name, but can be called with just name as long as the function name is unique. The returned <tt>FunctionMethod</tt> object may be further manipulated depending upon the needs of the source. An example of adding a custom concat vararg function in an <tt>ExecutionFactory</tt> subclass:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
public void start() throws TranslatorException {
super.start();
FunctionMethod func = addPushDownFunciton("oracle", "concat", "string", "string", "string");
func.setVarArgs(true);
...
}
</pre>
</div></div>
<h2><a name="TranslatorCapabilities-PhysicalLimits"></a>Physical Limits</h2>
<p>The method <tt>ExecutionFactory.getMaxInCriteriaSize()</tt> can be used to specify the maximum number of values that can be passed in an IN criteria. This is an important constraint as an IN criteria is frequently used to pass criteria between one source and another using a dependent join.</p>
<p>The method <tt>ExecutionFactory.getMaxDependentInPredicates()</tt> is used to specify the maximum number of IN predicates (of at most MaxInCriteriaSize) that can be passed as part of a dependent join. For example if there are 10000 values to pass as part of the dependent join and a MaxInCriteriaSize of 1000 and a MaxDependentInPredicates setting of 5, then the dependent join logic will form two source queries each with 5 IN predicates of 1000 values each combined by OR.</p>
<p>The method <tt>ExecutionFactory.getMaxFromGroups()</tt> can be used to specify the maximum number of FROM Clause groups that can used in a join. -1 indicates there is no limit.</p>
<h2><a name="TranslatorCapabilities-UpdateExecutionModes"></a>Update Execution Modes</h2>
<p>The method <tt>ExecutionFactory.supportsBatchedUpdates()</tt> can be used to indicate that the Translator supports executing the <tt>BatchedUpdates</tt> command.</p>
<p>The method <tt>ExecutionFactory.supportsBulkUpdate()</tt> can be used to indicate that the Translator accepts update commands containg multi valued Literals.</p>
<p>Note that if the translator does not support either of these update modes, the query engine will compensate by issuing the updates individually.</p>
<h2><a name="TranslatorCapabilities-DefaultBehavior"></a>Default Behavior</h2>
<p>The method <tt>ExecutionFactory.getDefaultNullOrder()</tt> specifies the default null order. Can be one of UNKNOWN, LOW, HIGH, FIRST, LAST. This is only used if ORDER BY is supported, but null ordering is not.</p>
</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/Translator+Capabilities">View Online</a>
|
<a href="https://docs.jboss.org/author/pages/diffpagesbyversion.action?pageId=21627400&revisedVersion=10&originalVersion=9">View Changes</a>
|
<a href="https://docs.jboss.org/author/display/TEIID/Translator+Capabilities?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>