db-derby-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chaa...@apache.org
Subject svn commit: r1609573 [1/2] - /db/derby/docs/trunk/src/tuning/
Date Thu, 10 Jul 2014 21:29:49 GMT
Author: chaase3
Date: Thu Jul 10 21:29:48 2014
New Revision: 1609573

URL: http://svn.apache.org/r1609573
Log:
DERBY-6379  Manuals are inconsistent in their use of the <shortdesc> element

Modified 52 Tuning Guide topics.

Patch: DERBY-6379-tun-opt-stats.diff

Modified:
    db/derby/docs/trunk/src/tuning/ctunoptimz1004264.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz1004373.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz1008884.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz1011736.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz11775.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz11941.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz12168.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz19357.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz20327.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz22111.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz22460.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz22900.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz23173.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz23977.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz24840.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz26019.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz27036.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz27975.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz29384.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz30217.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz30768.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz32184.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz32767.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz33368.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz39106.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz39739.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz41314.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz42065.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz42425.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz56859.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz856914.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz857385.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz859947.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz859974.dita
    db/derby/docs/trunk/src/tuning/ctunoptimz860097.dita
    db/derby/docs/trunk/src/tuning/ctunoptimzoverride.dita
    db/derby/docs/trunk/src/tuning/ctunperf98197.dita
    db/derby/docs/trunk/src/tuning/ctunstats18908.dita
    db/derby/docs/trunk/src/tuning/ctunstats46438.dita
    db/derby/docs/trunk/src/tuning/ctunstats52657.dita
    db/derby/docs/trunk/src/tuning/ctunstats57373.dita
    db/derby/docs/trunk/src/tuning/ctunstats57793.dita
    db/derby/docs/trunk/src/tuning/ctunstats60669.dita
    db/derby/docs/trunk/src/tuning/ctunstats72938.dita
    db/derby/docs/trunk/src/tuning/ctunstats848901.dita
    db/derby/docs/trunk/src/tuning/ctunstats848961.dita
    db/derby/docs/trunk/src/tuning/ctunstats849000.dita
    db/derby/docs/trunk/src/tuning/ctunstats849203.dita
    db/derby/docs/trunk/src/tuning/ctunstats849251.dita
    db/derby/docs/trunk/src/tuning/ctunstats849505.dita
    db/derby/docs/trunk/src/tuning/rtunoptimz1004602.dita
    db/derby/docs/trunk/src/tuning/rtunoptimz1004810.dita

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz1004264.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz1004264.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz1004264.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz1004264.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,8 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz1004264">
 <title>Indirectly optimizable predicates</title>
+<shortdesc>Some predicates are transformed internally into ones that provide
+starting and stopping points and are therefore optimizable.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Predicates<indexterm>indirectly optimizable</indexterm></indexterm>
@@ -26,14 +28,13 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Some predicates are transformed internally into ones that provide starting
-and stopping points and are therefore optimizable.</p>
 <p>Predicates that use the following comparison operators can be transformed
-internally into optimizable predicates:  
+internally into optimizable predicates:</p>
 <ul>
 <li>BETWEEN</li>
 <li>LIKE (in certain situations)</li>
 <li>IN (in certain situations)</li>
-</ul></p>
-<p>For details on these and other transformations, see <xref href="ctuntransform13966.dita#ctuntransform13966"/>.</p>
+</ul>
+<p>For details on these and other transformations, see
+<xref href="ctuntransform13966.dita"/>.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz1004373.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz1004373.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz1004373.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz1004373.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,7 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz1004373">
 <title>Joins</title>
+<shortdesc>Joins specified by the JOIN keyword are optimizable.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Joins<indexterm>optimizability of</indexterm></indexterm>
@@ -25,11 +26,11 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Joins specified by the JOIN keyword are optimizable. This means that <ph conref="../conrefs.dita#prod/productshortname"></ph> can
-use an index on the inner table of the join (start and stop conditions are
-being supplied implicitly by the rows in the outer table).</p>
-<p>Note that joins built using traditional predicates are also optimizable.
-For example, the following statement is optimizable:  
+<p>This means that <ph conref="../conrefs.dita#prod/productshortname"></ph> can
+use an index on the inner table of the join (start and stop conditions are being
+supplied implicitly by the rows in the outer table).</p>
+<p>Note that joins built using traditional predicates are also optimizable. For
+example, the following statement is optimizable:</p>
 <codeblock><b>SELECT * FROM Countries, Cities
-WHERE Countries.country_ISO_code = Cities.country_ISO_code</b></codeblock></p>
+WHERE Countries.country_ISO_code = Cities.country_ISO_code</b></codeblock>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz1008884.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz1008884.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz1008884.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz1008884.dita Thu Jul 10 21:29:48 2014
@@ -18,27 +18,25 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz1008884">
 <title>How the system makes its decision if it has a choice</title>
+<shortdesc>If the lock granularity (whether to lock rows or entire tables) is
+not forced by the user, the system makes a decision using the following
+rules.</shortdesc>
 <prolog>
 </prolog>
 <conbody>
-<p>If the lock granularity (whether to lock rows or entire tables) is not
-forced by the user, the system makes a decision using the following rules:
- 
 <ul>
-<li>For SELECT statements running in READ_COMMITTED isolation, the system
-always chooses row-level locking.</li>
-<li>If the statement scans the entire table or index and it does not meet
-the criteria above, the system chooses table-level locking. (A statement scans
-the entire table whenever it chooses a table as the access path.)</li>
+<li>For SELECT statements running in READ_COMMITTED isolation, the system always
+chooses row-level locking.</li>
+<li>If the statement scans the entire table or index and it does not meet the
+criteria above, the system chooses table-level locking. (A statement scans the
+entire table whenever it chooses a table as the access path.)</li>
 <li>If a statement partially scans the index, the system uses row-level locking,
 until the number of rows touched on a table reaches lock escalation threshold.
 It is then escalated to a table lock. (You can configure this threshold number;
-see <xref href="ctunoptimz26019.dita#ctunoptimz26019"/>.)  
-<ul>
-<li>For SELECT, UPDATE, and DELETE statements, the number of rows touched
-is different from the number of rows read. If the same row is read more than
-once, it is considered to have been touched only once. Each row in the inner
-table of a join can be read many times, but can be touched at most one time.</li>
-</ul></li>
-</ul></p>
+see <xref href="ctunoptimz26019.dita"/>.)  
+<p>For SELECT, UPDATE, and DELETE statements, the number of rows touched is
+different from the number of rows read. If the same row is read more than once,
+it is considered to have been touched only once. Each row in the inner table of
+a join can be read many times, but can be touched at most one time.</p></li>
+</ul>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz1011736.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz1011736.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz1011736.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz1011736.dita Thu Jul 10 21:29:48 2014
@@ -18,19 +18,20 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz1011736">
 <title>Quick DISTINCT scans</title>
+<shortdesc><ph conref="../conrefs.dita#prod/productshortname"></ph> can use a
+hash table instead of a sorter to eliminate duplicates when performing a
+DISTINCT in the following cases.</shortdesc>
 <prolog>
 </prolog>
 <conbody>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> can use a hash table instead of a sorter to eliminate duplicates
-when performing a DISTINCT in the following cases:  
 <ul>
-<li>There is a single table in the query block. </li>
-<li>An ORDER BY clause is not merged into the DISTINCT. </li>
-<li>All entries in the SELECT list are simple column references. </li>
-<li>There are no predicates in the query block. </li>
-</ul></p>
+<li>There is a single table in the query block.</li>
+<li>An ORDER BY clause is not merged into the DISTINCT.</li>
+<li>All entries in the SELECT list are simple column references.</li>
+<li>There are no predicates in the query block.</li>
+</ul>
 <p>This technique allows for minimal locking when performing the scan at the
