db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1307409 - in /db/derby/docs/trunk/src: ref/crefproper22250.dita ref/refderby.ditamap ref/rrefproperindexstatsauto.dita ref/rrefproperindexstatslog.dita ref/rrefproperindexstatstrace.dita tuning/ctunstats57373.dita
Date Fri, 30 Mar 2012 13:38:21 GMT
Author: chaase3
Date: Fri Mar 30 13:38:20 2012
New Revision: 1307409

URL: http://svn.apache.org/viewvc?rev=1307409&view=rev
Log:
DERBY-5083  Document automatic update and creation of index cardinality statistics (istat)

Added 3 new Reference Manual topics, modified another; modified a Tuning manual topic.

Patch: DERBY-5083.diff

Added:
    db/derby/docs/trunk/src/ref/rrefproperindexstatsauto.dita   (with props)
    db/derby/docs/trunk/src/ref/rrefproperindexstatslog.dita   (with props)
    db/derby/docs/trunk/src/ref/rrefproperindexstatstrace.dita   (with props)
Modified:
    db/derby/docs/trunk/src/ref/crefproper22250.dita
    db/derby/docs/trunk/src/ref/refderby.ditamap
    db/derby/docs/trunk/src/tuning/ctunstats57373.dita

Modified: db/derby/docs/trunk/src/ref/crefproper22250.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/crefproper22250.dita?rev=1307409&r1=1307408&r2=1307409&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/crefproper22250.dita (original)
+++ db/derby/docs/trunk/src/ref/crefproper22250.dita Fri Mar 30 13:38:20 2012
@@ -263,6 +263,21 @@ about when changes to the property are d
 <entry colname="3">Static</entry>
 </row>
 <row>
+<entry colname="1"><i><xref href="rrefproperindexstatsauto.dita#rrefproperindexstatsauto">derby.storage.indexStats.auto</xref></i></entry>
+<entry colname="2">S, D</entry>
+<entry colname="3">Static</entry>
+</row>
+<row>
+<entry colname="1"><i><xref href="rrefproperindexstatslog.dita#rrefproperindexstatslog">derby.storage.indexStats.log</xref></i></entry>
+<entry colname="2">S, D</entry>
+<entry colname="3">Static</entry>
+</row>
+<row>
+<entry colname="1"><i><xref href="rrefproperindexstatstrace.dita#rrefproperindexstatstrace">derby.storage.indexStats.trace</xref></i></entry>
+<entry colname="2">S, D</entry>
+<entry colname="3">Static</entry>
+</row>
+<row>
 <entry colname="1"><i><xref href="rrefproper27529.dita#rrefproper27529">derby.storage.initialPages</xref></i></entry>
 <entry colname="2">C</entry>
 <entry colname="3">Static</entry>

Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=1307409&r1=1307408&r2=1307409&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Fri Mar 30 13:38:20 2012
@@ -784,6 +784,12 @@ URL syntax"></topicref>
 <topicref href="rrefpropermaxlogshippinginterval.dita" navtitle="derby.replication.maxLogShippingInterval"></topicref>
 <topicref href="rrefproperminlogshippinginterval.dita" navtitle="derby.replication.minLogShippingInterval"></topicref>
 <topicref href="rrefproperverbose.dita" navtitle="derby.replication.verbose"></topicref>
+<topicref href="rrefproperindexstatsauto.dita" navtitle="derby.storage.indexStats.auto">
+</topicref>
+<topicref href="rrefproperindexstatslog.dita" navtitle="derby.storage.indexStats.log">
+</topicref>
+<topicref href="rrefproperindexstatstrace.dita" navtitle="derby.storage.indexStats.trace">
+</topicref>
 <topicref href="rrefproper27529.dita" navtitle="derby.storage.initialPages">
 </topicref>
 <topicref href="rrefproperstormin.dita" navtitle="derby.storage.minimumRecordSize">

