datatype.sgml

PostgreSQL7.4.6 for Linux

      <primary>time</primary>
     </indexterm>
     <indexterm>
      <primary>time without time zone</primary>
     </indexterm>
     <indexterm>
      <primary>time with time zone</primary>
     </indexterm>

     <para>
      The time-of-day types are <type>time [
      (<replaceable>p</replaceable>) ] without time zone</type> and
      <type>time [ (<replaceable>p</replaceable>) ] with time
      zone</type>.  Writing just <type>time</type> is equivalent to
      <type>time without time zone</type>.
     </para>

     <para>
      Valid input for these types consists of a time of day followed
      by an optional time zone. (See <xref
      linkend="datatype-datetime-time-table"> 
      and <xref linkend="datatype-timezone-table">.)  If a time zone is
      specified in the input for <type>time without time zone</type>,
      it is silently ignored.
     </para>

      <table id="datatype-datetime-time-table">
       <title>Time Input</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Example</entry>
          <entry>Description</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><literal>04:05:06.789</literal></entry>
          <entry>ISO 8601</entry>
         </row>
         <row>
          <entry><literal>04:05:06</literal></entry>
          <entry>ISO 8601</entry>
         </row>
         <row>
          <entry><literal>04:05</literal></entry>
          <entry>ISO 8601</entry>
         </row>
         <row>
          <entry><literal>040506</literal></entry>
          <entry>ISO 8601</entry>
         </row>
         <row>
          <entry><literal>04:05 AM</literal></entry>
          <entry>same as 04:05; AM does not affect value</entry>
         </row>
         <row>
          <entry><literal>04:05 PM</literal></entry>
          <entry>same as 16:05; input hour must be <= 12</entry>
         </row>
         <row>
          <entry><literal>04:05:06.789-8</literal></entry>
          <entry>ISO 8601</entry>
         </row>
         <row>
          <entry><literal>04:05:06-08:00</literal></entry>
          <entry>ISO 8601</entry>
         </row>
         <row>
          <entry><literal>04:05-08:00</literal></entry>
          <entry>ISO 8601</entry>
         </row>
         <row>
          <entry><literal>040506-08</literal></entry>
          <entry>ISO 8601</entry>
         </row>
         <row>
          <entry><literal>04:05:06 PST</literal></entry>
          <entry>time zone specified by name</entry>
         </row>
        </tbody>
       </tgroup>
      </table>

      <table tocentry="1" id="datatype-timezone-table">
       <title>Time Zone Input</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Example</entry>
          <entry>Description</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><literal>PST</literal></entry>
          <entry>Pacific Standard Time</entry>
         </row>
         <row>
          <entry><literal>-8:00</literal></entry>
          <entry>ISO-8601 offset for PST</entry>
         </row>
         <row>
          <entry><literal>-800</literal></entry>
          <entry>ISO-8601 offset for PST</entry>
         </row>
         <row>
          <entry><literal>-8</literal></entry>
          <entry>ISO-8601 offset for PST</entry>
         </row>
         <row>
          <entry><literal>zulu</literal></entry>
          <entry>Military abbreviation for UTC</entry>
         </row>
         <row>
          <entry><literal>z</literal></entry>
          <entry>Short form of <literal>zulu</literal></entry>
         </row>
        </tbody>
       </tgroup>
      </table>
    </sect3>

    <sect3>
    <title>Time Stamps</title>

    <indexterm>
     <primary>timestamp</primary>
    </indexterm>

    <indexterm>
     <primary>timestamp with time zone</primary>
    </indexterm>

    <indexterm>
     <primary>timestamp without time zone</primary>
    </indexterm>

     <para>
      Valid input for the time stamp types consists of a concatenation
      of a date and a time, followed by an optional
      <literal>AD</literal> or <literal>BC</literal>, followed by an
      optional time zone. Thus

<programlisting>
1999-01-08 04:05:06
</programlisting>
      and
