<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % CustomDTD SYSTEM "../../../../../../docbook/custom.dtd">
%CustomDTD;
]>
<chapter id="cache-hint-options">
    <title>Hints and Options</title>
	<section id="cache-hint">
		<title>Cache Hint</title>
	   	<para>A query cache hint can be used to:</para>
	   	<itemizedlist>
	   		<listitem><para>Indicate that a user query is eligible for result set caching and set the cache entry memory preference or time to live.
	   		</para></listitem>
	   		<listitem><para>Set the materialized view memory preference, time to live, or updatablity.
	   		</para></listitem>
	   		<listitem><para>Indicate that a virtual procedure should be cachable and set the cache entry memory preference or time to live.
	   		</para></listitem>
	   	</itemizedlist>
	   	<para><synopsis>/*+ cache[([pref_mem] [ttl:n] [updatable])] [scope:(session|user|vdb)] */ sql ...</synopsis>
	   	<itemizedlist>
	   		<listitem><para>The cache hint should appear at the beginning of the SQL.  It will not have any affect on INSERT/UPDATE/DELETE statements or virtual update procedure definitions.</para></listitem>
	   		<listitem><para><emphasis>pref_mem</emphasis> - if present indicates that the cached results should prefer to remain in memory.  They are not however required to be memory only.
	   		<note><para>Care should be taken to not over use the pref_mem option.  
	   		The memory preference is implemented with Java soft references.  While soft references are effective at preventing out of memory conditions.  
	   		Too much memory held by soft references can limit the effective working memory.  Consult your JVM options for clearing soft references if you need to tune their behavior.</para></note>
	   		</para></listitem>
	   		<listitem><para><emphasis>ttl:n</emphasis> - if present n indicates the time to live value in milliseconds.
	   		</para></listitem>
	   		<listitem><para><emphasis>updatable</emphasis> - if present indicates that the cached results can be updated.  This is currently only applicable to materialized views.
	   		</para></listitem>
            <listitem><para><emphasis>scope</emphasis> - if present indicates the override scope of query results. Using this flag, the user can override the computed scope.
            There are three different cache scopes: session - cached only for current session, user - cached for any session by the current user, vdb - cached for any user connected to the same vdb. 
            </para></listitem>
            
	 	</itemizedlist>
	   	</para>
	   	   	<section>
   		<title>Limitations</title>
	   	<itemizedlist>
	   		<listitem><para>The form of the query hint must be matched exactly for the hint to have affect.  
	   		For a user query if the hint is not specified correctly, e.g. <code>/*+ cach(pref_mem) */</code>, it will not be used by the engine nor will 
	   		there be an informational log.  As a workaround, the query plan may be checked though (see the Client Developers Guide) to see if the user command
	   		in the plan has retained the proper hint.
	   		</para></listitem>
	  	</itemizedlist>
	   	</section>
   	</section>
   	<section id="nocache">
   		<title>OPTION NOCACHE</title>
   		<para>Individual queries may override the use of cached results by
			specifying <code>OPTION NOCACHE</code> on the query.  0 or more fully qualified view or procedure names may be specified to exclude using their cached results.  
			If no names are specified, cached results will not be used transitively.
		</para>
		<example>
			<title>Full NOCACHE</title>
			<programlisting>SELECT * from vg1, vg2, vg3 WHERE … OPTION NOCACHE</programlisting>
			<para>No cached results will be used at all.</para>
		</example>
		<example>
			<title>Specific NOCACHE</title>
			<programlisting>SELECT * from vg1, vg2, vg3 WHERE … OPTION NOCACHE vg1, vg3</programlisting>
			<para>Only the vg1 and vg3 caches will be skipped, vg2 or any cached results nested under vg1 and vg3 will be used.</para>
		</example>
		<para><code>OPTION NOCACHE</code> may be specified in procedure or view definitions.  In that way, transformations can
			specify to always use real-time data obtained directly from sources.
			</para>
   	</section>
</chapter>