svn commit: r763965 - in /db/derby/docs/trunk/src: ref/rrefupdatestatsproc.dita tuning/ctunstats849505.dita

[ch...@apache.org]

Author: chaase3
Date: Fri Apr 10 15:49:54 2009
New Revision: 763965

URL: http://svn.apache.org/viewvc?rev=763965&view=rev
Log:
DERBY-4121: Documentation: more UPDATE_STATISTICS fixes needed for Reference Manual and Tuning Derby

Corrections and additions to Reference topic, new paragraph for Tuning topic

Patch: DERBY-4121-2.diff

Modified:
    db/derby/docs/trunk/src/ref/rrefupdatestatsproc.dita
    db/derby/docs/trunk/src/tuning/ctunstats849505.dita

Modified: db/derby/docs/trunk/src/ref/rrefupdatestatsproc.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefupdatestatsproc.dita?rev=763965&r1=763964&r2=763965&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefupdatestatsproc.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefupdatestatsproc.dita Fri Apr 10 15:49:54 2009
@@ -23,23 +23,32 @@
 <section><p>The SYSCS_UTIL.SYSCS_UPDATE_STATISTICS system procedure
 updates the cardinality statistics, or creates the statistics if they
 do not exist, for the index that you specify or for all of the indexes
-on a table. <ph>Derby</ph> uses cardinality statistics to determine
+on a table. <ph conref="../conrefs.dita#prod/productshortname"></ph> uses cardinality statistics to determine
 the optimal query plan during the compilation of a query. If the statistics
-are missing, <ph>Derby</ph> might use a query plan which is not the
-most efficient plan. </p><p>For more information on cardinality statistics,
+are missing, <ph conref="../conrefs.dita#prod/productshortname"></ph> might use a query plan which is not the
+most efficient plan. </p>
+<p>Once statistics have been created, they cannot be dropped and should be
+maintained. It is a good idea to call the SYSCS_UTIL.SYSCS_UPDATE_STATISTICS
+procedure when the number of distinct values in an index is likely to have
+changed significantly.</p>
+<p>For more information on cardinality statistics,
 see "Working with cardinality statistics" in the <ph
 conref="../conrefs.dita#pub/cittuning"></ph> guide.</p></section>
-<section><title>Syntax</title><codeblock>SYSCS_UTIL.SYSCS_UPDATE_STATISTICS(SCHEMANAME, TABLENAME, INDEXNAME)</codeblock><note>You
+<section><title>Syntax</title>
+<codeblock>SYSCS_UTIL.SYSCS_UPDATE_STATISTICS(IN SCHEMANAME VARCHAR(128), 
+                                   IN TABLENAME VARCHAR(128), 
+                                   IN INDEXNAME VARCHAR(128)))</codeblock>
+<note>You
 can specify <userinput>null</userinput> for the INDEXNAME to update
 any existing statistics and create statistics for those statistics
 that are missing.</note></section>
 <section><title>Examples</title><p>In the following example, the system
 procedure updates statistics for the index PAY_DESC on the SAMP.EMPLOYEE
-table:</p><codeblock>SYSCS_UTIL.SYSCS_UPDATE_STATISTICS('SAMP','EMPLOYEE','PAY_DESC');
+table:</p><codeblock>CALL SYSCS_UTIL.SYSCS_UPDATE_STATISTICS('SAMP','EMPLOYEE','PAY_DESC');
 </codeblock><p>In the following example, <userinput>null</userinput> is
 specified instead of an index name. For all of the indexes, the existing
 statistics are updated and statistics are created for any missing
-statistics on the EMPLOYEE table in the SAMP schema.</p><codeblock>SYSCS_UTIL.SYSCS_UPDATE_STATISTICS('SAMP', 'EMPLOYEE', null); 
+statistics on the EMPLOYEE table in the SAMP schema.</p><codeblock>CALL SYSCS_UTIL.SYSCS_UPDATE_STATISTICS('SAMP', 'EMPLOYEE', null);
 </codeblock></section>
 </refbody>
 </reference>

Modified: db/derby/docs/trunk/src/tuning/ctunstats849505.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunstats849505.dita?rev=763965&r1=763964&r2=763965&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunstats849505.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunstats849505.dita Fri Apr 10 15:49:54 2009
@@ -31,4 +31,9 @@
 means that statistics can go stale. Stale statistics can slow your system
 down, because they worsen the accuracy of the optimizer's estimates of
 selectivity.  </p>
+<p>Statistics are likely to be stale if the number of distinct values in an
+index has changed significantly. This can happen often or rarely, depending on
+the nature of the column being indexed. You can refresh cardinality statistics
+by calling the procedure SYSCS_UTIL.SYSCS_UPDATE_STATISTICS. For information
+about this procedure, see the <ph conref="../conrefs.dita#pub/citref"></ph>.</p>
 </conbody></concept>