Improve documentation for COPY ... ON_ERROR ...

Discussion: https://postgr.es/m/20240126112829.d420b28859fbe84379fdb7ad%40sraoss.co.jp
Author: Yugo Nagata
Reviewed-by: Masahiko Sawada, David G. Johnston, Atsushi Torikoshi

diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index 21a5c4a0529df4d136c5a7aa76a44fecb4346c3a..55764fc1f24a844723516376e5a57a9ad724af69 100644 (file)
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -90,6 +90,13 @@ COPY { table_name [ ( 
     in the pg_stat_progress_copy view. See
      for details.
   
+
+  
+    By default, COPY will fail if it encounters an error
+    during processing. For use cases where a best-effort attempt at loading
+    the entire file is desired, the ON_ERROR clause can
+    be used to specify some other behavior.
+  
  
 
  
@@ -378,17 +385,20 @@ COPY { table_name [ ( 
     ON_ERROR
     
      
-      Specifies which 
-      error_action to perform when there is malformed data in the input.
-      Currently, only stop (default) and ignore
-      values are supported.
-      If the stop value is specified,
-      COPY stops operation at the first error.
-      If the ignore value is specified,
-      COPY skips malformed data and continues copying data.
-      The option is allowed only in COPY FROM.
-      Only stop value is allowed when
-      using binary format.
+      Specifies how to behave when encountering an error converting a column's
+      input value into its data type.
+      An error_action value of
+      stop means fail the command, while
+      ignore means discard the input row and continue with the next one.
+      The default is stop.
+     
+     
+      The ignore option is applicable only for COPY FROM
+      when the FORMAT is text or csv.
+     
+     
+      A NOTICE message containing the ignored row count is emitted at the end
+      of the COPY FROM if at least one row was discarded.
      
     
    
@@ -576,15 +586,13 @@ COPY count
    
 
    
-    COPY stops operation at the first error when
-    ON_ERROR is not specified. This
-    should not lead to problems in the event of a COPY
-    TO, but the target table will already have received
-    earlier rows in a COPY FROM. These rows will not
-    be visible or accessible, but they still occupy disk space. This might
-    amount to a considerable amount of wasted disk space if the failure
-    happened well into a large copy operation. You might wish to invoke
-    VACUUM to recover the wasted space.
+    The COPY FROM command physically inserts input rows
+    into the table as it progresses.  If the command fails, these rows are
+    left in a deleted state; these rows will not be visible, but still
+    occupy disk space. This might amount to considerable
+    wasted disk space if the failure happened well into a large copy
+    operation. VACUUM should be used to recover the
+    wasted space.