rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Doc: document EXTRACT(JULIAN ...), improve Julian Date explanation. 

For some reason, the "julian" option for extract()/date_part() has
never gotten listed in the manual.  Also, while Appendix B mentioned
in passing that we don't conform to the usual astronomical definition
that a Julian date starts at noon UTC, it was kind of vague about what
we do instead.  Clarify that, and add an example showing how to get
the astronomical definition if you want it.

It's been like this for ages, so back-patch to all supported branches.

Discussion: https://postgr.es/m/1197050.1619123213@sss.pgh.pa.us
This commit is contained in:
Tom Lane 2021-04-26 11:50:35 -04:00
parent 38c9a5938a
commit 79a5928ebc
2 changed files with 61 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
doc/src/sgml/datetime.sgml
View File

@ -763,9 +763,6 @@
<indexterm zone="datetime-units-history">
<primary>Gregorian calendar</primary>
</indexterm>
<indexterm zone="datetime-units-history">
<primary>Julian date</primary>
</indexterm>
<para>
The SQL standard states that <quote>Within the definition of a
@ -868,14 +865,27 @@ $ <userinput>cal 9 1752</userinput>
festivals.
</para>
</sect1>
<sect1 id="datetime-julian-dates">
<title>Julian Dates</title>
<indexterm zone="datetime-julian-dates">
<primary>Julian date</primary>
</indexterm>
<para>
The <firstterm>Julian Date</firstterm> system is another type of
calendar, unrelated to the Julian calendar though it is confusingly
The <firstterm>Julian Date</firstterm> system is a method for
numbering days. It is
unrelated to the Julian calendar, though it is confusingly
named similarly to that calendar.
The Julian Date system was invented by the French scholar
Joseph Justus Scaliger (1540&ndash;1609)
and probably takes its name from Scaliger's father,
the Italian scholar Julius Caesar Scaliger (1484&ndash;1558).
</para>
<para>
In the Julian Date system, each day has a sequential number, starting
from JD 0 (which is sometimes called <emphasis>the</emphasis> Julian Date).
JD 0 corresponds to 1 January 4713 BC in the Julian calendar, or
@ -891,7 +901,31 @@ $ <userinput>cal 9 1752</userinput>
input and output of dates (and also uses Julian dates for some internal
datetime calculations), it does not observe the nicety of having dates
run from noon to noon. <productname>PostgreSQL</productname> treats a Julian Date
as running from midnight to midnight.
as running from local midnight to local midnight, the same as a normal
date.
</para>
<para>
This definition does, however, provide a way to obtain the astronomical
definition when you need it: do the arithmetic in time
zone <literal>UTC-12</literal>. For example,
<programlisting>
=&gt; SELECT extract(julian from '2021-06-23 7:00:00-04'::timestamptz at time zone 'UTC-12');
extract
------------------------------
2459389.95833333333333333333
(1 row)
=&gt; SELECT extract(julian from '2021-06-23 8:00:00-04'::timestamptz at time zone 'UTC-12');
extract
--------------------------------------
2459390.0000000000000000000000000000
(1 row)
=&gt; SELECT extract(julian from date '2021-06-24');
extract
---------
2459390
(1 row)
</programlisting>
</para>
</sect1>

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

@ -7539,7 +7539,8 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
</row>
<row>
<entry><literal>J</literal></entry>
<entry>Julian Day (integer days since November 24, 4714 BC at midnight UTC)</entry>
<entry>Julian Date (integer days since November 24, 4714 BC at local
midnight; see <xref linkend="datetime-julian-dates"/>)</entry>
</row>
<row>
<entry><literal>Q</literal></entry>
@ -9609,6 +9610,25 @@ SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
</listitem>
</varlistentry>
<varlistentry>
<term><literal>julian</literal></term>
<listitem>
<para>
The <firstterm>Julian Date</firstterm> corresponding to the
date or timestamp (not applicable to intervals). Timestamps
that are not local midnight result in a fractional value. See
<xref linkend="datetime-julian-dates"/> for more information.
</para>
<screen>
SELECT EXTRACT(JULIAN FROM DATE '2006-01-01');
<lineannotation>Result: </lineannotation><computeroutput>2453737</computeroutput>
SELECT EXTRACT(JULIAN FROM TIMESTAMP '2006-01-01 12:00');
<lineannotation>Result: </lineannotation><computeroutput>2453737.50000000000000000000</computeroutput>
</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>microseconds</literal></term>
<listitem>