diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 425544ae50..a411f866a0 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -6431,7 +6431,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
interval
Subtract arguments, producing a symbolic result that
- uses years and months
+ uses years and months, rather than just days
age(timestamp '2001-04-10', timestamp '1957-06-13')
43 years 9 mons 27 days
@@ -6794,6 +6794,36 @@ SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS
days because May has 31 days, while April has only 30.
+
+ Subtraction of dates and timestamps can also be complex. The most
+ accurate way to perform subtraction is to convert each value to a number
+ of seconds using EXTRACT(EPOCH FROM ...) and compute the
+ number of seconds between the two values. This will adjust
+ for the number of days in each month, timezone changes, and daylight
+ saving time adjustments. Operator subtraction of date or timestamp
+ values returns the number of days (24-hours) and hours/minutes/seconds
+ between the values, making the same adjustments. The age
+ function returns years, months, days, and hours/minutes/seconds,
+ performing field-by-field subtraction and then adjusting for negative
+ field values. The following queries, produced with timezone
+ = 'US/Eastern' and including a daylight saving time change,
+ illustrates these issues:
+
+
+
+SELECT EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
+ EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00');
+Result: 10537200
+SELECT (EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
+ EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00'))
+ / 60 / 60 / 24;
+Result: 121.958333333333
+SELECT timestamptz '2013-07-01 12:00:00' - timestamptz '2013-03-01 12:00:00';
+Result: 121 days 23:00:00
+SELECT age(timestamptz '2013-07-01 12:00:00', timestamptz '2013-03-01 12:00:00');
+Result: 4 mons
+
+