@@ -391,7 +391,21 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
391391 </term>
392392 <listitem>
393393 <para>
394- This sets the compression method for a column. The supported compression
394+ This sets the compression method to be used for data inserted into a column.
395+
396+ This does not cause the table to be rewritten, so existing data may still
397+ be compressed with other compression methods. If the table is rewritten with
398+ <command>VACUUM FULL</command> or <command>CLUSTER</command>, or restored
399+ with <application>pg_restore</application>, then all tuples are rewritten
400+ with the configured compression methods.
401+
402+ Also, note that when data is inserted from another relation (for example,
403+ by <command>INSERT ... SELECT</command>), tuples from the source data are
404+ not necessarily detoasted, and any previously compressed data is retained
405+ with its existing compression method, rather than recompressing with the
406+ compression methods of the target columns.
407+
408+ The supported compression
395409 methods are <literal>pglz</literal> and <literal>lz4</literal>.
396410 <literal>lz4</literal> is available only if <literal>--with-lz4</literal>
397411 was used when building <productname>PostgreSQL</productname>.