granicus.if.org Git - postgresql/blob - doc/src/sgml/datatype.sgml

   1  <chapter id="datatype">
   2   <title>Data Types</title>
   3
   4   <abstract>
   5    <para>
   6     Describes the built-in data types available in
   7     <productname>Postgres</productname>.
   8    </para>
   9   </abstract>
  10
  11   <para>
  12    <productname>Postgres</productname> has a rich set of native data
  13    types available to users.
  14    Users may add new types to <productname>Postgres</productname> using the
  15    <command>DEFINE TYPE</command>
  16    command described elsewhere.
  17   </para>
  18
  19   <para>
  20    In the context of data types, the following sections will discuss
  21    <acronym>SQL</acronym> standards compliance, porting issues, and usage.
  22
  23    Some <productname>Postgres</productname> types correspond directly to
  24    <acronym>SQL92</acronym>-compatible types. In other
  25    cases, data types defined by <acronym>SQL92</acronym> syntax are mapped directly
  26    into native <productname>Postgres</productname> types.
  27
  28    Many of the built-in types have obvious external formats. However, several
  29    types are either unique to <productname>Postgres</productname>,
  30    such as open and closed paths, or have
  31    several possibilities for formats, such as the date and time types.
  32   </para>
  33
  34   <para>
  35    <table tocentry="1">
  36     <title><productname>Postgres</productname> Data Types</title>
  37     <titleabbrev>Data Types</titleabbrev>
  38     <tgroup cols="3">
  39      <thead>
  40       <row>
  41        <entry><productname>Postgres</productname> Type</entry>
  42        <entry><acronym>SQL92</acronym> or <acronym>SQL3</acronym> Type</entry>
  43        <entry>Description</entry>
  44       </row>
  45      </thead>
  46      <tbody>
  47       <row>
  48        <entry>bool</entry>
  49        <entry>boolean</entry>
  50        <entry>logical boolean (true/false)</entry>
  51       </row>
  52       <row>
  53        <entry>box</entry>
  54        <entry></entry>
  55        <entry>rectangular box in 2D plane</entry>
  56       </row>
  57       <row>
  58        <entry>char(n)</entry>
  59        <entry>character(n)</entry>
  60        <entry>fixed-length character string</entry>
  61       </row>
  62       <row>
  63        <entry>cidr</entry>
  64        <entry></entry>
  65        <entry>IP version 4 network or host address</entry>
  66       </row>
  67       <row>
  68        <entry>circle</entry>
  69        <entry></entry>
  70        <entry>circle in 2D plane</entry>
  71       </row>
  72       <row>
  73        <entry>date</entry>
  74        <entry>date</entry>
  75        <entry>calendar date without time of day</entry>
  76       </row>
  77       <row>
  78        <entry>float4/8</entry>
  79        <entry>float(p)</entry>
  80        <entry>floating-point number with precision p</entry>
  81       </row>
  82       <row>
  83        <entry>float8</entry>
  84        <entry>real, double precision</entry>
  85        <entry>double-precision floating-point number</entry>
  86       </row>
  87       <row>
  88        <entry>inet</entry>
  89        <entry></entry>
  90        <entry>IP version 4 network or host address</entry>
  91       </row>
  92       <row>
  93        <entry>int2</entry>
  94        <entry>smallint</entry>
  95        <entry>signed two-byte integer</entry>
  96       </row>
  97       <row>
  98        <entry>int4</entry>
  99        <entry>int, integer</entry>
 100        <entry>signed 4-byte integer</entry>
 101       </row>
 102       <row>
 103        <entry>int4</entry>
 104        <entry>decimal(p,s)</entry>
 105        <entry>exact numeric for p <= 9, s = 0</entry>
 106       </row>
 107       <row>
 108        <entry>int4</entry>
 109        <entry>numeric(p,s)</entry>
 110        <entry>exact numeric for p == 9, s = 0</entry>
 111       </row>
 112       <row>
 113        <entry>int8</entry>
 114        <entry></entry>
 115        <entry>signed 8-byte integer</entry>
 116       </row>
 117       <row>
 118        <entry>line</entry>
 119        <entry></entry>
 120        <entry>infinite line in 2D plane</entry>
 121       </row>
 122       <row>
 123        <entry>lseg</entry>
 124        <entry></entry>
 125        <entry>line segment in 2D plane</entry>
 126       </row>
 127       <row>
 128        <entry>money</entry>
 129        <entry>decimal(9,2)</entry>
 130        <entry>US-style currency</entry>
 131       </row>
 132       <row>
 133        <entry>path</entry>
 134        <entry></entry>
 135        <entry>open and closed geometric path in 2D plane</entry>
 136       </row>
 137       <row>
 138        <entry>point</entry>
 139        <entry></entry>
 140        <entry>geometric point in 2D plane</entry>
 141       </row>
 142       <row>
 143        <entry>polygon</entry>
 144        <entry></entry>
 145        <entry>closed geometric path in 2D plane</entry>
 146       </row>
 147       <row>
 148        <entry>serial</entry>
 149        <entry></entry>
 150        <entry>unique id for indexing and cross-reference</entry>
 151       </row>
 152       <row>
 153        <entry>time</entry>
 154        <entry>time</entry>
 155        <entry>time of day</entry>
 156       </row>
 157       <row>
 158        <entry>timespan</entry>
 159        <entry>interval</entry>
 160        <entry>general-use time span</entry>
 161       </row>
 162       <row>
 163        <entry>timestamp</entry>
 164        <entry>timestamp with time zone</entry>
 165        <entry>date/time</entry>
 166       </row>
 167       <row>
 168        <entry>varchar(n)</entry>
 169        <entry>character varying(n)</entry>
 170        <entry>variable-length character string</entry>
 171       </row>
 172      </tbody>
 173     </tgroup>
 174    </table>
 175   </para>
 176
 177   <para>
 178    <note>
 179     <para>
 180      The <type>cidr</type> and <type>inet</type> types are designed to handle any IP type
 181      but only ipv4 is handled in the current implementation.
 182      Everything here that talks about ipv4 will apply to ipv6 in a future release.</para>
 183    </note></para>
 184
 185   <para>
 186    <table tocentry="1">
 187     <title><productname>Postgres</productname> Function Constants</title>
 188     <titleabbrev>Constants</titleabbrev>
 189     <tgroup cols="3">
 190      <thead>
 191       <row>
 192        <entry><productname>Postgres</productname> Function</entry>
 193        <entry><acronym>SQL92</acronym> Constant</entry>
 194        <entry>Description</entry>
 195       </row>
 196      </thead>
 197      <tbody>
 198       <row>
 199        <entry>getpgusername()</entry>
 200        <entry>current_user</entry>
 201        <entry>user name in current session</entry>
 202       </row>
 203       <row>
 204        <entry>date('now')</entry>
 205        <entry>current_date</entry>
 206        <entry>date of current transaction</entry>
 207       </row>
 208       <row>
 209        <entry>time('now')</entry>
 210        <entry>current_time</entry>
 211        <entry>time of current transaction</entry>
 212       </row>
 213       <row>
 214        <entry>timestamp('now')</entry>
 215        <entry>current_timestamp</entry>
 216        <entry>date and time of current transaction</entry>
 217       </row>
 218      </tbody>
 219     </tgroup>
 220    </table>
 221   </para>
 222
 223   <para>
 224    <productname>Postgres</productname> has features at the forefront of
 225    <acronym>ORDBMS</acronym> development. In addition to
 226    <acronym>SQL3</acronym> conformance, substantial portions
 227    of <acronym>SQL92</acronym> are also supported.
 228    Although we strive for <acronym>SQL92</acronym> compliance,
 229    there are some aspects of the standard
 230    which are ill considered and which should not live through subsequent standards.
 231    <productname>Postgres</productname> will not make great efforts to
 232    conform to these features; however, these tend to apply in little-used
 233    or obsure cases, and a typical user is not likely to run into them.</para>
 234
 235   <para>
 236    Most of the input and output functions corresponding to the
 237    base types (e.g., integers and floating point numbers) do some
 238    error-checking.
 239    Some of the operators and functions (e.g.,
 240    addition and multiplication) do not perform run-time error-checking in the
 241    interests of improving execution speed.
 242    On some systems, for example, the numeric operators for some data types may
 243    silently underflow or overflow.
 244   </para>
 245
 246   <para>
 247    Note that some of the input and output functions are not invertible.  That is,
 248    the result of an output function may lose precision when compared to
 249    the original input.
 250
 251    <note>
 252     <para>
 253      The original <productname>Postgres</productname> v4.2 code received from
 254      Berkeley rounded all double precision floating point results to six digits for
 255      output. Starting with v6.1, floating point numbers are allowed to retain
 256      most of the intrinsic precision of the type (typically 15 digits for doubles,
 257      6 digits for 4-byte floats).
 258      Other types with underlying floating point fields (e.g. geometric
 259      types) carry similar precision.</para>
 260    </note>
 261   </para>
 262
 263   <sect1>
 264    <title>Numeric Types</title>
 265
 266    <para>
 267     Numeric types consist of two- and four-byte integers and four- and eight-byte
 268     floating point numbers.</para>
 269
 270 <para>
 271 <table tocentry="1">
 272 <title><productname>Postgres</productname> Numeric Types</title>
 273 <titleabbrev>Numerics</titleabbrev>
 274 <tgroup cols="4">
 275 <thead>
 276   <row>
 277     <entry>Numeric Type</entry>
 278     <entry>Storage</entry>
 279     <entry>Description</entry>
 280     <entry>Range</entry>
 281   </row>
 282 </thead>
 283 <tbody>
 284   <row>
 285     <entry>float4</entry>
 286     <entry>4 bytes</entry>
 287     <entry>Variable-precision</entry>
 288     <entry>6 decimal places</entry>
 289   </row>
 290   <row>
 291     <entry>float8</entry>
 292     <entry>8 bytes</entry>
 293     <entry>Variable-precision</entry>
 294     <entry>15 decimal places</entry>
 295   </row>
 296   <row>
 297     <entry>int2</entry>
 298     <entry>2 bytes</entry>
 299     <entry>Fixed-precision</entry>
 300     <entry>-32768 to +32767</entry>
 301   </row>
 302   <row>
 303     <entry>int4</entry>
 304     <entry>4 bytes</entry>
 305     <entry>Usual choice for fixed-precision</entry>
 306     <entry>-2147483648 to +2147483647</entry>
 307   </row>
 308   <row>
 309     <entry>int8</entry>
 310     <entry>8 bytes</entry>
 311     <entry>Very large range fixed-precision</entry>
 312     <entry>+/- &gt; 18 decimal places</entry>
 313   </row>
 314   <row>
 315     <entry>serial</entry>
 316     <entry>4 bytes</entry>
 317     <entry>Identifer or cross-reference</entry>
 318     <entry>0 to +2147483647</entry>
 319   </row>
 320 </tbody>
 321 </tgroup>
 322 </table>
 323 </para>
 324
 325 <para>
 326 The numeric types have a full set of corresponding arithmetic operators and
 327 functions. Refer to <xref endterm="math-opers" linkend="math-opers">
 328 and <xref endterm="math-funcs" linkend="math-funcs"> for more information.
 329    </para>
 330
 331 <para>
 332 The <type>serial</type> type is a special-case type constructed by
 333 <productname>Postgres</productname> from other existing components.
 334 It is typically used to create unique identifiers for table entries.
 335 In the current implementation, specifying
 336
 337 <programlisting>
 338 CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
 339 </programlisting>
 340
 341 is equivalent to specifying:
 342
 343 <programlisting>
 344 CREATE SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq;
 345 CREATE TABLE <replaceable class="parameter">tablename</replaceable>
 346     (<replaceable class="parameter">colname</replaceable> INT4 DEFAULT nextval('<replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_seq');
 347 CREATE UNIQUE INDEX <replaceable class="parameter">tablename</replaceable>_<replaceable class="parameter">colname</replaceable>_key on <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable>);
 348 </programlisting>
 349
 350 <caution>
 351 <para>
 352 The implicit sequence created for the <type>serial</type> type will
 353 <emphasis>not</emphasis> be automatically removed when the table is dropped.
 354 So, the following commands executed in order will likely fail:
 355
 356 <programlisting>
 357 CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
 358 DROP TABLE <replaceable class="parameter">tablename</replaceable>;
 359 CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceable class="parameter">colname</replaceable> SERIAL);
 360 </programlisting>
 361
 362 The sequence will remain in the database until explicitly dropped using
 363 <command>DROP SEQUENCE</command>.</para>
 364 </caution>
 365    </para>
 366
 367 <para>
 368 The <firstterm>exact numerics</firstterm> <type>decimal</type> and
 369 <type>numeric</type>
 370 have fully implemented syntax but currently
 371 (<productname>Postgres</productname> v6.4)
 372  support only a small range of precision and/or range values.
 373 The <type>int8</type> type may not be available on all platforms since
 374 it relies on compiler support for this.
 375 </para>
 376
 377 </sect1>
 378
 379 <sect1>
 380 <title>Monetary Type</title>
 381
 382 <para>
 383 The <type>money</type> type supports US-style currency with
 384 fixed decimal point representation.
 385 If <productname>Postgres</productname> is compiled with USE_LOCALE
 386 then the money type should use the monetary conventions defined for
 387 <citetitle>locale(7)</citetitle>.
 388    </para>
 389
 390 <para>
 391 <table tocentry="1">
 392 <title><productname>Postgres</productname> Monetary Types</title>
 393 <titleabbrev>Money</titleabbrev>
 394 <tgroup cols="4">
 395 <thead>
 396   <row>
 397     <entry>Monetary Type</entry>
 398     <entry>Storage</entry>
 399     <entry>Description</entry>
 400     <entry>Range</entry>
 401   </row>
 402 </thead>
 403 <tbody>
 404   <row>
 405     <entry>money</entry>
 406     <entry>4 bytes</entry>
 407     <entry>Fixed-precision</entry>
 408     <entry>-21474836.48 to +21474836.47</entry>
 409   </row>
 410 </tbody>
 411 </tgroup>
 412 </table>
 413 </para>
 414
 415 <para>
 416 <type>numeric</type>
 417 should eventually replace the money type. It has a
 418 fully implemented syntax but currently
 419 (<productname>Postgres</productname> v6.4)
 420  support only a small range of precision and/or range values
 421 and cannot adequately substitute for the money type.
 422 </para>
 423
 424 </sect1>
 425
 426 <sect1>
 427 <title>Character Types</title>
 428
 429 <para>
 430 <acronym>SQL92</acronym> defines two primary character types:
 431  <type>char</type> and <type>varchar</type>.
 432 <productname>Postgres</productname> supports these types, in
 433 addition to the more general <type>text</type> type,
 434 which unlike <type>varchar</type>
 435 does not require an upper
 436 limit to be declared on the size of the field.
 437 </para>
 438
 439 <para>
 440 <table tocentry="1">
 441 <title><productname>Postgres</productname> Character Types</title>
 442 <titleabbrev>Characters</titleabbrev>
 443 <tgroup cols="4">
 444 <thead>
 445   <row>
 446     <entry>Character Type</entry>
 447     <entry>Storage</entry>
 448     <entry>Recommendation</entry>
 449     <entry>Description</entry>
 450   </row>
 451 </thead>
 452 <tbody>
 453   <row>
 454     <entry>char</entry>
 455     <entry>1 byte</entry>
 456     <entry><acronym>SQL92</acronym>-compatible</entry>
 457     <entry>Single character</entry>
 458   </row>
 459   <row>
 460     <entry>char(n)</entry>
 461     <entry>(4+n) bytes</entry>
 462     <entry><acronym>SQL92</acronym>-compatible</entry>
 463     <entry>Fixed-length blank padded</entry>
 464   </row>
 465   <row>
 466     <entry>text</entry>
 467     <entry>(4+x) bytes</entry>
 468     <entry>Best choice</entry>
 469     <entry>Variable-length</entry>
 470   </row>
 471   <row>
 472     <entry>varchar(n)</entry>
 473     <entry>(4+n) bytes</entry>
 474     <entry><acronym>SQL92</acronym>-compatible</entry>
 475     <entry>Variable-length with limit</entry>
 476   </row>
 477 </tbody>
 478 </tgroup>
 479 </table>
 480 </para>
 481
 482 <para>
 483 There is one other fixed-length character type.
 484 The <type>name</type> type
 485 only has one purpose and that is to provide
 486 <productname>Postgres</productname> with a
 487 special type to use for internal names.
 488 It is not intended for use by the general user.
 489 It's length is currently defined as 32 chars
 490 but should be reference using NAMEDATALEN.
 491 This is set at compile time and may change in a future release.
 492 </para>
 493
 494 <para>
 495 <table tocentry="1">
 496 <title><productname>Postgres</productname> Specialty Character Type</title>
 497 <titleabbrev>Specialty Characters</titleabbrev>
 498 <tgroup cols="3">
 499 <thead>
 500   <row>
 501     <entry>Character Type</entry>
 502     <entry>Storage</entry>
 503     <entry>Description</entry>
 504   </row>
 505 </thead>
 506 <tbody>
 507   <row>
 508     <entry>name</entry>
 509     <entry>32 bytes</entry>
 510     <entry>Thirty-two character internal type</entry>
 511   </row>
 512 </tbody>
 513 </tgroup>
 514 </table>
 515 </para>
 516
 517 </sect1>
 518
 519   <sect1>
 520    <title>Date/Time Types</title>
 521
 522    <para>
 523     There are two fundamental kinds of date and time measurements
 524     provided by <productname>Postgres</productname>:
 525     absolute clock times and relative time intervals.
 526     Both kinds of time measurements should demonstrate both
 527     continuity and smoothness.
 528    </para>
 529
 530    <para>
 531     <productname>Postgres</productname> supplies two primary user-oriented
 532     date and time types,
 533     <type>datetime</type> and <type>timespan</type>, as well as
 534     the related <acronym>SQL92</acronym> types <type>timestamp</type>,
 535     <type>interval</type>,
 536     <type>date</type> and <type>time</type>.
 537    </para>
 538
 539    <para>
 540     In a future release, <type>datetime</type> and <type>timespan</type> are likely
 541     to merge with the <acronym>SQL92</acronym> types <type>timestamp</type>,
 542     <type>interval</type>.
 543     Other date and time types are also available, mostly
 544     for historical reasons.
 545    </para>
 546
 547    <para>
 548     <table tocentry="1">
 549      <title><productname>Postgres</productname> Date/Time Types</title>
 550      <titleabbrev>Date/Time</titleabbrev>
 551      <tgroup cols="4">
 552       <thead>
 553        <row>
 554         <entry>Date/Time Type</entry>
 555         <entry>Storage</entry>
 556         <entry>Recommendation</entry>
 557         <entry>Description</entry>
 558        </row>
 559       </thead>
 560       <tbody>
 561        <row>
 562         <entry>abstime</entry>
 563         <entry>4 bytes</entry>
 564         <entry>original date and time</entry>
 565         <entry>limited range</entry>
 566        </row>
 567        <row>
 568         <entry>date</entry>
 569         <entry>4 bytes</entry>
 570         <entry><acronym>SQL92</acronym> type</entry>
 571         <entry>wide range</entry>
 572        </row>
 573        <row>
 574         <entry>datetime</entry>
 575         <entry>8 bytes</entry>
 576         <entry>best general date and time</entry>
 577         <entry>wide range, high precision</entry>
 578        </row>
 579        <row>
 580         <entry>interval</entry>
 581         <entry>12 bytes</entry>
 582         <entry><acronym>SQL92</acronym> type</entry>
 583         <entry>equivalent to timespan</entry>
 584        </row>
 585        <row>
 586         <entry>reltime</entry>
 587         <entry>4 bytes</entry>
 588         <entry>original time interval</entry>
 589         <entry>limited range, low precision</entry>
 590        </row>
 591        <row>
 592         <entry>time</entry>
 593         <entry>4 bytes</entry>
 594         <entry><acronym>SQL92</acronym> type</entry>
 595         <entry>wide range</entry>
 596        </row>
 597        <row>
 598         <entry>timespan</entry>
 599         <entry>12 bytes</entry>
 600         <entry>best general time interval</entry>
 601         <entry>wide range, high precision</entry>
 602        </row>
 603        <row>
 604         <entry>timestamp</entry>
 605         <entry>4 bytes</entry>
 606         <entry><acronym>SQL92</acronym> type</entry>
 607         <entry>limited range</entry>
 608        </row>
 609       </tbody>
 610      </tgroup>
 611     </table>
 612
 613     <type>timestamp</type> is currently implemented separately from
 614     <type>datetime</type>, although they share input and output routines.
 615    </para>
 616
 617    <para>
 618     <table tocentry="1">
 619      <title><productname>Postgres</productname> Date/Time Ranges</title>
 620      <titleabbrev>Ranges</titleabbrev>
 621      <tgroup cols="4">
 622       <thead>
 623        <row>
 624         <entry>Date/Time Type</entry>
 625         <entry>Earliest</entry>
 626         <entry>Latest</entry>
 627         <entry>Resolution</entry>
 628        </row>
 629       </thead>
 630       <tbody>
 631        <row>
 632         <entry>abstime</entry>
 633         <entry>1901-12-14</entry>
 634         <entry>2038-01-19</entry>
 635         <entry>1 sec</entry>
 636        </row>
 637        <row>
 638         <entry>date</entry>
 639         <entry>4713 BC</entry>
 640         <entry>32767 AD</entry>
 641         <entry>1 day</entry>
 642        </row>
 643        <row>
 644         <entry>datetime</entry>
 645         <entry>4713 BC</entry>
 646         <entry>1465001 AD</entry>
 647         <entry>1 microsec to 14 digits</entry>
 648        </row>
 649        <row>
 650         <entry>interval</entry>
 651         <entry>-178000000 years</entry>
 652         <entry>178000000 years</entry>
 653         <entry>1 microsec</entry>
 654        </row>
 655        <row>
 656         <entry>reltime</entry>
 657         <entry>-68 years</entry>
 658         <entry>+68 years</entry>
 659         <entry>1 sec</entry>
 660        </row>
 661        <row>
 662         <entry>time</entry>
 663         <entry>00:00:00.00</entry>
 664         <entry>23:59:59.99</entry>
 665         <entry>1 microsec</entry>
 666        </row>
 667        <row>
 668         <entry>timespan</entry>
 669         <entry>-178000000 years</entry>
 670         <entry>178000000 years</entry>
 671         <entry>1 microsec (14 digits)</entry>
 672        </row>
 673        <row>
 674         <entry>timestamp</entry>
 675         <entry>1901-12-14</entry>
 676         <entry>2038-01-19</entry>
 677         <entry>1 sec</entry>
 678        </row>
 679       </tbody>
 680      </tgroup>
 681     </table>
 682    </para>
 683
 684    <sect2>
 685     <title>SQL92 Conventions</title>
 686
 687     <para>
 688      <productname>Postgres</productname> endeavors to be compatible with
 689      <acronym>SQL92</acronym> definitions for typical usage.
 690      However, the <acronym>SQL92</acronym> standard has an odd mix of date and
 691      time types and capabilities. Two obvious problems are:
 692
 693      <itemizedlist>
 694       <listitem>
 695        <para>
 696         Although the <type>date</type> type
 697         does not have an associated time zone, the
 698         <type>time</type> type can or does.
 699        </para>
 700       </listitem>
 701
 702       <listitem>
 703        <para>
 704         The default time zone is specified as a constant integer offset
 705         from GMT/UTC.
 706        </para>
 707       </listitem>
 708
 709      </itemizedlist>
 710
 711      Time zones in the real world can have no meaning unless
 712      associated with a date as well as a time
 713      since the offset may vary through the year with daylight savings
 714      time boundaries.
 715     </para>
 716
 717     <para>
 718      To address these difficulties, <productname>Postgres</productname>
 719      associates time zones only with date and time
 720      types which contain both date and time,
 721      and assumes local time for any type containing only
 722      date or time. Further, time zone support is derived from
 723      the underlying operating system
 724      time zone capabilities, and hence can handle daylight savings time
 725      and other expected behavior.
 726     </para>
 727
 728     <para>
 729      In future releases, the number of date/time types will decrease,
 730      with the current implementation of
 731      <type>datetime</type> becoming <type>timestamp</type>,
 732      <type>timespan</type> becoming <type>interval</type>,
 733      and (possibly) <type>abstime</type> and <type>reltime</type>
 734      being deprecated in favor of <type>timestamp</type> and <type>interval</type>.
 735      The more arcane features of the date/time definitions from
 736      the <acronym>SQL92</acronym> standard are not likely to be pursued.
 737     </para>
 738    </sect2>
 739
 740 <sect2>
 741 <title>Date/Time Styles</title>
 742
 743 <para>
 744 Output formats can be set to one of four styles:
 745 ISO-8601, <acronym>SQL</acronym> (Ingres), traditional
 746 Postgres, and German.
 747
 748 <table tocentry="1">
 749 <title><productname>Postgres</productname> Date Styles</title>
 750 <titleabbrev>Styles</titleabbrev>
 751 <tgroup cols="3">
 752 <thead>
 753   <row>
 754     <entry>Style Specification</entry>
 755     <entry>Description</entry>
 756     <entry>Example</entry>
 757   </row>
 758 </thead>
 759 <tbody>
 760   <row>
 761     <entry>ISO</entry>
 762     <entry>ISO-8601 standard</entry>
 763     <entry>1997-12-17 07:37:16-08</entry>
 764   </row>
 765   <row>
 766     <entry><acronym>SQL</acronym></entry>
 767     <entry>Traditional style</entry>
 768     <entry>12/17/1997 07:37:16.00 PST</entry>
 769   </row>
 770   <row>
 771     <entry>Postgres</entry>
 772     <entry>Original style</entry>
 773     <entry>Wed Dec 17 07:37:16 1997 PST</entry>
 774   </row>
 775   <row>
 776     <entry>German</entry>
 777     <entry>Regional style</entry>
 778     <entry>17.12.1997 07:37:16.00 PST</entry>
 779   </row>
 780 </tbody>
 781 </tgroup>
 782 </table>
 783 </para>
 784
 785 <para>
 786 The <acronym>SQL</acronym> style has European and non-European (US) variants,
 787 which determines whether month follows day or vica versa.
 788
 789 <table tocentry="1">
 790 <title><productname>Postgres</productname> Date Order Conventions</title>
 791 <titleabbrev>Order</titleabbrev>
 792 <tgroup cols="3">
 793 <thead>
 794   <row>
 795     <entry>Style Specification</entry>
 796     <entry>Description</entry>
 797     <entry>Example</entry>
 798   </row>
 799 </thead>
 800 <tbody>
 801   <row>
 802     <entry>European</entry>
 803     <entry>Regional convention</entry>
 804     <entry>17/12/1997 15:37:16.00 MET</entry>
 805   </row>
 806   <row>
 807     <entry>NonEuropean</entry>
 808     <entry>Regional convention</entry>
 809     <entry>12/17/1997 07:37:16.00 PST</entry>
 810   </row>
 811   <row>
 812     <entry>US</entry>
 813     <entry>Regional convention</entry>
 814     <entry>12/17/1997 07:37:16.00 PST</entry>
 815   </row>
 816 </tbody>
 817 </tgroup>
 818 </table>
 819 </para>
 820
 821 <para>
 822 There are several ways to affect the appearance of date/time types:
 823
 824 <itemizedlist spacing="compact" mark="bullet">
 825 <listitem>
 826 <para>
 827 The PGDATESTYLE environment variable used by the backend directly
 828 on postmaster startup.
 829 </para>
 830 </listitem>
 831 <listitem>
 832 <para>
 833 The PGDATESTYLE environment variable used by the frontend libpq
 834 on session startup.
 835 </para>
 836 </listitem>
 837 <listitem>
 838 <para>
 839 <command>SET DATESTYLE</command> <acronym>SQL</acronym> command.
 840 </para>
 841 </listitem>
 842 </itemizedlist>
 843 </para>
 844
 845     <para>
 846      For <productname>Postgres</productname> v6.4 (and earlier)
 847      the default date/time style is
 848      "non-European traditional Postgres".
 849      In future releases, the default may become "ISO" (compatible with ISO-8601),
 850      which alleviates date specification ambiguities and Y2K collation problems.
 851     </para>
 852
 853    </sect2>
 854
 855    <sect2>
 856     <title>Calendar</title>
 857
 858     <para>
 859      <productname>Postgres</productname> uses Julian dates
 860      for all date/time calculations. They have the nice property of correctly
 861      predicting/calculating any date more recent than 4713BC
 862      to far into the future, using the assumption that the length of the
 863      year is 365.2425 days.
 864     </para>
 865
 866     <para>
 867      Date conventions before the 19th century make for interesting reading,
 868      but are not consistant enough to warrant coding into a date/time handler.
 869     </para>
 870    </sect2>
 871
 872    <sect2>
 873     <title>Time Zones</title>
 874
 875     <para>
 876      <productname>Postgres</productname> obtains time zone support
 877      from the underlying operating system for dates between 1902 and
 878      2038 (near the typical date limits for Unix-style
 879      systems). Outside of this range, all dates are assumed to be
 880      specified and used in Universal Coordinated Time (UTC).
 881     </para>
 882
 883     <para>
 884      All dates and times are stored internally in Universal UTC,
 885      alternately known as Greenwich Mean Time (GMT).
 886      Times are converted to local time on the database server before being
 887      sent to the client frontend, hence by default are in the server
 888      time zone.
 889     </para>
 890
 891     <para>
 892      There are several ways to affect the time zone behavior:
 893
 894      <itemizedlist spacing="compact" mark="bullet">
 895       <listitem>
 896        <para>
 897         The TZ environment variable used by the backend directly
 898         on postmaster startup as the default time zone.
 899        </para>
 900       </listitem>
 901       <listitem>
 902        <para>
 903         The PGTZ environment variable set at the client used by libpq
 904         to send time zone information to the backend upon connection.
 905        </para>
 906       </listitem>
 907       <listitem>
 908        <para>
 909         The <acronym>SQL</acronym> command <command>SET TIME ZONE</command>
 910         sets the time zone for the session.
 911        </para>
 912       </listitem>
 913      </itemizedlist></para>
 914
 915     <para>
 916      If an invalid time zone is specified,
 917      the time zone becomes GMT (on most systems anyway).
 918     </para>
 919    </sect2>
 920
 921    <sect2>
 922     <title>Date/Time Input</title>
 923
 924     <para>
 925      General-use date and time is input using a wide range of
 926      styles, including ISO-compatible, <acronym>SQL</acronym>-compatible,
 927      traditional <productname>Postgres</productname>
 928      and other permutations of date and time. In cases where interpretation
 929      can be ambiguous (quite possible with many traditional styles of date
 930      specification) <productname>Postgres</productname> uses a style setting
 931      to resolve the ambiguity.
 932     </para>
 933
 934     <para>
 935      Most date and time types share code for data input. For those types
 936      the input can have any of a wide variety of styles. For numeric date
 937      representations,
 938      European and US conventions can differ, and the proper interpretation
 939      is obtained by using the <command>SET DATESTYLE</command>
 940      command before entering data.
 941      Note that the style setting does not preclude use of various styles for input;
 942      it is used primarily to determine the output style and to resolve ambiguities.
 943     </para>
 944
 945     <para>
 946      The special values <literal>current</literal>,
 947      <literal>infinity</literal> and <literal>-infinity</literal> are provided.
 948      <literal>infinity</literal> specifies a time later than any other valid time, and
 949      <literal>-infinity</literal> specifies a time earlier than any other valid time.
 950      <literal>current</literal> indicates that the current time should be
 951      substituted whenever this value appears in a computation.
 952     </para>
 953
 954     <para>
 955      The strings
 956      <literal>now</literal>,
 957      <literal>today</literal>,
 958      <literal>yesterday</literal>,
 959      <literal>tomorrow</literal>,
 960      and <literal>epoch</literal>
 961      can be used to specify time values.
 962      <literal>now</literal>
 963      means the current transaction time, and differs from
 964      <literal>current</literal>
 965      in that the current time is immediately substituted for it.
 966      <literal>epoch</literal> means <literal>Jan 1 00:00:00 1970 GMT</literal>.
 967     </para>
 968
 969     <para>
 970      <table tocentry="1">
 971       <title><productname>Postgres</productname> Date/Time Special Constants</title>
 972       <titleabbrev>Constants</titleabbrev>
 973       <tgroup cols="2">
 974        <thead>
 975         <row>
 976          <entry>Constant</entry>
 977          <entry>Description</entry>
 978         </row>
 979        </thead>
 980        <tbody>
 981         <row>
 982          <entry>current</entry>
 983          <entry>Current transaction time, deferred</entry>
 984         </row>
 985         <row>
 986          <entry>epoch</entry>
 987          <entry>1970-01-01 00:00:00+00 (Unix system time zero)</entry>
 988         </row>
 989         <row>
 990          <entry>infinity</entry>
 991          <entry>Later than other valid times</entry>
 992         </row>
 993         <row>
 994          <entry>-infinity</entry>
 995          <entry>Earlier than other valid times</entry>
 996         </row>
 997         <row>
 998          <entry>invalid</entry>
 999          <entry>Illegal entry</entry>