-READ COMMITTED isolation level.   
-<note>This technique appears in
-RunTimeStatistics as a <i>DistinctScanResultSe</i>t.</note></p>
+READ COMMITTED isolation level.</p>   
+<p><note>This technique appears in RunTimeStatistics as a
+<i>DistinctScanResultSet</i>.</note></p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz11775.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz11775.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz11775.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz11775.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,8 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz11775">
 <title>Locking a table for the duration of a transaction</title>
+<shortdesc>You can explicitly lock a table for the duration of a transaction
+with the LOCK TABLE statement.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>LOCK TABLE statement</indexterm>
@@ -26,9 +28,8 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>In addition, you can explicitly lock a table for the duration of a transaction
-with the LOCK TABLE statement. This is useful if you know in advance that
-an entire table should be locked and want to save the resources required for
-obtaining row locks until the system escalates the locking. For information
-about this feature, see "LOCK TABLE statement" in the <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite>.</p>
+<p>This is useful if you know in advance that an entire table should be locked
+and you want to save the resources required for obtaining row locks until the
+system escalates the locking. For information about this feature, see
+"LOCK TABLE statement" in the <ph conref="../conrefs.dita#pub/citref"></ph>.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz11941.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz11941.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz11941.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz11941.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz11941">
 <title>About the optimizer's choice of join strategy</title>
+<shortdesc>The optimizer compares the cost of choosing a hash join (if a hash
+join is possible) to the cost of choosing a nested loop join and chooses the
+cheaper strategy.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Join strategies<indexterm>how optimizer chooses</indexterm></indexterm>
@@ -25,15 +28,14 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>The optimizer compares the cost of choosing a hash join (if a hash join
-is possible) to the cost of choosing a nested loop join and chooses the cheaper
-strategy. For information about when hash joins are possible, see <xref href="ctunoptimz23173.dita#ctunoptimz23173"/>.</p>
-<p>In some cases, the size of the hash table that <ph conref="../conrefs.dita#prod/productshortname"></ph> would have to
-build is prohibitive and can cause the JVM to run out of memory. For this
-reason, the optimizer has an upper limit on the size of a table on which it
-will consider a hash join. It will not consider a hash join for a statement
-if it estimates that the size of the hash table would exceed the system-wide
-limit of memory use for a table, the optimizer chooses a nested loop join
-instead. The optimizer's estimates of size of hash tables are approximate
-only.  </p>
+<p>For information about when hash joins are possible, see
+<xref href="ctunoptimz23173.dita"/>.</p>
+<p>In some cases, the size of the hash table that
+<ph conref="../conrefs.dita#prod/productshortname"></ph> would have to build is
+prohibitive and can cause the JVM to run out of memory. For this reason, the
+optimizer has an upper limit on the size of a table on which it will consider a
+hash join. It will not consider a hash join for a statement if it estimates that
+the size of the hash table would exceed the system-wide limit of memory use for
+a table; the optimizer chooses a nested loop join instead. The optimizer's
+estimates of size of hash tables are approximate only.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz12168.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz12168.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz12168.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz12168.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,11 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz12168">
 <title>Joins and performance</title>
+<shortdesc>Joins, SQL statements in which
+<ph conref="../conrefs.dita#prod/productshortname"></ph> selects data from two
+or more tables using one or more key columns from each table, can vary widely in
+performance. Factors that affect the performance of joins are join order,
+indexes, and join strategy.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Joins<indexterm>performance factors</indexterm></indexterm>
@@ -25,8 +30,4 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Joins, SQL statements in which <ph conref="../conrefs.dita#prod/productshortname"></ph> selects data from two
-or more tables using one or more key columns from each table, can vary widely
-in performance. Factors that affect the performance of joins are join order,
-indexes, and join strategy.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz19357.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz19357.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz19357.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz19357.dita Thu Jul 10 21:29:48 2014
@@ -18,36 +18,42 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz19357">
 <title>About the system's selection of lock granularity</title>
+<shortdesc>When a system is configured for row-level locking, it decides whether
+to use table-level locking or row-level locking for each table in each DML
+statement.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Lock granularity<indexterm>how optimizer chooses</indexterm></indexterm>
 <indexterm>Lock escalation<indexterm>chosen by optimizer</indexterm></indexterm>
-</keywords>
+<indexterm>Table-level locking<indexterm>forcing for a specific table at creation time</indexterm></indexterm></keywords>
 </metadata>
 </prolog>
 <conbody>
-<p>When a system is configured for row-level locking, it decides whether to
-use table-level locking or row-level locking for each table in each DML statement.
-The system bases this decision on the number of rows read or written for each
-table, and on whether a full conglomerate scan is done for each table.   
-<note>When you have turned off row-level locking for your system, <ph conref="../conrefs.dita#prod/productshortname"></ph> always
-uses table-level locking.</note></p>
+<p>The system bases this decision on the number of rows read or written for each
+table, and on whether a full conglomerate scan is done for each table.</p>   
+<p><note>When you have turned off row-level locking for your system,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> always uses table-level
+locking.</note></p>
 <p>The first goal of the system's decision is concurrency; wherever possible,
-the system chooses row-level locking. However, row-level locking uses a lot
-of resources and might have a negative impact on performance. Sometimes row-level
+the system chooses row-level locking. However, row-level locking uses a lot of
+resources and might have a negative impact on performance. Sometimes row-level
 locking does not provide much more concurrency than table-level locking. In
 those situations, the system might choose to escalate the locking scheme from
-row-level locking to table-level locking to improve performance. For example,
-if a connection is configured for TRANSACTION_SERIALIZABLE isolation, the
-system chooses table-level locking for the following statement:  
+row-level locking to table-level locking to improve performance. For example, if
+a connection is configured for TRANSACTION_SERIALIZABLE isolation, the system
+chooses table-level locking for the following statement:</p>
 <codeblock><b>SELECT *
 FROM FlightAvailability AS fa, Flights AS fts
 WHERE fts.flight_id = fa.flight_id
-AND fts.segment_number = fa.segment_number</b></codeblock></p>
-<p>To satisfy the isolation requirements, <ph conref="../conrefs.dita#prod/productshortname"></ph> would have to lock all
-the rows in both the<i> FlightAvailability</i> and the <i>Flights</i> tables. Locking both the tables would be cheaper,
-would provide the same isolation, and would allow the same concurrency.  
-<note>You can force lock escalation for specific tables when you alter
-them with the LOCKSIZE clause. For these tables, <ph conref="../conrefs.dita#prod/productshortname"></ph> always chooses
-table-level locking. For more information, see the <cite><ph conref="../conrefs.dita#pub/citref"></ph></cite>.</note><indexterm>Table-level locking<indexterm>forcing for a specific table at creation time</indexterm></indexterm></p>
+AND fts.segment_number = fa.segment_number</b></codeblock>
+<p>To satisfy the isolation requirements,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> would have to lock all
+the rows in both the <codeph>FlightAvailability</codeph> and the
+<codeph>Flights</codeph> tables. Locking both the tables would be cheaper, would
+provide the same isolation, and would allow the same concurrency.</p>
+<p><note>You can force lock escalation for specific tables when you alter them
+with the LOCKSIZE clause. For these tables,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> always chooses
+table-level locking. For more information, see the
+<ph conref="../conrefs.dita#pub/citref"></ph>.</note></p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz20327.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz20327.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz20327.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz20327.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,8 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz20327">
 <title>About the optimizer's choice of join order</title>
+<shortdesc>The optimizer chooses the optimal join order as well as the optimal
+index for each table.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Join order<indexterm>how optimizer chooses</indexterm></indexterm>
@@ -25,17 +27,16 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>The optimizer chooses the optimal join order as well as the optimal index
-for each table. The join order can affect which index is the best choice.
-The optimizer can choose an index as the access path for a table if it is
-the inner table, but not if it is the outer table (and there are no further
-qualifications).</p>
+<p>The join order can affect which index is the best choice. The optimizer can
+choose an index as the access path for a table if it is the inner table, but not
+if it is the outer table (and there are no further qualifications).</p>
 <p>The optimizer chooses the join order of tables only in simple FROM clauses.
 Most joins using the JOIN keyword are flattened into simple joins, so the
 optimizer chooses their join order.</p>
 <p>The optimizer does not choose the join order for outer joins; it uses the
 order specified in the statement.</p>
