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

diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml
index 39fbc39cb0ddb26cab7d9bf4bc0e504bc4d495f4..cb250a63d42785223f07e2d34f99d9f9b6287d62 100644 (file)
--- a/doc/src/sgml/datetime.sgml
+++ b/doc/src/sgml/datetime.sgml
@@ -763,9 +763,6 @@
   
    Gregorian calendar
   
-  
-   Julian date
-  
 
   
    The SQL standard states that Within the definition of a
@@ -868,14 +865,27 @@ $ cal 9 1752
    festivals.
   
 
+  
+
+  
+  Julian Dates
+
+  
+   Julian date
+  
+
   
-   The Julian Date system is another type of
-   calendar, unrelated to the Julian calendar though it is confusingly
+   The Julian Date 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–1609)
    and probably takes its name from Scaliger's father,
    the Italian scholar Julius Caesar Scaliger (1484–1558).
+  
+
+  
    In the Julian Date system, each day has a sequential number, starting
    from JD 0 (which is sometimes called the Julian Date).
    JD 0 corresponds to 1 January 4713 BC in the Julian calendar, or
@@ -891,7 +901,31 @@ $ cal 9 1752
    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.  PostgreSQL treats a Julian Date
-   as running from midnight to midnight.
+   as running from local midnight to local midnight, the same as a normal
+   date.
+  
+
+  
+   This definition does, however, provide a way to obtain the astronomical
+   definition when you need it: do the arithmetic in time
+   zone UTC-12.  For example,
+
+=> SELECT extract(julian from '2021-06-23 7:00:00-04'::timestamptz at time zone 'UTC-12');
+     date_part
+--------------------
+ 2459389.9583333335
+(1 row)
+=> SELECT extract(julian from '2021-06-23 8:00:00-04'::timestamptz at time zone 'UTC-12');
+ date_part
+-----------
+   2459390
+(1 row)
+=> SELECT extract(julian from date '2021-06-24');
+ date_part
+-----------
+   2459390
+(1 row)
+
   
 
  

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 60ac5ef6585a2ec2c56b688ffd78079eb40a7251..930eef9f36e3940fe372ddb98fbfa4e7defcebea 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -7404,7 +7404,8 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
        
        
         J
-        Julian Day (integer days since November 24, 4714 BC at midnight UTC)
+        Julian Date (integer days since November 24, 4714 BC at local
+        midnight; see )
        
        
         Q
@@ -9452,6 +9453,25 @@ SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
       
      
 
+     
+      julian
+      
+       
+        The Julian Date corresponding to the
+        date or timestamp (not applicable to intervals).  Timestamps
+        that are not local midnight result in a fractional value.  See
+         for more information.
+       
+
+
+SELECT EXTRACT(JULIAN FROM DATE '2006-01-01');
+Result: 2453737
+SELECT EXTRACT(JULIAN FROM TIMESTAMP '2006-01-01 12:00');
+Result: 2453737.5
+
+      
+     
+
      
       microseconds