analyze_in_stages.patch

diff --git i/doc/src/sgml/ref/vacuumdb.sgml w/doc/src/sgml/ref/vacuumdb.sgml
index 223b986..05a288a 100644
--- i/doc/src/sgml/ref/vacuumdb.sgml
+++ w/doc/src/sgml/ref/vacuumdb.sgml
@@ -397,17 +397,19 @@ PostgreSQL documentation
       <listitem>
        <para>
         Only calculate statistics for use by the optimizer (no vacuum),
-        like <option>--analyze-only</option>.  Run several (currently three)
-        stages of analyze with different configuration settings, to produce
-        usable statistics faster.
+        like <option>--analyze-only</option>.  Run three stages of
+        analyze. The first stage uses a low statistics target
+        (see <xref linkend="guc-default-statistics-target"/>)
+        to produce statistics quickly, and subsequent stages build the
+        full statistics.  Be aware running this option in a database
+        with statistics may cause the query optimizer choices to become transiently
+        worse due to the very low statistics targets of the early stages.
        </para>
 
        <para>
-        This option is useful to analyze a database that was newly populated
-        from a restored dump or by <command>pg_upgrade</command>.  This option
-        will try to create some statistics as fast as possible, to make the
-        database usable, and then produce full statistics in the subsequent
-        stages.
+        This option is only useful to analyze a database that current has no,
+        or wholly incorrect, statistics e.g. it was newly populated
+        from a restored dump or by <command>pg_upgrade</command>.
        </para>
       </listitem>
      </varlistentry>