-<p>When selecting a join order, the optimizer takes into account:  
+<p>When selecting a join order, the optimizer takes the following into
+account:</p>
 <ul>
 <li>The size of each table</li>
 <li>The indexes available on each table</li>
@@ -43,6 +44,7 @@ order specified in the statement.</p>
 <li>The number of rows and pages to be scanned for each table in each join
 order</li>
 </ul>
-<note><ph conref="../conrefs.dita#prod/productshortname"></ph> does transitive closure on qualifications.
-For details, see <xref href="ctuntransform37032.dita#ctuntransform37032"/>.</note></p>
+<p><note><ph conref="../conrefs.dita#prod/productshortname"></ph> does
+transitive closure on qualifications. For details, see
+<xref href="ctuntransform37032.dita"/>.</note></p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz22111.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz22111.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz22111.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz22111.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz22111">
 <title>The MIN() and MAX() optimizations</title>
+<shortdesc>The optimizer knows that it can avoid iterating through all the
+source rows in a result to compute a MIN() or MAX() aggregate when data are
+already in the right order.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>MIN() optimization</indexterm>
@@ -26,29 +29,28 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>The optimizer knows that it can avoid iterating through all the source
-rows in a result to compute a MIN() or MAX() aggregate when data are already
-in the right order. When data are guaranteed to be in the right order, <ph conref="../conrefs.dita#prod/productshortname"></ph> can
-go immediately to the smallest (minimum) or largest (maximum) row.</p>
-<p>The following conditions must be true:  
+<p>When data are guaranteed to be in the right order,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> can go immediately to
+the smallest (minimum) or largest (maximum) row.</p>
+<p>The following conditions must be true:</p>
 <ul>
 <li>The MIN() or MAX() is the only entry in the SELECT list.</li>
-<li>The MIN() or MAX() is on a simple column reference, not on an expression.</li>
+<li>The MIN() or MAX() is on a simple column reference, not on an
+expression.</li>
 <li>For MAX(), there must not be a WHERE clause.</li>
 <li>For MIN():  
 <ul>
-<li>The referenced table is the outermost table in the optimizer's chosen
-join order for the query block.</li>
+<li>The referenced table is the outermost table in the optimizer's chosen join
+order for the query block.</li>
 <li>The optimizer chose an index containing the referenced column as the access
 path.</li>
-<li>The referenced column is the first key column in that index OR the referenced
-column is a key column in that index and equality predicates exist on all
-key columns prior to the simple column reference in that index.</li>
+<li>The referenced column is the first key column in that index OR the
+referenced column is a key column in that index and equality predicates exist on
+all key columns prior to the simple column reference in that index.</li>
 </ul></li>
-</ul></p>
+</ul>
 <p>For example, the optimizer can use this optimization for the following
-queries (if the optimizer uses the appropriate indexes as the access paths):
- 
+queries (if the optimizer uses the appropriate indexes as the access paths):</p>
 <codeblock><b><ph>-- index on orig_airport</ph>
 SELECT MIN(orig_airport)
 FROM Flights
@@ -68,7 +70,7 @@ SELECT * 
 FROM Flights 
 WHERE segment_number = (SELECT MIN(segment_number) 
 FROM Flights 
-WHERE flight_id = 'AA1111')</b></codeblock></p>
+WHERE flight_id = 'AA1111')</b></codeblock>
 <p>The optimizer decides whether to implement the optimization after choosing
 the plan for the query. The optimizer does not take this optimization into
 account when costing the plan.</p>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz22460.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz22460.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz22460.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz22460.dita Thu Jul 10 21:29:48 2014
@@ -18,21 +18,26 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz22460">
 <title>Non-cost-based sort avoidance (tuple filtering)</title>
+<shortdesc>In most cases,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> needs to perform two
+separate steps for statements that use DISTINCT or GROUP BY: first sorting the
+selected columns, then either discarding duplicate rows or aggregating grouped
+rows. Sometimes it is able to avoid sorting for these statements with tuple
+filtering.</shortdesc>
 <prolog>
 </prolog>
 <conbody>
-<p>In most cases, <ph conref="../conrefs.dita#prod/productshortname"></ph> needs to perform two separate steps for statements
-that use DISTINCT or GROUP BY: first sorting the selected columns, then either
-discarding duplicate rows or aggregating grouped rows. Sometimes it is able
-to avoid sorting for these statements with tuple filtering. <i>Tuple filtering</i> means that the rows are <i>already</i> in
-a useful order. For DISTINCT, <ph conref="../conrefs.dita#prod/productshortname"></ph> can simply filter out duplicate
-values when they are found and return results to the user sooner. For GROUP
-BY, <ph conref="../conrefs.dita#prod/productshortname"></ph> can aggregate a group of rows until a new set of rows is detected
-and return results to the user sooner.</p>
+<p><i>Tuple filtering</i> means that the rows are <i>already</i> in a useful
+order. For DISTINCT, <ph conref="../conrefs.dita#prod/productshortname"></ph>
+can simply filter out duplicate values when they are found and return results to
+the user sooner. For GROUP BY,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> can aggregate a group
+of rows until a new set of rows is detected and return results to the user
+sooner.</p>
 <p>These are non-cost-based optimizations; the optimizer does not yet consider
 the cost of these optimizations.</p>
-<p>The examples in this section refer to the following tables:  
+<p>The examples in this section refer to the following tables: </p> 
 <codeblock><b>CREATE TABLE t1(c1 INT, c2 INT, c3 INT, c4 INT)
 CREATE INDEX i1 ON t1(c1)
-CREATE INDEX i1_2_3_4 ON t1(c1, c2, c3, c4)</b></codeblock></p>
+CREATE INDEX i1_2_3_4 ON t1(c1, c2, c3, c4)</b></codeblock>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz22900.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz22900.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz22900.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz22900.dita Thu Jul 10 21:29:48 2014
@@ -17,27 +17,30 @@ limitations under the License.
 -->
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz22900">
-<title>When a table scan Is better</title>
+<title>When a table scan is better</title>
+<shortdesc>Sometimes a table scan is the most efficient way to access data, even
+if a potentially useful index is available.</shortdesc>
 <prolog>
 </prolog>
 <conbody>
-<p>Sometimes a table scan is the most efficient way to access data, even if
-a potentially useful index is available. For example, if the statement returns
-virtually all the data in the table, it is more efficient to go straight to
-the table instead of looking values up in an index, because then <ph conref="../conrefs.dita#prod/productshortname"></ph> is
-able to avoid the intermediate step of retrieving the rows from the index
-lookup values.</p>
-<p>For example:  
+<p>For example, if the statement returns virtually all the data in the table, it
+is more efficient to go straight to the table instead of looking values up in an
+index, because then <ph conref="../conrefs.dita#prod/productshortname"></ph> is
+able to avoid the intermediate step of retrieving the rows from the index lookup
+values.</p>
+<p>For example:</p>
 <codeblock><b>SELECT *
 FROM Flights
-WHERE dest_airport &lt; 'Z'</b></codeblock></p>
-<p>In the <i>Flights </i>table, most of the airport codes
-begin with letters that are less than <i>Z</i>. Depending
-on the number of rows in the table, it is probably more efficient for <ph conref="../conrefs.dita#prod/productshortname"></ph> to
-go straight to the table to retrieve the appropriate rows. However, for the
-following query, <ph conref="../conrefs.dita#prod/productshortname"></ph> uses the index:  
+WHERE dest_airport &lt; 'Z'</b></codeblock>
+<p>In the <codeph>Flights</codeph> table, most of the airport codes begin with
+letters that are less than 'Z'. Depending on the number of rows in the table, it
+is probably more efficient for
+<ph conref="../conrefs.dita#prod/productshortname"></ph> to go straight to the
+table to retrieve the appropriate rows. However, for the following query,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> uses the index:</p>
 <codeblock><b>SELECT *
 FROM Flights
