mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Tom Lane 2021-01-01 15:51:09 -05:00
parent 55e5352266
commit 4750d92ce8
1 changed files with 16 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
doc/src/sgml/func.sgml
View File

@ -9348,9 +9348,11 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
<listitem> <listitem>
<para> <para>
For <type>timestamp with time zone</type> values, the For <type>timestamp with time zone</type> 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 <type>date</type> and <type>timestamp</type> values, the for <type>date</type> and <type>timestamp</type> 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 <type>interval</type> values, the total number for <type>interval</type> values, the total number
of seconds in the interval of seconds in the interval
</para> </para>
@ -9359,18 +9361,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'); SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40.12-08');
<lineannotation>Result: </lineannotation><computeroutput>982384720.12</computeroutput> <lineannotation>Result: </lineannotation><computeroutput>982384720.12</computeroutput>
SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40.12');
<lineannotation>Result: </lineannotation><computeroutput>982355920.12</computeroutput>
SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours'); SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
<lineannotation>Result: </lineannotation><computeroutput>442800</computeroutput> <lineannotation>Result: </lineannotation><computeroutput>442800</computeroutput>
</screen> </screen>
<para> <para>
You can convert an epoch value back to a time stamp You can convert an epoch value back to a <type>timestamp with time zone</type>
with <function>to_timestamp</function>: with <function>to_timestamp</function>:
</para> </para>
<screen> <screen>
SELECT to_timestamp(982384720.12); SELECT to_timestamp(982384720.12);
<lineannotation>Result: </lineannotation><computeroutput>2001-02-17 04:38:40.12+00</computeroutput> <lineannotation>Result: </lineannotation><computeroutput>2001-02-17 04:38:40.12+00</computeroutput>
</screen> </screen>
<para>
Beware that applying <function>to_timestamp</function> to an epoch
extracted from a <type>date</type> or <type>timestamp</type> 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.
</para>
</listitem> </listitem>
</varlistentry> </varlistentry>