<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/Results+Caching">Results Caching</a></h2>
<h4>Page <b>edited</b> by <a href="https://docs.jboss.org/author/display/~shawkins">Steven Hawkins</a>
</h4>
<br/>
<h4>Changes (16)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-changed-lines" >Teiid provides the capability to cache the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">results of</span> <span class="diff-added-words"style="background-color: #dfd;">results&nbsp;of</span> specific user queries and virtual procedure calls. <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> This</span> <span class="diff-added-words"style="background-color: #dfd;">&nbsp;This</span> caching technique can yield significant performance gains if users of the system submit the same queries or execute the same procedures often. <br></td></tr>
<tr><td class="diff-unchanged" > <br>h2. Support Summary <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >* Caching of virtual procedure results. <br> <br></td></tr>
<tr><td class="diff-changed-lines" >* Scoping of results is automatically determined to be VDB/user <span class="diff-changed-words"><span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">\</span>(replicated)</span> or session level. <br></td></tr>
<tr><td class="diff-unchanged" > <br>* Configurable number of cache entries and time to live. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >User query result set caching will cache result sets based on an exact match of the incoming SQL string and PreparedStatement parameter values if present. Caching only applies to SELECT, set query, and stored procedure execution statements; it does not apply to SELECT INTO statements, or INSERT, UPDATE, or DELETE statements. <br> <br></td></tr>
<tr><td class="diff-changed-lines" >End users or client applications explicitly state whether to use result set caching. This can be done by setting the JDBC ResultSetCacheMode execution property to true <span class="diff-changed-words"><span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">\</span>(default</span> false) or by adding a [Cache Hint|Hints and Options#Cache Hint] to the query. Note that if either of these mechanisms are used, Teiid must also have result set caching enabled <span class="diff-changed-words"><span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">\</span>(the</span> default is enabled). <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >The most basic form of the cache hint, <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">{{/\*+</span> <span class="diff-added-words"style="background-color: #dfd;">{{/*\+</span> cache \*/}}, is sufficient to inform the engine that the results of the <span class="diff-changed-words">non<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">\</span>-update</span> command should be cached. <br></td></tr>
<tr><td class="diff-unchanged" > <br>{code:title=PreparedStatement ResultSet Caching} <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >The results will be cached with the default ttl and use the SQL string and the parameter value as part of the cache key. <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The <span class="diff-changed-words">pref<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">\</span>_mem</span> and ttl options of the cache hint may also be used for result set cache queries. If a cache hint is not specified, then the default time to live of the result set caching configuration will be used. <br></td></tr>
<tr><td class="diff-unchanged" > <br>{code:title=Advanced ResultSet Caching} <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" > <br>{note} <br></td></tr>
<tr><td class="diff-changed-lines" >Each query is <span class="diff-changed-words">re<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">\</span>-checked</span> for authorization using the current user’s permissions, regardless of whether or not the results have been cached. <br></td></tr>
<tr><td class="diff-unchanged" >{note} <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >Results will be cached with the default ttl. <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The <span class="diff-changed-words">pref<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">\</span>_mem</span> and ttl options of the cache hint may also be used for procedure caching. <br></td></tr>
<tr><td class="diff-unchanged" > <br>Procedure results cache keys include the input parameter values. To prevent one procedure from filling the cache, at most 256 cache keys may be created per procedure per VDB. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >h2. Cache Configuration <br> <br></td></tr>
<tr><td class="diff-changed-lines" >By default result set caching is enabled with 1024 maximum entries with a maximum entry age of 2 hours. There are actually 2 caches configured with these settings. One cache holds results that are specific to sessions and is local to each Teiid instance. The other cache holds VDB scoped results and can be replicated. See <span class="diff-added-words"style="background-color: #dfd;">the</span> teiid subsystem configuration for tuning. The user may also override the default maximum entry age via the [Cache Hint|Hints and Options#Cache Hint]. <br></td></tr>
<tr><td class="diff-unchanged" > <br>Result set caching is not limited to memory. There is no explicit limit on the size of the results that can be cached. Cached results are primarily stored in the _BufferManager_ and are subject to it's configuration - including the restriction of maximum buffer space. <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{note} <br> <br></td></tr>
<tr><td class="diff-changed-lines" >Result set cache entries can be invalidated by data change events. The <span class="diff-changed-words">_max<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">\</span>-staleness_</span> setting determines how long an entry will remain in the case after one of the tables that contributed to the results has been changed. See the [Developer's Guide] for further customization. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. Cache Administration <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h2. Extension Metadata <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The result set cache can be cleared through the AdminAPI using the {{clearCache}} method. The expected cache key is "QUERY\_SERVICE\_RESULT\_SET\_CACHE". <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">You can use the extension metadata property {code}{http://www.teiid.org/ext/relational/2012}data-ttl{code} as a model property or on a source table to indicate a default TTL. A negative value means no TTL, 0 means do not cache, and a positive number indicates the time to live in milliseconds. If no TTL is specified on the table, then the schema will be checked. The TTL for the cache entry will be taken as the least positive value among all TTLs. Thus setting this value as a model property can quickly disable any caching against a particular source. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">For example, setting the property in the vdb.xml: <br> <br>{code:lang=XML}<vdb name="vdbname" version="1"> <br> <model name="Customers"> <br> <property name="teiid_rel:data-ttl" value="0"/> <br> ... <br>{code} <br> <br>h2. Cache Administration <br> <br>The result set cache can be cleared through the AdminAPI using the {{clearCache}} method. The expected cache key is "QUERY_SERVICE_RESULT_SET_CACHE". <br> <br></td></tr>
<tr><td class="diff-unchanged" >{code:title=Clearing the ResultSet Cache in AdminShell} <br>connectAsAdmin() <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >* The exact SQL string, including the cache hint if present, must match the cached entry for the results to be reused. This allows cache usage to skip parsing and resolving for faster responses. <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">* Result set caching is not transactional. Transactions depend on \(and enforce) consistency of data, and cached data is not guaranteed to be consistent with the data store’s data. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">* Result set caching is transactional by default using the NON_XA transaction mode. If you want full XA support, then change the configuration to use NON_DURABLE_XA. <br></td></tr>
<tr><td class="diff-unchanged" > <br>* Clearing the results cache clears all cache entries for all VDBs. <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<p>Teiid provides the capability to cache the results of specific user queries and virtual procedure calls. This caching technique can yield significant performance gains if users of the system submit the same queries or execute the same procedures often.</p>
<h2><a name="ResultsCaching-SupportSummary"></a>Support Summary</h2>
<ul>
<li>Caching of user query results including XML document model results.</li>
</ul>
<ul>
<li>Caching of virtual procedure results.</li>
</ul>
<ul>
<li>Scoping of results is automatically determined to be VDB/user (replicated) or session level.</li>
</ul>
<ul>
<li>Configurable number of cache entries and time to live.</li>
</ul>
<ul>
<li>Administrative clearing.</li>
</ul>
<h2><a name="ResultsCaching-UserInteraction"></a>User Interaction</h2>
<h3><a name="ResultsCaching-UserQueryCache"></a>User Query Cache</h3>
<p>User query result set caching will cache result sets based on an exact match of the incoming SQL string and PreparedStatement parameter values if present. Caching only applies to SELECT, set query, and stored procedure execution statements; it does not apply to SELECT INTO statements, or INSERT, UPDATE, or DELETE statements.</p>
<p>End users or client applications explicitly state whether to use result set caching. This can be done by setting the JDBC ResultSetCacheMode execution property to true (default false) or by adding a <a href="/author/display/TEIID/Hints+and+Options#HintsandOptions-CacheHint">Cache Hint</a> to the query. Note that if either of these mechanisms are used, Teiid must also have result set caching enabled (the default is enabled).</p>
<p>The most basic form of the cache hint, <tt>/*+ cache */</tt>, is sufficient to inform the engine that the results of the non-update command should be cached.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>PreparedStatement ResultSet Caching</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
...
PreparedStatement ps = connection.prepareStatement("/*+ cache */ select col from t where col2 = ?");
ps.setInt(1, 5);
ps.execute();
...
</pre>
</div></div>
<p>The results will be cached with the default ttl and use the SQL string and the parameter value as part of the cache key.</p>
<p>The pref_mem and ttl options of the cache hint may also be used for result set cache queries. If a cache hint is not specified, then the default time to live of the result set caching configuration will be used.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Advanced ResultSet Caching</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
/*+ cache(pref_mem ttl:60000) */ select col from t
</pre>
</div></div>
<p>In this example the memory preference has been enabled and the time to live is set to 60000 milliseconds or 1 minute. The ttl for an entry is actually treated as it's maximum age and the entry may be purged sooner if the maximum number of cache entries has been reached.</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>Each query is re-checked for authorization using the current user’s permissions, regardless of whether or not the results have been cached.</td></tr></table></div>
<h3><a name="ResultsCaching-ProcedureResultCache"></a>Procedure Result Cache</h3>
<p>Similar to materialized views, cached virtual procedure results are used automatically when a matching set of parameter values is detected for the same procedure execution. Usage of the cached results may be bypassed when used with the <a href="/author/display/TEIID/Hints+and+Options#HintsandOptions-OPTIONNOCACHE">OPTION NOCACHE</a> clause. Usage is covered in <a href="/author/display/TEIID/Hints+and+Options#HintsandOptions-OPTIONNOCACHE">Hints and Options</a>.</p>
<h2><a name="ResultsCaching-CachedVirtualProcedureDefinition"></a>Cached Virtual Procedure Definition</h2>
<p>To indicate that a virtual procedure should be cached, it's definition should include a <a href="/author/display/TEIID/Hints+and+Options#HintsandOptions-CacheHint">Cache Hint</a>.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Procedure Caching</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
/*+ cache */
BEGIN
...
END
</pre>
</div></div>
<p>Results will be cached with the default ttl.</p>
<p>The pref_mem and ttl options of the cache hint may also be used for procedure caching.</p>
<p>Procedure results cache keys include the input parameter values. To prevent one procedure from filling the cache, at most 256 cache keys may be created per procedure per VDB.</p>
<p>A cached procedure will always produce all of its results prior to allowing those results to be consumed and placed in the cache. This differs from normal procedure execution which in some situations allows the returned results to be consumed in a streaming manner.</p>
<h2><a name="ResultsCaching-CacheConfiguration"></a>Cache Configuration</h2>
<p>By default result set caching is enabled with 1024 maximum entries with a maximum entry age of 2 hours. There are actually 2 caches configured with these settings. One cache holds results that are specific to sessions and is local to each Teiid instance. The other cache holds VDB scoped results and can be replicated. See the teiid subsystem configuration for tuning. The user may also override the default maximum entry age via the <a href="/author/display/TEIID/Hints+and+Options#HintsandOptions-CacheHint">Cache Hint</a>.</p>
<p>Result set caching is not limited to memory. There is no explicit limit on the size of the results that can be cached. Cached results are primarily stored in the <em>BufferManager</em> and are subject to it's configuration - including the restriction of maximum buffer space.</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>While the result data is not held in memory, cache keys - including parameter values - may be held in memory. Thus the cache should not be given an unlimited maximum size.</td></tr></table></div>
<p>Result set cache entries can be invalidated by data change events. The <em>max-staleness</em> setting determines how long an entry will remain in the case after one of the tables that contributed to the results has been changed. See the <a href="/author/display/TEIID/Developer%27s+Guide" title="Developer's Guide">Developer's Guide</a> for further customization.</p>
<h2><a name="ResultsCaching-ExtensionMetadata"></a>Extension Metadata</h2>
<p>You can use the extension metadata property <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;">{http://www.teiid.org/ext/relational/2012}data-ttl</pre>
</div></div> as a model property or on a source table to indicate a default TTL. A negative value means no TTL, 0 means do not cache, and a positive number indicates the time to live in milliseconds. If no TTL is specified on the table, then the schema will be checked. The TTL for the cache entry will be taken as the least positive value among all TTLs. Thus setting this value as a model property can quickly disable any caching against a particular source.</p>
<p>For example, setting the property in the vdb.xml:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: xml; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;"><vdb name="vdbname" version="1">
<model name="Customers">
<property name="teiid_rel:data-ttl" value="0"/>
...
</pre>
</div></div>
<h2><a name="ResultsCaching-CacheAdministration"></a>Cache Administration</h2>
<p>The result set cache can be cleared through the AdminAPI using the <tt>clearCache</tt> method. The expected cache key is "QUERY_SERVICE_RESULT_SET_CACHE".</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Clearing the ResultSet Cache in AdminShell</b></div><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: java; gutter: false" style="font-size:12px; font-family: ConfluenceInstalledFont,monospace;">
connectAsAdmin()
clearCache("QUERY_SERVICE_RESULT_SET_CACHE")
...
</pre>
</div></div>
<p>See the <a href="/author/display/TEIID/Administrator%27s+Guide" title="Administrator's Guide">Administrator's Guide</a> for more on using the AdminAPI and AdminShell.</p>
<h2><a name="ResultsCaching-Limitations"></a>Limitations</h2>
<ul>
<li>XML, BLOB, CLOB, and OBJECT type cannot be used as part of the cache key for prepared statement of procedure cache keys.</li>
</ul>
<ul>
<li>The exact SQL string, including the cache hint if present, must match the cached entry for the results to be reused. This allows cache usage to skip parsing and resolving for faster responses.</li>
</ul>
<ul>
<li>Result set caching is transactional by default using the NON_XA transaction mode. If you want full XA support, then change the configuration to use NON_DURABLE_XA.</li>
</ul>
<ul>
<li>Clearing the results cache clears all cache entries for all VDBs.</li>
</ul>
</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/Results+Caching">View Online</a>
|
<a href="https://docs.jboss.org/author/pages/diffpagesbyversion.action?pageId=18646091&revisedVersion=8&originalVersion=7">View Changes</a>
|
<a href="https://docs.jboss.org/author/display/TEIID/Results+Caching?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>