-WHERE dest_airport &lt; 'B'</b></codeblock></p>
-<p>Only a few flights have airport codes that begin with a letter less than <i>B</i>.</p>
+WHERE dest_airport &lt; 'B'</b></codeblock>
+<p>Only a few flights have airport codes that begin with a letter less than
+'B'.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz23173.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz23173.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz23173.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz23173.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,12 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz23173">
 <title>Join strategies</title>
+<shortdesc>The most common join strategy in
+<ph conref="../conrefs.dita#prod/productshortname"></ph> is called a
+<i>nested loop</i>. For each qualifying row in the outer table,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> uses the appropriate
+access path (index or table) to find the matching rows in the inner
+table.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Join strategies</indexterm>
@@ -31,33 +37,35 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>The most common join strategy in <ph conref="../conrefs.dita#prod/productshortname"></ph> is called a <i>nested loop</i>. For each qualifying row in the outer table, <ph conref="../conrefs.dita#prod/productshortname"></ph> uses
-the appropriate access path (index or table) to find the matching rows in
-the inner table.</p>
-<p>Another type of join in <ph conref="../conrefs.dita#prod/productshortname"></ph> is called a <i>hash</i> join. For joins of this type, <ph conref="../conrefs.dita#prod/productshortname"></ph> constructs a hash table representing
-all the selected columns of the inner table. For each qualifying row in the
-outer table, <ph conref="../conrefs.dita#prod/productshortname"></ph> does a quick lookup on the hash table to get the
-inner table data. <ph conref="../conrefs.dita#prod/productshortname"></ph> has to scan the inner table or index only once,
-to build the hash table.</p>
+<p>Another type of join in
+<ph conref="../conrefs.dita#prod/productshortname"></ph> is called a <i>hash</i>
+join. For joins of this type,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> constructs a hash table
+representing all the selected columns of the inner table. For each qualifying
+row in the outer table, <ph conref="../conrefs.dita#prod/productshortname"></ph>
+does a quick lookup on the hash table to get the inner table data.
+<ph conref="../conrefs.dita#prod/productshortname"></ph> has to scan the inner
+table or index only once, to build the hash table.</p>
 <p>Nested loop joins are preferable in most situations.</p>
-<p>Hash joins are preferable in situations in which the inner table values
-are unique and there are many qualifying rows in the outer table. Hash joins
-require that the statement's WHERE clause be an optimizable equijoin:
- 
+<p>Hash joins are preferable in situations in which the inner table values are
+unique and there are many qualifying rows in the outer table. Hash joins require
+that the statement's WHERE clause be an optimizable equijoin:</p>
 <ul>
-<li>It must use the = operator to compare column(s) in the outer table to
-column(s) in the inner table.</li>
+<li>It must use the <codeph>=</codeph> operator to compare column(s) in the
+outer table to column(s) in the inner table.</li>
 <li>References to columns in the inner table must be simple column references.
-Simple column references are described in <xref href="ctunoptimz24840.dita#ctunoptimz24840"/>.</li>
-</ul></p>
-<p>The hash table for a hash join is held in memory and if it gets big enough,
-it will spill to the disk. The optimizer makes a very rough
-estimate of the amount of memory required to make the hash table. If it estimates
-that the amount of memory required would exceed the system-wide limit of memory
-use for a table, the optimizer chooses a nested loop join instead. </p>
-<p>If memory use is not a problem for your environment, set this property
-to a high number; allowing the optimizer the maximum flexibility in considering
-a join strategy queries involving large queries leads to better performance.
-It can also be set to smaller values for more limited environments.  
-<note><ph conref="../conrefs.dita#prod/productshortname"></ph> allows multiple columns as hash keys.</note></p>
+Simple column references are described in
+<xref href="ctunoptimz24840.dita"/>.</li>
+</ul>
+<p>The hash table for a hash join is held in memory, and if it gets big enough,
+it will spill to the disk. The optimizer makes a very rough estimate of the
+amount of memory required to make the hash table. If it estimates that the
+amount of memory required would exceed the system-wide limit of memory use for a
+table, the optimizer chooses a nested loop join instead.</p>
+<p>If memory use is not a problem for your environment, set this property to a
+high number; allowing the optimizer the maximum flexibility in considering a
+join strategy queries involving large queries leads to better performance. It
+can also be set to smaller values for more limited environments.</p>
+<p><note><ph conref="../conrefs.dita#prod/productshortname"></ph> allows
+multiple columns as hash keys.</note></p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz23977.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz23977.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz23977.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz23977.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,8 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz23977">
 <title>Performance and optimization</title>
+<shortdesc><i>Optimization</i> means that a DBMS makes the best (optimal) choice
+of access paths, join order, and join strategy.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Optimization</indexterm>
@@ -28,20 +30,21 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>A DBMS often has a choice about the access path for retrieving data. For
-example, the DBMS can use an index (fast lookup for specific entries) or scan
-the entire table to retrieve the appropriate rows. In addition, in statements
-in which two tables are joined, the DBMS can choose which table to examine
-first (join order) and how to join the tables (join strategy). <i>Optimization</i> means that DBMS makes the best (optimal) choice of access
-paths, join order, and join strategy. True query optimization means that the
-DBMS will usually make a good choice regardless of how the query is written.
-The optimizer does not necessarily make the <i>best</i> choice,
-just a good one.</p>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> can use indexes to improve the performance of DML (data manipulation
-language) statements such as queries, updates, and deletes. The query optimizer
-can make decisions about whether to use an index for a particular table (access
-path) and also makes decisions about join order, type of join, and a few other
-matters.</p>
-<p>This section gives an overview of the <ph conref="../conrefs.dita#prod/productshortname"></ph> optimizer and discusses
+<p>A DBMS often has a choice about the <i>access path</i> for retrieving data.
+For example, the DBMS can use an index (fast lookup for specific entries) or
+scan the entire table to retrieve the appropriate rows. In addition, in
+statements in which two tables are joined, the DBMS can choose which table to
+examine first (<i>join order</i>) and how to join the tables (<i>join
+strategy</i>).</p>
+<p>True query optimization means that the DBMS will usually make a good choice
+regardless of how the query is written. The optimizer does not necessarily make
+the <i>best</i> choice, just a good one.</p>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> can use indexes to
+improve the performance of DML (data manipulation language) statements such as
+queries, updates, and deletes. The query optimizer can make decisions about
+whether to use an index for a particular table (access path) and also makes
+decisions about join order, type of join, and a few other matters.</p>
+<p>This section gives an overview of the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> optimizer and discusses
 performance issues in the execution of DML statements.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz24840.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz24840.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz24840.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz24840.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz24840">
 <title>Directly optimizable predicates</title>
+<shortdesc>Some predicates provide clear-cut starting and stopping
+points. A predicate provides start or stop conditions, and is therefore
+optimizable, when at least one of the following conditions is met.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Predicates<indexterm>directly optimizable</indexterm></indexterm>
@@ -29,36 +32,37 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Some predicates provide clear-cut starting and stopping points. A predicate
-provides start or stop conditions, and is therefore optimizable, when:  
 <ul>
-<li>It uses a simple column reference to a column (the name of the column,
-not the name of the column within an expression or method call). For example,
-the following is a simple column reference:  
+<li>It uses a simple column reference to a column (the name of the column, not
+the name of the column within an expression or method call). For example, the
+following is a simple column reference:  
 <codeblock><b>WHERE orig_airport = 'SFO'</b></codeblock>
