Author: paul
Date: 2007-06-13 19:10:13 +0200 (Wed, 13 Jun 2007)
New Revision: 6783
Log:
r21501@frost: paul | 2007-06-13 10:37:33 -0500
Add information about mysqltest "sorted_result" command.
Modified:
trunk/mysqltest/command-reference.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:26211
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:21491
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:17792
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:26211
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:21501
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:17792
Modified: trunk/mysqltest/command-reference.xml
===================================================================
--- trunk/mysqltest/command-reference.xml 2007-06-13 17:08:43 UTC (rev 6782)
+++ trunk/mysqltest/command-reference.xml 2007-06-13 17:10:13 UTC (rev 6783)
Changed blocks: 2, Lines Added: 112, Lines Deleted: 17; 5232 bytes
@@ -1251,23 +1251,6 @@
<listitem>
<para>
- <literal>query_sorted
- <replaceable>statement</replaceable></literal>
- </para>
-
- <para>
- Execute the statement and display its result with the rows
- sorted as strings.
- </para>
-
- <para>
- <literal>query_sorted</literal> was added in MySQL
- 4.1.23/5.0.32/5.1.18.
- </para>
- </listitem>
-
- <listitem>
- <para>
<literal>query_vertical
<replaceable>statement</replaceable></literal>
</para>
@@ -1636,6 +1619,118 @@
<listitem>
<para>
+ <literal>sorted_result</literal>
+ </para>
+
+ <para>
+ Sort the output from the next statement if it produces a
+ result set. <literal>sorted_result</literal> is applied just
+ before displaying the result, after any other result modifiers
+ that might have been specified, such as
+ <literal>replace_result</literal> or
+ <literal>replace_column</literal>. If the next statement
+ produces no result set, <literal>sorted_result</literal> has
+ no effect because there is nothing to sort.
+ </para>
+
+<programlisting>
+sorted_result;
+SELECT 2 as "my_col" UNION SELECT 1;
+let $my_stmt=SELECT 2 as "my_col" UNION SELECT 1;
+--sorted_result
+eval $my_stmt;
+--sorted_result
+--replace_column 1 #
+SELECT '1' as "my_col1",2 as "my_col2"
+UNION
+SELECT '2',1;
+</programlisting>
+
+ <para>
+ <literal>sorted_result</literal> sorts the entire result of
+ the next query. If this involves constructs such as
+ <literal>UNION</literal>, stored procedures, or
+ multi-statements, the output will be in a fixed order, but all
+ the results will be sorted together and might appear somewhat
+ strange.
+ </para>
+
+ <para>
+ The purpose of the <literal>sorted_result</literal> command is
+ to produce output with a deterministic order for a given set
+ of result rows. It is possible to use <literal>ORDER
+ BY</literal> to sort query results, but that can sometimes
+ present its own problems. For example, if the optimizer is
+ being investigated for some bug, <literal>ORDER BY</literal>
+ might order the result but return an incorrect set of rows.
+ <literal>sorted_result</literal> can be used to produce sorted
+ output even in the absence of <literal>ORDER BY</literal>.
+ </para>
+
+ <para>
+ <literal>sorted_result</literal> is useful for eliminating
+ differences between test runs that may otherwise be difficult
+ to compensate for. Results without <literal>ORDER BY</literal>
+ are not guaranteed to be returned in any given order, so the
+ result for a given query might differ between test runs. For
+ example, the order might vary between different server
+ versions, so a result file created by one server might fail
+ when compared to the result created by another server. The
+ same is true for different storage engines.
+ <literal>sorted_result</literal> eliminates these order
+ differences by producing a deterministic row order.
+ </para>
+
+ <para>
+ Other ways to eliminate differences from results without use
+ of <literal>sorted_result</literal> include:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Remove columns from the select list to reduce variability
+ in the output
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use aggregate functions such as <literal>AVG()</literal>
+ on all columns of the select list
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use <literal>ORDER BY</literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The use of aggregate functions or <literal>ORDER BY</literal>
+ may also have the advantage of exposing other bugs by
+ introducing additional stress on the server. The choice of
+ whether to use <literal>sorted_result</literal> or
+ <literal>ORDER BY</literal> (or perhaps both) may be dictated
+ by whether you are trying to expose bugs, or avoid having them
+ affect results. This means that care should be taken with
+ <literal>sorted_result</literal> because it has the potential
+ of hiding server bugs that result in true problems with result
+ order.
+ </para>
+
+ <para>
+ <literal>sorted_result</literal> was added in MySQL
+ 4.1.23/5.0.32/5.1.18.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
<literal>source <replaceable>file_name</replaceable></literal>
</para>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r6783 - in trunk: . mysqltest | paul | 13 Jun |