Added: db/derby/docs/trunk/src/ref/rrefproperindexstatsauto.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefproperindexstatsauto.dita?rev=1307409&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefproperindexstatsauto.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefproperindexstatsauto.dita Fri Mar 30 13:38:20 2012
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "../dtd/reference.dtd">
+<reference xml:lang="en-us" id="rrefproperindexstatsauto">
+<title>derby.storage.indexStats.auto</title>
+<prolog><metadata>
+<keywords><indexterm>derby.storage.indexStats.auto</indexterm>
+<indexterm>databases<indexterm>configuring automatic updating of statistics</indexterm></indexterm>
+<indexterm>statistics<indexterm>configuring automatic updating</indexterm></indexterm>
+<indexterm>index statistics<indexterm>configuring automatic updating</indexterm></indexterm>
+</keywords>
+</metadata>
+</prolog>
+<refbody>
+<section><title>Function</title>
+<p>If this property is set to true (the default), outdated index cardinality
+statistics are updated automatically during query compilation. The query
+compiler schedules a job that updates the statistics in a separate thread.</p>
+<p>The thread that updates the statistics in the background may affect the
+performance of the user threads. If this causes problems, you can set
+<i>derby.storage.indexStats.auto</i> to false.</p>
+<p>To diagnose problems with automatic updating of index statistics, an
+application can set the property
+<i><xref href="rrefproperindexstatslog.dita#rrefproperindexstatslog"></xref></i>
+to true. The
+<i><xref href="rrefproperindexstatstrace.dita#rrefproperindexstatstrace"></xref></i>
+property can be used to provide more detailed information.</p>
+<p>For more information about index statistics, see "Working with cardinality
+statistics" in <ph conref="../conrefs.dita#pub/cittuning"></ph>.</p>
+</section>
+<section><title>Default</title>
+<p>True.</p>
+</section>
+<example><title>Example</title>
+<codeblock><b><ph>-- system-wide property</ph>
+derby.storage.indexStats.auto=false</b></codeblock>
+<codeblock><b><ph>-- database-level property</ph>
+CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY(
+    'derby.storage.indexStats.auto', 'false')</b></codeblock>
+</example>
+<section><title>Dynamic or static</title>
+<p>Static. For system-wide properties, you must reboot
+<ph conref="../conrefs.dita#prod/productshortname"></ph> for the change to take
+effect. For database-wide properties, you must reboot the database for the
+change to take effect.</p>
+</section>
+</refbody>
+</reference>

Propchange: db/derby/docs/trunk/src/ref/rrefproperindexstatsauto.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/ref/rrefproperindexstatslog.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefproperindexstatslog.dita?rev=1307409&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefproperindexstatslog.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefproperindexstatslog.dita Fri Mar 30 13:38:20 2012
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "../dtd/reference.dtd">
+<reference xml:lang="en-us" id="rrefproperindexstatslog">
+<title>derby.storage.indexStats.log</title>
+<prolog><metadata>
+<keywords><indexterm>derby.storage.indexStats.log</indexterm>
+<indexterm>databases<indexterm>logging automatic updating of statistics</indexterm></indexterm>
+<indexterm>statistics<indexterm>logging automatic updating</indexterm></indexterm>
+<indexterm>index statistics<indexterm>logging automatic updating</indexterm></indexterm>
+</keywords>
+</metadata>
+</prolog>
+<refbody>
+<section><title>Function</title>
+<p>If this property is set to true, the thread that updates index cardinality
+statistics during query compilation will write messages to the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> system log
+(<i>derby.log</i>) every time it performs a task. The log entries should help
+you to diagnose problems with the automatic updating of index statistics.</p>
+<p>The
+<i><xref href="rrefproperindexstatstrace.dita#rrefproperindexstatstrace"></xref></i>
+property can be used to provide more detailed information and to specify where
+the trace output should appear.</p>
+<p>To disable the automatic updating of index statistics, set the database
+property
+<i><xref href="rrefproperindexstatsauto.dita#rrefproperindexstatsauto"></xref></i>
+to false.</p>
+<p>For more information about index statistics, see "Working with cardinality
+statistics" in <ph conref="../conrefs.dita#pub/cittuning"></ph>.</p>
+</section>
+<section><title>Default</title>
+<p>False.</p>
+</section>
+<example><title>Example</title>
+<codeblock><b><ph>-- system-wide property</ph>
+derby.storage.indexStats.log=true</b></codeblock>
+<codeblock><b><ph>-- database-level property</ph>
+CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY(
+    'derby.storage.indexStats.log', 'true')</b></codeblock>
+</example>
+<section><title>Dynamic or static</title>
+<p>Static. For system-wide properties, you must reboot
+<ph conref="../conrefs.dita#prod/productshortname"></ph> for the change to take
+effect. For database-wide properties, you must reboot the database for the
+change to take effect.</p>
+</section>
+</refbody>
+</reference>

