Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 4750d92

Browse files
committed
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
1 parent 55e5352 commit 4750d92

File tree

1 file changed

+16
-3
lines changed

1 file changed

+16
-3
lines changed

doc/src/sgml/func.sgml

+16-3
Original file line numberDiff line numberDiff line change
@@ -9348,9 +9348,11 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
93489348
<listitem>
93499349
<para>
93509350
For <type>timestamp with time zone</type> values, the
9351-
number of seconds since 1970-01-01 00:00:00 UTC (can be negative);
9351+
number of seconds since 1970-01-01 00:00:00 UTC (negative for
9352+
timestamps before that);
93529353
for <type>date</type> and <type>timestamp</type> values, the
9353-
number of seconds since 1970-01-01 00:00:00 local time;
9354+
nominal number of seconds since 1970-01-01 00:00:00,
9355+
without regard to timezone or daylight-savings rules;
93549356
for <type>interval</type> values, the total number
93559357
of seconds in the interval
93569358
</para>
@@ -9359,18 +9361,29 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
93599361
SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40.12-08');
93609362
<lineannotation>Result: </lineannotation><computeroutput>982384720.12</computeroutput>
93619363

9364+
SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40.12');
9365+
<lineannotation>Result: </lineannotation><computeroutput>982355920.12</computeroutput>
9366+
93629367
SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
93639368
<lineannotation>Result: </lineannotation><computeroutput>442800</computeroutput>
93649369
</screen>
93659370

93669371
<para>
9367-
You can convert an epoch value back to a time stamp
9372+
You can convert an epoch value back to a <type>timestamp with time zone</type>
93689373
with <function>to_timestamp</function>:
93699374
</para>
93709375
<screen>
93719376
SELECT to_timestamp(982384720.12);
93729377
<lineannotation>Result: </lineannotation><computeroutput>2001-02-17 04:38:40.12+00</computeroutput>
93739378
</screen>
9379+
9380+
<para>
9381+
Beware that applying <function>to_timestamp</function> to an epoch
9382+
extracted from a <type>date</type> or <type>timestamp</type> value
9383+
could produce a misleading result: the result will effectively
9384+
assume that the original value had been given in UTC, which might
9385+
not be the case.
9386+
</para>
93749387
</listitem>
93759388
</varlistentry>
93769389

0 commit comments

Comments
 (0)