begriffs open source - ai-pg/blob - full-docs/src/sgml/html/functions-datetime.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.9. Date/Time Functions and Operators</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-formatting.html" title="9.8. Data Type Formatting Functions" /><link rel="next" href="functions-enum.html" title="9.10. Enum Support Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.9. Date/Time Functions and Operators</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-enum.html" title="9.10. Enum Support Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-DATETIME"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.9. Date/Time Functions and Operators <a href="#FUNCTIONS-DATETIME" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT">9.9.1. <code class="function">EXTRACT</code>, <code class="function">date_part</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-TRUNC">9.9.2. <code class="function">date_trunc</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-BIN">9.9.3. <code class="function">date_bin</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT">9.9.4. <code class="literal">AT TIME ZONE</code> and <code class="literal">AT LOCAL</code></a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT">9.9.5. Current Date/Time</a></span></dt><dt><span class="sect2"><a href="functions-datetime.html#FUNCTIONS-DATETIME-DELAY">9.9.6. Delaying Execution</a></span></dt></dl></div><p>
   3    <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-TABLE" title="Table 9.33. Date/Time Functions">Table 9.33</a> shows the available
   4    functions for date/time value processing, with details appearing in
   5    the following subsections.  <a class="xref" href="functions-datetime.html#OPERATORS-DATETIME-TABLE" title="Table 9.32. Date/Time Operators">Table 9.32</a> illustrates the behaviors of
   6    the basic arithmetic operators (<code class="literal">+</code>,
   7    <code class="literal">*</code>, etc.).  For formatting functions, refer to
   8    <a class="xref" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Section 9.8</a>.  You should be familiar with
   9    the background information on date/time data types from <a class="xref" href="datatype-datetime.html" title="8.5. Date/Time Types">Section 8.5</a>.
  10   </p><p>
  11    In addition, the usual comparison operators shown in
  12    <a class="xref" href="functions-comparison.html#FUNCTIONS-COMPARISON-OP-TABLE" title="Table 9.1. Comparison Operators">Table 9.1</a> are available for the
  13    date/time types.  Dates and timestamps (with or without time zone) are
  14    all comparable, while times (with or without time zone) and intervals
  15    can only be compared to other values of the same data type.  When
  16    comparing a timestamp without time zone to a timestamp with time zone,
  17    the former value is assumed to be given in the time zone specified by
  18    the <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> configuration parameter, and is
  19    rotated to UTC for comparison to the latter value (which is already
  20    in UTC internally).  Similarly, a date value is assumed to represent
  21    midnight in the <code class="varname">TimeZone</code> zone when comparing it
  22    to a timestamp.
  23   </p><p>
  24    All the functions and operators described below that take <code class="type">time</code> or <code class="type">timestamp</code>
  25    inputs actually come in two variants: one that takes <code class="type">time with time zone</code> or <code class="type">timestamp
  26    with time zone</code>, and one that takes <code class="type">time without time zone</code> or <code class="type">timestamp without time zone</code>.
  27    For brevity, these variants are not shown separately.  Also, the
  28    <code class="literal">+</code> and <code class="literal">*</code> operators come in commutative pairs (for
  29    example both <code class="type">date</code> <code class="literal">+</code> <code class="type">integer</code>
  30    and <code class="type">integer</code> <code class="literal">+</code> <code class="type">date</code>); we show
  31    only one of each such pair.
  32   </p><div class="table" id="OPERATORS-DATETIME-TABLE"><p class="title"><strong>Table 9.32. Date/Time Operators</strong></p><div class="table-contents"><table class="table" summary="Date/Time Operators" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
  33          Operator
  34         </p>
  35         <p>
  36          Description
  37         </p>
  38         <p>
  39          Example(s)
  40         </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
  41          <code class="type">date</code> <code class="literal">+</code> <code class="type">integer</code>
  42          → <code class="returnvalue">date</code>
  43         </p>
  44         <p>
  45          Add a number of days to a date
  46         </p>
  47         <p>
  48          <code class="literal">date '2001-09-28' + 7</code>
  49          → <code class="returnvalue">2001-10-05</code>
  50         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  51          <code class="type">date</code> <code class="literal">+</code> <code class="type">interval</code>
  52          → <code class="returnvalue">timestamp</code>
  53         </p>
  54         <p>
  55          Add an interval to a date
  56         </p>
  57         <p>
  58          <code class="literal">date '2001-09-28' + interval '1 hour'</code>
  59          → <code class="returnvalue">2001-09-28 01:00:00</code>
  60         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  61          <code class="type">date</code> <code class="literal">+</code> <code class="type">time</code>
  62          → <code class="returnvalue">timestamp</code>
  63         </p>
  64         <p>
  65          Add a time-of-day to a date
  66         </p>
  67         <p>
  68          <code class="literal">date '2001-09-28' + time '03:00'</code>
  69          → <code class="returnvalue">2001-09-28 03:00:00</code>
  70         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  71          <code class="type">interval</code> <code class="literal">+</code> <code class="type">interval</code>
  72          → <code class="returnvalue">interval</code>
  73         </p>
  74         <p>
  75          Add intervals
  76         </p>
  77         <p>
  78          <code class="literal">interval '1 day' + interval '1 hour'</code>
  79          → <code class="returnvalue">1 day 01:00:00</code>
  80         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  81          <code class="type">timestamp</code> <code class="literal">+</code> <code class="type">interval</code>
  82          → <code class="returnvalue">timestamp</code>
  83         </p>
  84         <p>
  85          Add an interval to a timestamp
  86         </p>
  87         <p>
  88          <code class="literal">timestamp '2001-09-28 01:00' + interval '23 hours'</code>
  89          → <code class="returnvalue">2001-09-29 00:00:00</code>
  90         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  91          <code class="type">time</code> <code class="literal">+</code> <code class="type">interval</code>
  92          → <code class="returnvalue">time</code>
  93         </p>
  94         <p>
  95          Add an interval to a time
  96         </p>
  97         <p>
  98          <code class="literal">time '01:00' + interval '3 hours'</code>
  99          → <code class="returnvalue">04:00:00</code>
 100         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 101          <code class="literal">-</code> <code class="type">interval</code>
 102          → <code class="returnvalue">interval</code>
 103         </p>
 104         <p>
 105          Negate an interval
 106         </p>
 107         <p>
 108          <code class="literal">- interval '23 hours'</code>
 109          → <code class="returnvalue">-23:00:00</code>
 110         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 111          <code class="type">date</code> <code class="literal">-</code> <code class="type">date</code>
 112          → <code class="returnvalue">integer</code>
 113         </p>
 114         <p>
 115          Subtract dates, producing the number of days elapsed
 116         </p>
 117         <p>
 118          <code class="literal">date '2001-10-01' - date '2001-09-28'</code>
 119          → <code class="returnvalue">3</code>
 120         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 121          <code class="type">date</code> <code class="literal">-</code> <code class="type">integer</code>
 122          → <code class="returnvalue">date</code>
 123         </p>
 124         <p>
 125          Subtract a number of days from a date
 126         </p>
 127         <p>
 128          <code class="literal">date '2001-10-01' - 7</code>
 129          → <code class="returnvalue">2001-09-24</code>
 130         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 131          <code class="type">date</code> <code class="literal">-</code> <code class="type">interval</code>
 132          → <code class="returnvalue">timestamp</code>
 133         </p>
 134         <p>
 135          Subtract an interval from a date
 136         </p>
 137         <p>
 138          <code class="literal">date '2001-09-28' - interval '1 hour'</code>
 139          → <code class="returnvalue">2001-09-27 23:00:00</code>
 140         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 141          <code class="type">time</code> <code class="literal">-</code> <code class="type">time</code>
 142          → <code class="returnvalue">interval</code>
 143         </p>
 144         <p>
 145          Subtract times
 146         </p>
 147         <p>
 148          <code class="literal">time '05:00' - time '03:00'</code>
 149          → <code class="returnvalue">02:00:00</code>
 150         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 151          <code class="type">time</code> <code class="literal">-</code> <code class="type">interval</code>
 152          → <code class="returnvalue">time</code>
 153         </p>
 154         <p>
 155          Subtract an interval from a time
 156         </p>
 157         <p>
 158          <code class="literal">time '05:00' - interval '2 hours'</code>
 159          → <code class="returnvalue">03:00:00</code>
 160         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 161          <code class="type">timestamp</code> <code class="literal">-</code> <code class="type">interval</code>
 162          → <code class="returnvalue">timestamp</code>
 163         </p>
 164         <p>
 165          Subtract an interval from a timestamp
 166         </p>
 167         <p>
 168          <code class="literal">timestamp '2001-09-28 23:00' - interval '23 hours'</code>
 169          → <code class="returnvalue">2001-09-28 00:00:00</code>
 170         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 171          <code class="type">interval</code> <code class="literal">-</code> <code class="type">interval</code>
 172          → <code class="returnvalue">interval</code>
 173         </p>
 174         <p>
 175          Subtract intervals
 176         </p>
 177         <p>
 178          <code class="literal">interval '1 day' - interval '1 hour'</code>
 179          → <code class="returnvalue">1 day -01:00:00</code>
 180         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 181          <code class="type">timestamp</code> <code class="literal">-</code> <code class="type">timestamp</code>
 182          → <code class="returnvalue">interval</code>
 183         </p>
 184         <p>
 185          Subtract timestamps (converting 24-hour intervals into days,
 186          similarly to <a class="link" href="functions-datetime.html#FUNCTION-JUSTIFY-HOURS"><code class="function">justify_hours()</code></a>)
 187         </p>
 188         <p>
 189          <code class="literal">timestamp '2001-09-29 03:00' - timestamp '2001-07-27 12:00'</code>
 190          → <code class="returnvalue">63 days 15:00:00</code>
 191         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 192          <code class="type">interval</code> <code class="literal">*</code> <code class="type">double precision</code>
 193          → <code class="returnvalue">interval</code>
 194         </p>
 195         <p>
 196          Multiply an interval by a scalar
 197         </p>
 198         <p>
 199          <code class="literal">interval '1 second' * 900</code>
 200          → <code class="returnvalue">00:15:00</code>
 201         </p>
 202         <p>
 203          <code class="literal">interval '1 day' * 21</code>
 204          → <code class="returnvalue">21 days</code>
 205         </p>
 206         <p>
 207          <code class="literal">interval '1 hour' * 3.5</code>
 208          → <code class="returnvalue">03:30:00</code>
 209         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 210          <code class="type">interval</code> <code class="literal">/</code> <code class="type">double precision</code>
 211          → <code class="returnvalue">interval</code>
 212         </p>
 213         <p>
 214          Divide an interval by a scalar
 215         </p>
 216         <p>
 217          <code class="literal">interval '1 hour' / 1.5</code>
 218          → <code class="returnvalue">00:40:00</code>
 219         </p></td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="FUNCTIONS-DATETIME-TABLE"><p class="title"><strong>Table 9.33. Date/Time Functions</strong></p><div class="table-contents"><table class="table" summary="Date/Time Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
 220          Function
 221         </p>
 222         <p>
 223          Description
 224         </p>
 225         <p>
 226          Example(s)
 227         </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
 228          <a id="id-1.5.8.15.6.2.2.1.1.1.1" class="indexterm"></a>
 229          <code class="function">age</code> ( <code class="type">timestamp</code>, <code class="type">timestamp</code> )
 230          → <code class="returnvalue">interval</code>
 231         </p>
 232         <p>
 233          Subtract arguments, producing a <span class="quote">“<span class="quote">symbolic</span>”</span> result that
 234          uses years and months, rather than just days
 235         </p>
 236         <p>
 237          <code class="literal">age(timestamp '2001-04-10', timestamp '1957-06-13')</code>
 238          → <code class="returnvalue">43 years 9 mons 27 days</code>
 239         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 240          <code class="function">age</code> ( <code class="type">timestamp</code> )
 241          → <code class="returnvalue">interval</code>
 242         </p>
 243         <p>
 244          Subtract argument from <code class="function">current_date</code> (at midnight)
 245         </p>
 246         <p>
 247          <code class="literal">age(timestamp '1957-06-13')</code>
 248          → <code class="returnvalue">62 years 6 mons 10 days</code>
 249         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 250          <a id="id-1.5.8.15.6.2.2.3.1.1.1" class="indexterm"></a>
 251          <code class="function">clock_timestamp</code> ( )
 252          → <code class="returnvalue">timestamp with time zone</code>
 253         </p>
 254         <p>
 255          Current date and time (changes during statement execution);
 256          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 257         </p>
 258         <p>
 259          <code class="literal">clock_timestamp()</code>
 260          → <code class="returnvalue">2019-12-23 14:39:53.662522-05</code>
 261         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 262          <a id="id-1.5.8.15.6.2.2.4.1.1.1" class="indexterm"></a>
 263          <code class="function">current_date</code>
 264          → <code class="returnvalue">date</code>
 265         </p>
 266         <p>
 267          Current date; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 268         </p>
 269         <p>
 270          <code class="literal">current_date</code>
 271          → <code class="returnvalue">2019-12-23</code>
 272         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 273          <a id="id-1.5.8.15.6.2.2.5.1.1.1" class="indexterm"></a>
 274          <code class="function">current_time</code>
 275          → <code class="returnvalue">time with time zone</code>
 276         </p>
 277         <p>
 278          Current time of day; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 279         </p>
 280         <p>
 281          <code class="literal">current_time</code>
 282          → <code class="returnvalue">14:39:53.662522-05</code>
 283         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 284          <code class="function">current_time</code> ( <code class="type">integer</code> )
 285          → <code class="returnvalue">time with time zone</code>
 286         </p>
 287         <p>
 288          Current time of day, with limited precision;
 289          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 290         </p>
 291         <p>
 292          <code class="literal">current_time(2)</code>
 293          → <code class="returnvalue">14:39:53.66-05</code>
 294         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 295          <a id="id-1.5.8.15.6.2.2.7.1.1.1" class="indexterm"></a>
 296          <code class="function">current_timestamp</code>
 297          → <code class="returnvalue">timestamp with time zone</code>
 298         </p>
 299         <p>
 300          Current date and time (start of current transaction);
 301          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 302         </p>
 303         <p>
 304          <code class="literal">current_timestamp</code>
 305          → <code class="returnvalue">2019-12-23 14:39:53.662522-05</code>
 306         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 307          <code class="function">current_timestamp</code> ( <code class="type">integer</code> )
 308          → <code class="returnvalue">timestamp with time zone</code>
 309         </p>
 310         <p>
 311          Current date and time (start of current transaction), with limited precision;
 312          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 313         </p>
 314         <p>
 315          <code class="literal">current_timestamp(0)</code>
 316          → <code class="returnvalue">2019-12-23 14:39:53-05</code>
 317         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 318          <a id="id-1.5.8.15.6.2.2.9.1.1.1" class="indexterm"></a>
 319          <code class="function">date_add</code> ( <code class="type">timestamp with time zone</code>, <code class="type">interval</code> [<span class="optional">, <code class="type">text</code> </span>] )
 320          → <code class="returnvalue">timestamp with time zone</code>
 321         </p>
 322         <p>
 323          Add an <code class="type">interval</code> to a <code class="type">timestamp with time
 324          zone</code>, computing times of day and daylight-savings adjustments
 325          according to the time zone named by the third argument, or the
 326          current <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> setting if that is omitted.
 327          The form with two arguments is equivalent to the <code class="type">timestamp with
 328          time zone</code> <code class="literal">+</code> <code class="type">interval</code> operator.
 329         </p>
 330         <p>
 331          <code class="literal">date_add('2021-10-31 00:00:00+02'::timestamptz, '1 day'::interval, 'Europe/Warsaw')</code>
 332          → <code class="returnvalue">2021-10-31 23:00:00+00</code>
 333         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 334          <code class="function">date_bin</code> ( <code class="type">interval</code>, <code class="type">timestamp</code>, <code class="type">timestamp</code> )
 335          → <code class="returnvalue">timestamp</code>
 336         </p>
 337         <p>
 338          Bin input into specified interval aligned with specified origin; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-BIN" title="9.9.3. date_bin">Section 9.9.3</a>
 339         </p>
 340         <p>
 341          <code class="literal">date_bin('15 minutes', timestamp '2001-02-16 20:38:40', timestamp '2001-02-16 20:05:00')</code>
 342          → <code class="returnvalue">2001-02-16 20:35:00</code>
 343         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 344          <a id="id-1.5.8.15.6.2.2.11.1.1.1" class="indexterm"></a>
 345          <code class="function">date_part</code> ( <code class="type">text</code>, <code class="type">timestamp</code> )
 346          → <code class="returnvalue">double precision</code>
 347         </p>
 348         <p>
 349          Get timestamp subfield (equivalent to <code class="function">extract</code>);
 350          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT" title="9.9.1. EXTRACT, date_part">Section 9.9.1</a>
 351         </p>
 352         <p>
 353          <code class="literal">date_part('hour', timestamp '2001-02-16 20:38:40')</code>
 354          → <code class="returnvalue">20</code>
 355         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 356          <code class="function">date_part</code> ( <code class="type">text</code>, <code class="type">interval</code> )
 357          → <code class="returnvalue">double precision</code>
 358         </p>
 359         <p>
 360          Get interval subfield (equivalent to <code class="function">extract</code>);
 361          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT" title="9.9.1. EXTRACT, date_part">Section 9.9.1</a>
 362         </p>
 363         <p>
 364          <code class="literal">date_part('month', interval '2 years 3 months')</code>
 365          → <code class="returnvalue">3</code>
 366         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 367          <a id="id-1.5.8.15.6.2.2.13.1.1.1" class="indexterm"></a>
 368          <code class="function">date_subtract</code> ( <code class="type">timestamp with time zone</code>, <code class="type">interval</code> [<span class="optional">, <code class="type">text</code> </span>] )
 369          → <code class="returnvalue">timestamp with time zone</code>
 370         </p>
 371         <p>
 372          Subtract an <code class="type">interval</code> from a <code class="type">timestamp with time
 373          zone</code>, computing times of day and daylight-savings adjustments
 374          according to the time zone named by the third argument, or the
 375          current <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> setting if that is omitted.
 376          The form with two arguments is equivalent to the <code class="type">timestamp with
 377          time zone</code> <code class="literal">-</code> <code class="type">interval</code> operator.
 378         </p>
 379         <p>
 380          <code class="literal">date_subtract('2021-11-01 00:00:00+01'::timestamptz, '1 day'::interval, 'Europe/Warsaw')</code>
 381          → <code class="returnvalue">2021-10-30 22:00:00+00</code>
 382         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 383          <a id="id-1.5.8.15.6.2.2.14.1.1.1" class="indexterm"></a>
 384          <code class="function">date_trunc</code> ( <code class="type">text</code>, <code class="type">timestamp</code> )
 385          → <code class="returnvalue">timestamp</code>
 386         </p>
 387         <p>
 388          Truncate to specified precision; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-TRUNC" title="9.9.2. date_trunc">Section 9.9.2</a>
 389         </p>
 390         <p>
 391          <code class="literal">date_trunc('hour', timestamp '2001-02-16 20:38:40')</code>
 392          → <code class="returnvalue">2001-02-16 20:00:00</code>
 393         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 394          <code class="function">date_trunc</code> ( <code class="type">text</code>, <code class="type">timestamp with time zone</code>, <code class="type">text</code> )
 395          → <code class="returnvalue">timestamp with time zone</code>
 396         </p>
 397         <p>
 398          Truncate to specified precision in the specified time zone; see
 399          <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-TRUNC" title="9.9.2. date_trunc">Section 9.9.2</a>
 400         </p>
 401         <p>
 402          <code class="literal">date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')</code>
 403          → <code class="returnvalue">2001-02-16 13:00:00+00</code>
 404         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 405          <code class="function">date_trunc</code> ( <code class="type">text</code>, <code class="type">interval</code> )
 406          → <code class="returnvalue">interval</code>
 407         </p>
 408         <p>
 409          Truncate to specified precision; see
 410          <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-TRUNC" title="9.9.2. date_trunc">Section 9.9.2</a>
 411         </p>
 412         <p>
 413          <code class="literal">date_trunc('hour', interval '2 days 3 hours 40 minutes')</code>
 414          → <code class="returnvalue">2 days 03:00:00</code>
 415         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 416          <a id="id-1.5.8.15.6.2.2.17.1.1.1" class="indexterm"></a>
 417          <code class="function">extract</code> ( <em class="parameter"><code>field</code></em> <code class="literal">from</code> <code class="type">timestamp</code> )
 418          → <code class="returnvalue">numeric</code>
 419         </p>
 420         <p>
 421          Get timestamp subfield; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT" title="9.9.1. EXTRACT, date_part">Section 9.9.1</a>
 422         </p>
 423         <p>
 424          <code class="literal">extract(hour from timestamp '2001-02-16 20:38:40')</code>
 425          → <code class="returnvalue">20</code>
 426         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 427          <code class="function">extract</code> ( <em class="parameter"><code>field</code></em> <code class="literal">from</code> <code class="type">interval</code> )
 428          → <code class="returnvalue">numeric</code>
 429         </p>
 430         <p>
 431          Get interval subfield; see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-EXTRACT" title="9.9.1. EXTRACT, date_part">Section 9.9.1</a>
 432         </p>
 433         <p>
 434          <code class="literal">extract(month from interval '2 years 3 months')</code>
 435          → <code class="returnvalue">3</code>
 436         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 437          <a id="id-1.5.8.15.6.2.2.19.1.1.1" class="indexterm"></a>
 438          <code class="function">isfinite</code> ( <code class="type">date</code> )
 439          → <code class="returnvalue">boolean</code>
 440         </p>
 441         <p>
 442          Test for finite date (not +/-infinity)
 443         </p>
 444         <p>
 445          <code class="literal">isfinite(date '2001-02-16')</code>
 446          → <code class="returnvalue">true</code>
 447         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 448          <code class="function">isfinite</code> ( <code class="type">timestamp</code> )
 449          → <code class="returnvalue">boolean</code>
 450         </p>
 451         <p>
 452          Test for finite timestamp (not +/-infinity)
 453         </p>
 454         <p>
 455          <code class="literal">isfinite(timestamp 'infinity')</code>
 456          → <code class="returnvalue">false</code>
 457         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 458          <code class="function">isfinite</code> ( <code class="type">interval</code> )
 459          → <code class="returnvalue">boolean</code>
 460         </p>
 461         <p>
 462          Test for finite interval (not +/-infinity)
 463         </p>
 464         <p>
 465          <code class="literal">isfinite(interval '4 hours')</code>
 466          → <code class="returnvalue">true</code>
 467         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 468          <a id="FUNCTION-JUSTIFY-DAYS" class="indexterm"></a>
 469          <code class="function">justify_days</code> ( <code class="type">interval</code> )
 470          → <code class="returnvalue">interval</code>
 471         </p>
 472         <p>
 473          Adjust interval, converting 30-day time periods to months
 474         </p>
 475         <p>
 476          <code class="literal">justify_days(interval '1 year 65 days')</code>
 477          → <code class="returnvalue">1 year 2 mons 5 days</code>
 478         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 479          <a id="FUNCTION-JUSTIFY-HOURS" class="indexterm"></a>
 480          <code class="function">justify_hours</code> ( <code class="type">interval</code> )
 481          → <code class="returnvalue">interval</code>
 482         </p>
 483         <p>
 484          Adjust interval, converting 24-hour time periods to days
 485         </p>
 486         <p>
 487          <code class="literal">justify_hours(interval '50 hours 10 minutes')</code>
 488          → <code class="returnvalue">2 days 02:10:00</code>
 489         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 490          <a id="id-1.5.8.15.6.2.2.24.1.1.1" class="indexterm"></a>
 491          <code class="function">justify_interval</code> ( <code class="type">interval</code> )
 492          → <code class="returnvalue">interval</code>
 493         </p>
 494         <p>
 495          Adjust interval using <code class="function">justify_days</code>
 496          and <code class="function">justify_hours</code>, with additional sign
 497          adjustments
 498         </p>
 499         <p>
 500          <code class="literal">justify_interval(interval '1 mon -1 hour')</code>
 501          → <code class="returnvalue">29 days 23:00:00</code>
 502         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 503          <a id="id-1.5.8.15.6.2.2.25.1.1.1" class="indexterm"></a>
 504          <code class="function">localtime</code>
 505          → <code class="returnvalue">time</code>
 506         </p>
 507         <p>
 508          Current time of day;
 509          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 510         </p>
 511         <p>
 512          <code class="literal">localtime</code>
 513          → <code class="returnvalue">14:39:53.662522</code>
 514         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 515          <code class="function">localtime</code> ( <code class="type">integer</code> )
 516          → <code class="returnvalue">time</code>
 517         </p>
 518         <p>
 519          Current time of day, with limited precision;
 520          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 521         </p>
 522         <p>
 523          <code class="literal">localtime(0)</code>
 524          → <code class="returnvalue">14:39:53</code>
 525         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 526          <a id="id-1.5.8.15.6.2.2.27.1.1.1" class="indexterm"></a>
 527          <code class="function">localtimestamp</code>
 528          → <code class="returnvalue">timestamp</code>
 529         </p>
 530         <p>
 531          Current date and time (start of current transaction);
 532          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 533         </p>
 534         <p>
 535          <code class="literal">localtimestamp</code>
 536          → <code class="returnvalue">2019-12-23 14:39:53.662522</code>
 537         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 538          <code class="function">localtimestamp</code> ( <code class="type">integer</code> )
 539          → <code class="returnvalue">timestamp</code>
 540         </p>
 541         <p>
 542          Current date and time (start of current
 543          transaction), with limited precision;
 544          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 545         </p>
 546         <p>
 547          <code class="literal">localtimestamp(2)</code>
 548          → <code class="returnvalue">2019-12-23 14:39:53.66</code>
 549         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 550          <a id="id-1.5.8.15.6.2.2.29.1.1.1" class="indexterm"></a>
 551          <code class="function">make_date</code> ( <em class="parameter"><code>year</code></em> <code class="type">int</code>,
 552          <em class="parameter"><code>month</code></em> <code class="type">int</code>,
 553          <em class="parameter"><code>day</code></em> <code class="type">int</code> )
 554          → <code class="returnvalue">date</code>
 555         </p>
 556         <p>
 557          Create date from year, month and day fields
 558          (negative years signify BC)
 559         </p>
 560         <p>
 561          <code class="literal">make_date(2013, 7, 15)</code>
 562          → <code class="returnvalue">2013-07-15</code>
 563         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature"><a id="id-1.5.8.15.6.2.2.30.1.1.1" class="indexterm"></a>
 564          <code class="function">make_interval</code> ( [<span class="optional"> <em class="parameter"><code>years</code></em> <code class="type">int</code>
 565          [<span class="optional">, <em class="parameter"><code>months</code></em> <code class="type">int</code>
 566          [<span class="optional">, <em class="parameter"><code>weeks</code></em> <code class="type">int</code>
 567          [<span class="optional">, <em class="parameter"><code>days</code></em> <code class="type">int</code>
 568          [<span class="optional">, <em class="parameter"><code>hours</code></em> <code class="type">int</code>
 569          [<span class="optional">, <em class="parameter"><code>mins</code></em> <code class="type">int</code>
 570          [<span class="optional">, <em class="parameter"><code>secs</code></em> <code class="type">double precision</code>
 571          </span>]</span>]</span>]</span>]</span>]</span>]</span>] )
 572          → <code class="returnvalue">interval</code>
 573         </p>
 574         <p>
 575          Create interval from years, months, weeks, days, hours, minutes and
 576          seconds fields, each of which can default to zero
 577         </p>
 578         <p>
 579          <code class="literal">make_interval(days =&gt; 10)</code>
 580          → <code class="returnvalue">10 days</code>
 581         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 582          <a id="id-1.5.8.15.6.2.2.31.1.1.1" class="indexterm"></a>
 583          <code class="function">make_time</code> ( <em class="parameter"><code>hour</code></em> <code class="type">int</code>,
 584          <em class="parameter"><code>min</code></em> <code class="type">int</code>,
 585          <em class="parameter"><code>sec</code></em> <code class="type">double precision</code> )
 586          → <code class="returnvalue">time</code>
 587         </p>
 588         <p>
 589          Create time from hour, minute and seconds fields
 590         </p>
 591         <p>
 592          <code class="literal">make_time(8, 15, 23.5)</code>
 593          → <code class="returnvalue">08:15:23.5</code>
 594         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 595          <a id="id-1.5.8.15.6.2.2.32.1.1.1" class="indexterm"></a>
 596          <code class="function">make_timestamp</code> ( <em class="parameter"><code>year</code></em> <code class="type">int</code>,
 597          <em class="parameter"><code>month</code></em> <code class="type">int</code>,
 598          <em class="parameter"><code>day</code></em> <code class="type">int</code>,
 599          <em class="parameter"><code>hour</code></em> <code class="type">int</code>,
 600          <em class="parameter"><code>min</code></em> <code class="type">int</code>,
 601          <em class="parameter"><code>sec</code></em> <code class="type">double precision</code> )
 602          → <code class="returnvalue">timestamp</code>
 603         </p>
 604         <p>
 605          Create timestamp from year, month, day, hour, minute and seconds fields
 606          (negative years signify BC)
 607         </p>
 608         <p>
 609          <code class="literal">make_timestamp(2013, 7, 15, 8, 15, 23.5)</code>
 610          → <code class="returnvalue">2013-07-15 08:15:23.5</code>
 611         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 612          <a id="id-1.5.8.15.6.2.2.33.1.1.1" class="indexterm"></a>
 613          <code class="function">make_timestamptz</code> ( <em class="parameter"><code>year</code></em> <code class="type">int</code>,
 614          <em class="parameter"><code>month</code></em> <code class="type">int</code>,
 615          <em class="parameter"><code>day</code></em> <code class="type">int</code>,
 616          <em class="parameter"><code>hour</code></em> <code class="type">int</code>,
 617          <em class="parameter"><code>min</code></em> <code class="type">int</code>,
 618          <em class="parameter"><code>sec</code></em> <code class="type">double precision</code>
 619          [<span class="optional">, <em class="parameter"><code>timezone</code></em> <code class="type">text</code> </span>] )
 620          → <code class="returnvalue">timestamp with time zone</code>
 621         </p>
 622         <p>
 623          Create timestamp with time zone from year, month, day, hour, minute
 624          and seconds fields (negative years signify BC).
 625          If <em class="parameter"><code>timezone</code></em> is not
 626          specified, the current time zone is used; the examples assume the
 627          session time zone is <code class="literal">Europe/London</code>
 628         </p>
 629         <p>
 630          <code class="literal">make_timestamptz(2013, 7, 15, 8, 15, 23.5)</code>
 631          → <code class="returnvalue">2013-07-15 08:15:23.5+01</code>
 632         </p>
 633         <p>
 634          <code class="literal">make_timestamptz(2013, 7, 15, 8, 15, 23.5, 'America/New_York')</code>
 635          → <code class="returnvalue">2013-07-15 13:15:23.5+01</code>
 636         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 637          <a id="id-1.5.8.15.6.2.2.34.1.1.1" class="indexterm"></a>
 638          <code class="function">now</code> ( )
 639          → <code class="returnvalue">timestamp with time zone</code>
 640         </p>
 641         <p>
 642          Current date and time (start of current transaction);
 643          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 644         </p>
 645         <p>
 646          <code class="literal">now()</code>
 647          → <code class="returnvalue">2019-12-23 14:39:53.662522-05</code>
 648         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 649          <a id="id-1.5.8.15.6.2.2.35.1.1.1" class="indexterm"></a>
 650          <code class="function">statement_timestamp</code> ( )
 651          → <code class="returnvalue">timestamp with time zone</code>
 652         </p>
 653         <p>
 654          Current date and time (start of current statement);
 655          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 656         </p>
 657         <p>
 658          <code class="literal">statement_timestamp()</code>
 659          → <code class="returnvalue">2019-12-23 14:39:53.662522-05</code>
 660         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 661          <a id="id-1.5.8.15.6.2.2.36.1.1.1" class="indexterm"></a>
 662          <code class="function">timeofday</code> ( )
 663          → <code class="returnvalue">text</code>
 664         </p>
 665         <p>
 666          Current date and time
 667          (like <code class="function">clock_timestamp</code>, but as a <code class="type">text</code> string);
 668          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 669         </p>
 670         <p>
 671          <code class="literal">timeofday()</code>
 672          → <code class="returnvalue">Mon Dec 23 14:39:53.662522 2019 EST</code>
 673         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 674          <a id="id-1.5.8.15.6.2.2.37.1.1.1" class="indexterm"></a>
 675          <code class="function">transaction_timestamp</code> ( )
 676          → <code class="returnvalue">timestamp with time zone</code>
 677         </p>
 678         <p>
 679          Current date and time (start of current transaction);
 680          see <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-CURRENT" title="9.9.5. Current Date/Time">Section 9.9.5</a>
 681         </p>
 682         <p>
 683          <code class="literal">transaction_timestamp()</code>
 684          → <code class="returnvalue">2019-12-23 14:39:53.662522-05</code>
 685         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
 686          <a id="id-1.5.8.15.6.2.2.38.1.1.1" class="indexterm"></a>
 687          <code class="function">to_timestamp</code> ( <code class="type">double precision</code> )
 688          → <code class="returnvalue">timestamp with time zone</code>
 689         </p>
 690         <p>
 691          Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to
 692          timestamp with time zone
 693         </p>
 694         <p>
 695          <code class="literal">to_timestamp(1284352323)</code>
 696          → <code class="returnvalue">2010-09-13 04:32:03+00</code>
 697         </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
 698     <a id="id-1.5.8.15.7.1" class="indexterm"></a>
 699     In addition to these functions, the SQL <code class="literal">OVERLAPS</code> operator is
 700     supported:
 701 </p><pre class="synopsis">
 702 (<em class="replaceable"><code>start1</code></em>, <em class="replaceable"><code>end1</code></em>) OVERLAPS (<em class="replaceable"><code>start2</code></em>, <em class="replaceable"><code>end2</code></em>)
 703 (<em class="replaceable"><code>start1</code></em>, <em class="replaceable"><code>length1</code></em>) OVERLAPS (<em class="replaceable"><code>start2</code></em>, <em class="replaceable"><code>length2</code></em>)
 704 </pre><p>
 705     This expression yields true when two time periods (defined by their
 706     endpoints) overlap, false when they do not overlap.  The endpoints
 707     can be specified as pairs of dates, times, or time stamps; or as
 708     a date, time, or time stamp followed by an interval.  When a pair
 709     of values is provided, either the start or the end can be written
 710     first; <code class="literal">OVERLAPS</code> automatically takes the earlier value
 711     of the pair as the start.  Each time period is considered to
 712     represent the half-open interval <em class="replaceable"><code>start</code></em> <code class="literal">&lt;=</code>
 713     <em class="replaceable"><code>time</code></em> <code class="literal">&lt;</code> <em class="replaceable"><code>end</code></em>, unless
 714     <em class="replaceable"><code>start</code></em> and <em class="replaceable"><code>end</code></em> are equal in which case it
 715     represents that single time instant.  This means for instance that two
 716     time periods with only an endpoint in common do not overlap.
 717    </p><pre class="screen">
 718 SELECT (DATE '2001-02-16', DATE '2001-12-21') OVERLAPS
 719        (DATE '2001-10-30', DATE '2002-10-30');
 720 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">true</code>
 721 SELECT (DATE '2001-02-16', INTERVAL '100 days') OVERLAPS
 722        (DATE '2001-10-30', DATE '2002-10-30');
 723 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">false</code>
 724 SELECT (DATE '2001-10-29', DATE '2001-10-30') OVERLAPS
 725        (DATE '2001-10-30', DATE '2001-10-31');
 726 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">false</code>
 727 SELECT (DATE '2001-10-30', DATE '2001-10-30') OVERLAPS
 728        (DATE '2001-10-30', DATE '2001-10-31');
 729 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">true</code>
 730 </pre><p>
 731    When adding an <code class="type">interval</code> value to (or subtracting an
 732    <code class="type">interval</code> value from) a <code class="type">timestamp</code>
 733    or <code class="type">timestamp with time zone</code> value, the months, days, and
 734    microseconds fields of the <code class="type">interval</code> value are handled in turn.
 735    First, a nonzero months field advances or decrements the date of the
 736    timestamp by the indicated number of months, keeping the day of month the
 737    same unless it would be past the end of the new month, in which case the
 738    last day of that month is used.  (For example, March 31 plus 1 month
 739    becomes April 30, but March 31 plus 2 months becomes May 31.)
 740    Then the days field advances or decrements the date of the timestamp by
 741    the indicated number of days.  In both these steps the local time of day
 742    is kept the same.  Finally, if there is a nonzero microseconds field, it
 743    is added or subtracted literally.
 744    When doing arithmetic on a <code class="type">timestamp with time zone</code> value in
 745    a time zone that recognizes DST, this means that adding or subtracting
 746    (say) <code class="literal">interval '1 day'</code> does not necessarily have the
 747    same result as adding or subtracting <code class="literal">interval '24
 748    hours'</code>.
 749    For example, with the session time zone set
 750    to <code class="literal">America/Denver</code>:
 751 </p><pre class="screen">
 752 SELECT timestamp with time zone '2005-04-02 12:00:00-07' + interval '1 day';
 753 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2005-04-03 12:00:00-06</code>
 754 SELECT timestamp with time zone '2005-04-02 12:00:00-07' + interval '24 hours';
 755 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2005-04-03 13:00:00-06</code>
 756 </pre><p>
 757    This happens because an hour was skipped due to a change in daylight saving
 758    time at <code class="literal">2005-04-03 02:00:00</code> in time zone
 759    <code class="literal">America/Denver</code>.
 760   </p><p>
 761    Note there can be ambiguity in the <code class="literal">months</code> field returned by
 762    <code class="function">age</code> because different months have different numbers of
 763    days.  <span class="productname">PostgreSQL</span>'s approach uses the month from the
 764    earlier of the two dates when calculating partial months.  For example,
 765    <code class="literal">age('2004-06-01', '2004-04-30')</code> uses April to yield
 766    <code class="literal">1 mon 1 day</code>, while using May would yield <code class="literal">1 mon 2
 767    days</code> because May has 31 days, while April has only 30.
 768   </p><p>
 769    Subtraction of dates and timestamps can also be complex.  One conceptually
 770    simple way to perform subtraction is to convert each value to a number
 771    of seconds using <code class="literal">EXTRACT(EPOCH FROM ...)</code>, then subtract the
 772    results; this produces the
 773    number of <span class="emphasis"><em>seconds</em></span> between the two values.  This will adjust
 774    for the number of days in each month, timezone changes, and daylight
 775    saving time adjustments.  Subtraction of date or timestamp
 776    values with the <span class="quote">“<span class="quote"><code class="literal">-</code></span>”</span> operator
 777    returns the number of days (24-hours) and hours/minutes/seconds
 778    between the values, making the same adjustments.  The <code class="function">age</code>
 779    function returns years, months, days, and hours/minutes/seconds,
 780    performing field-by-field subtraction and then adjusting for negative
 781    field values.  The following queries illustrate the differences in these
 782    approaches.  The sample results were produced with <code class="literal">timezone
 783    = 'US/Eastern'</code>; there is a daylight saving time change between the
 784    two dates used:
 785   </p><pre class="screen">
 786 SELECT EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
 787        EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00');
 788 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">10537200.000000</code>
 789 SELECT (EXTRACT(EPOCH FROM timestamptz '2013-07-01 12:00:00') -
 790         EXTRACT(EPOCH FROM timestamptz '2013-03-01 12:00:00'))
 791         / 60 / 60 / 24;
 792 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">121.9583333333333333</code>
 793 SELECT timestamptz '2013-07-01 12:00:00' - timestamptz '2013-03-01 12:00:00';
 794 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">121 days 23:00:00</code>
 795 SELECT age(timestamptz '2013-07-01 12:00:00', timestamptz '2013-03-01 12:00:00');
 796 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">4 mons</code>
 797 </pre><div class="sect2" id="FUNCTIONS-DATETIME-EXTRACT"><div class="titlepage"><div><div><h3 class="title">9.9.1. <code class="function">EXTRACT</code>, <code class="function">date_part</code> <a href="#FUNCTIONS-DATETIME-EXTRACT" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.15.13.2" class="indexterm"></a><a id="id-1.5.8.15.13.3" class="indexterm"></a><pre class="synopsis">
 798 EXTRACT(<em class="replaceable"><code>field</code></em> FROM <em class="replaceable"><code>source</code></em>)
 799 </pre><p>
 800     The <code class="function">extract</code> function retrieves subfields
 801     such as year or hour from date/time values.
 802     <em class="replaceable"><code>source</code></em> must be a value expression of
 803     type <code class="type">timestamp</code>, <code class="type">date</code>, <code class="type">time</code>,
 804     or <code class="type">interval</code>.  (Timestamps and times can be with or
 805     without time zone.)
 806     <em class="replaceable"><code>field</code></em> is an identifier or
 807     string that selects what field to extract from the source value.
 808     Not all fields are valid for every input data type; for example, fields
 809     smaller than a day cannot be extracted from a <code class="type">date</code>, while
 810     fields of a day or more cannot be extracted from a <code class="type">time</code>.
 811     The <code class="function">extract</code> function returns values of type
 812     <code class="type">numeric</code>.
 813    </p><p>
 814     The following are valid field names:
 815
 816
 817     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">century</code></span></dt><dd><p>
 818         The century; for <code class="type">interval</code> values, the year field
 819         divided by 100
 820        </p><pre class="screen">
 821 SELECT EXTRACT(CENTURY FROM TIMESTAMP '2000-12-16 12:21:13');
 822 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">20</code>
 823 SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40');
 824 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">21</code>
 825 SELECT EXTRACT(CENTURY FROM DATE '0001-01-01 AD');
 826 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">1</code>
 827 SELECT EXTRACT(CENTURY FROM DATE '0001-12-31 BC');
 828 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">-1</code>
 829 SELECT EXTRACT(CENTURY FROM INTERVAL '2001 years');
 830 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">20</code>
 831 </pre></dd><dt><span class="term"><code class="literal">day</code></span></dt><dd><p>
 832         The day of the month (1–31); for <code class="type">interval</code>
 833         values, the number of days
 834        </p><pre class="screen">
 835 SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
 836 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">16</code>
 837 SELECT EXTRACT(DAY FROM INTERVAL '40 days 1 minute');
 838 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">40</code>
 839 </pre></dd><dt><span class="term"><code class="literal">decade</code></span></dt><dd><p>
 840         The year field divided by 10
 841        </p><pre class="screen">
 842 SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
 843 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">200</code>
 844 </pre></dd><dt><span class="term"><code class="literal">dow</code></span></dt><dd><p>
 845         The day of the week as Sunday (<code class="literal">0</code>) to
 846         Saturday (<code class="literal">6</code>)
 847        </p><pre class="screen">
 848 SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
 849 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">5</code>
 850 </pre><p>
 851         Note that <code class="function">extract</code>'s day of the week numbering
 852         differs from that of the <code class="function">to_char(...,
 853         'D')</code> function.
 854        </p></dd><dt><span class="term"><code class="literal">doy</code></span></dt><dd><p>
 855         The day of the year (1–365/366)
 856        </p><pre class="screen">
 857 SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
 858 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">47</code>
 859 </pre></dd><dt><span class="term"><code class="literal">epoch</code></span></dt><dd><p>
 860         For <code class="type">timestamp with time zone</code> values, the
 861         number of seconds since 1970-01-01 00:00:00 UTC (negative for
 862         timestamps before that);
 863         for <code class="type">date</code> and <code class="type">timestamp</code> values, the
 864         nominal number of seconds since 1970-01-01 00:00:00,
 865         without regard to timezone or daylight-savings rules;
 866         for <code class="type">interval</code> values, the total number
 867         of seconds in the interval
 868        </p><pre class="screen">
 869 SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40.12-08');
 870 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">982384720.120000</code>
 871 SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40.12');
 872 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">982355920.120000</code>
 873 SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
 874 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">442800.000000</code>
 875 </pre><p>
 876         You can convert an epoch value back to a <code class="type">timestamp with time zone</code>
 877         with <code class="function">to_timestamp</code>:
 878        </p><pre class="screen">
 879 SELECT to_timestamp(982384720.12);
 880 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-17 04:38:40.12+00</code>
 881 </pre><p>
 882         Beware that applying <code class="function">to_timestamp</code> to an epoch
 883         extracted from a <code class="type">date</code> or <code class="type">timestamp</code> value
 884         could produce a misleading result: the result will effectively
 885         assume that the original value had been given in UTC, which might
 886         not be the case.
 887        </p></dd><dt><span class="term"><code class="literal">hour</code></span></dt><dd><p>
 888         The hour field (0–23 in timestamps, unrestricted in
 889         intervals)
 890        </p><pre class="screen">
 891 SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
 892 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">20</code>
 893 </pre></dd><dt><span class="term"><code class="literal">isodow</code></span></dt><dd><p>
 894         The day of the week as Monday (<code class="literal">1</code>) to
 895         Sunday (<code class="literal">7</code>)
 896        </p><pre class="screen">
 897 SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
 898 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">7</code>
 899 </pre><p>
 900         This is identical to <code class="literal">dow</code> except for Sunday.  This
 901         matches the <acronym class="acronym">ISO</acronym> 8601 day of the week numbering.
 902        </p></dd><dt><span class="term"><code class="literal">isoyear</code></span></dt><dd><p>
 903         The <acronym class="acronym">ISO</acronym> 8601 week-numbering year that the date
 904         falls in
 905        </p><pre class="screen">
 906 SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01');
 907 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2005</code>
 908 SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
 909 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2006</code>
 910 </pre><p>
 911         Each <acronym class="acronym">ISO</acronym> 8601 week-numbering year begins with the
 912         Monday of the week containing the 4th of January, so in early
 913         January or late December the <acronym class="acronym">ISO</acronym> year may be
 914         different from the Gregorian year.  See the <code class="literal">week</code>
 915         field for more information.
 916        </p></dd><dt><span class="term"><code class="literal">julian</code></span></dt><dd><p>
 917         The <em class="firstterm">Julian Date</em> corresponding to the
 918         date or timestamp.  Timestamps
 919         that are not local midnight result in a fractional value.  See
 920         <a class="xref" href="datetime-julian-dates.html" title="B.7. Julian Dates">Section B.7</a> for more information.
 921        </p><pre class="screen">
 922 SELECT EXTRACT(JULIAN FROM DATE '2006-01-01');
 923 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2453737</code>
 924 SELECT EXTRACT(JULIAN FROM TIMESTAMP '2006-01-01 12:00');
 925 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2453737.50000000000000000000</code>
 926 </pre></dd><dt><span class="term"><code class="literal">microseconds</code></span></dt><dd><p>
 927         The seconds field, including fractional parts, multiplied by 1
 928         000 000;  note that this includes full seconds
 929        </p><pre class="screen">
 930 SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
 931 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">28500000</code>
 932 </pre></dd><dt><span class="term"><code class="literal">millennium</code></span></dt><dd><p>
 933         The millennium; for <code class="type">interval</code> values, the year field
 934         divided by 1000
 935        </p><pre class="screen">
 936 SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40');
 937 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">3</code>
 938 SELECT EXTRACT(MILLENNIUM FROM INTERVAL '2001 years');
 939 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2</code>
 940 </pre><p>
 941         Years in the 1900s are in the second millennium.
 942         The third millennium started January 1, 2001.
 943        </p></dd><dt><span class="term"><code class="literal">milliseconds</code></span></dt><dd><p>
 944         The seconds field, including fractional parts, multiplied by
 945         1000.  Note that this includes full seconds.
 946        </p><pre class="screen">
 947 SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
 948 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">28500.000</code>
 949 </pre></dd><dt><span class="term"><code class="literal">minute</code></span></dt><dd><p>
 950         The minutes field (0–59)
 951        </p><pre class="screen">
 952 SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
 953 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">38</code>
 954 </pre></dd><dt><span class="term"><code class="literal">month</code></span></dt><dd><p>
 955         The number of the month within the year (1–12);
 956         for <code class="type">interval</code> values, the number of months modulo 12
 957         (0–11)
 958        </p><pre class="screen">
 959 SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40');
 960 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2</code>
 961 SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months');
 962 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">3</code>
 963 SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months');
 964 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">1</code>
 965 </pre></dd><dt><span class="term"><code class="literal">quarter</code></span></dt><dd><p>
 966         The quarter of the year (1–4) that the date is in;
 967         for <code class="type">interval</code> values, the month field divided by 3
 968         plus 1
 969        </p><pre class="screen">
 970 SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40');
 971 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">1</code>
 972 SELECT EXTRACT(QUARTER FROM INTERVAL '1 year 6 months');
 973 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">3</code>
 974 </pre></dd><dt><span class="term"><code class="literal">second</code></span></dt><dd><p>
 975         The seconds field, including any fractional seconds
 976        </p><pre class="screen">
 977 SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40');
 978 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">40.000000</code>
 979 SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
 980 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">28.500000</code>
 981 </pre></dd><dt><span class="term"><code class="literal">timezone</code></span></dt><dd><p>
 982         The time zone offset from UTC, measured in seconds.  Positive values
 983         correspond to time zones east of UTC, negative values to
 984         zones west of UTC.  (Technically,
 985         <span class="productname">PostgreSQL</span> does not use UTC because
 986         leap seconds are not handled.)
 987        </p></dd><dt><span class="term"><code class="literal">timezone_hour</code></span></dt><dd><p>
 988         The hour component of the time zone offset
 989        </p></dd><dt><span class="term"><code class="literal">timezone_minute</code></span></dt><dd><p>
 990         The minute component of the time zone offset
 991        </p></dd><dt><span class="term"><code class="literal">week</code></span></dt><dd><p>
 992         The number of the <acronym class="acronym">ISO</acronym> 8601 week-numbering week of
 993         the year.  By definition, ISO weeks start on Mondays and the first
 994         week of a year contains January 4 of that year.  In other words, the
 995         first Thursday of a year is in week 1 of that year.
 996        </p><p>
 997         In the ISO week-numbering system, it is possible for early-January
 998         dates to be part of the 52nd or 53rd week of the previous year, and for
 999         late-December dates to be part of the first week of the next year.