<programlisting>
1999-01-08 04:05:06 -8:00
</programlisting>

      are valid values, which follow the <acronym>ISO</acronym> 8601
      standard.  In addition, the wide-spread format

<programlisting>
January 8 04:05:06 1999 PST
</programlisting>
      is supported.
     </para>

     <para>
      For <type>timestamp [without time zone]</type>, any explicit time
      zone specified in the input is silently ignored. That is, the
      resulting date/time value is derived from the explicit date/time
      fields in the input value, and is not adjusted for time zone.
     </para>

     <para>
      For <type>timestamp with time zone</type>, the internally stored
      value is always in UTC (Universal
      Coordinated Time, traditionally known as Greenwich Mean Time,
      <acronym>GMT</>).  An input value that has an explicit
      time zone specified is converted to UTC using the appropriate offset
      for that time zone.  If no time zone is stated in the input string,
      then it is assumed to be in the time zone indicated by the system's
      <varname>timezone</> parameter, and is converted to UTC using the
      offset for the <varname>timezone</> zone.
     </para>

     <para>
      When a <type>timestamp with time
      zone</type> value is output, it is always converted from UTC to the
      current <varname>timezone</> zone, and displayed as local time in that
      zone.  To see the time in another time zone, either change
      <varname>timezone</> or use the <literal>AT TIME ZONE</> construct
      (see <xref linkend="functions-datetime-zoneconvert">).
     </para>

     <para>
      Conversions between <type>timestamp without time zone</type> and
      <type>timestamp with time zone</type> normally assume that the
      <type>timestamp without time zone</type> value should be taken or given
      as <varname>timezone</> local time.  A different zone reference can
      be specified for the conversion using <literal>AT TIME ZONE</>.
     </para>
    </sect3>

    <sect3>
     <title>Intervals</title>

     <indexterm>
      <primary>interval</primary>
     </indexterm>

      <para>
       <type>interval</type> values can be written with the following syntax:

<programlisting>
<optional>@</> <replaceable>quantity</> <replaceable>unit</> <optional><replaceable>quantity</> <replaceable>unit</>...</> <optional><replaceable>direction</></optional>
</programlisting>

      Where: <replaceable>quantity</> is a number (possibly signed);
      <replaceable>unit</> is <literal>second</literal>,
      <literal>minute</literal>, <literal>hour</literal>, <literal>day</literal>,
      <literal>week</literal>, <literal>month</literal>, <literal>year</literal>,
      <literal>decade</literal>, <literal>century</literal>, <literal>millennium</literal>,
      or abbreviations or plurals of these units;
      <replaceable>direction</> can be <literal>ago</literal> or
      empty.  The at sign (<literal>@</>) is optional noise.  The amounts
      of different units are implicitly added up with appropriate
      sign accounting.
     </para>

     <para>
      Quantities of days, hours, minutes, and seconds can be specified without
      explicit unit markings.  For example, <literal>'1 12:59:10'</> is read
      the same as <literal>'1 day 12 hours 59 min 10 sec'</>.
     </para>

     <para>
      The optional precision
      <replaceable>p</replaceable> should be between 0 and 6, and
      defaults to the precision of the input literal.
     </para>
    </sect3>

    <sect3>
     <title>Special Values</title>

     <indexterm>
      <primary>time</primary>
      <secondary>constants</secondary>
     </indexterm>

     <indexterm>
      <primary>date</primary>
      <secondary>constants</secondary>
     </indexterm>

     <para>
      The following <acronym>SQL</acronym>-compatible functions can be
      used as date or time values for the corresponding data type: 
      <literal>CURRENT_DATE</literal>, <literal>CURRENT_TIME</literal>, 
      <literal>CURRENT_TIMESTAMP</literal>, <literal>LOCALTIME</literal>, 
      <literal>LOCALTIMESTAMP</literal>.  The latter four accept an 
      optional precision specification.  (See also <xref 
      linkend="functions-datetime-current">.)
     </para>

     <para>
      <productname>PostgreSQL</productname> also supports several
      special date/time input values for convenience, as shown in <xref
      linkend="datatype-datetime-special-table">.  The values
      <literal>infinity</literal> and <literal>-infinity</literal>
      are specially represented inside the system and will be displayed
      the same way; but the others are simply notational shorthands
      that will be converted to ordinary date/time values when read.
      All of these values are treated as normal constants and need to be
      written in single quotes.
     </para>

      <table id="datatype-datetime-special-table">
       <title>Special Date/Time Inputs</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Input String</entry>
          <entry>Valid Types</entry>
          <entry>Description</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry><literal>epoch</literal></entry>
          <entry><type>date</type>, <type>timestamp</type></entry>
          <entry>1970-01-01 00:00:00+00 (Unix system time zero)</entry>
         </row>
         <row>
          <entry><literal>infinity</literal></entry>
          <entry><type>timestamp</type></entry>
          <entry>later than all other time stamps</entry>
         </row>
         <row>
          <entry><literal>-infinity</literal></entry>
          <entry><type>timestamp</type></entry>
          <entry>earlier than all other time stamps</entry>
         </row>
         <row>
          <entry><literal>now</literal></entry>
          <entry><type>date</type>, <type>time</type>, <type>timestamp</type></entry>
          <entry>current transaction's start time</entry>
         </row>
         <row>
          <entry><literal>today</literal></entry>
          <entry><type>date</type>, <type>timestamp</type></entry>
          <entry>midnight today</entry>
         </row>
         <row>
          <entry><literal>tomorrow</literal></entry>
          <entry><type>date</type>, <type>timestamp</type></entry>
          <entry>midnight tomorrow</entry>
         </row>
         <row>
          <entry><literal>yesterday</literal></entry>
          <entry><type>date</type>, <type>timestamp</type></entry>
          <entry>midnight yesterday</entry>
         </row>
         <row>
          <entry><literal>allballs</literal></entry>
          <entry><type>time</type></entry>
          <entry>00:00:00.00 UTC</entry>
         </row>
        </tbody>
       </tgroup>
      </table>

    </sect3>
   </sect2>

   <sect2 id="datatype-datetime-output">
    <title>Date/Time Output</title>

    <indexterm>
     <primary>date</primary>
     <secondary>output format</secondary>
     <seealso>formatting</seealso>
    </indexterm>

    <indexterm>
     <primary>time</primary>
     <secondary>output format</secondary>
     <seealso>formatting</seealso>
    </indexterm>

    <para>
     The output format of the date/time types can be set to one of the four
     styles ISO 8601,
     <acronym>SQL</acronym> (Ingres), traditional POSTGRES, and
     German, using the command <literal>SET datestyle</literal>.  The default
     is the <acronym>ISO</acronym> format.  (The
     <acronym>SQL</acronym> standard requires the use of the ISO 8601
     format.  The name of the <quote>SQL</quote> output format is a
     historical accident.)  <xref
     linkend="datatype-datetime-output-table"> shows examples of each
     output style.  The output of the <type>date</type> and
     <type>time</type> types is of course only the date or time part
     in accordance with the given examples.
    </para>

     <table id="datatype-datetime-output-table">
      <title>Date/Time Output Styles</title>
      <tgroup cols="3">
       <thead>
        <row>
         <entry>Style Specification</entry>
         <entry>Description</entry>
         <entry>Example</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>ISO</entry>
         <entry>ISO 8601/SQL standard</entry>
         <entry>1997-12-17 07:37:16-08</entry>
        </row>
        <row>
         <entry>SQL</entry>
         <entry>traditional style</entry>
         <entry>12/17/1997 07:37:16.00 PST</entry>
        </row>
        <row>
         <entry>POSTGRES</entry>
         <entry>original style</entry>
         <entry>Wed Dec 17 07:37:16 1997 PST</entry>
        </row>
        <row>