1000         </row>
1001         <row>
1002          <entry>now</entry>
1003          <entry>Current transaction time</entry>
1004         </row>
1005         <row>
1006          <entry>today</entry>
1007          <entry>Midnight today</entry>
1008         </row>
1009         <row>
1010          <entry>tomorrow</entry>
1011          <entry>Midnight tomorrow</entry>
1012         </row>
1013         <row>
1014          <entry>yesterday</entry>
1015          <entry>Midnight yesterday</entry>
1016         </row>
1017        </tbody>
1018       </tgroup>
1019      </table>
1020     </para>
1021
1022     <para>
1023      <table tocentry="1">
1024       <title><productname>Postgres</productname> Date Input</title>
1025       <titleabbrev>Date Inputs</titleabbrev>
1026       <tgroup cols="2">
1027        <thead>
1028         <row>
1029          <entry>Example</entry>
1030          <entry>Description</entry>
1031         </row>
1032        </thead>
1033        <tbody>
1034         <row>
1035          <entry>January 8, 1999</entry>
1036          <entry>Unambiguous text month</entry>
1037         </row>
1038         <row>
1039          <entry>1999-01-08</entry>
1040          <entry>ISO-8601</entry>
1041         </row>
1042         <row>
1043          <entry>1/8/1999</entry>
1044          <entry>US; read as August 1 in European mode</entry>
1045         </row>
1046         <row>
1047          <entry>8/1/1999</entry>
1048          <entry>European; read as August 1 in US mode</entry>
1049         </row>
1050         <row>
1051          <entry>1/18/1999</entry>
1052          <entry>US; read as January 18 in any mode</entry>
1053         </row>
1054         <row>
1055          <entry>1999.008</entry>
1056          <entry>Year and day of year</entry>
1057         </row>
1058         <row>
1059          <entry>19990108</entry>
1060          <entry>ISO-8601 year, month, day</entry>
1061         </row>
1062         <row>
1063          <entry>990108</entry>
1064          <entry>ISO-8601 year, month, day</entry>
1065         </row>
1066         <row>
1067          <entry>1999.008</entry>
1068          <entry>Year and day of year</entry>
1069         </row>
1070         <row>
1071          <entry>99008</entry>
1072          <entry>Year and day of year</entry>
1073         </row>
1074         <row>
1075          <entry>January 8, 99 BC</entry>
1076          <entry>Year 99 before the Christian Era</entry>
1077         </row>
1078        </tbody>
1079       </tgroup>
1080      </table>
1081     </para>
1082
1083     <para>
1084      <table tocentry="1">
1085       <title><productname>Postgres</productname> Month Abbreviations</title>
1086       <titleabbrev>Month Abbreviations</titleabbrev>
1087       <tgroup cols="2">
1088        <thead>
1089         <row>
1090          <entry>Month</entry>
1091          <entry>Abbreviations</entry>
1092         </row>
1093        </thead>
1094        <tbody>
1095         <row>
1096          <entry>April</entry>
1097          <entry>Apr</entry>
1098         </row>
1099         <row>
1100          <entry>August</entry>
1101          <entry>Aug</entry>
1102         </row>
1103         <row>
1104          <entry>December</entry>
1105          <entry>Dec</entry>
1106         </row>
1107         <row>
1108          <entry>February</entry>
1109          <entry>Feb</entry>
1110         </row>
1111         <row>
1112          <entry>January</entry>
1113          <entry>Jan</entry>
1114         </row>
1115         <row>
1116          <entry>July</entry>
1117          <entry>Jul</entry>
1118         </row>
1119         <row>
1120          <entry>June</entry>
1121          <entry>Jun</entry>
1122         </row>
1123         <row>
1124          <entry>March</entry>
1125          <entry>Mar</entry>
1126         </row>
1127         <row>
1128          <entry>November</entry>
1129          <entry>Nov</entry>
1130         </row>
1131         <row>
1132          <entry>October</entry>
1133          <entry>Oct</entry>
1134         </row>
1135         <row>
1136          <entry>September</entry>
1137          <entry>Sep, Sept</entry>
1138         </row>
1139        </tbody>
1140       </tgroup>
1141      </table>
1142
1143      <note>
1144       <para>
1145        The month <literal>May</literal> has no explicit abbreviation, for obvious reasons.
1146       </para>
1147      </note>
1148     </para>
1149
1150     <para>
1151      <table tocentry="1">
1152       <title><productname>Postgres</productname> Day of Week Abbreviations</title>
1153       <titleabbrev>Day of Week Abbreviations</titleabbrev>
1154       <tgroup cols="2">
1155        <thead>
1156         <row>
1157          <entry>Day</entry>
1158          <entry>Abbreviation</entry>
1159         </row>
1160        </thead>
1161        <tbody>
1162         <row>
1163          <entry>Sunday</entry>
1164          <entry>Sun</entry>
1165         </row>
1166         <row>
1167          <entry>Monday</entry>
1168          <entry>Mon</entry>
1169         </row>
1170         <row>
1171          <entry>Tuesday</entry>
1172          <entry>Tue, Tues</entry>
1173         </row>
1174         <row>
1175          <entry>Wednesday</entry>
1176          <entry>Wed, Weds</entry>
1177         </row>
1178         <row>
1179          <entry>Thursday</entry>
1180          <entry>Thu, Thur, Thurs</entry>
1181         </row>
1182         <row>
1183          <entry>Friday</entry>
1184          <entry>Fri</entry>
1185         </row>
1186         <row>
1187          <entry>Saturday</entry>
1188          <entry>Sat</entry>
1189         </row>
1190        </tbody>
1191       </tgroup>
1192      </table>
1193     </para>
1194
1195     <para>
1196      <table tocentry="1">
1197       <title><productname>Postgres</productname> Time Input</title>
1198       <titleabbrev>Time Inputs</titleabbrev>
1199       <tgroup cols="2">
1200        <thead>
1201         <row>
1202          <entry>Example</entry>
1203          <entry>Description</entry>
1204         </row>
1205        </thead>
1206        <tbody>
1207         <row>
1208          <entry>04:05:06.789</entry>
1209          <entry>ISO-8601, with all time fields</entry>
1210         </row>
1211         <row>
1212          <entry>04:05:06</entry>
1213          <entry>ISO-8601</entry>
1214         </row>
1215         <row>
1216          <entry>04:05</entry>
1217          <entry>ISO-8601</entry>
1218         </row>
1219         <row>
1220          <entry>040506</entry>
1221          <entry>ISO-8601</entry>
1222         </row>
1223         <row>
1224          <entry>04:05 AM</entry>
1225          <entry>Same as 04:05; AM does not affect value</entry>
1226         </row>
1227         <row>
1228          <entry>04:05 PM</entry>
1229          <entry>Same as 16:05; input hour must be <= 12</entry>
1230         </row>
1231         <row>
1232          <entry>z</entry>
1233          <entry>Same as 00:00:00</entry>
1234         </row>
1235         <row>
1236          <entry>zulu</entry>
1237          <entry>Same as 00:00:00</entry>
1238         </row>
1239         <row>
1240          <entry>allballs</entry>
1241          <entry>Same as 00:00:00</entry>
1242         </row>
1243        </tbody>
1244       </tgroup>
1245      </table>
1246     </para>
1247
1248     <para>
1249      <table tocentry="1">
1250       <title><productname>Postgres</productname> Time Zone Input</title>
1251       <titleabbrev>Time Zone Inputs</titleabbrev>
1252       <tgroup cols="2">
1253        <thead>
1254         <row>
1255          <entry>Time Zone</entry>
1256          <entry>Description</entry>
1257         </row>
1258        </thead>
1259        <tbody>
1260         <row>
1261          <entry>PST</entry>
1262          <entry>Pacific Standard Time</entry>
1263         </row>
1264         <row>
1265          <entry>-8:00</entry>
1266          <entry>ISO-8601 offset for PST</entry>
1267         </row>
1268         <row>
1269          <entry>-800</entry>
1270          <entry>ISO-8601 offset for PST</entry>
1271         </row>
1272         <row>
1273          <entry>-8</entry>
1274          <entry>ISO-8601 offset for PST</entry>
1275         </row>
1276        </tbody>
1277       </tgroup>
1278      </table>
1279     </para>
1280
1281     <para>
1282      See <xref linkend="datetime-appendix-title" endterm="datetime-appendix-title">
1283      for details on time zones recognized by <productname>Postgres</productname>.
1284
1285      <note>
1286       <para>
1287        If the compiler option USE_AUSTRALIAN_RULES is set
1288        then <literal>EST</literal> refers to Australia Eastern Std Time,
1289        which has an offset of +10:00 hours from UTC.
1290       </para>
1291      </note>
1292     </para>
1293
1294     <para>
1295      Australian time zones and their naming variants
1296      account for fully one quarter of all time zones in the
1297      <productname>Postgres</productname> time zone lookup table.
1298     </para>
1299
1300    </sect2>
1301
1302    <sect2>
1303     <title>datetime</title>
1304
1305 <para>
1306 General-use date and time is input using a wide range of
1307 styles, including ISO-compatible, <acronym>SQL</acronym>-compatible, traditional
1308 <productname>Postgres</productname> (see section on "absolute time")
1309 and other permutations of date and time. Output styles can be ISO-compatible,
1310 <acronym>SQL</acronym>-compatible, or traditional
1311 <productname>Postgres</productname>, with the default set to be compatible
1312 with <productname>Postgres</productname> v6.0.
1313 </para>
1314
1315 <para>
1316 <type>datetime</type> is specified using the following syntax:
1317
1318 <programlisting>
1319 Year-Month-Day [ Hour : Minute : Second ]      [AD,BC] [ Timezone ]
1320   YearMonthDay [ Hour : Minute : Second ]      [AD,BC] [ Timezone ]
1321      Month Day [ Hour : Minute : Second ] Year [AD,BC] [ Timezone ]
1322 where
1323     Year is 4013 BC, ..., very large
1324     Month is Jan, Feb, ..., Dec or 1, 2, ..., 12
1325     Day is 1, 2, ..., 31
1326     Hour is 00, 02, ..., 23
1327     Minute is 00, 01, ..., 59
1328     Second is 00, 01, ..., 59 (60 for leap second)
1329     Timezone is 3 characters or ISO offset to GMT
1330 </programlisting>
1331     </para>
1332
1333 <para>
1334 Valid dates are from Nov 13 00:00:00 4013 BC GMT to far into the future.
1335 Timezones are either three characters (e.g. "GMT" or "PST") or ISO-compatible
1336 offsets to GMT (e.g. "-08" or "-08:00" when in Pacific Standard Time).
1337 Dates are stored internally in Greenwich Mean Time. Input and output routines
1338 translate time to the local time zone of the server.
1339 </para></sect2>
1340
1341 <sect2>
1342 <title><type>timespan</type></title>
1343
1344 <para>
1345 General-use time span is input using a wide range of
1346 syntaxes, including ISO-compatible, <acronym>SQL</acronym>-compatible,
1347 traditional
1348 <productname>Postgres</productname> (see section on "relative time")
1349  and other permutations of time span. Output formats can be ISO-compatible,
1350 <acronym>SQL</acronym>-compatible, or traditional
1351 <productname>Postgres</productname>,
1352 with the default set to be <productname>Postgres</productname>-compatible.
1353 Months and years are a "qualitative" time interval, and are stored separately
1354 from the other "quantitative" time intervals such as day or hour.
1355 For date arithmetic,
1356 the qualitative time units are instantiated in the context of the
1357 relevant date or time.
1358     </para>
1359
1360 <para>
1361 Time span is specified with the following syntax:
1362
1363 <programlisting>
1364   Quantity Unit [Quantity Unit...] [Direction]
1365 @ Quantity Unit [Direction]
1366 where
1367     Quantity is ..., <literal>-1</literal>, <literal>0</literal>, <literal>1</literal>, <literal>2</literal>, ...
1368     Unit is <literal>second</literal>, <literal>minute</literal>, <literal>hour</literal>, <literal>day</literal>, <literal>week</literal>, <literal>month</literal>, <literal>year</literal>,
1369       <literal>decade</literal>, <literal>century</literal>, <literal>millenium</literal>, or abbreviations or plurals of these units.
1370     Direction is <literal>ago</literal>.
1371 </programlisting>
1372 </para>
1373 </sect2>
1374
1375 <sect2>
1376 <title>abstime</title>
1377
1378     <para>
1379      Absolute time (<type>abstime</type>) is a limited-range (+/- 68 years) and
1380      limited-precision (1 sec)
1381      date data type. <type>datetime</type> may be preferred, since it
1382      covers a larger range with greater precision.
1383     </para>
1384
1385 <para>
1386 Absolute time is specified using the following syntax:
1387
1388 <programlisting>
1389 Month  Day [ Hour : Minute : Second ]  Year [ Timezone ]
1390 where
1391     Month is Jan, Feb, ..., Dec
1392     Day is 1, 2, ..., 31
1393     Hour is 01, 02, ..., 24
1394     Minute is 00, 01, ..., 59
1395     Second is 00, 01, ..., 59
1396     Year is 1901, 1902, ..., 2038
1397 </programlisting>
1398 </para>
1399
1400 <para>
1401      Valid dates are from <literal>Dec 13 20:45:53 1901 GMT</literal>
1402      to <literal>Jan 19 03:14:04 2038 GMT</literal>.
1403
1404 <note>
1405 <title>Historical Note</title>
1406 <para>
1407 As of Version 3.0, times are no longer read and written
1408 using Greenwich Mean Time; the input and output routines default to
1409 the local time zone.</para>
1410 </note>
1411
1412 All special values allowed for <type>datetime</type> are also
1413 allowed for "absolute time".
1414 </para>
1415
1416 </sect2>
1417
1418 <sect2>
1419 <title>reltime</title>
1420
1421 <para>
1422 Relative time <type>reltime</type> is a limited-range (+/- 68 years)
1423  and limited-precision (1 sec) time span data type.
1424 <type>timespan</type> should be preferred, since it
1425 covers a larger range with greater precision and, more importantly,
1426 can distinguish between
1427 relative units (months and years) and quantitative units (days, hours, etc).
1428 Instead, reltime
1429 must force months to be exactly 30 days, so time arithmetic does not
1430 always work as expected.
1431      For example, adding one reltime <literal>year</literal> to abstime <literal>today</literal> does not
1432 produce today's date one year from
1433 now, but rather a date 360 days from today.
1434 </para>
1435
1436 <para>
1437 <type>reltime</type> shares input and output routines with the other
1438 time span types.
1439 The section on <type>timespan</type> covers this in more detail.
1440 </para>
1441
1442 </sect2>
1443
1444 <sect2>
1445 <title><type>timestamp</type></title>
1446
1447 <para>
1448 This is currently a limited-range absolute time which closely resembles the
1449 abstime
1450 data type. It shares the general input parser with the other date/time types.
1451 In future releases this type will absorb the capabilities of the
1452 <type>datetime</type> type
1453 and will move toward <acronym>SQL92</acronym> compliance.
1454 </para>
1455
1456 <para>
1457 <type>timestamp</type> is specified using the same syntax as for
1458 <type>datetime</type>.
1459 </para>
1460 </sect2>
1461
1462 <sect2>
1463 <title><type>interval</type></title>
1464
1465 <para>
1466 <type>interval</type> is an <acronym>SQL92</acronym> data type which is
1467 currently mapped to the <type>timespan</type>
1468 <productname>Postgres</productname> data type.
1469 </para>
1470 </sect2>
1471
1472 <sect2>
1473 <title>tinterval</title>
1474
1475 <para>
1476 Time ranges are specified as:
1477
1478 <programlisting>
1479 [ 'abstime' 'abstime']
1480 where
1481     abstime is a time in the absolute time format.
1482 </programlisting>
1483
1484 Special abstime values such as
1485 <literal>current', <literal>infinity' and <literal>-infinity' can be used.</literal></literal></literal>
1486 </para></sect2>
1487
1488 </sect1>
1489
1490 <sect1>
1491 <title>Boolean Type</title>
1492
1493 <para>
1494 <productname>Postgres</productname> supports <type>bool</type> as
1495 the <acronym>SQL3</acronym> boolean type.
1496 <type>bool</type> can have one of only two states: 'true' or 'false'.
1497 A third state, 'unknown', is not
1498 implemented and is not suggested in <acronym>SQL3</acronym>;
1499 <acronym>NULL</acronym> is an
1500 effective substitute. <type>bool</type> can be used in any boolean expression,
1501 and boolean expressions
1502 always evaluate to a result compatible with this type.</para>
1503
1504 <para>
1505 <type>bool</type> uses 1 byte of storage.
1506 </para>
1507
1508 <para>
1509 <table tocentry="1">
1510 <title><productname>Postgres</productname> Boolean Type</title>
1511 <titleabbrev>Booleans</titleabbrev>
1512 <tgroup cols="3">
1513 <thead>
1514   <row>
1515     <entry>State</entry>
1516     <entry>Output</entry>
1517     <entry>Input</entry>
1518   </row>
1519 </thead>
1520 <tbody>
1521   <row>
1522     <entry>True</entry>
1523     <entry>'t'</entry>
1524     <entry>TRUE, 't', 'true', 'y', 'yes', '1'</entry>
1525   </row>
1526   <row>
1527     <entry>False</entry>
1528     <entry>'f'</entry>
1529     <entry>FALSE, 'f', 'false', 'n', 'no', '0'</entry>
1530   </row>
1531 </tbody>
1532 </tgroup>
1533 </table>
1534 </para>
1535 </sect1>
1536
1537 <sect1>
1538 <title>Geometric Types</title>
1539
1540 <para>
1541 Geometric types represent two-dimensional spatial objects.
1542 The most fundamental type,
1543 the point, forms the basis for all of the other types.
1544 </para>
1545
1546 <para>
1547 <table tocentry="1">
1548 <title><productname>Postgres</productname> Geometric Types</title>
1549 <titleabbrev>Geometrics</titleabbrev>
1550 <tgroup cols="4">
1551 <thead>
1552   <row>
1553     <entry>Geometric Type</entry>
1554     <entry>Storage</entry>
1555     <entry>Representation</entry>
1556     <entry>Description</entry>
1557   </row>
1558 </thead>
1559 <tbody>
1560   <row>
1561     <entry>point</entry>
1562     <entry>16 bytes</entry>
1563     <entry>(x,y)</entry>
1564     <entry>Point in space</entry>
1565   </row>
1566   <row>
1567     <entry>line</entry>
1568     <entry>32 bytes</entry>
1569     <entry>((x1,y1),(x2,y2))</entry>
1570     <entry>Infinite line</entry>
1571   </row>
1572   <row>
1573     <entry>lseg</entry>
1574     <entry>32 bytes</entry>
1575     <entry>((x1,y1),(x2,y2))</entry>
1576     <entry>Finite line segment</entry>
1577   </row>
1578   <row>
1579     <entry>box</entry>
1580     <entry>32 bytes</entry>
1581     <entry>((x1,y1),(x2,y2))</entry>
1582     <entry>Rectangular box</entry>
1583   </row>
1584   <row>
1585     <entry>path</entry>
1586     <entry>4+32n bytes</entry>
1587     <entry>((x1,y1),...)</entry>
1588     <entry>Closed path (similar to polygon)</entry>
1589   </row>
1590   <row>
1591     <entry>path</entry>
1592     <entry>4+32n bytes</entry>
1593     <entry>[(x1,y1),...]</entry>
1594     <entry>Open path</entry>
1595   </row>
1596   <row>
1597     <entry>polygon</entry>
1598     <entry>4+32n bytes</entry>
1599     <entry>((x1,y1),...)</entry>
1600     <entry>Polygon (similar to closed path)</entry>
1601   </row>
1602   <row>
1603     <entry>circle</entry>
1604     <entry>24 bytes</entry>
1605     <entry><(x,y),r></entry>
1606     <entry>Circle (center and radius)</entry>
1607   </row>
1608 </tbody>
1609 </tgroup>
1610 </table>
1611 </para>
1612
1613 <para>
1614 A rich set of functions and operators is available to perform various geometric
1615 operations such as scaling, translation, rotation, and determining
1616 intersections.
1617 </para>
1618
1619 <sect2>
1620 <title>Point</title>
1621
1622     <para>
1623      Points are the fundamental two-dimensional building block for geometric types.
1624     </para>
1625
1626 <para>
1627 <type>point</type> is specified using the following syntax:
1628
1629 <programlisting>
1630 ( x , y )
1631   x , y
1632 where
1633     x is the x-axis coordinate as a floating point number
1634     y is the y-axis coordinate as a floating point number
1635 </programlisting>
1636 </para>
1637 </sect2>
1638
1639 <sect2>
1640 <title>Line Segment</title>
1641
1642 <para>
1643 Line segments (lseg) are represented by pairs of points.
1644 </para>
1645
1646 <para>
1647 <type>lseg</type> is specified using the following syntax:
1648 <programlisting>
1649 ( ( x1 , y1 ) , ( x2 , y2 ) )
1650   ( x1 , y1 ) , ( x2 , y2 )
1651     x1 , y1   ,   x2 , y2
1652 where
1653     (x1,y1) and (x2,y2) are the endpoints of the segment
1654 </programlisting>
1655 </para>
1656 </sect2>
1657
1658 <sect2>
1659 <title>Box</title>
1660
1661 <para>
1662 Boxes are represented by pairs of points which are opposite
1663 corners of the box.
1664 </para>
1665
1666 <para>
1667      <type>box</type> is specified using the following syntax:
1668
1669 <programlisting>
1670 ( ( x1 , y1 ) , ( x2 , y2 ) )
1671   ( x1 , y1 ) , ( x2 , y2 )
1672     x1 , y1   ,   x2 , y2
1673 where
1674     (x1,y1) and (x2,y2) are opposite corners
1675 </programlisting>
1676
1677 Boxes are output using the first syntax.
1678 The corners are reordered on input to store
1679 the lower left corner first and the upper right corner last.
1680 Other corners of the box can be entered, but the lower
1681 left and upper right corners are determined from the input and stored.
1682 </para>
1683 </sect2>
1684
1685 <sect2>
1686 <title>Path</title>
1687
1688 <para>
1689 Paths are represented by connected sets of points. Paths can be "open", where
1690 the first and last points in the set are not connected, and "closed",
1691 where the first and last point are connected. Functions
1692 <function>popen(p)</function>
1693 and
1694 <function>pclose(p)</function>
1695 are supplied to force a path to be open or closed, and functions
1696 <function>isopen(p)</function>
1697 and
1698 <function>isclosed(p)</function>
1699 are supplied to select either type in a query.
1700 </para>
1701
1702 <para>
1703 path is specified using the following syntax:
1704
1705 <programlisting>
1706 ( ( x1 , y1 ) , ... , ( xn , yn ) )
1707 [ ( x1 , y1 ) , ... , ( xn , yn ) ]
1708   ( x1 , y1 ) , ... , ( xn , yn )
1709   ( x1 , y1   , ... ,   xn , yn )
1710     x1 , y1   , ... ,   xn , yn
1711 where
1712     (x1,y1),...,(xn,yn) are points 1 through n
1713     a leading "[" indicates an open path
1714     a leading "(" indicates a closed path
1715 </programlisting>
1716 Paths are output using the first syntax.
1717 Note that <productname>Postgres</productname> versions prior to
1718 v6.1 used a format for paths which had a single leading parenthesis,
1719 a "closed" flag,
1720 an integer count of the number of points, then the list of points followed by a
1721 closing parenthesis.
1722 The built-in function <function>upgradepath</function> is supplied to convert
1723 paths dumped and reloaded from pre-v6.1 databases.
1724 </para>
1725 </sect2>
1726
1727 <sect2>
1728 <title>Polygon</title>
1729
1730 <para>
1731 Polygons are represented by sets of points. Polygons should probably be
1732 considered equivalent to closed paths, but are stored differently
1733 and have their own set of support routines.
1734 </para>
1735
1736 <para>
1737 <type>polygon</type> is specified using the following syntax:
1738
1739 <programlisting>
1740 ( ( x1 , y1 ) , ... , ( xn , yn ) )
1741   ( x1 , y1 ) , ... , ( xn , yn )
1742   ( x1 , y1   , ... ,   xn , yn )
1743     x1 , y1   , ... ,   xn , yn
1744 where
1745     (x1,y1),...,(xn,yn) are points 1 through n
1746 </programlisting>
1747
1748 Polygons are output using the first syntax.
1749 Note that <productname>Postgres</productname> versions prior to
1750 v6.1 used a format for polygons which had a single leading parenthesis, the list
1751 of x-axis coordinates, the list of y-axis coordinates,
1752 followed by a closing parenthesis.
1753 The built-in function <function>upgradepoly</function> is supplied to convert
1754 polygons dumped and reloaded from pre-v6.1 databases.
1755 </para>
1756 </sect2>
1757
1758 <sect2>
1759 <title>Circle</title>
1760
1761 <para>
1762 Circles are represented by a center point and a radius.
1763 </para>
1764
1765 <para>
1766 circle is specified using the following syntax:
1767
1768 <programlisting>
1769 < ( x , y ) , r >
1770 ( ( x , y ) , r )
1771   ( x , y ) , r
1772     x , y   , r
1773 where
1774     (x,y) is the center of the circle
1775     r is the radius of the circle
1776 </programlisting>
1777
1778 Circles are output using the first syntax.
1779 </para>
1780 </sect2>
1781
1782 </sect1>
1783
1784 <sect1>
1785 <title>IP Version 4 Networks and Host Addresses</title>
1786
1787 <para>
1788 The <type>cidr</type> type stores networks specified
1789 in <acronym>CIDR</acronym> (Classless Inter-Domain Routing) notation.
1790 The <type>inet</type> type stores hosts and networks in CIDR notation using a simple
1791 variation in representation to represent simple host TCP/IP addresses.
1792 </para>
1793
1794 <para>
1795 <table tocentry="1">
1796 <title><productname>Postgres</productname>IP Version 4 Types</title>
1797 <titleabbrev>IPV4</titleabbrev>
1798 <tgroup cols="4">
1799 <thead>
1800   <row>
1801     <entry>IPV4 Type</entry>
1802     <entry>Storage</entry>
1803     <entry>Description</entry>
1804     <entry>Range</entry>
1805   </row>
1806 </thead>
1807 <tbody>
1808   <row>
1809     <entry>cidr</entry>
1810     <entry>variable</entry>
1811     <entry>CIDR networks</entry>
1812     <entry>Valid IPV4 CIDR blocks</entry>
1813   </row>
1814   <row>
1815     <entry>inet</entry>
1816     <entry>variable</entry>
1817     <entry>nets and hosts</entry>
1818     <entry>Valid IPV4 CIDR blocks</entry>
1819   </row>
1820 </tbody>
1821 </tgroup>
1822 </table>
1823 </para>
1824
1825 <sect2>
1826 <title>CIDR</title>
1827
1828 <para>
1829 The <type>cidr</type> type holds a CIDR network.
1830 The format for specifying classless networks is <replaceable class="parameter">x.x.x.x/y</replaceable>
1831  where <replaceable class="parameter">x.x.x.x</replaceable> is the
1832 network and <replaceable class="parameter">/y</replaceable> is the number of bits in the netmask.
1833 If <replaceable class="parameter">/y</replaceable> omitted, it is calculated using assumptions from
1834 the older classfull naming system except that it is extended to include at least
1835 all of the octets in the input.
1836 </para>
1837
1838 <para>
1839 Here are some examples:
1840
1841      <table tocentry="1">
1842       <title><productname>Postgres</productname>IP Types Examples</title>
1843       <tgroup cols="2">
1844        <thead>
1845         <row>
1846          <entry>CIDR Input</entry>
1847          <entry>CIDR Displayed</entry>
1848         </row>
1849        </thead>
1850        <tbody>
1851         <row>
1852          <entry>192.168.1</entry>
1853          <entry>192.168.1/24</entry>
1854         </row>
1855         <row>
1856          <entry>192.168</entry>
1857          <entry>192.168.0/24</entry>
1858         </row>
1859         <row>
1860          <entry>128.1</entry>
1861          <entry>128.1/16</entry>
1862         </row>
1863         <row>
1864          <entry>128</entry>
1865          <entry>128.0/16</entry>
1866         </row>
1867         <row>
1868          <entry>128.1.2</entry>
1869          <entry>128.1.2/24</entry>
1870         </row>
1871         <row>
1872          <entry>10.1.2</entry>
1873          <entry>10.1.2/24</entry>
1874         </row>
1875         <row>
1876          <entry>10.1</entry>
1877          <entry>10.1/16</entry>
1878         </row>
1879         <row>
1880          <entry>10</entry>
1881          <entry>10/8</entry>
1882         </row>
1883        </tbody>
1884       </tgroup>
1885      </table>
1886     </para>
1887    </sect2>
1888
1889    <sect2>
1890     <title id="inet-type"><type>inet</type></title>
1891
1892 <para>
1893 The <type>inet</type> type is designed to hold, in one field, all of the information
1894 about a host including the CIDR-style subnet that it is in.
1895 Note that if you want to store proper CIDR networks,
1896 you should use the <type>cidr</type> type.
1897 The <type>inet</type> type is similar to the <type>cidr</type> type except that the bits in the
1898 host part can be non-zero.
1899 Functions exist to extract the various elements of the field.
1900 </para>
1901
1902 <para>
1903      The input format for this function is
1904  <replaceable class="parameter">x.x.x.x/y</replaceable>
1905 where <replaceable class="parameter">x.x.x.x</replaceable> is
1906 an internet host and <replaceable class="parameter">y</replaceable>
1907 is the number of bits in the netmask.
1908 If the <replaceable class="parameter">/y</replaceable> part is left off,
1909 it is treated as <literal>/32</literal>.
1910 On output, the <replaceable class="parameter">/y</replaceable> part is not printed
1911 if it is <literal>/32</literal>.
1912 This allows the type to be used as a straight host type by just leaving off
1913 the bits part.
1914 </para></sect2>
1915 </sect1>
1916
1917 </chapter>
1918
1919 <!-- Keep this comment at the end of the file
1920 Local variables:
1921 mode: sgml
1922 sgml-omittag:nil
1923 sgml-shorttag:t
1924 sgml-minimize-attributes:nil
1925 sgml-always-quote-attributes:t
1926 sgml-indent-step:1
1927 sgml-indent-data:t
1928 sgml-parent-document:nil
1929 sgml-default-dtd-file:"./reference.ced"
1930 sgml-exposed-tags:nil
1931 sgml-local-catalogs:"/usr/lib/sgml/catalog"
1932 sgml-local-ecat-files:nil
1933 End:
1934 -->