1000         For example, <code class="literal">2005-01-01</code> is part of the 53rd week of year
1001         2004, and <code class="literal">2006-01-01</code> is part of the 52nd week of year
1002         2005, while <code class="literal">2012-12-31</code> is part of the first week of 2013.
1003         It's recommended to use the <code class="literal">isoyear</code> field together with
1004         <code class="literal">week</code> to get consistent results.
1005        </p><p>
1006         For <code class="type">interval</code> values, the week field is simply the number
1007         of integral days divided by 7.
1008        </p><pre class="screen">
1009 SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
1010 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">7</code>
1011 SELECT EXTRACT(WEEK FROM INTERVAL '13 days 24 hours');
1012 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">1</code>
1013 </pre></dd><dt><span class="term"><code class="literal">year</code></span></dt><dd><p>
1014         The year field.  Keep in mind there is no <code class="literal">0 AD</code>, so subtracting
1015         <code class="literal">BC</code> years from <code class="literal">AD</code> years should be done with care.
1016        </p><pre class="screen">
1017 SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
1018 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001</code>
1019 </pre></dd></dl></div><p>
1020    </p><p>
1021     When processing an <code class="type">interval</code> value,
1022     the <code class="function">extract</code> function produces field values that
1023     match the interpretation used by the interval output function.  This
1024     can produce surprising results if one starts with a non-normalized
1025     interval representation, for example:
1026 </p><pre class="screen">
1027 SELECT INTERVAL '80 minutes';
1028 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">01:20:00</code>
1029 SELECT EXTRACT(MINUTES FROM INTERVAL '80 minutes');
1030 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">20</code>
1031 </pre><p>
1032    </p><div class="note"><h3 class="title">Note</h3><p>
1033      When the input value is +/-Infinity, <code class="function">extract</code> returns
1034      +/-Infinity for monotonically-increasing fields (<code class="literal">epoch</code>,
1035      <code class="literal">julian</code>, <code class="literal">year</code>, <code class="literal">isoyear</code>,
1036      <code class="literal">decade</code>, <code class="literal">century</code>, and <code class="literal">millennium</code>
1037      for <code class="type">timestamp</code> inputs; <code class="literal">epoch</code>, <code class="literal">hour</code>,
1038      <code class="literal">day</code>, <code class="literal">year</code>, <code class="literal">decade</code>,
1039      <code class="literal">century</code>, and <code class="literal">millennium</code> for
1040      <code class="type">interval</code> inputs).
1041      For other fields, NULL is returned.  <span class="productname">PostgreSQL</span>
1042      versions before 9.6 returned zero for all cases of infinite input.
1043     </p></div><p>
1044     The <code class="function">extract</code> function is primarily intended
1045     for computational processing.  For formatting date/time values for
1046     display, see <a class="xref" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Section 9.8</a>.
1047    </p><p>
1048     The <code class="function">date_part</code> function is modeled on the traditional
1049     <span class="productname">Ingres</span> equivalent to the
1050     <acronym class="acronym">SQL</acronym>-standard function <code class="function">extract</code>:
1051 </p><pre class="synopsis">
1052 date_part('<em class="replaceable"><code>field</code></em>', <em class="replaceable"><code>source</code></em>)
1053 </pre><p>
1054     Note that here the <em class="replaceable"><code>field</code></em> parameter needs to
1055     be a string value, not a name.  The valid field names for
1056     <code class="function">date_part</code> are the same as for
1057     <code class="function">extract</code>.
1058     For historical reasons, the <code class="function">date_part</code> function
1059     returns values of type <code class="type">double precision</code>.  This can result in
1060     a loss of precision in certain uses.  Using <code class="function">extract</code>
1061     is recommended instead.
1062    </p><pre class="screen">
1063 SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40');
1064 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">16</code>
1065 SELECT date_part('hour', INTERVAL '4 hours 3 minutes');
1066 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">4</code>
1067 </pre></div><div class="sect2" id="FUNCTIONS-DATETIME-TRUNC"><div class="titlepage"><div><div><h3 class="title">9.9.2. <code class="function">date_trunc</code> <a href="#FUNCTIONS-DATETIME-TRUNC" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.15.14.2" class="indexterm"></a><p>
1068     The function <code class="function">date_trunc</code> is conceptually
1069     similar to the <code class="function">trunc</code> function for numbers.
1070    </p><p>
1071 </p><pre class="synopsis">
1072 date_trunc(<em class="replaceable"><code>field</code></em>, <em class="replaceable"><code>source</code></em> [<span class="optional">, <em class="replaceable"><code>time_zone</code></em> </span>])
1073 </pre><p>
1074     <em class="replaceable"><code>source</code></em> is a value expression of type
1075     <code class="type">timestamp</code>, <code class="type">timestamp with time zone</code>,
1076     or <code class="type">interval</code>.
1077     (Values of type <code class="type">date</code> and
1078     <code class="type">time</code> are cast automatically to <code class="type">timestamp</code> or
1079     <code class="type">interval</code>, respectively.)
1080     <em class="replaceable"><code>field</code></em> selects to which precision to
1081     truncate the input value.  The return value is likewise of type
1082     <code class="type">timestamp</code>, <code class="type">timestamp with time zone</code>,
1083     or <code class="type">interval</code>,
1084     and it has all fields that are less significant than the
1085     selected one set to zero (or one, for day and month).
1086    </p><p>
1087     Valid values for <em class="replaceable"><code>field</code></em> are:
1088     </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="literal">microseconds</code></td></tr><tr><td><code class="literal">milliseconds</code></td></tr><tr><td><code class="literal">second</code></td></tr><tr><td><code class="literal">minute</code></td></tr><tr><td><code class="literal">hour</code></td></tr><tr><td><code class="literal">day</code></td></tr><tr><td><code class="literal">week</code></td></tr><tr><td><code class="literal">month</code></td></tr><tr><td><code class="literal">quarter</code></td></tr><tr><td><code class="literal">year</code></td></tr><tr><td><code class="literal">decade</code></td></tr><tr><td><code class="literal">century</code></td></tr><tr><td><code class="literal">millennium</code></td></tr></table><p>
1089    </p><p>
1090     When the input value is of type <code class="type">timestamp with time zone</code>,
1091     the truncation is performed with respect to a particular time zone;
1092     for example, truncation to <code class="literal">day</code> produces a value that
1093     is midnight in that zone.  By default, truncation is done with respect
1094     to the current <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> setting, but the
1095     optional <em class="replaceable"><code>time_zone</code></em> argument can be provided
1096     to specify a different time zone.  The time zone name can be specified
1097     in any of the ways described in <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a>.
1098    </p><p>
1099     A time zone cannot be specified when processing <code class="type">timestamp without
1100     time zone</code> or <code class="type">interval</code> inputs.  These are always
1101     taken at face value.
1102    </p><p>
1103     Examples (assuming the local time zone is <code class="literal">America/New_York</code>):
1104 </p><pre class="screen">
1105 SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40');
1106 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 20:00:00</code>
1107 SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
1108 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-01-01 00:00:00</code>
1109 SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00');
1110 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 00:00:00-05</code>
1111 SELECT date_trunc('day', TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40+00', 'Australia/Sydney');
1112 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 08:00:00-05</code>
1113 SELECT date_trunc('hour', INTERVAL '3 days 02:47:33');
1114 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">3 days 02:00:00</code>
1115 </pre><p>
1116    </p></div><div class="sect2" id="FUNCTIONS-DATETIME-BIN"><div class="titlepage"><div><div><h3 class="title">9.9.3. <code class="function">date_bin</code> <a href="#FUNCTIONS-DATETIME-BIN" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.15.15.2" class="indexterm"></a><p>
1117     The function <code class="function">date_bin</code> <span class="quote">“<span class="quote">bins</span>”</span> the input
1118     timestamp into the specified interval (the <em class="firstterm">stride</em>)
1119     aligned with a specified origin.
1120    </p><p>
1121 </p><pre class="synopsis">
1122 date_bin(<em class="replaceable"><code>stride</code></em>, <em class="replaceable"><code>source</code></em>, <em class="replaceable"><code>origin</code></em>)
1123 </pre><p>
1124     <em class="replaceable"><code>source</code></em> is a value expression of type
1125     <code class="type">timestamp</code> or <code class="type">timestamp with time zone</code>.  (Values
1126     of type <code class="type">date</code> are cast automatically to
1127     <code class="type">timestamp</code>.)  <em class="replaceable"><code>stride</code></em> is a value
1128     expression of type <code class="type">interval</code>.  The return value is likewise
1129     of type <code class="type">timestamp</code> or <code class="type">timestamp with time zone</code>,
1130     and it marks the beginning of the bin into which the
1131     <em class="replaceable"><code>source</code></em> is placed.
1132    </p><p>
1133     Examples:
1134 </p><pre class="screen">
1135 SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01');
1136 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2020-02-11 15:30:00</code>
1137 SELECT date_bin('15 minutes', TIMESTAMP '2020-02-11 15:44:17', TIMESTAMP '2001-01-01 00:02:30');
1138 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2020-02-11 15:32:30</code>
1139 </pre><p>
1140    </p><p>
1141     In the case of full units (1 minute, 1 hour, etc.), it gives the same result as
1142     the analogous <code class="function">date_trunc</code> call, but the difference is
1143     that <code class="function">date_bin</code> can truncate to an arbitrary interval.
1144    </p><p>
1145     The <em class="parameter"><code>stride</code></em> interval must be greater than zero and
1146     cannot contain units of month or larger.
1147    </p></div><div class="sect2" id="FUNCTIONS-DATETIME-ZONECONVERT"><div class="titlepage"><div><div><h3 class="title">9.9.4. <code class="literal">AT TIME ZONE</code> and <code class="literal">AT LOCAL</code> <a href="#FUNCTIONS-DATETIME-ZONECONVERT" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.15.16.2" class="indexterm"></a><a id="id-1.5.8.15.16.3" class="indexterm"></a><a id="id-1.5.8.15.16.4" class="indexterm"></a><p>
1148     The <code class="literal">AT TIME ZONE</code> operator converts time
1149     stamp <span class="emphasis"><em>without</em></span> time zone to/from
1150     time stamp <span class="emphasis"><em>with</em></span> time zone, and
1151     <code class="type">time with time zone</code> values to different time
1152     zones. <a class="xref" href="functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT-TABLE" title="Table 9.34. AT TIME ZONE and AT LOCAL Variants">Table 9.34</a> shows its
1153     variants.
1154    </p><div class="table" id="FUNCTIONS-DATETIME-ZONECONVERT-TABLE"><p class="title"><strong>Table 9.34. <code class="literal">AT TIME ZONE</code> and <code class="literal">AT LOCAL</code> Variants</strong></p><div class="table-contents"><table class="table" summary="AT TIME ZONE and AT LOCAL Variants" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
1155          Operator
1156         </p>
1157         <p>
1158          Description
1159         </p>
1160         <p>
1161          Example(s)
1162         </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
1163          <code class="type">timestamp without time zone</code> <code class="literal">AT TIME ZONE</code> <em class="replaceable"><code>zone</code></em>
1164          → <code class="returnvalue">timestamp with time zone</code>
1165         </p>
1166         <p>
1167          Converts given time stamp <span class="emphasis"><em>without</em></span> time zone to
1168          time stamp <span class="emphasis"><em>with</em></span> time zone, assuming the given
1169          value is in the named time zone.
1170         </p>
1171         <p>
1172          <code class="literal">timestamp '2001-02-16 20:38:40' at time zone 'America/Denver'</code>
1173          → <code class="returnvalue">2001-02-17 03:38:40+00</code>
1174         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1175          <code class="type">timestamp without time zone</code> <code class="literal">AT LOCAL</code>
1176          → <code class="returnvalue">timestamp with time zone</code>
1177         </p>
1178         <p>
1179          Converts given time stamp <span class="emphasis"><em>without</em></span> time zone to
1180          time stamp <span class="emphasis"><em>with</em></span> the session's
1181          <code class="varname">TimeZone</code> value as time zone.
1182         </p>
1183         <p>
1184          <code class="literal">timestamp '2001-02-16 20:38:40' at local</code>
1185          → <code class="returnvalue">2001-02-17 03:38:40+00</code>
1186         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1187          <code class="type">timestamp with time zone</code> <code class="literal">AT TIME ZONE</code> <em class="replaceable"><code>zone</code></em>
1188          → <code class="returnvalue">timestamp without time zone</code>
1189         </p>
1190         <p>
1191          Converts given time stamp <span class="emphasis"><em>with</em></span> time zone to
1192          time stamp <span class="emphasis"><em>without</em></span> time zone, as the time would
1193          appear in that zone.
1194         </p>
1195         <p>
1196          <code class="literal">timestamp with time zone '2001-02-16 20:38:40-05' at time zone 'America/Denver'</code>
1197          → <code class="returnvalue">2001-02-16 18:38:40</code>
1198         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1199          <code class="type">timestamp with time zone</code> <code class="literal">AT LOCAL</code>
1200          → <code class="returnvalue">timestamp without time zone</code>
1201         </p>
1202         <p>
1203          Converts given time stamp <span class="emphasis"><em>with</em></span> time zone to
1204          time stamp <span class="emphasis"><em>without</em></span> time zone, as the time would
1205          appear with the session's <code class="varname">TimeZone</code> value as time zone.
1206         </p>
1207         <p>
1208          <code class="literal">timestamp with time zone '2001-02-16 20:38:40-05' at local</code>
1209          → <code class="returnvalue">2001-02-16 18:38:40</code>
1210         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1211          <code class="type">time with time zone</code> <code class="literal">AT TIME ZONE</code> <em class="replaceable"><code>zone</code></em>
1212          → <code class="returnvalue">time with time zone</code>
1213         </p>
1214         <p>
1215          Converts given time <span class="emphasis"><em>with</em></span> time zone to a new time
1216          zone.  Since no date is supplied, this uses the currently active UTC
1217          offset for the named destination zone.
1218         </p>
1219         <p>
1220          <code class="literal">time with time zone '05:34:17-05' at time zone 'UTC'</code>
1221          → <code class="returnvalue">10:34:17+00</code>
1222         </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1223          <code class="type">time with time zone</code> <code class="literal">AT LOCAL</code>
1224          → <code class="returnvalue">time with time zone</code>
1225         </p>
1226         <p>
1227          Converts given time <span class="emphasis"><em>with</em></span> time zone to a new time
1228          zone.  Since no date is supplied, this uses the currently active UTC
1229          offset for the session's <code class="varname">TimeZone</code> value.
1230         </p>
1231         <p>
1232          Assuming the session's <code class="varname">TimeZone</code> is set to <code class="literal">UTC</code>:
1233         </p>
1234         <p>
1235          <code class="literal">time with time zone '05:34:17-05' at local</code>
1236          → <code class="returnvalue">10:34:17+00</code>
1237         </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
1238     In these expressions, the desired time zone <em class="replaceable"><code>zone</code></em> can be
1239     specified either as a text value (e.g., <code class="literal">'America/Los_Angeles'</code>)
1240     or as an interval (e.g., <code class="literal">INTERVAL '-08:00'</code>).
1241     In the text case, a time zone name can be specified in any of the ways
1242     described in <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a>.
1243     The interval case is only useful for zones that have fixed offsets from
1244     UTC, so it is not very common in practice.
1245    </p><p>
1246     The syntax <code class="literal">AT LOCAL</code> may be used as shorthand for
1247     <code class="literal">AT TIME ZONE <em class="replaceable"><code>local</code></em></code>, where
1248     <em class="replaceable"><code>local</code></em> is the session's
1249     <code class="varname">TimeZone</code> value.
1250    </p><p>
1251     Examples (assuming the current <a class="xref" href="runtime-config-client.html#GUC-TIMEZONE">TimeZone</a> setting
1252     is <code class="literal">America/Los_Angeles</code>):
1253 </p><pre class="screen">
1254 SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'America/Denver';
1255 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 19:38:40-08</code>
1256 SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'America/Denver';
1257 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 18:38:40</code>
1258 SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'America/Chicago';
1259 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 05:38:40</code>
1260 SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT LOCAL;
1261 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 17:38:40</code>
1262 SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE '+05';
1263 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2001-02-16 20:38:40</code>
1264 SELECT TIME WITH TIME ZONE '20:38:40-05' AT LOCAL;
1265 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">17:38:40</code>
1266 </pre><p>
1267     The first example adds a time zone to a value that lacks it, and
1268     displays the value using the current <code class="varname">TimeZone</code>
1269     setting.  The second example shifts the time stamp with time zone value
1270     to the specified time zone, and returns the value without a time zone.
1271     This allows storage and display of values different from the current
1272     <code class="varname">TimeZone</code> setting.  The third example converts
1273     Tokyo time to Chicago time.  The fourth example shifts the time stamp
1274     with time zone value to the time zone currently specified by the
1275     <code class="varname">TimeZone</code> setting and returns the value without a
1276     time zone.  The fifth example demonstrates that the sign in a POSIX-style
1277     time zone specification has the opposite meaning of the sign in an
1278     ISO-8601 datetime literal, as described in <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a>
1279     and <a class="xref" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Appendix B</a>.
1280    </p><p>
1281     The sixth example is a cautionary tale. Due to the fact that there is no
1282     date associated with the input value, the conversion is made using the
1283     current date of the session. Therefore, this static example may show a wrong
1284     result depending on the time of the year it is viewed because
1285     <code class="literal">'America/Los_Angeles'</code> observes Daylight Savings Time.
1286    </p><p>
1287     The function <code class="literal"><code class="function">timezone</code>(<em class="replaceable"><code>zone</code></em>,
1288     <em class="replaceable"><code>timestamp</code></em>)</code> is equivalent to the SQL-conforming construct
1289     <code class="literal"><em class="replaceable"><code>timestamp</code></em> AT TIME ZONE
1290     <em class="replaceable"><code>zone</code></em></code>.
1291    </p><p>
1292     The function <code class="literal"><code class="function">timezone</code>(<em class="replaceable"><code>zone</code></em>,
1293     <em class="replaceable"><code>time</code></em>)</code> is equivalent to the SQL-conforming construct
1294     <code class="literal"><em class="replaceable"><code>time</code></em> AT TIME ZONE
1295     <em class="replaceable"><code>zone</code></em></code>.
1296    </p><p>
1297     The function <code class="literal"><code class="function">timezone</code>(<em class="replaceable"><code>timestamp</code></em>)</code>
1298     is equivalent to the SQL-conforming construct <code class="literal"><em class="replaceable"><code>timestamp</code></em>
1299     AT LOCAL</code>.
1300    </p><p>
1301     The function <code class="literal"><code class="function">timezone</code>(<em class="replaceable"><code>time</code></em>)</code>
1302     is equivalent to the SQL-conforming construct <code class="literal"><em class="replaceable"><code>time</code></em>
1303     AT LOCAL</code>.
1304    </p></div><div class="sect2" id="FUNCTIONS-DATETIME-CURRENT"><div class="titlepage"><div><div><h3 class="title">9.9.5. Current Date/Time <a href="#FUNCTIONS-DATETIME-CURRENT" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.15.17.2" class="indexterm"></a><a id="id-1.5.8.15.17.3" class="indexterm"></a><p>
1305     <span class="productname">PostgreSQL</span> provides a number of functions
1306     that return values related to the current date and time.  These
1307     SQL-standard functions all return values based on the start time of
1308     the current transaction:
1309 </p><pre class="synopsis">
1310 CURRENT_DATE
1311 CURRENT_TIME
1312 CURRENT_TIMESTAMP
1313 CURRENT_TIME(<em class="replaceable"><code>precision</code></em>)
1314 CURRENT_TIMESTAMP(<em class="replaceable"><code>precision</code></em>)
1315 LOCALTIME
1316 LOCALTIMESTAMP
1317 LOCALTIME(<em class="replaceable"><code>precision</code></em>)
1318 LOCALTIMESTAMP(<em class="replaceable"><code>precision</code></em>)
1319 </pre><p>
1320     </p><p>
1321      <code class="function">CURRENT_TIME</code> and
1322      <code class="function">CURRENT_TIMESTAMP</code> deliver values with time zone;
1323      <code class="function">LOCALTIME</code> and
1324      <code class="function">LOCALTIMESTAMP</code> deliver values without time zone.
1325     </p><p>
1326      <code class="function">CURRENT_TIME</code>,
1327      <code class="function">CURRENT_TIMESTAMP</code>,
1328      <code class="function">LOCALTIME</code>, and
1329      <code class="function">LOCALTIMESTAMP</code>
1330      can optionally take
1331      a precision parameter, which causes the result to be rounded
1332      to that many fractional digits in the seconds field.  Without a precision parameter,
1333      the result is given to the full available precision.
1334     </p><p>
1335     Some examples:
1336 </p><pre class="screen">
1337 SELECT CURRENT_TIME;
1338 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">14:39:53.662522-05</code>
1339 SELECT CURRENT_DATE;
1340 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2019-12-23</code>
1341 SELECT CURRENT_TIMESTAMP;
1342 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2019-12-23 14:39:53.662522-05</code>
1343 SELECT CURRENT_TIMESTAMP(2);
1344 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2019-12-23 14:39:53.66-05</code>
1345 SELECT LOCALTIMESTAMP;
1346 <em class="lineannotation"><span class="lineannotation">Result: </span></em><code class="computeroutput">2019-12-23 14:39:53.662522</code>
1347 </pre><p>
1348    </p><p>
1349     Since these functions return
1350     the start time of the current transaction, their values do not
1351     change during the transaction. This is considered a feature:
1352     the intent is to allow a single transaction to have a consistent
1353     notion of the <span class="quote">“<span class="quote">current</span>”</span> time, so that multiple
1354     modifications within the same transaction bear the same
1355     time stamp.
1356    </p><div class="note"><h3 class="title">Note</h3><p>
1357      Other database systems might advance these values more
1358      frequently.
1359     </p></div><p>
1360     <span class="productname">PostgreSQL</span> also provides functions that
1361     return the start time of the current statement, as well as the actual
1362     current time at the instant the function is called.  The complete list
1363     of non-SQL-standard time functions is:
1364 </p><pre class="synopsis">
1365 transaction_timestamp()
1366 statement_timestamp()
1367 clock_timestamp()
1368 timeofday()
1369 now()
1370 </pre><p>
1371    </p><p>
1372     <code class="function">transaction_timestamp()</code> is equivalent to
1373     <code class="function">CURRENT_TIMESTAMP</code>, but is named to clearly reflect
1374     what it returns.
1375     <code class="function">statement_timestamp()</code> returns the start time of the current
1376     statement (more specifically, the time of receipt of the latest command
1377     message from the client).
1378     <code class="function">statement_timestamp()</code> and <code class="function">transaction_timestamp()</code>
1379     return the same value during the first statement of a transaction, but might
1380     differ during subsequent statements.
1381     <code class="function">clock_timestamp()</code> returns the actual current time, and
1382     therefore its value changes even within a single SQL statement.
1383     <code class="function">timeofday()</code> is a historical
1384     <span class="productname">PostgreSQL</span> function.  Like
1385     <code class="function">clock_timestamp()</code>, it returns the actual current time,
1386     but as a formatted <code class="type">text</code> string rather than a <code class="type">timestamp
1387     with time zone</code> value.
1388     <code class="function">now()</code> is a traditional <span class="productname">PostgreSQL</span>
1389     equivalent to <code class="function">transaction_timestamp()</code>.
1390    </p><p>
1391     All the date/time data types also accept the special literal value
1392     <code class="literal">now</code> to specify the current date and time (again,
1393     interpreted as the transaction start time).  Thus,
1394     the following three all return the same result:
1395 </p><pre class="programlisting">
1396 SELECT CURRENT_TIMESTAMP;
1397 SELECT now();
1398 SELECT TIMESTAMP 'now';  -- but see tip below
1399 </pre><p>
1400    </p><div class="tip"><h3 class="title">Tip</h3><p>
1401       Do not use the third form when specifying a value to be evaluated later,
1402       for example in a <code class="literal">DEFAULT</code> clause for a table column.
1403       The system will convert <code class="literal">now</code>
1404       to a <code class="type">timestamp</code> as soon as the constant is parsed, so that when
1405       the default value is needed,
1406       the time of the table creation would be used!  The first two
1407       forms will not be evaluated until the default value is used,
1408       because they are function calls.  Thus they will give the desired
1409       behavior of defaulting to the time of row insertion.
1410       (See also <a class="xref" href="datatype-datetime.html#DATATYPE-DATETIME-SPECIAL-VALUES" title="8.5.1.4. Special Values">Section 8.5.1.4</a>.)
1411      </p></div></div><div class="sect2" id="FUNCTIONS-DATETIME-DELAY"><div class="titlepage"><div><div><h3 class="title">9.9.6. Delaying Execution <a href="#FUNCTIONS-DATETIME-DELAY" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.15.18.2" class="indexterm"></a><a id="id-1.5.8.15.18.3" class="indexterm"></a><a id="id-1.5.8.15.18.4" class="indexterm"></a><a id="id-1.5.8.15.18.5" class="indexterm"></a><a id="id-1.5.8.15.18.6" class="indexterm"></a><p>
1412     The following functions are available to delay execution of the server
1413     process:
1414 </p><pre class="synopsis">
1415 pg_sleep ( <code class="type">double precision</code> )
1416 pg_sleep_for ( <code class="type">interval</code> )
1417 pg_sleep_until ( <code class="type">timestamp with time zone</code> )
1418 </pre><p>
1419
1420     <code class="function">pg_sleep</code> makes the current session's process
1421     sleep until the given number of seconds have
1422     elapsed.  Fractional-second delays can be specified.
1423     <code class="function">pg_sleep_for</code> is a convenience function to
1424     allow the sleep time to be specified as an <code class="type">interval</code>.
1425     <code class="function">pg_sleep_until</code> is a convenience function for when
1426     a specific wake-up time is desired.
1427     For example:
1428
1429 </p><pre class="programlisting">
1430 SELECT pg_sleep(1.5);
1431 SELECT pg_sleep_for('5 minutes');
1432 SELECT pg_sleep_until('tomorrow 03:00');
1433 </pre><p>
1434    </p><div class="note"><h3 class="title">Note</h3><p>
1435       The effective resolution of the sleep interval is platform-specific;
1436       0.01 seconds is a common value.  The sleep delay will be at least as long
1437       as specified. It might be longer depending on factors such as server load.
1438       In particular, <code class="function">pg_sleep_until</code> is not guaranteed to
1439       wake up exactly at the specified time, but it will not wake up any earlier.
1440      </p></div><div class="warning"><h3 class="title">Warning</h3><p>
1441       Make sure that your session does not hold more locks than necessary
1442       when calling <code class="function">pg_sleep</code> or its variants.  Otherwise
1443       other sessions might have to wait for your sleeping process, slowing down
1444       the entire system.
1445      </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-formatting.html" title="9.8. Data Type Formatting Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-enum.html" title="9.10. Enum Support Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.8. Data Type Formatting Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.10. Enum Support Functions</td></tr></table></div></body></html>