-<p>The following is not:  
-<codeblock><b>WHERE lower(orig_airport) = 'sfo'</b></codeblock></p></li>
-<li>It refers to a column that is the first or only column in the index.  
-<p>References to <i>contiguous</i> columns in other predicates
-in the statement when there is a multi-column index can further define the
-starting or stopping points. (If the columns are not contiguous with the first
-column, they are not optimizable predicates but can be used as <i>qualifiers</i>.) For example, given a composite index on <i>FlightAvailability</i> (<i>flight_id</i>, <i>segment_number,</i> and <i>flight_date</i>), the following
-predicate satisfies that condition:</p>
+<p>The following is not:</p>
+<codeblock><b>WHERE lower(orig_airport) = 'sfo'</b></codeblock></li>
+<li>It refers to a column that is the first or only column in the index.
+<p>References to <i>contiguous</i> columns in other predicates in the statement
+when there is a multi-column index can further define the starting or stopping
+points. (If the columns are not contiguous with the first column, they are not
+optimizable predicates but can be used as <i>qualifiers</i>.) For example, given
+a composite index on <codeph>FlightAvailability</codeph>
+(<codeph>flight_id</codeph>, <codeph>segment_number,</codeph> and
+<codeph>flight_date</codeph>), the following predicate satisfies that
+condition:</p>
 <codeblock><b>WHERE flight_id = 'AA1200' AND segment_number = 2</b></codeblock>
-<p>The following
-one does not:  
-<codeblock><b>WHERE flight_id = 'AA1200' AND flight_date = CURRENT_DATE</b></codeblock></p></li>
-<li>The column is compared to a <i>constant</i> or to an
-expression that does not include columns in the same table. Examples of valid
-expressions: <i>other_table.column_a</i>, <i>?</i> (dynamic parameter), <i>7+9</i>. The comparison
-must use the following operators:  
-<ul>
-<li>=</li>
-<li>&lt;</li>
-<li>&lt;=</li>
-<li>&gt;</li>
-<li>&gt;=</li>
+<p>The following one does not:</p>
+<codeblock><b>WHERE flight_id = 'AA1200' AND flight_date = CURRENT_DATE</b></codeblock></li>
+<li>The column is compared to a <i>constant</i> or to an expression that does
+not include columns in the same table. Examples of valid expressions are as
+follows: <codeph>other_table.column_a</codeph>, <codeph>?</codeph> (dynamic
+parameter), <codeph>7+9</codeph>. The comparison must use one of the following
+operators:  
+<p><ul>
+<li><codeph>=</codeph></li>
+<li><codeph>&lt;</codeph></li>
+<li><codeph>&lt;=</codeph></li>
+<li><codeph>&gt;</codeph></li>
+<li><codeph>&gt;=</codeph></li>
 <li>IS NULL</li>
-</ul></li>
-</ul></p>
+</ul></p></li>
+</ul>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz26019.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz26019.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz26019.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz26019.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz26019">
 <title>Lock escalation threshold</title>
+<shortdesc>The system property <i>derby.locks.escalationThreshold</i> determines
+the threshold for number of rows touched for a particular table above which the
+system will escalate to table-level locking.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Lock escalation<indexterm>threshold</indexterm></indexterm>
@@ -26,15 +29,13 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>The system property <i>derby.locks.escalationThreshold</i> determines
-the threshold for number of rows touched for a particular table above which
-the system will escalate to table-level locking. The default value of this
-property is 5000. For large systems, set this property to a higher value.
-For smaller systems, lower it. See the
+<p>The default value of this property is 5000. For large systems, set this
+property to a higher value. For smaller systems, lower it. See the
 "<ph conref="../conrefs.dita#prod/productshortname"></ph> properties" section of
-the <ph conref="../conrefs.dita#pub/citref"></ph> for details on this property.</p>
+the <ph conref="../conrefs.dita#pub/citref"></ph> for details on this
+property.</p>
 <p>This property also sets the threshold for transaction-based lock escalation
-(see <xref href="ctunoptimz42065.dita#ctunoptimz42065"/>).  
-<note>For more
-information about lock escalation, see <xref href="ctunoptimz27975.dita#ctunoptimz27975"/>.</note></p>
+(see <xref href="ctunoptimz42065.dita"/>).</p>
+<p><note>For more information about lock escalation, see
+<xref href="ctunoptimz27975.dita"/>.</note></p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz27036.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz27036.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz27036.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz27036.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz27036">
 <title>About the optimizer's choice of sort avoidance</title>
+<shortdesc>Some SQL statements require that data be ordered, including those
+with ORDER BY, GROUP BY, and DISTINCT. MIN() and MAX() aggregates also require
+ordering of data.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Sort avoidance</indexterm>
@@ -25,20 +28,18 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Some SQL statements require that data be ordered, including those with
-ORDER BY, GROUP BY, and DISTINCT. MIN() and MAX() aggregates also require
-ordering of data.</p>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> can sometimes avoid sorting steps for:  
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> can sometimes avoid
+sorting steps for:</p>
 <ul>
-<li>statements with ORDER BY  
-<p>See <xref href="ctunoptimz56859.dita#ctunoptimz56859"/></p></li>
-</ul></p>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> can also perform the following optimizations, but they are
-not based on cost:  
+<li>Statements with ORDER BY  
+<p>See <xref href="ctunoptimz56859.dita"/>.</p></li>
+</ul>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> can also perform the
+following optimizations, but they are not based on cost:</p>
 <ul>
-<li>sort avoidance for DISTINCT and GROUP BYs  
-<p>See <xref href="ctunoptimz22460.dita#ctunoptimz22460"/></p></li>
-<li>statements with a MIN() aggregate  
-<p>See <xref href="ctunoptimz22111.dita#ctunoptimz22111"/></p></li>
-</ul></p>
+<li>Sort avoidance for DISTINCT and GROUP BYs  
+<p>See <xref href="ctunoptimz22460.dita"/>.</p></li>
+<li>Statements with a MIN() aggregate  
+<p>See <xref href="ctunoptimz22111.dita"/>.</p></li>
+</ul>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz27975.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz27975.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz27975.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz27975.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,8 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz27975">
 <title>Locking and performance</title>
+<shortdesc>Row-level locking improves concurrency in a multi-user system.
+However, a large number of row locks can degrade performance.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Locking<indexterm>performance implications of</indexterm></indexterm>
@@ -25,10 +27,9 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Row-level locking improves concurrency in a multi-user system. However,
-a large number of row locks can degrade performance. <xref href="ctunoptimz19357.dita#ctunoptimz19357"/> discussed the way the optimizer makes some compile-time decisions
-about escalating row locks to table locks for performance reasons. This section
-discusses ways in which the <ph conref="../conrefs.dita#prod/productshortname"></ph> system and the user can make similar
-lock escalations.  
-</p>
+<p><xref href="ctunoptimz19357.dita"/> discussed the way the optimizer makes
+some compile-time decisions about escalating row locks to table locks for
+performance reasons. This section discusses ways in which the
+<ph conref="../conrefs.dita#prod/productshortname"></ph> system and the user can
+make similar lock escalations.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz29384.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz29384.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz29384.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz29384.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz29384">
 <title>About the optimizer's selection of bulk fetch</title>
+<shortdesc>When <ph conref="../conrefs.dita#prod/productshortname"></ph>
+retrieves data from a conglomerate, it can fetch more than one row at a time.
+Fetching more than one row at a time is called <i>bulk fetch</i>.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Bulk fetch<indexterm>how optimizer chooses</indexterm></indexterm>
@@ -25,21 +28,21 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>When <ph conref="../conrefs.dita#prod/productshortname"></ph> retrieves data from a conglomerate, it can fetch more
-than one row at a time. Fetching more than one row at a time is called bulk
-fetch. By default, <ph conref="../conrefs.dita#prod/productshortname"></ph> fetches 16 rows at a time.</p>
-<p>Bulk fetch is faster than retrieving one row at a time when a large number
-of rows qualify for each scan of the table or index. Bulk fetch uses extra
-memory to hold the pre-fetched rows, so it should be avoided in situations
-in which memory is scarce.</p>
-<p>Bulk fetch is automatically turned off for updatable cursors, for hash
-joins, for statements in which the scan returns a single row, and for subqueries.
-It is useful, however, for table scans or index range scans:  
+<p>By default, <ph conref="../conrefs.dita#prod/productshortname"></ph> fetches
+16 rows at a time.</p>
+<p>Bulk fetch is faster than retrieving one row at a time when a large number of
+rows qualify for each scan of the table or index. Bulk fetch uses extra memory
+to hold the pre-fetched rows, so it should be avoided in situations in which
+memory is scarce.</p>
+<p>Bulk fetch is automatically turned off for updatable cursors, for hash joins,
+for statements in which the scan returns a single row, and for subqueries. It is
+useful, however, for table scans or index range scans:</p>
 <codeblock><b>SELECT *
 FROM Flights
 WHERE miles &gt; 4
 
 SELECT *
