← Back to branch summary

~ubuntu-branches/ubuntu/lucid/postgresql-8.4/lucid-proposed

« back to all changes in this revision

Viewing changes to doc/src/sgml/datatype.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2009-07-11 16:59:35 UTC
  • mfrom: (5.1.1 karmic)
  • Revision ID: james.westby@ubuntu.com-20090711165935-jfwin6gfrxf0gfsi
Tags: 8.4.0-2
http://bugs.debian.org/536139
* debian/libpq-dev.install: Ship catalog/genbki.h. (Closes: #536139)
* debian/rules: Drop --enable-cassert for final release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/datatype.sgml
1
 
<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.237 2009/04/27 16:27:35 momjian Exp $ -->
 
1
<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.239 2009/06/17 21:58:49 tgl Exp $ -->
2
2
 
3
3
 <chapter id="datatype">
4
4
  <title id="datatype-title">Data Types</title>
290
290
   to <productname>PostgreSQL</productname>, such as geometric
291
291
   paths, or have several possible formats, such as the date
292
292
   and time types.
293
 
   Some of the input and output functions are not invertible, i.e.
 
293
   Some of the input and output functions are not invertible, i.e.,
294
294
   the result of an output function might lose accuracy when compared to
295
295
   the original input.
296
296
  </para>
441
441
 
442
442
    <para>
443
443
     On very minimal operating systems the <type>bigint</type> type
444
 
     might not function correctly because it relies on compiler support
 
444
     might not function correctly, because it relies on compiler support
445
445
     for eight-byte integers.  On such machines, <type>bigint</type>
446
 
     acts the same as <type>integer</type> (but still takes up eight
447
 
     bytes of storage).  (We are not aware of any
448
 
     platform where this is true.)
 
446
     acts the same as <type>integer</type>, but still takes up eight
 
447
     bytes of storage.  (We are not aware of any modern
 
448
     platform where this is the case.)
449
449
    </para>
450
450
 
451
451
    <para>
453
453
     <type>integer</type> (or <type>int</type>),
454
454
     <type>smallint</type>, and <type>bigint</type>.  The
455
455
     type names <type>int2</type>, <type>int4</type>, and
456
 
     <type>int8</type> are extensions, which are also used by
 
456
     <type>int8</type> are extensions, which are also used by some
457
457
     other <acronym>SQL</acronym> database systems.
458
458
    </para>
459
459
 
481
481
     especially recommended for storing monetary amounts and other
482
482
     quantities where exactness is required. However, arithmetic on
483
483
     <type>numeric</type> values is very slow compared to the integer
484
 
     and floating-point types described in the next section.
 
484
     types, or to the floating-point types described in the next section.
485
485
    </para>
486
486
 
487
487
    <para>
681
681
     <quote>not-a-number</quote>, respectively.  (On a machine whose
682
682
     floating-point arithmetic does not follow IEEE 754, these values
683
683
     will probably not work as expected.)  When writing these values
684
 
     as constants in a SQL command, you must put quotes around them,
 
684
     as constants in an SQL command, you must put quotes around them,
685
685
     for example <literal>UPDATE table SET x = 'Infinity'</>.  On input,
686
686
     these strings are recognized in a case-insensitive manner.
687
687
    </para>
785
785
 
786
786
     Thus, we have created an integer column and arranged for its default
787
787
     values to be assigned from a sequence generator.  A <literal>NOT NULL</>
788
 
     constraint is applied to ensure that a null value cannot be explicitly
 
788
     constraint is applied to ensure that a null value cannot be
789
789
     inserted.  (In most cases you would also want to attach a
790
790
     <literal>UNIQUE</> or <literal>PRIMARY KEY</> constraint to prevent
791
791
     duplicate values from being inserted by accident, but this is
798
798
      Prior to <productname>PostgreSQL</productname> 7.3, <type>serial</type>
799
799
      implied <literal>UNIQUE</literal>.  This is no longer automatic.  If
800
800
      you wish a serial column to have a unique constraint or be a
801
 
      primary key, it must now be specified just like
 
801
      primary key, it must now be specified, just like
802
802
      any other data type.
803
803
     </para>
804
804
    </note>
837
837
   <para>
838
838
    The <type>money</type> type stores a currency amount with a fixed
839
839
    fractional precision; see <xref
840
 
    linkend="datatype-money-table">.  The fractional precision
841
 
    is controlled by the database locale.
 
840
    linkend="datatype-money-table">.  The fractional precision is
 
841
    determined by the database's <xref linkend="guc-lc-monetary"> setting.
842
842
    Input is accepted in a variety of formats, including integer and
843
843
    floating-point literals, as well as typical
844
844
    currency formatting, such as <literal>'$1,000.00'</literal>.
845
845
    Output is generally in the latter form but depends on the locale.
846
846
    Non-quoted numeric values can be converted to <type>money</type> by
847
847
    casting the numeric value to <type>text</type> and then
848
 
    <type>money</type>:
 
848
    <type>money</type>, for example:
849
849
<programlisting>
850
850
SELECT 1234::text::money;
851
851
</programlisting>
961
961
    <type>character varying(<replaceable>n</>)</type> and
962
962
    <type>character(<replaceable>n</>)</type>, where <replaceable>n</>
963
963
    is a positive integer.  Both of these types can store strings up to
964
 
    <replaceable>n</> characters in length (not bytes).  An attempt to store a
 
964
    <replaceable>n</> characters (not bytes) in length.  An attempt to store a
965
965
    longer string into a column of these types will result in an
966
966
    error, unless the excess characters are all spaces, in which case
967
967
    the string will be truncated to the maximum length. (This somewhat
1033
1033
 
1034
1034
   <tip>
1035
1035
    <para>
1036
 
     There is no performance difference between these three types,
 
1036
     There is no performance difference among these three types,
1037
1037
     apart from increased storage space when using the blank-padded
1038
1038
     type, and a few extra CPU cycles to check the length when storing into
1039
1039
     a length-constrained column.  While
1040
1040
     <type>character(<replaceable>n</>)</type> has performance
1041
1041
     advantages in some other database systems, there is no such advantage in
1042
 
     <productname>PostgreSQL</productname>.  In most situations
 
1042
     <productname>PostgreSQL</productname>; in fact
 
1043
     <type>character(<replaceable>n</>)</type> is usually the slowest of
 
1044
     the three because of its additional storage costs.  In most situations
1043
1045
     <type>text</type> or <type>character varying</type> should be used
1044
1046
     instead.
1045
1047
    </para>
1583
1585
<synopsis>
1584
1586
<replaceable>type</replaceable> [ (<replaceable>p</replaceable>) ] '<replaceable>value</replaceable>'
1585
1587
</synopsis>
1586
 
     where <replaceable>p</replaceable> is an optional precision corresponding to the number of
 
1588
     where <replaceable>p</replaceable> is an optional precision
 
1589
     specification giving the number of
1587
1590
     fractional digits in the seconds field. Precision can be
1588
1591
     specified for <type>time</type>, <type>timestamp</type>, and
1589
1592
     <type>interval</type> types.  The allowed values are mentioned
1705
1708
      The time-of-day types are <type>time [
1706
1709
      (<replaceable>p</replaceable>) ] without time zone</type> and
1707
1710
      <type>time [ (<replaceable>p</replaceable>) ] with time
1708
 
      zone</type>;   <type>time</type> is equivalent to
 
1711
      zone</type>.  <type>time</type> alone is equivalent to
1709
1712
      <type>time without time zone</type>.
1710
1713
     </para>
1711
1714
 
1752
1755
         </row>
1753
1756
         <row>
1754
1757
          <entry><literal>04:05 AM</literal></entry>
1755
 
          <entry>same as 04:05 (AM ignored)</entry>
 
1758
          <entry>same as 04:05; AM does not affect value</entry>
1756
1759
         </row>
1757
1760
         <row>
1758
1761
          <entry><literal>04:05 PM</literal></entry>
1878
1881
     </para>
1879
1882
 
1880
1883
     <para>
1881
 
      The <acronym>SQL</acronym> standard differentiates <type>timestamp without time zone</type> 
 
1884
      The <acronym>SQL</acronym> standard differentiates
 
1885
      <type>timestamp without time zone</type> 
1882
1886
      and <type>timestamp with time zone</type> literals by the presence of a 
1883
 
      <quote>+</quote> or <quote>-</quote> symbol after the time
1884
 
      indicating the time zone offset. Hence, according to the standard:
 
1887
      <quote>+</quote> or <quote>-</quote> symbol and time zone offset after
 
1888
      the time.  Hence, according to the standard,
1885
1889
 
1886
1890
      <programlisting>TIMESTAMP '2004-10-19 10:23:54'</programlisting>
1887
1891
 
1888
 
      is a <type>timestamp without time zone</type>, while:
 
1892
      is a <type>timestamp without time zone</type>, while
1889
1893
 
1890
1894
      <programlisting>TIMESTAMP '2004-10-19 10:23:54+02'</programlisting>
1891
1895
 
2048
2052
    </indexterm>
2049
2053
 
2050
2054
    <para>
2051
 
     The output format of the date/time types can one of the four
2052
 
     styles: ISO 8601,
 
2055
     The output format of the date/time types can be set to one of the four
 
2056
     styles ISO 8601,
2053
2057
     <acronym>SQL</acronym> (Ingres), traditional <productname>POSTGRES</>
2054
 
     (Unix <application>date</> format), and
2055
 
     German.  It can be set using the <literal>SET datestyle</literal> command.  The default
 
2058
     (Unix <application>date</> format), or
 
2059
     German.  The default
2056
2060
     is the <acronym>ISO</acronym> format.  (The
2057
2061
     <acronym>SQL</acronym> standard requires the use of the ISO 8601
2058
 
     format.  The name of the <literal>SQL</> output format poorly
2059
 
     chosen and an historical accident.)  <xref
 
2062
     format.  The name of the <quote>SQL</quote> output format is a
 
2063
     historical accident.)  <xref
2060
2064
     linkend="datatype-datetime-output-table"> shows examples of each
2061
2065
     output style.  The output of the <type>date</type> and
2062
2066
     <type>time</type> types is of course only the date or time part
2273
2277
      </listitem>
2274
2278
     </itemizedlist>
2275
2279
 
2276
 
     In summary, there is a difference between abbreviations
 
2280
     In short, this is the difference between abbreviations
2277
2281
     and full names: abbreviations always represent a fixed offset from
2278
2282
     UTC, whereas most of the full names imply a local daylight-savings time
2279
2283
     rule, and so have two possible UTC offsets.
2358
2362
    </indexterm>
2359
2363
 
2360
2364
     <para>
2361
 
      <type>interval</type> values can be written using the following:
 
2365
      <type>interval</type> values can be written using the following
2362
2366
      verbose syntax:
2363
2367
 
2364
2368
<synopsis>
2708
2712
     <member><literal>'off'</literal></member>
2709
2713
     <member><literal>'0'</literal></member>
2710
2714
    </simplelist>
2711
 
    Leading and trailing whitespace and case are ignored. The key words
2712
 
    <literal>TRUE</literal> and <literal>FALSE</literal> is the preferred
2713
 
    usage (and <acronym>SQL</acronym>-compliant).
 
2715
    Leading or trailing whitespace is ignored, and case does not matter.
 
2716
    The key words
 
2717
    <literal>TRUE</literal> and <literal>FALSE</literal> are the preferred
 
2718
    (<acronym>SQL</acronym>-compliant) usage.
2714
2719
   </para>
2715
2720
 
2716
2721
   <example id="datatype-boolean-example">
3072
3077
    </para>
3073
3078
 
3074
3079
    <para>
3075
 
     Boxes are output using the first syntax.  Any two opposite corners
3076
 
     can be supplied; the corners are reordered on input to store the
 
3080
     Boxes are output using the first syntax.
 
3081
     Any two opposite corners can be supplied on input, but the values
 
3082
     will be reordered as needed to store the
3077
3083
     upper right and lower left corners.
3078
3084
    </para>
3079
3085
   </sect2>
3111
3117
    </para>
3112
3118
 
3113
3119
    <para>
3114
 
     Paths are output using the first appropriate syntax.
 
3120
     Paths are output using the first or second syntax, as appropriate.
3115
3121
    </para>
3116
3122
   </sect2>
3117
3123
 
3190
3196
    <productname>PostgreSQL</> offers data types to store IPv4, IPv6, and MAC
3191
3197
    addresses, as shown in <xref linkend="datatype-net-types-table">.  It
3192
3198
    is better to use these types instead of plain text types to store
3193
 
    network addresses because
 
3199
    network addresses, because
3194
3200
    these types offer input error checking and specialized
3195
3201
    operators and functions (see <xref linkend="functions-net">).
3196
3202
   </para>
3266
3272
      <replaceable class="parameter">y</replaceable>
3267
3273
      is the number of bits in the netmask.  If the
3268
3274
      <replaceable class="parameter">/y</replaceable>
3269
 
      is missing, the
 
3275
      portion is missing, the
3270
3276
      netmask is 32 for IPv4 and 128 for IPv6, so the value represents
3271
3277
      just a single host.  On display, the
3272
3278
      <replaceable class="parameter">/y</replaceable>
3560
3566
    are designed to support full text search, which is the activity of
3561
3567
    searching through a collection of natural-language <firstterm>documents</>
3562
3568
    to locate those that best match a <firstterm>query</>.
3563
 
    The <type>tsvector</type> type represents a document stored in a form optimized
3564
 
    for text search;  <type>tsquery</type> type similarly represents
 
3569
    The <type>tsvector</type> type represents a document in a form optimized
 
3570
    for text search; the <type>tsquery</type> type similarly represents
3565
3571
    a text query.
3566
3572
    <xref linkend="textsearch"> provides a detailed explanation of this
3567
3573
    facility, and <xref linkend="functions-textsearch"> summarizes the
3577
3583
 
3578
3584
    <para>
3579
3585
     A <type>tsvector</type> value is a sorted list of distinct
3580
 
     <firstterm>lexemes</>, which are words which have been
 
3586
     <firstterm>lexemes</>, which are words that have been
3581
3587
     <firstterm>normalized</> to merge different variants of the same word
3582
3588
     (see <xref linkend="textsearch"> for details).  Sorting and
3583
3589
     duplicate-elimination are done automatically during input, as shown in
3687
3693
 
3688
3694
    <para>
3689
3695
     A <type>tsquery</type> value stores lexemes that are to be
3690
 
     searched for, and combines them by honoring the boolean operators
 
3696
     searched for, and combines them honoring the boolean operators
3691
3697
     <literal>&amp;</literal> (AND), <literal>|</literal> (OR), and
3692
3698
     <literal>!</> (NOT).  Parentheses can be used to enforce grouping
3693
3699
     of the operators:
3825
3831
   <para>
3826
3832
    The <type>xml</type> data type can be used to store XML data.  Its
3827
3833
    advantage over storing XML data in a <type>text</type> field is that it
3828
 
    checks the input values for well-formedness, and support
3829
 
    functions can perform type-safe operations on it; see <xref
 
3834
    checks the input values for well-formedness, and there are support
 
3835
    functions to perform type-safe operations on it; see <xref
3830
3836
    linkend="functions-xml">.  Use of this data type requires the
3831
3837
    installation to have been built with <command>configure 
3832
3838
    --with-libxml</>.
3870
3876
 
3871
3877
   <para>
3872
3878
    The <type>xml</type> type does not validate input values
3873
 
    against an optionally-supplied document type declaration
3874
 
    (DTD).<indexterm><primary>DTD</primary></indexterm>
 
3879
    against a document type declaration
 
3880
    (DTD),<indexterm><primary>DTD</primary></indexterm>
 
3881
    even when the input value specifies a DTD.
3875
3882
   </para>
3876
3883
 
3877
3884
   <para>
3883
3890
</synopsis>
3884
3891
    <replaceable>type</replaceable> can be
3885
3892
    <type>character</type>, <type>character varying</type>, or
3886
 
    <type>text</type> (or an alias name for those).  Again, according
 
3893
    <type>text</type> (or an alias for one of those).  Again, according
3887
3894
    to the SQL standard, this is the only way to convert between type
3888
3895
    <type>xml</type> and character types, but PostgreSQL also allows
3889
3896
    you to simply cast the value.
3923
3930
    representations of XML values, such as in the above examples.
3924
3931
    This would ordinarily mean that encoding declarations contained in
3925
3932
    XML data can become invalid as the character data is converted
3926
 
    to other encodings while travelling between client and server
 
3933
    to other encodings while travelling between client and server,
3927
3934
    because the embedded encoding declaration is not changed.  To cope
3928
3935
    with this behavior, encoding declarations contained in
3929
3936
    character strings presented for input to the <type>xml</type> type
3932
3939
    processing, character strings of XML data must be sent
3933
3940
    from the client in the current client encoding.  It is the
3934
3941
    responsibility of the client to either convert documents to the
3935
 
    current client encoding before sending them to the server or to
 
3942
    current client encoding before sending them to the server, or to
3936
3943
    adjust the client encoding appropriately.  On output, values of
3937
3944
    type <type>xml</type> will not have an encoding declaration, and
3938
3945
    clients should assume all data is in the current client
3958
3965
    processed in UTF-8, computations will be most efficient if the
3959
3966
    server encoding is also UTF-8.
3960
3967
   </para>
 
3968
 
 
3969
   <caution>
 
3970
    <para>
 
3971
     Some XML-related functions may not work at all on non-ASCII data
 
3972
     when the server encoding is not UTF-8.  This is known to be an
 
3973
     issue for <function>xpath()</> in particular.
 
3974
    </para>
 
3975
   </caution>
3961
3976
   </sect2>
3962
3977
 
3963
3978
   <sect2>