bk commit - mysqldoc tree (1.740)

[paul]

Below is the list of changes that have just been committed into a local
mysqldoc repository of paul. When paul does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://www.mysql.com/doc/I/n/Installing_source_tree.html

ChangeSet
  1.740 03/08/21 18:13:32 paul@stripped +1 -0
  Info about SQL_CALC_FOUND_ROWS/FOUND_ROWS() when used with UNION.

  Docs/manual.texi
    1.698 03/08/21 18:13:31 paul@stripped +48 -11
    Info about SQL_CALC_FOUND_ROWS/FOUND_ROWS() when used with UNION.

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User:	paul
# Host:	teton.kitebird.com
# Root:	/home/paul/mysqldoc

--- 1.697/Docs/manual.texi	Thu Aug 21 14:28:12 2003
+++ 1.698/Docs/manual.texi	Thu Aug 21 18:13:31 2003
@@ -39609,11 +39609,13 @@
 @findex LIMIT
 @item FOUND_ROWS()
 @c description_for_help_topic FOUND_ROWS
-Returns the number of rows that the preceding @code{SELECT} statement
-would have returned, if it had not been restricted with @code{LIMIT}.
-For @code{FOUND_ROWS()} to work correctly following a @code{SELECT}
-statement that includes a @code{LIMIT} clause, the statement must
-include the @code{SQL_CALC_FOUND_ROWS} option:
+
+A @code{SELECT} statement may include a @code{LIMIT} clause to restrict the
+number of rows the server returns to the client.
+In some cases, it is desirable to know how many rows the statement would have
+returned without the @code{LIMIT}, but without running the statement again.
+To get this row count, include a @code{SQL_CALC_FOUND_ROWS} option in the
+@code{SELECT} statement, then invoke @code{FOUND_ROWS()} afterward:
 @c end_description_for_help_topic
 
 @c example_for_help_topic FOUND_ROWS
@@ -39626,15 +39628,50 @@
 The second @code{SELECT} will return a number indicating how many rows the
 first @code{SELECT} would have returned had it been written without the
 @code{LIMIT} clause.
+(If the preceding @code{SELECT} statement does not include the
+@code{SQL_CALC_FOUND_ROWS} option, then @code{FOUND_ROWS()} may return
+a different result when @code{LIMIT} is used than when it is not.)
 
 Note that if you are using @code{SELECT SQL_CALC_FOUND_ROWS ...} MySQL has
-to calculate all rows in the result set.  However, this is faster than
-if you would not use @code{LIMIT}, as the result set need not be sent
-to the client.
+to calculate how many rows are in the full result set.  However, this is
+faster than running the query again without @code{LIMIT}, because the result
+set need not be sent to the client.
 
-If the preceding @code{SELECT} statement does not include the
-@code{SQL_CALC_FOUND_ROWS} option, then @code{FOUND_ROWS()} may return
-a different result when @code{LIMIT} is used than when it is not.
+@code{SQL_CALC_FOUND_ROWS} and @code{FOUND_ROWS()} can be useful in situations
+when you want to restrict the number of rows that a query returns, but also
+determine the number of rows in the full result set without running the query
+again. An example is a web script that presents a paged display containing
+links to the pages that show other sections of a search result. Using
+@code{FOUND_ROWS()} allows you to determine how many other pages are needed
+for the rest of the result.
+
+The use of @code{SQL_CALC_FOUND_ROWS} and @code{FOUND_ROWS()} is more complex
+for @code{UNION} queries than for simple @code{SELECT} statements, because
+@code{LIMIT} may occur at multiple places in a @code{UNION}. It may be applied
+to individual @code{SELECT} statements in the @code{UNION}, or global to the
+@code{UNION} result as a whole.
+
+The intent of @code{SQL_CALC_FOUND_ROWS} for @code{UNION} is that it should
+return the row count that would be returned without a global @code{LIMIT}.
+The conditions for use of @code{SQL_CALC_FOUND_ROWS} with @code{UNION} are:
+
+@itemize @bullet
+
+@item
+The @code{SQL_CALC_FOUND_ROWS} keyword must appear in the first @code{SELECT}
+of the @code{UNION}.
+
+@item
+The value of @code{FOUND_ROWS()} is exact only if @code{UNION ALL} is used.
+If @code{UNION} without @code{ALL} is used, duplicate removal occurs and the
+value of @code{FOUND_ROWS()} is only approximate.
+
+@item
+If no @code{LIMIT} is present in the @code{UNION}, @code{SQL_CALC_FOUND_ROWS}
+is ignored and returns the number of rows in the temporary table that is
+created to process the @code{UNION}.
+
+@end itemize
 
 @code{SQL_CALC_FOUND_ROWS} and @code{FOUND_ROWS()} are available starting at MySQL
version 4.0.0.
 @end table