-FROM Flights</b></codeblock></p>
-<p>The default size for bulk fetch (16 rows) typically provides good performance.</p>
+FROM Flights</b></codeblock>
+<p>The default size for bulk fetch (16 rows) typically provides good
+performance.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz30217.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz30217.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz30217.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz30217.dita Thu Jul 10 21:29:48 2014
@@ -18,13 +18,16 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz30217">
 <title>Index use and access paths</title>
+<shortdesc>If you define an index on a column or columns, the query optimizer
+can use the index to find data in the column more quickly.</shortdesc>
 <prolog>
 </prolog>
 <conbody>
-<p>If you define an index on a column or columns, the query optimizer can
-use the index to find data in the column more quickly. <ph conref="../conrefs.dita#prod/productshortname"></ph> automatically
-creates indexes to back up primary key, foreign key, and unique constraints,
-so those indexes are always available to the optimizer, as well as those that
-you explicitly create with the CREATE INDEX command. The way <ph conref="../conrefs.dita#prod/productshortname"></ph> gets
-to the data-via an index or directly via the table-is called the <i>access path</i>.</p>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> automatically
+creates indexes to back up primary key, foreign key, and unique constraints, so
+those indexes are always available to the optimizer, as well as those that you
+explicitly create with the CREATE INDEX command. The way
+<ph conref="../conrefs.dita#prod/productshortname"></ph> gets to the data --
+through an index or directly through the table -- is called the
+<i>access path</i>.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz30768.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz30768.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz30768.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz30768.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,10 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz30768">
 <title>Covering indexes</title>
+<shortdesc>Even when there is no definite starting or stopping point for an
+index scan, an index can speed up the execution of a query if the index covers
+the query. An index <i>covers the query</i> if all the columns specified in the
+query are part of the index.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Covering indexes</indexterm>
@@ -25,21 +29,20 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Even when there is no definite starting or stopping point for an index
-scan, an index can speed up the execution of a query if the index covers the
-query. An index <i>covers the query</i> if all the columns
-specified in the query are part of the index. These are the columns that are
-all columns referenced in the query, not just columns in a WHERE clause. If
-so, <ph conref="../conrefs.dita#prod/productshortname"></ph> never has to go to the data pages at all, but can retrieve
-all data through index access alone. For example, in the following queries, <i>OrigIndex</i> covers the query:  
+<p>These are the columns that are all columns referenced in the query, not just
+columns in a WHERE clause. If so,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> never has to go to the
+data pages at all, but can retrieve all data through index access alone. For
+example, in the following queries, <codeph>OrigIndex</codeph> covers the
+query:</p>  
 <codeblock><b>SELECT orig_airport
 FROM Flights
 
 SELECT DISTINCT lower(orig_airport) FROM Flights 
-FROM Flights</b></codeblock></p>
-<p><ph conref="../conrefs.dita#prod/productshortname"></ph> can get all required data out of the index instead of from
-the table.</p>
-<note>If the query produces an updatable result set, 
-<ph conref="../conrefs.dita#prod/productshortname"></ph> will retrieve all 
-data from the data pages even if there is an index that covers the query.</note>
+FROM Flights</b></codeblock>
+<p><ph conref="../conrefs.dita#prod/productshortname"></ph> can get all required
+data out of the index instead of from the table.</p>
+<p><note>If the query produces an updatable result set,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> will retrieve all data
+from the data pages even if there is an index that covers the query.</note></p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz32184.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz32184.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz32184.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz32184.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz32184">
 <title>About the optimizer's choice of access path</title>
+<shortdesc>The optimizer's choice of access path can depend on the number of
+rows it will have to read. It tries to choose a path that requires the fewest
+number of rows read. </shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Access path<indexterm>how optimizer chooses</indexterm></indexterm>
@@ -26,11 +29,9 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>The optimizer's choice of access path can depend on the number of rows
-it will have to read. It tries to choose a path that requires the fewest number
-of rows read. For joins, the number of rows read also depends heavily on the
-join order (discussed in <xref href="ctunoptimz20327.dita#ctunoptimz20327"/>.)</p>
-<p>How does the optimizer know how many rows a particular access path will
-read? The answer: sometimes it knows exactly, and sometimes it has to make
-an educated guess. See <xref href="ctunstats18908.dita#ctunstats18908"/>.</p>
+<p>For joins, the number of rows read also depends heavily on the join order
+(discussed in <xref href="ctunoptimz20327.dita"/>.)</p>
+<p>How does the optimizer know how many rows a particular access path will read?
+Sometimes it knows exactly, and sometimes it has to make an educated guess. See
+<xref href="ctunstats18908.dita"/>.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz32767.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz32767.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz32767.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz32767.dita Thu Jul 10 21:29:48 2014
@@ -18,42 +18,59 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz32767">
 <title>Join order case study</title>
+<shortdesc>As an example of how the optimizer chooses a join order, consider the
+following situation.</shortdesc>
 <prolog>
 </prolog>
 <conbody>
-<p>For example, consider the following situation:</p>
-<p>The <i>Flights</i> table (as you know) stores information
-about flight segments. It has a primary key on the <i>flight_id</i> and <i>segment_number </i>columns. This primary key
-constraint is backed up by a unique index on those columns.</p>
-<p>The <i>FlightAvailability</i> table, which stores information
-about the availability of flight segments on particular days, can store several
-rows for a particular row in the <i>Flights</i> table (one
-for each date).</p>
-<p>You want to see information about all the flights, and you issue the following
-query:  
+<p>The <codeph>Flights</codeph> table (as you know) stores information about
+flight segments. It has a primary key on the <codeph>flight_id</codeph> and
+<codeph>segment_number</codeph> columns. This primary key constraint is backed
+up by a unique index on those columns.</p>
+<p>The <codeph>FlightAvailability</codeph> table, which stores information about
+the availability of flight segments on particular days, can store several rows
+for a particular row in the <codeph>Flights</codeph> table (one for each
+date).</p>
+<p>You want to see information about all the flights, and you issue the
+following query:</p>
 <codeblock><b>SELECT *
 FROM FlightAvailability AS fa, Flights AS fts
 WHERE fa.flight_id = fts.flight_id
