Doc: improve explanation of EXTRACT(EPOCH) for timestamp without tz.

Try to be clearer about what computation is actually happening here.

Per bug #16797 from Dana Burd.

Discussion: https://postgr.es/m/16797-f264b0b980b53b8b@postgresql.org

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 1e044b51a16840c5275e90aa14777997a3242b77..02a37658ad9a23195e85a108ff1430cf957b19cb 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -9354,9 +9354,11 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
       
        
         For timestamp with time zone values, the
-        number of seconds since 1970-01-01 00:00:00 UTC (can be negative);
+        number of seconds since 1970-01-01 00:00:00 UTC (negative for
+        timestamps before that);
         for date and timestamp values, the
-        number of seconds since 1970-01-01 00:00:00 local time;
+        nominal number of seconds since 1970-01-01 00:00:00,
+        without regard to timezone or daylight-savings rules;
         for interval values, the total number
         of seconds in the interval
        
@@ -9365,18 +9367,29 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
 SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40.12-08');
 Result: 982384720.12
 
+SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40.12');
+Result: 982355920.12
+
 SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
 Result: 442800
 
 
        
-        You can convert an epoch value back to a time stamp
+        You can convert an epoch value back to a timestamp with time zone
         with to_timestamp:
        
 
 SELECT to_timestamp(982384720.12);
 Result: 2001-02-17 04:38:40.12+00
 
+
+       
+        Beware that applying to_timestamp to an epoch
+        extracted from a date or timestamp value
+        could produce a misleading result: the result will effectively
+        assume that the original value had been given in UTC, which might
+        not be the case.
+