Propchange: db/derby/docs/trunk/src/ref/rrefproperindexstatslog.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Added: db/derby/docs/trunk/src/ref/rrefproperindexstatstrace.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefproperindexstatstrace.dita?rev=1307409&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefproperindexstatstrace.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefproperindexstatstrace.dita Fri Mar 30 13:38:20 2012
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at      
+
+http://www.apache.org/licenses/LICENSE-2.0  
+
+Unless required by applicable law or agreed to in writing, software  
+distributed under the License is distributed on an "AS IS" BASIS,  
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
+See the License for the specific language governing permissions and  
+limitations under the License.
+-->
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "../dtd/reference.dtd">
+<reference xml:lang="en-us" id="rrefproperindexstatstrace">
+<title>derby.storage.indexStats.trace</title>
+<prolog><metadata>
+<keywords><indexterm>derby.storage.indexStats.trace</indexterm>
+<indexterm>databases<indexterm>tracing automatic updating of statistics</indexterm></indexterm>
+<indexterm>statistics<indexterm>tracing automatic updating</indexterm></indexterm>
+<indexterm>index statistics<indexterm>tracing automatic updating</indexterm></indexterm>
+</keywords>
+</metadata>
+</prolog>
+<refbody>
+<section><title>Function</title>
+<p>This property allows you to enable more detailed logging of index cardinality
+statics than the
+<i><xref href="rrefproperindexstatslog.dita#rrefproperindexstatslog"></xref></i>
+property provides. It also allows you to specify where the tracing output should
+appear. Valid values are as follows:</p>
+<ul>
+<li><codeph>off</codeph>
+<p>Tracing is disabled (the default).</p>
+</li>
+<li><codeph>log</codeph>
+<p>Tracing output goes to the log file, <i>derby.log</i>.</p>
+</li>
+<li><codeph>stdout</codeph>
+<p>Tracing output goes to standard output.</p>
+</li>
+<li><codeph>both</codeph>
+<p>Tracing output goes to both <i>derby.log</i> and standard output.</p>
+</li>
+</ul>
+<p>For more information about index statistics, see "Working with cardinality
+statistics" in <ph conref="../conrefs.dita#pub/cittuning"></ph>.</p>
+</section>
+<refsyn><title>Syntax</title>
+<codeblock><b>derby.storage.indexStats.trace=
+    { off | log | stdout | both }</b></codeblock>
+</refsyn>
+<section><title>Default</title>
+<p><codeph>off</codeph>.</p>
+</section>
+<example><title>Example</title>
+<codeblock><b><ph>-- system-wide property</ph>
+derby.storage.indexStats.trace=log</b></codeblock>
+<codeblock><b><ph>-- database-level property</ph>
+CALL SYSCS_UTIL.SYSCS_SET_DATABASE_PROPERTY(
+    'derby.storage.indexStats.trace', 'stdout')</b></codeblock>
+</example>
+<section><title>Dynamic or static</title>
+<p>Static. For system-wide properties, you must reboot
+<ph conref="../conrefs.dita#prod/productshortname"></ph> for the change to take
+effect. For database-wide properties, you must reboot the database for the
+change to take effect.</p>
+</section>
+</refbody>
+</reference>

Propchange: db/derby/docs/trunk/src/ref/rrefproperindexstatstrace.dita
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: db/derby/docs/trunk/src/tuning/ctunstats57373.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunstats57373.dita?rev=1307409&r1=1307408&r2=1307409&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunstats57373.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunstats57373.dita Fri Mar 30 13:38:20 2012
@@ -34,6 +34,9 @@ are automatically created for only the n
 non-empty table. If there is no existing index that can be used for the new
 key or constraint, <ph conref="../conrefs.dita#prod/productshortname"></ph> automatically
 creates statistics for only the new indexes.</li>
+<li>During query compilation. If the index cardinality statistics for the tables
+involved in the query are deemed to be out of date, the query compiler will
+schedule a job that updates them in a separate thread.</li>
 <li>When you run the SYSCS_UTIL.SYSCS_COMPRESS_TABLE system procedure. Statistics
 are created automatically for all indexes if the statistics do not already
 exist.</li>
@@ -41,5 +44,20 @@ exist.</li>
 for the affected index are dropped. Statistics are automatically updated for
 the other indexes on the table.</li>
 </ul></p>
+<p>The thread that updates the statistics in the background during query
+compilation may affect the performance of the user threads. If this causes
+problems, you can disable automatic updating of statistics by setting the
+database property <i>derby.storage.indexStats.auto</i> to false.</p>
+<p>To diagnose problems with automatic updating of index statistics, an
+application can set the database property
+<i>derby.storage.indexStats.log</i> to true. When this property is set, the
+thread that updates the statistics will write messages to the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> system log
+(<i>derby.log</i>) every time it performs a task. You can obtain more detailed
+logging information by setting the property
+<i>derby.storage.indexStats.trace</i>, which also lets you specify where the
+trace output should appear.</p>
+<p>See the <ph conref="../conrefs.dita#pub/citref"></ph> for details about
these
+properties.</p>
 </conbody>
 </concept>



Mime
View raw message