-AND fa.segment_number = fts.segment_number</b></codeblock></p>
-<p>First imagine the situation in which there are no useful indexes on the <i>FlightAvailability</i> table.</p>
-<p>Using the join order with <i>FlightAvailability</i> as
-the outer table and <i>Flights</i> as the inner table is
-cheaper because it allows the <i>flight_id</i>/<i>segment_number</i> columns from <i>FlightAvailability</i> to
-be used to probe into and find matching rows in <i>Flights,</i> using the primary key index on <i>Flights.flight_id</i> and <i>Flights.segment_number</i>.</p>
-<p>This is preferable to the opposite join order (with <i>Flights</i> as the outer table and <i>FlightAvailability</i> as the inner table) because in that case, for each row in <i>Flights,</i> the system would have to scan the entire <i>FlightAvailability</i> table to find the matching rows (because there is
-no useful index- an index on the <i>flight_id</i>/<i>segment_number</i> columns).</p>
-<p>Second, imagine the situation in which there is a useful index on the <i>FlightAvailability</i> table (this is actually the case in
-the sample database). <i>FlightAvailability</i> has a primary
-key index on <i>flight_id</i>, <i>segment_number</i>, and <i>booking_date</i>. In that index, the <i>flight_id</i>-<i>segment_number</i> combination is not unique,
-since there is a one-to-many correspondence between the <i>Flights</i> table and the <i>FlightAvailability</i> table.
-However, the index is still very useful for finding rows with particular <i>flight_id</i>/<i>segment_number</i> values.</p>
-<p>You issue the same query:  
+AND fa.segment_number = fts.segment_number</b></codeblock>
+<p>First imagine the situation in which there are no useful indexes on the
+<codeph>FlightAvailability</codeph> table.</p>
+<p>Using the join order with <codeph>FlightAvailability</codeph> as the outer
+table and <codeph>Flights</codeph> as the inner table is cheaper because it
+allows the <codeph>flight_id</codeph>/<codeph>segment_number</codeph> columns
+from <codeph>FlightAvailability</codeph> to be used to probe into and find
+matching rows in <codeph>Flights</codeph>, using the primary key index on
+<codeph>Flights.flight_id</codeph> and
+<codeph>Flights.segment_number</codeph>.</p>
+<p>This is preferable to the opposite join order (with <codeph>Flights</codeph>
+as the outer table and <codeph>FlightAvailability</codeph> as the inner table)
+because in that case, for each row in <codeph>Flights</codeph>, the system would
+have to scan the entire <codeph>FlightAvailability</codeph> table to find the
+matching rows (because there is no useful index -- an index on the
+<codeph>flight_id</codeph>/<codeph>segment_number</codeph> columns).</p>
+<p>Second, imagine the situation in which there is a useful index on the
+<codeph>FlightAvailability</codeph> table (this is actually the case in the
+sample database). <codeph>FlightAvailability</codeph> has a primary key index on
+<codeph>flight_id</codeph>, <codeph>segment_number</codeph>, and
+<codeph>booking_date</codeph>. In that index, the
+<codeph>flight_id</codeph>/<codeph>segment_number</codeph> combination is not
+unique, since there is a one-to-many correspondence between the
+<codeph>Flights</codeph> table and the <codeph>FlightAvailability</codeph>
+table. However, the index is still very useful for finding rows with particular
+<codeph>flight_id</codeph>/<codeph>segment_number</codeph> values.</p>
+<p>You issue the same query:</p>
 <codeblock><b>SELECT *
 FROM FlightAvailability AS fa, Flights AS fts
 WHERE fa.flight_id = fts.flight_id
-AND fa.segment_number = fts.segment_number</b></codeblock></p>
-<p>Although the difference in cost is smaller, it is still cheaper for the <i>Flights</i> table to be the inner table, because its index
-is unique, whereas <i>FlightAvailability</i>'s index
-is not. That is because it is cheaper for <ph conref="../conrefs.dita#prod/productshortname"></ph> to step through a unique
-index than through a non-unique index.</p>
+AND fa.segment_number = fts.segment_number</b></codeblock>
+<p>Although the difference in cost is smaller, it is still cheaper for the
+<codeph>Flights</codeph> table to be the inner table, because its index is
+unique, whereas <codeph>FlightAvailability</codeph>'s index is not. That is
+because it is cheaper for
+<ph conref="../conrefs.dita#prod/productshortname"></ph> to step through a
+unique index than through a non-unique index.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz33368.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz33368.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz33368.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz33368.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,8 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz33368">
 <title>What is an index?</title>
+<shortdesc>An index is a database structure that provides quick lookup of data
+in a column or columns of a table.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Indexes<indexterm>definition</indexterm></indexterm>
@@ -26,37 +28,46 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>An index is a database structure that provides quick lookup of data in
-a column or columns of a table.</p>
-<p>For example, a <i>Flights</i> table in a <i>travelDB</i> database has three indexes:  
+<p>For example, a <codeph>Flights</codeph> table in a <codeph>travelDB</codeph>
+database has three indexes:</p>
 <ul>
-<li>An index on the <i>orig_airport</i> column (called <i>OrigIndex</i>)</li>
-<li>An index on the <i>dest_airport</i> column (called <i>DestIndex</i>)</li>
-<li>An index enforcing the <i>primary key</i> constraint
-on the <i>flight_id</i> and <i>segment_number</i> columns (which has a system-generated name)</li>
-</ul></p>
+<li>An index on the <codeph>orig_airport</codeph> column (called
+<codeph>OrigIndex</codeph>)</li>
+<li>An index on the <codeph>dest_airport</codeph> column (called
+<codeph>DestIndex</codeph>)</li>
+<li>An index enforcing the <codeph>primary key</codeph> constraint on the
+<codeph>flight_id</codeph> and <codeph>segment_number</codeph> columns (which
+has a system-generated name)</li>
+</ul>
 <p>This means there are three separate structures that provide shortcuts into
-the <i>Flights</i> table. Let's look at one of those
-structures, <i>OrigIndex</i>.</p>
-<p><i>OrigIndex</i> stores every value in the <i>orig_airport</i> column, plus information on how to retrieve the entire corresponding
-row for each value.   
-<ul>
-<li>For every row in <i>Flights</i>, there is an entry in <i>OrigIndex</i> that includes the value of the <i>orig_airport</i> column and the address of the row itself. The entries are
-stored in ascending order by the <i>orig_airport</i> values.</li>
-</ul></p>
+the <codeph>Flights</codeph> table. Let's look at one of those structures,
+<codeph>OrigIndex</codeph>.</p>
+<p><codeph>OrigIndex</codeph> stores every value in the
+<codeph>orig_airport</codeph> column, plus information on how to retrieve the
+entire corresponding row for each value.</p> 
+<p>For every row in <codeph>Flights</codeph>, there is an entry in
+<codeph>OrigIndex</codeph> that includes the value of the
+<codeph>orig_airport</codeph> column and the address of the row itself. The
+entries are stored in ascending order by the <codeph>orig_airport</codeph>
+values.</p>
 <p>When an index includes more than one column, the first column is the main
-one by which the entries are ordered. For example, the index on (<i>flight_id</i>, <i>segment_number</i>) is ordered first by <i>flight_id</i>. If there is more than one <i>flight_id</i> of the same value, those entries are then ordered by <i>segment_number</i>. An excerpt from the entries in the index might look like
-this:  
+one by which the entries are ordered. For example, the index on
+(<codeph>flight_id</codeph>, <codeph>segment_number</codeph>) is ordered first
+by <codeph>flight_id</codeph>. If there is more than one
+<codeph>flight_id</codeph> of the same value, those entries are then ordered by
+<codeph>segment_number</codeph>. An excerpt from the entries in the index might
+look like this:</p>
 <codeblock>'AA1111' 1
 'AA1111' 2
 'AA1112' 1
 'AA1113' 1
-'AA1113' 2</codeblock></p>
-<p>Indexes are helpful only sometimes. This particular index is useful when
-a statement's WHERE clause is looking for rows for which the value of <i>orig_airport</i> is some specific value or range of values.
+'AA1113' 2</codeblock>
+<p>Indexes are only sometimes helpful. This particular index is useful when a
+statement's WHERE clause is looking for rows for which the value of
+<codeph>orig_airport</codeph> is some specific value or range of values.
 SELECTs, UPDATEs, and DELETEs can all have WHERE clauses.</p>
-<p>For example, <i>OrigIndex</i> is helpful for statements
-such as the following:  
+<p>For example, <codeph>OrigIndex</codeph> is helpful for statements such as the
+following:</p>
 <codeblock><b>SELECT *
 FROM Flights
 WHERE orig_airport = 'SFO'
@@ -67,13 +78,15 @@ WHERE orig_airport &lt; 'BBB'
 
 SELECT *
 FROM Flights
-WHERE orig_airport &gt;= 'MMM'</b></codeblock></p>
-<p><i>DestIndex</i> is helpful for statements such as the
-following:  
+WHERE orig_airport &gt;= 'MMM'</b></codeblock>
+<p><codeph>DestIndex</codeph> is helpful for statements such as the
+following:</p>
 <codeblock><b>SELECT *
 FROM Flights
