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

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