-WHERE dest_airport = 'SCL'</b></codeblock></p>
-<p>The primary key index (on <i>flight_id</i> and <i>segment_number</i>) is helpful for statements such as the following:  
+WHERE dest_airport = 'SCL'</b></codeblock>
+<p>The primary key index (on <codeph>flight_id</codeph> and
+<codeph>segment_number</codeph>) is helpful for statements such as the
+following:</p>
 <codeblock><b>SELECT *
 FROM Flights
 WHERE flight_id = 'AA1111'
@@ -86,7 +99,7 @@ SELECT *
 FROM FlightAvailability AS fa, Flights AS fts
 WHERE flight_date &gt; CURRENT_DATE
 AND fts.flight_id = fa.flight_id
-AND fts.segment_number = fa.segment_number</b></codeblock></p>
-<p>The next section discusses why the indexes are helpful for these statements
-but not for others.</p>
+AND fts.segment_number = fa.segment_number</b></codeblock>
+<p><xref href="ctunoptimz39106.dita"/> discusses why the indexes are helpful for
+these statements but not for others.</p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz39106.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz39106.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz39106.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz39106.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,11 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz39106">
 <title>What's optimizable?</title>
+<shortdesc>As you learned in the previous section,
+<ph conref="../conrefs.dita#prod/productshortname"></ph> might be able to use an
+index on a column to find data more quickly. If
+<ph conref="../conrefs.dita#prod/productshortname"></ph> can use an index for a
+statement, that statement is said to be <i>optimizable</i>.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Statements<indexterm>when they are optimizable</indexterm></indexterm>
@@ -25,26 +30,29 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>As you learned in the previous section, <ph conref="../conrefs.dita#prod/productshortname"></ph> might be able to use
-an index on a column to find data more quickly. If <ph conref="../conrefs.dita#prod/productshortname"></ph> can use an
-index for a statement, that statement is said to be <i>optimizable</i>. The statements shown in the preceding section allow <ph conref="../conrefs.dita#prod/productshortname"></ph> to
-use the index because their WHERE clauses provide start and stop conditions.
-That is, they tell <ph conref="../conrefs.dita#prod/productshortname"></ph> the point at which to begin its scan of the
-index and where to end the scan.</p>
-<p>For example, a statement with a WHERE clause looking for rows for which
-the <i>orig_airport</i> value is less than <i>BBB</i> means that <ph conref="../conrefs.dita#prod/productshortname"></ph> must begin the scan at the beginning of the
-index; it can end the scan at <i>BBB</i>. This means that
-it avoids scanning the index for most of the entries.</p>
-<p>An index scan that uses start or stop conditions is called a <i>matching index scan</i>.  
-<note>A WHERE clause can have more than
-one part. Parts are linked with the word <i>AND</i> or <i>OR</i>. Each part is called a <i>predicate</i>. WHERE clauses with predicates joined by OR are not optimizable. WHERE
-clauses with predicates joined by AND are optimizable if <i>at least one</i> of the predicates is optimizable. For example:  
+<p>The statements shown in <xref href="ctunoptimz33368.dita"/> allow
+<ph conref="../conrefs.dita#prod/productshortname"></ph> to use the index
+because their WHERE clauses provide start and stop conditions. That is, they
+tell <ph conref="../conrefs.dita#prod/productshortname"></ph> the point at which
+to begin its scan of the index and where to end the scan.</p>
+<p>For example, a statement with a WHERE clause looking for rows for which the
+<codeph>orig_airport</codeph> value is less than <codeph>BBB</codeph> means that
+<ph conref="../conrefs.dita#prod/productshortname"></ph> must begin the scan at
+the beginning of the index; it can end the scan at <codeph>BBB</codeph>. This
+means that it avoids scanning the index for most of the entries.</p>
+<p>An index scan that uses start or stop conditions is called a <i>matching
+index scan</i>.</p>
+<p><note>A WHERE clause can have more than one part. Parts are linked with the
+word AND or OR. Each part is called a <i>predicate</i>. WHERE clauses with
+predicates joined by OR are not optimizable. WHERE clauses with predicates
+joined by AND are optimizable if <i>at least one</i> of the predicates is
+optimizable. For example:
 <codeblock><b>SELECT * FROM Flights
 WHERE flight_id = 'AA1111' AND
 segment_number &lt;&gt; 2</b></codeblock></note></p>
 <p>In this example, the first predicate is optimizable; the second predicate
-is not. Therefore, the statement is optimizable.  
-<note>In a few
-cases, a WHERE clause with predicates joined by OR can be transformed into
-an optimizable statement. See <xref href="rtuntransform590.dita#rtuntransform590"/>.</note></p>
+is not. Therefore, the statement is optimizable.</p>
+<p><note>In a few cases, a WHERE clause with predicates joined by OR can be
+transformed into an optimizable statement. See
+<xref href="rtuntransform590.dita"/>.</note></p>
 </conbody></concept>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz39739.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz39739.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz39739.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz39739.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,9 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz39739">
 <title>DML statements and performance</title>
+<shortdesc>This section provides more in-depth information about how
+<ph conref="../conrefs.dita#prod/productshortname"></ph> executes queries, how
+the optimizer works, and how to tune query execution.</shortdesc>
 <prolog>
 </prolog>
 <conbody>

Modified: db/derby/docs/trunk/src/tuning/ctunoptimz41314.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunoptimz41314.dita?rev=1609573&r1=1609572&r2=1609573&view=diff
==============================================================================
--- db/derby/docs/trunk/src/tuning/ctunoptimz41314.dita (original)
+++ db/derby/docs/trunk/src/tuning/ctunoptimz41314.dita Thu Jul 10 21:29:48 2014
@@ -18,6 +18,8 @@ limitations under the License.
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd">
 <concept xml:lang="en-us" id="ctunoptimz41314">
 <title>Useful indexes can use qualifiers</title>
+<shortdesc>Matching index scans can use qualifiers that further restrict the
+result set.</shortdesc>
 <prolog><metadata>
 <keywords>
 <indexterm>Qualifiers<indexterm>in matching index scans</indexterm></indexterm>
@@ -25,20 +27,20 @@ limitations under the License.
 </metadata>
 </prolog>
 <conbody>
-<p>Matching index scans can use qualifiers that further restrict the result
-set. Remember that a WHERE clause that contains at least one optimizable predicate
+<p>Remember that a WHERE clause that contains at least one optimizable predicate
 is optimizable. Nonoptimizable predicates can be useful in other ways.</p>
-<p>Consider the following query:  
+<p>Consider the following query:</p>
 <codeblock><b>SELECT *
 FROM FLIGHTS
 WHERE orig_airport &lt; 'BBB'
-AND orig_airport &lt;&gt; 'AKL'</b></codeblock></p>
+AND orig_airport &lt;&gt; 'AKL'</b></codeblock>
 <p>The second predicate is not optimizable, but the first predicate is. The
-second predicate becomes a qualification for which <ph conref="../conrefs.dita#prod/productshortname"></ph> evaluates the
-entries in the index as it traverses it.  
+second predicate becomes a qualification for which
+<ph conref="../conrefs.dita#prod/productshortname"></ph> evaluates the entries
+in the index as it traverses it.</p>
 <ul>
 <li>The following comparisons are valid qualifiers:  
-<ul>
+<p><ul>
 <li>=</li>
 <li>&lt;</li>
 <li>&lt;=</li>
@@ -49,10 +51,10 @@ entries in the index as it traverses it.
 <li>LIKE</li>
 <li>&lt;&gt;</li>
 <li>IS NOT NULL</li>
-</ul></li>
-<li>The qualifier's reference to the column does not have to be a simple
-column reference; you can put the column in an expression.</li>
-<li>The qualifier's column does not have to be the first column in the
-index and does not have to be contiguous with the first column in the index.</li>
-</ul></p>
+</ul></p></li>
+<li>The qualifier's reference to the column does not have to be a simple column
+reference; you can put the column in an expression.</li>
+<li>The qualifier's column does not have to be the first column in the index and
+does not have to be contiguous with the first column in the index.</li>
+</ul>
 </conbody></concept>



Mime
View raw message