doc/src/sgml/func.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3  <chapter id="functions">
   4   <title>Functions and Operators</title>
   5
   6   <indexterm zone="functions">
   7    <primary>function</primary>
   8   </indexterm>
   9
  10   <indexterm zone="functions">
  11    <primary>operator</primary>
  12   </indexterm>
  13
  14   <para>
  15    <productname>PostgreSQL</productname> provides a large number of
  16    functions and operators for the built-in data types.  Users can also
  17    define their own functions and operators, as described in
  18    <xref linkend="server-programming">.  The
  19    <application>psql</application> commands <command>\df</command> and
  20    <command>\do</command> can be used to list all
  21    available functions and operators, respectively.
  22   </para>
  23
  24   <para>
  25    If you are concerned about portability then note that most of
  26    the functions and operators described in this chapter, with the
  27    exception of the most trivial arithmetic and comparison operators
  28    and some explicitly marked functions, are not specified by the
  29    <acronym>SQL</acronym> standard. Some of this extended functionality
  30    is present in other <acronym>SQL</acronym> database management
  31    systems, and in many cases this functionality is compatible and
  32    consistent between the various implementations.  This chapter is also
  33    not exhaustive;  additional functions appear in relevant sections of
  34    the manual.
  35   </para>
  36
  37
  38   <sect1 id="functions-logical">
  39    <title>Logical Operators</title>
  40
  41    <indexterm zone="functions-logical">
  42     <primary>operator</primary>
  43     <secondary>logical</secondary>
  44    </indexterm>
  45
  46    <indexterm>
  47     <primary>Boolean</primary>
  48     <secondary>operators</secondary>
  49     <see>operators, logical</see>
  50    </indexterm>
  51
  52    <para>
  53     The usual logical operators are available:
  54
  55     <indexterm>
  56      <primary>AND (operator)</primary>
  57     </indexterm>
  58
  59     <indexterm>
  60      <primary>OR (operator)</primary>
  61     </indexterm>
  62
  63     <indexterm>
  64      <primary>NOT (operator)</primary>
  65     </indexterm>
  66
  67     <indexterm>
  68      <primary>conjunction</primary>
  69     </indexterm>
  70
  71     <indexterm>
  72      <primary>disjunction</primary>
  73     </indexterm>
  74
  75     <indexterm>
  76      <primary>negation</primary>
  77     </indexterm>
  78
  79     <simplelist>
  80      <member><literal>AND</></member>
  81      <member><literal>OR</></member>
  82      <member><literal>NOT</></member>
  83     </simplelist>
  84
  85     <acronym>SQL</acronym> uses a three-valued Boolean logic where the null value represents
  86     <quote>unknown</quote>.  Observe the following truth tables:
  87
  88     <informaltable>
  89      <tgroup cols="4">
  90       <thead>
  91        <row>
  92         <entry><replaceable>a</replaceable></entry>
  93         <entry><replaceable>b</replaceable></entry>
  94         <entry><replaceable>a</replaceable> AND <replaceable>b</replaceable></entry>
  95         <entry><replaceable>a</replaceable> OR <replaceable>b</replaceable></entry>
  96        </row>
  97       </thead>
  98
  99       <tbody>
 100        <row>
 101         <entry>TRUE</entry>
 102         <entry>TRUE</entry>
 103         <entry>TRUE</entry>
 104         <entry>TRUE</entry>
 105        </row>
 106
 107        <row>
 108         <entry>TRUE</entry>
 109         <entry>FALSE</entry>
 110         <entry>FALSE</entry>
 111         <entry>TRUE</entry>
 112        </row>
 113
 114        <row>
 115         <entry>TRUE</entry>
 116         <entry>NULL</entry>
 117         <entry>NULL</entry>
 118         <entry>TRUE</entry>
 119        </row>
 120
 121        <row>
 122         <entry>FALSE</entry>
 123         <entry>FALSE</entry>
 124         <entry>FALSE</entry>
 125         <entry>FALSE</entry>
 126        </row>
 127
 128        <row>
 129         <entry>FALSE</entry>
 130         <entry>NULL</entry>
 131         <entry>FALSE</entry>
 132         <entry>NULL</entry>
 133        </row>
 134
 135        <row>
 136         <entry>NULL</entry>
 137         <entry>NULL</entry>
 138         <entry>NULL</entry>
 139         <entry>NULL</entry>
 140        </row>
 141       </tbody>
 142      </tgroup>
 143     </informaltable>
 144
 145     <informaltable>
 146      <tgroup cols="2">
 147       <thead>
 148        <row>
 149         <entry><replaceable>a</replaceable></entry>
 150         <entry>NOT <replaceable>a</replaceable></entry>
 151        </row>
 152       </thead>
 153
 154       <tbody>
 155        <row>
 156         <entry>TRUE</entry>
 157         <entry>FALSE</entry>
 158        </row>
 159
 160        <row>
 161         <entry>FALSE</entry>
 162         <entry>TRUE</entry>
 163        </row>
 164
 165        <row>
 166         <entry>NULL</entry>
 167         <entry>NULL</entry>
 168        </row>
 169       </tbody>
 170      </tgroup>
 171     </informaltable>
 172    </para>
 173
 174    <para>
 175     The operators <literal>AND</literal> and <literal>OR</literal> are
 176     commutative, that is, you can switch the left and right operand
 177     without affecting the result.  But see <xref
 178     linkend="syntax-express-eval"> for more information about the
 179     order of evaluation of subexpressions.
 180    </para>
 181   </sect1>
 182
 183   <sect1 id="functions-comparison">
 184    <title>Comparison Operators</title>
 185
 186    <indexterm zone="functions-comparison">
 187     <primary>comparison</primary>
 188     <secondary>operators</secondary>
 189    </indexterm>
 190
 191    <para>
 192     The usual comparison operators are available, shown in <xref
 193     linkend="functions-comparison-table">.
 194    </para>
 195
 196    <table id="functions-comparison-table">
 197     <title>Comparison Operators</title>
 198     <tgroup cols="2">
 199      <thead>
 200       <row>
 201        <entry>Operator</entry>
 202        <entry>Description</entry>
 203       </row>
 204      </thead>
 205
 206      <tbody>
 207       <row>
 208        <entry> <literal>&lt;</literal> </entry>
 209        <entry>less than</entry>
 210       </row>
 211
 212       <row>
 213        <entry> <literal>&gt;</literal> </entry>
 214        <entry>greater than</entry>
 215       </row>
 216
 217       <row>
 218        <entry> <literal>&lt;=</literal> </entry>
 219        <entry>less than or equal to</entry>
 220       </row>
 221
 222       <row>
 223        <entry> <literal>&gt;=</literal> </entry>
 224        <entry>greater than or equal to</entry>
 225       </row>
 226
 227       <row>
 228        <entry> <literal>=</literal> </entry>
 229        <entry>equal</entry>
 230       </row>
 231
 232       <row>
 233        <entry> <literal>&lt;&gt;</literal> or <literal>!=</literal> </entry>
 234        <entry>not equal</entry>
 235       </row>
 236      </tbody>
 237     </tgroup>
 238    </table>
 239
 240    <note>
 241     <para>
 242      The <literal>!=</literal> operator is converted to
 243      <literal>&lt;&gt;</literal> in the parser stage.  It is not
 244      possible to implement <literal>!=</literal> and
 245      <literal>&lt;&gt;</literal> operators that do different things.
 246     </para>
 247    </note>
 248
 249    <para>
 250     Comparison operators are available for all relevant data types.
 251     All comparison operators are binary operators that
 252     return values of type <type>boolean</type>; expressions like
 253     <literal>1 &lt; 2 &lt; 3</literal> are not valid (because there is
 254     no <literal>&lt;</literal> operator to compare a Boolean value with
 255     <literal>3</literal>).
 256    </para>
 257
 258    <para>
 259     <indexterm>
 260      <primary>BETWEEN</primary>
 261     </indexterm>
 262     In addition to the comparison operators, the special
 263     <token>BETWEEN</token> construct is available:
 264 <synopsis>
 265 <replaceable>a</replaceable> BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceable>
 266 </synopsis>
 267     is equivalent to
 268 <synopsis>
 269 <replaceable>a</replaceable> &gt;= <replaceable>x</replaceable> AND <replaceable>a</replaceable> &lt;= <replaceable>y</replaceable>
 270 </synopsis>
 271     Notice that <token>BETWEEN</token> treats the endpoint values as included
 272     in the range.
 273     <literal>NOT BETWEEN</literal> does the opposite comparison:
 274 <synopsis>
 275 <replaceable>a</replaceable> NOT BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceable>
 276 </synopsis>
 277     is equivalent to
 278 <synopsis>
 279 <replaceable>a</replaceable> &lt; <replaceable>x</replaceable> OR <replaceable>a</replaceable> &gt; <replaceable>y</replaceable>
 280 </synopsis>
 281     <indexterm>
 282      <primary>BETWEEN SYMMETRIC</primary>
 283     </indexterm>
 284     <literal>BETWEEN SYMMETRIC</> is the same as <literal>BETWEEN</>
 285     except there is no requirement that the argument to the left of
 286     <literal>AND</> be less than or equal to the argument on the right.
 287     If it is not, those two arguments are automatically swapped, so that
 288     a nonempty range is always implied.
 289    </para>
 290
 291    <para>
 292     <indexterm>
 293      <primary>IS NULL</primary>
 294     </indexterm>
 295     <indexterm>
 296      <primary>IS NOT NULL</primary>
 297     </indexterm>
 298     <indexterm>
 299      <primary>ISNULL</primary>
 300     </indexterm>
 301     <indexterm>
 302      <primary>NOTNULL</primary>
 303     </indexterm>
 304     To check whether a value is or is not null, use the constructs:
 305 <synopsis>
 306 <replaceable>expression</replaceable> IS NULL
 307 <replaceable>expression</replaceable> IS NOT NULL
 308 </synopsis>
 309     or the equivalent, but nonstandard, constructs:
 310 <synopsis>
 311 <replaceable>expression</replaceable> ISNULL
 312 <replaceable>expression</replaceable> NOTNULL
 313 </synopsis>
 314     <indexterm><primary>null value</primary><secondary>comparing</secondary></indexterm>
 315    </para>
 316
 317    <para>
 318     Do <emphasis>not</emphasis> write
 319     <literal><replaceable>expression</replaceable> = NULL</literal>
 320     because <literal>NULL</> is not <quote>equal to</quote>
 321     <literal>NULL</>.  (The null value represents an unknown value,
 322     and it is not known whether two unknown values are equal.) This
 323     behavior conforms to the SQL standard.
 324    </para>
 325
 326   <tip>
 327    <para>
 328     Some applications might expect that
 329     <literal><replaceable>expression</replaceable> = NULL</literal>
 330     returns true if <replaceable>expression</replaceable> evaluates to
 331     the null value.  It is highly recommended that these applications
 332     be modified to comply with the SQL standard. However, if that
 333     cannot be done the <xref linkend="guc-transform-null-equals">
 334     configuration variable is available. If it is enabled,
 335     <productname>PostgreSQL</productname> will convert <literal>x =
 336     NULL</literal> clauses to <literal>x IS NULL</literal>.
 337    </para>
 338   </tip>
 339
 340   <note>
 341    <para>
 342     If the <replaceable>expression</replaceable> is row-valued, then
 343     <literal>IS NULL</> is true when the row expression itself is null
 344     or when all the row's fields are null, while
 345     <literal>IS NOT NULL</> is true when the row expression itself is non-null
 346     and all the row's fields are non-null.  Because of this behavior,
 347     <literal>IS NULL</> and <literal>IS NOT NULL</> do not always return
 348     inverse results for row-valued expressions, i.e., a row-valued
 349     expression that contains both NULL and non-null values will return false
 350     for both tests.
 351     This definition conforms to the SQL standard, and is a change from the
 352     inconsistent behavior exhibited by <productname>PostgreSQL</productname>
 353     versions prior to 8.2.
 354    </para>
 355   </note>
 356
 357    <para>
 358     <indexterm>
 359      <primary>IS DISTINCT FROM</primary>
 360     </indexterm>
 361     <indexterm>
 362      <primary>IS NOT DISTINCT FROM</primary>
 363     </indexterm>
 364     Ordinary comparison operators yield null (signifying <quote>unknown</>),
 365     not true or false, when either input is null.  For example,
 366     <literal>7 = NULL</> yields null.  When this behavior is not suitable,
 367     use the
 368     <literal>IS <optional> NOT </> DISTINCT FROM</literal> constructs:
 369 <synopsis>
 370 <replaceable>expression</replaceable> IS DISTINCT FROM <replaceable>expression</replaceable>
 371 <replaceable>expression</replaceable> IS NOT DISTINCT FROM <replaceable>expression</replaceable>
 372 </synopsis>
 373     For non-null inputs, <literal>IS DISTINCT FROM</literal> is
 374     the same as the <literal>&lt;&gt;</> operator.  However, if both
 375     inputs are null it returns false, and if only one input is
 376     null it returns true.  Similarly, <literal>IS NOT DISTINCT
 377     FROM</literal> is identical to <literal>=</literal> for non-null
 378     inputs, but it returns true when both inputs are null, and false when only
 379     one input is null. Thus, these constructs effectively act as though null
 380     were a normal data value, rather than <quote>unknown</>.
 381    </para>
 382
 383    <para>
 384     <indexterm>
 385      <primary>IS TRUE</primary>
 386     </indexterm>
 387     <indexterm>
 388      <primary>IS NOT TRUE</primary>
 389     </indexterm>
 390     <indexterm>
 391      <primary>IS FALSE</primary>
 392     </indexterm>
 393     <indexterm>
 394      <primary>IS NOT FALSE</primary>
 395     </indexterm>
 396     <indexterm>
 397      <primary>IS UNKNOWN</primary>
 398     </indexterm>
 399     <indexterm>
 400      <primary>IS NOT UNKNOWN</primary>
 401     </indexterm>
 402     Boolean values can also be tested using the constructs
 403 <synopsis>
 404 <replaceable>expression</replaceable> IS TRUE
 405 <replaceable>expression</replaceable> IS NOT TRUE
 406 <replaceable>expression</replaceable> IS FALSE
 407 <replaceable>expression</replaceable> IS NOT FALSE
 408 <replaceable>expression</replaceable> IS UNKNOWN
 409 <replaceable>expression</replaceable> IS NOT UNKNOWN
 410 </synopsis>
 411     These will always return true or false, never a null value, even when the
 412     operand is null.
 413     A null input is treated as the logical value <quote>unknown</>.
 414     Notice that <literal>IS UNKNOWN</> and <literal>IS NOT UNKNOWN</> are
 415     effectively the same as <literal>IS NULL</literal> and
 416     <literal>IS NOT NULL</literal>, respectively, except that the input
 417     expression must be of Boolean type.
 418    </para>
 419
 420 <!-- IS OF does not conform to the ISO SQL behavior, so it is undocumented here
 421    <para>
 422     <indexterm>
 423      <primary>IS OF</primary>
 424     </indexterm>
 425     <indexterm>
 426      <primary>IS NOT OF</primary>
 427     </indexterm>
 428     It is possible to check the data type of an expression using the
 429     constructs
 430 <synopsis>
 431 <replaceable>expression</replaceable> IS OF (typename, ...)
 432 <replaceable>expression</replaceable> IS NOT OF (typename, ...)
 433 </synopsis>
 434     They return a boolean value based on whether the expression's data
 435     type is one of the listed data types.
 436    </para>
 437 -->
 438
 439   </sect1>
 440
 441   <sect1 id="functions-math">
 442    <title>Mathematical Functions and Operators</title>
 443
 444    <para>
 445     Mathematical operators are provided for many
 446     <productname>PostgreSQL</productname> types. For types without
 447     standard mathematical conventions
 448     (e.g., date/time types) we
 449     describe the actual behavior in subsequent sections.
 450    </para>
 451
 452    <para>
 453     <xref linkend="functions-math-op-table"> shows the available mathematical operators.
 454    </para>
 455
 456    <table id="functions-math-op-table">
 457     <title>Mathematical Operators</title>
 458
 459     <tgroup cols="4">
 460      <thead>
 461       <row>
 462        <entry>Operator</entry>
 463        <entry>Description</entry>
 464        <entry>Example</entry>
 465        <entry>Result</entry>
 466       </row>
 467      </thead>
 468
 469      <tbody>
 470       <row>
 471        <entry> <literal>+</literal> </entry>
 472        <entry>addition</entry>
 473        <entry><literal>2 + 3</literal></entry>
 474        <entry><literal>5</literal></entry>
 475       </row>
 476
 477       <row>
 478        <entry> <literal>-</literal> </entry>
 479        <entry>subtraction</entry>
 480        <entry><literal>2 - 3</literal></entry>
 481        <entry><literal>-1</literal></entry>
 482       </row>
 483
 484       <row>
 485        <entry> <literal>*</literal> </entry>
 486        <entry>multiplication</entry>
 487        <entry><literal>2 * 3</literal></entry>
 488        <entry><literal>6</literal></entry>
 489       </row>
 490
 491       <row>
 492        <entry> <literal>/</literal> </entry>
 493        <entry>division (integer division truncates the result)</entry>
 494        <entry><literal>4 / 2</literal></entry>
 495        <entry><literal>2</literal></entry>
 496       </row>
 497
 498       <row>
 499        <entry> <literal>%</literal> </entry>
 500        <entry>modulo (remainder)</entry>
 501        <entry><literal>5 % 4</literal></entry>
 502        <entry><literal>1</literal></entry>
 503       </row>
 504
 505       <row>
 506        <entry> <literal>^</literal> </entry>
 507        <entry>exponentiation</entry>
 508        <entry><literal>2.0 ^ 3.0</literal></entry>
 509        <entry><literal>8</literal></entry>
 510       </row>
 511
 512       <row>
 513        <entry> <literal>|/</literal> </entry>
 514        <entry>square root</entry>
 515        <entry><literal>|/ 25.0</literal></entry>
 516        <entry><literal>5</literal></entry>
 517       </row>
 518
 519       <row>
 520        <entry> <literal>||/</literal> </entry>
 521        <entry>cube root</entry>
 522        <entry><literal>||/ 27.0</literal></entry>
 523        <entry><literal>3</literal></entry>
 524       </row>
 525
 526       <row>
 527        <entry> <literal>!</literal> </entry>
 528        <entry>factorial</entry>
 529        <entry><literal>5 !</literal></entry>
 530        <entry><literal>120</literal></entry>
 531       </row>
 532
 533       <row>
 534        <entry> <literal>!!</literal> </entry>
 535        <entry>factorial (prefix operator)</entry>
 536        <entry><literal>!! 5</literal></entry>
 537        <entry><literal>120</literal></entry>
 538       </row>
 539
 540       <row>
 541        <entry> <literal>@</literal> </entry>
 542        <entry>absolute value</entry>
 543        <entry><literal>@ -5.0</literal></entry>
 544        <entry><literal>5</literal></entry>
 545       </row>
 546
 547       <row>
 548        <entry> <literal>&amp;</literal> </entry>
 549        <entry>bitwise AND</entry>
 550        <entry><literal>91 &amp; 15</literal></entry>
 551        <entry><literal>11</literal></entry>
 552       </row>
 553
 554       <row>
 555        <entry> <literal>|</literal> </entry>
 556        <entry>bitwise OR</entry>
 557        <entry><literal>32 | 3</literal></entry>
 558        <entry><literal>35</literal></entry>
 559       </row>
 560
 561       <row>
 562        <entry> <literal>#</literal> </entry>
 563        <entry>bitwise XOR</entry>
 564        <entry><literal>17 # 5</literal></entry>
 565        <entry><literal>20</literal></entry>
 566       </row>
 567
 568       <row>
 569        <entry> <literal>~</literal> </entry>
 570        <entry>bitwise NOT</entry>
 571        <entry><literal>~1</literal></entry>
 572        <entry><literal>-2</literal></entry>
 573       </row>
 574
 575       <row>
 576        <entry> <literal>&lt;&lt;</literal> </entry>
 577        <entry>bitwise shift left</entry>
 578        <entry><literal>1 &lt;&lt; 4</literal></entry>
 579        <entry><literal>16</literal></entry>
 580       </row>
 581
 582       <row>
 583        <entry> <literal>&gt;&gt;</literal> </entry>
 584        <entry>bitwise shift right</entry>
 585        <entry><literal>8 &gt;&gt; 2</literal></entry>
 586        <entry><literal>2</literal></entry>
 587       </row>
 588
 589      </tbody>
 590     </tgroup>
 591    </table>
 592
 593    <para>
 594     The bitwise operators work only on integral data types, whereas
 595     the others are available for all numeric data types.  The bitwise
 596     operators are also available for the bit
 597     string types <type>bit</type> and <type>bit varying</type>, as
 598     shown in <xref linkend="functions-bit-string-op-table">.
 599    </para>
 600
 601   <para>
 602    <xref linkend="functions-math-func-table"> shows the available
 603    mathematical functions.  In the table, <literal>dp</literal>
 604    indicates <type>double precision</type>.  Many of these functions
 605    are provided in multiple forms with different argument types.
 606    Except where noted, any given form of a function returns the same
 607    data type as its argument.
 608    The functions working with <type>double precision</type> data are mostly
 609    implemented on top of the host system's C library; accuracy and behavior in
 610    boundary cases can therefore vary depending on the host system.
 611   </para>
 612
 613    <indexterm>
 614     <primary>abs</primary>
 615    </indexterm>
 616    <indexterm>
 617     <primary>cbrt</primary>
 618    </indexterm>
 619    <indexterm>
 620     <primary>ceiling</primary>
 621    </indexterm>
 622    <indexterm>
 623     <primary>degrees</primary>
 624    </indexterm>
 625    <indexterm>
 626     <primary>div</primary>
 627    </indexterm>
 628    <indexterm>
 629     <primary>exp</primary>
 630    </indexterm>
 631    <indexterm>
 632     <primary>floor</primary>
 633    </indexterm>
 634    <indexterm>
 635     <primary>ln</primary>
 636    </indexterm>
 637    <indexterm>
 638     <primary>log</primary>
 639    </indexterm>
 640    <indexterm>
 641     <primary>mod</primary>
 642    </indexterm>
 643    <indexterm>
 644     <primary>pi</primary>
 645    </indexterm>
 646    <indexterm>
 647     <primary>power</primary>
 648    </indexterm>
 649    <indexterm>
 650     <primary>radians</primary>
 651    </indexterm>
 652    <indexterm>
 653     <primary>random</primary>
 654    </indexterm>
 655    <indexterm>
 656     <primary>round</primary>
 657    </indexterm>
 658    <indexterm>
 659     <primary>setseed</primary>
 660    </indexterm>
 661    <indexterm>
 662     <primary>sign</primary>
 663    </indexterm>
 664    <indexterm>
 665     <primary>sqrt</primary>
 666    </indexterm>
 667    <indexterm>
 668     <primary>trunc</primary>
 669    </indexterm>
 670    <indexterm>
 671     <primary>width_bucket</primary>
 672    </indexterm>
 673
 674    <table id="functions-math-func-table">
 675     <title>Mathematical Functions</title>
 676     <tgroup cols="5">
 677      <thead>
 678       <row>
 679        <entry>Function</entry>
 680        <entry>Return Type</entry>
 681        <entry>Description</entry>
 682        <entry>Example</entry>
 683        <entry>Result</entry>
 684       </row>
 685      </thead>
 686
 687      <tbody>
 688       <row>
 689        <entry><literal><function>abs</>(<replaceable>x</replaceable>)</literal></entry>
 690        <entry>(same as input)</entry>
 691        <entry>absolute value</entry>
 692        <entry><literal>abs(-17.4)</literal></entry>
 693        <entry><literal>17.4</literal></entry>
 694       </row>
 695
 696       <row>
 697        <entry><literal><function>cbrt</function>(<type>dp</type>)</literal></entry>
 698        <entry><type>dp</type></entry>
 699        <entry>cube root</entry>
 700        <entry><literal>cbrt(27.0)</literal></entry>
 701        <entry><literal>3</literal></entry>
 702       </row>
 703
 704       <row>
 705        <entry><literal><function>ceil</function>(<type>dp</type> or <type>numeric</type>)</literal></entry>
 706        <entry>(same as input)</entry>
 707        <entry>smallest integer not less than argument</entry>
 708        <entry><literal>ceil(-42.8)</literal></entry>
 709        <entry><literal>-42</literal></entry>
 710       </row>
 711
 712       <row>
 713        <entry><literal><function>ceiling</function>(<type>dp</type> or <type>numeric</type>)</literal></entry>
 714        <entry>(same as input)</entry>
 715        <entry>smallest integer not less than argument (alias for <function>ceil</function>)</entry>
 716        <entry><literal>ceiling(-95.3)</literal></entry>
 717        <entry><literal>-95</literal></entry>
 718       </row>
 719
 720       <row>
 721        <entry><literal><function>degrees</function>(<type>dp</type>)</literal></entry>
 722        <entry><type>dp</type></entry>
 723        <entry>radians to degrees</entry>
 724        <entry><literal>degrees(0.5)</literal></entry>
 725        <entry><literal>28.6478897565412</literal></entry>
 726       </row>
 727
 728       <row>
 729        <entry><literal><function>div</function>(<parameter>y</parameter> <type>numeric</>,
 730         <parameter>x</parameter> <type>numeric</>)</literal></entry>
 731        <entry><type>numeric</></entry>
 732        <entry>integer quotient of <parameter>y</parameter>/<parameter>x</parameter></entry>
 733        <entry><literal>div(9,4)</literal></entry>
 734        <entry><literal>2</literal></entry>
 735       </row>
 736
 737       <row>
 738        <entry><literal><function>exp</function>(<type>dp</type> or <type>numeric</type>)</literal></entry>
 739        <entry>(same as input)</entry>
 740        <entry>exponential</entry>
 741        <entry><literal>exp(1.0)</literal></entry>
 742        <entry><literal>2.71828182845905</literal></entry>
 743       </row>
 744
 745       <row>
 746        <entry><literal><function>floor</function>(<type>dp</type> or <type>numeric</type>)</literal></entry>
 747        <entry>(same as input)</entry>
 748        <entry>largest integer not greater than argument</entry>
 749        <entry><literal>floor(-42.8)</literal></entry>
 750        <entry><literal>-43</literal></entry>
 751       </row>
 752
 753       <row>
 754        <entry><literal><function>ln</function>(<type>dp</type> or <type>numeric</type>)</literal></entry>
 755        <entry>(same as input)</entry>
 756        <entry>natural logarithm</entry>
 757        <entry><literal>ln(2.0)</literal></entry>
 758        <entry><literal>0.693147180559945</literal></entry>
 759       </row>
 760
 761       <row>
 762        <entry><literal><function>log</function>(<type>dp</type> or <type>numeric</type>)</literal></entry>
 763        <entry>(same as input)</entry>
 764        <entry>base 10 logarithm</entry>
 765        <entry><literal>log(100.0)</literal></entry>
 766        <entry><literal>2</literal></entry>
 767       </row>
 768
 769       <row>
 770        <entry><literal><function>log</function>(<parameter>b</parameter> <type>numeric</type>,
 771         <parameter>x</parameter> <type>numeric</type>)</literal></entry>
 772        <entry><type>numeric</type></entry>
 773        <entry>logarithm to base <parameter>b</parameter></entry>
 774        <entry><literal>log(2.0, 64.0)</literal></entry>
 775        <entry><literal>6.0000000000</literal></entry>
 776       </row>
 777
 778       <row>
 779        <entry><literal><function>mod</function>(<parameter>y</parameter>,
 780         <parameter>x</parameter>)</literal></entry>
 781        <entry>(same as argument types)</entry>
 782        <entry>remainder of <parameter>y</parameter>/<parameter>x</parameter></entry>
 783        <entry><literal>mod(9,4)</literal></entry>
 784        <entry><literal>1</literal></entry>
 785       </row>
 786
 787       <row>
 788        <entry><literal><function>pi</function>()</literal></entry>
 789        <entry><type>dp</type></entry>
 790        <entry><quote>&pi;</quote> constant</entry>
 791        <entry><literal>pi()</literal></entry>
 792        <entry><literal>3.14159265358979</literal></entry>
 793       </row>
 794
 795       <row>
 796        <entry><literal><function>power</function>(<parameter>a</parameter> <type>dp</type>,
 797         <parameter>b</parameter> <type>dp</type>)</literal></entry>
 798        <entry><type>dp</type></entry>
 799        <entry><parameter>a</> raised to the power of <parameter>b</parameter></entry>
 800        <entry><literal>power(9.0, 3.0)</literal></entry>
 801        <entry><literal>729</literal></entry>
 802       </row>
 803
 804       <row>
 805        <entry><literal><function>power</function>(<parameter>a</parameter> <type>numeric</type>,
 806         <parameter>b</parameter> <type>numeric</type>)</literal></entry>
 807        <entry><type>numeric</type></entry>
 808        <entry><parameter>a</> raised to the power of <parameter>b</parameter></entry>
 809        <entry><literal>power(9.0, 3.0)</literal></entry>
 810        <entry><literal>729</literal></entry>
 811       </row>
 812
 813       <row>
 814        <entry><literal><function>radians</function>(<type>dp</type>)</literal></entry>
 815        <entry><type>dp</type></entry>
 816        <entry>degrees to radians</entry>
 817        <entry><literal>radians(45.0)</literal></entry>
 818        <entry><literal>0.785398163397448</literal></entry>
 819       </row>
 820
 821       <row>
 822        <entry><literal><function>random</function>()</literal></entry>
 823        <entry><type>dp</type></entry>
 824        <entry>random value between 0.0 and 1.0, inclusive</entry>
 825        <entry><literal>random()</literal></entry>
 826        <entry></entry>
 827       </row>
 828
 829       <row>
 830        <entry><literal><function>round</function>(<type>dp</type> or <type>numeric</type>)</literal></entry>
 831        <entry>(same as input)</entry>
 832        <entry>round to nearest integer</entry>
 833        <entry><literal>round(42.4)</literal></entry>
 834        <entry><literal>42</literal></entry>
 835       </row>
 836
 837       <row>
 838        <entry><literal><function>round</function>(<parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> <type>int</type>)</literal></entry>
 839        <entry><type>numeric</type></entry>
 840        <entry>round to <parameter>s</parameter> decimal places</entry>
 841        <entry><literal>round(42.4382, 2)</literal></entry>
 842        <entry><literal>42.44</literal></entry>
 843       </row>
 844
 845       <row>
 846        <entry><literal><function>setseed</function>(<type>dp</type>)</literal></entry>
 847        <entry><type>void</type></entry>
 848        <entry>set seed for subsequent <literal>random()</literal> calls (value between -1.0 and
 849        1.0, inclusive)</entry>
 850        <entry><literal>setseed(0.54823)</literal></entry>
 851        <entry></entry>
 852       </row>
 853
 854       <row>
 855        <entry><literal><function>sign</function>(<type>dp</type> or <type>numeric</type>)</literal></entry>
 856        <entry>(same as input)</entry>
 857        <entry>sign of the argument (-1, 0, +1)</entry>
 858        <entry><literal>sign(-8.4)</literal></entry>
 859        <entry><literal>-1</literal></entry>
 860       </row>
 861
 862       <row>
 863        <entry><literal><function>sqrt</function>(<type>dp</type> or <type>numeric</type>)</literal></entry>
 864        <entry>(same as input)</entry>
 865        <entry>square root</entry>
 866        <entry><literal>sqrt(2.0)</literal></entry>
 867        <entry><literal>1.4142135623731</literal></entry>
 868       </row>
 869
 870       <row>
 871        <entry><literal><function>trunc</function>(<type>dp</type> or <type>numeric</type>)</literal></entry>
 872        <entry>(same as input)</entry>
 873        <entry>truncate toward zero</entry>
 874        <entry><literal>trunc(42.8)</literal></entry>
 875        <entry><literal>42</literal></entry>
 876       </row>
 877
 878       <row>
 879        <entry><literal><function>trunc</function>(<parameter>v</parameter> <type>numeric</type>, <parameter>s</parameter> <type>int</type>)</literal></entry>
 880        <entry><type>numeric</type></entry>
 881        <entry>truncate to <parameter>s</parameter> decimal places</entry>
 882        <entry><literal>trunc(42.4382, 2)</literal></entry>
 883        <entry><literal>42.43</literal></entry>
 884       </row>
 885
 886       <row>
 887        <entry><literal><function>width_bucket</function>(<parameter>op</parameter> <type>numeric</type>, <parameter>b1</parameter> <type>numeric</type>, <parameter>b2</parameter> <type>numeric</type>, <parameter>count</parameter> <type>int</type>)</literal></entry>
 888        <entry><type>int</type></entry>
 889        <entry>return the bucket to which <parameter>operand</> would
 890        be assigned in an equidepth histogram with <parameter>count</>
 891        buckets, in the range <parameter>b1</> to <parameter>b2</></entry>
 892        <entry><literal>width_bucket(5.35, 0.024, 10.06, 5)</literal></entry>
 893        <entry><literal>3</literal></entry>
 894       </row>
 895
 896       <row>
 897        <entry><literal><function>width_bucket</function>(<parameter>op</parameter> <type>dp</type>, <parameter>b1</parameter> <type>dp</type>, <parameter>b2</parameter> <type>dp</type>, <parameter>count</parameter> <type>int</type>)</literal></entry>
 898        <entry><type>int</type></entry>
 899        <entry>return the bucket to which <parameter>operand</> would
 900        be assigned in an equidepth histogram with <parameter>count</>
 901        buckets, in the range <parameter>b1</> to <parameter>b2</></entry>
 902        <entry><literal>width_bucket(5.35, 0.024, 10.06, 5)</literal></entry>
 903        <entry><literal>3</literal></entry>
 904       </row>
 905      </tbody>
 906     </tgroup>
 907    </table>
 908
 909   <para>
 910    Finally, <xref linkend="functions-math-trig-table"> shows the
 911    available trigonometric functions.  All trigonometric functions
 912    take arguments and return values of type <type>double
 913    precision</type>.
 914   </para>
 915
 916    <indexterm>
 917     <primary>acos</primary>
 918    </indexterm>
 919    <indexterm>
 920     <primary>asin</primary>
 921    </indexterm>
 922    <indexterm>
 923     <primary>atan</primary>
 924    </indexterm>
 925    <indexterm>
 926     <primary>atan2</primary>
 927    </indexterm>
 928    <indexterm>
 929     <primary>cos</primary>
 930    </indexterm>
 931    <indexterm>
 932     <primary>cot</primary>
 933    </indexterm>
 934    <indexterm>
 935     <primary>sin</primary>
 936    </indexterm>
 937    <indexterm>
 938     <primary>tan</primary>
 939    </indexterm>
 940
 941    <table id="functions-math-trig-table">
 942     <title>Trigonometric Functions</title>
 943
 944     <tgroup cols="2">
 945      <thead>
 946       <row>
 947        <entry>Function</entry>
 948        <entry>Description</entry>
 949       </row>
 950      </thead>
 951
 952      <tbody>
 953       <row>
 954        <entry><literal><function>acos</function>(<replaceable>x</replaceable>)</literal></entry>
 955        <entry>inverse cosine</entry>
 956       </row>
 957
 958       <row>
 959        <entry><literal><function>asin</function>(<replaceable>x</replaceable>)</literal></entry>
 960        <entry>inverse sine</entry>
 961       </row>
 962
 963       <row>
 964        <entry><literal><function>atan</function>(<replaceable>x</replaceable>)</literal></entry>
 965        <entry>inverse tangent</entry>
 966       </row>
 967
 968       <row>
 969        <entry><literal><function>atan2</function>(<replaceable>y</replaceable>,
 970         <replaceable>x</replaceable>)</literal></entry>
 971        <entry>inverse tangent of
 972         <literal><replaceable>y</replaceable>/<replaceable>x</replaceable></literal></entry>
 973       </row>
 974
 975       <row>
 976        <entry><literal><function>cos</function>(<replaceable>x</replaceable>)</literal></entry>
 977        <entry>cosine</entry>
 978       </row>
 979
 980       <row>
 981        <entry><literal><function>cot</function>(<replaceable>x</replaceable>)</literal></entry>
 982        <entry>cotangent</entry>
 983       </row>
 984
 985       <row>
 986        <entry><literal><function>sin</function>(<replaceable>x</replaceable>)</literal></entry>
 987        <entry>sine</entry>
 988       </row>
 989
 990       <row>
 991        <entry><literal><function>tan</function>(<replaceable>x</replaceable>)</literal></entry>
 992        <entry>tangent</entry>
 993       </row>
 994      </tbody>
 995     </tgroup>
 996    </table>
 997
 998   </sect1>
 999
1000
1001   <sect1 id="functions-string">
1002    <title>String Functions and Operators</title>
1003
1004    <para>
1005     This section describes functions and operators for examining and
1006     manipulating string values.  Strings in this context include values
1007     of the types <type>character</type>, <type>character varying</type>,
1008     and <type>text</type>.  Unless otherwise noted, all
1009     of the functions listed below work on all of these types, but be
1010     wary of potential effects of automatic space-padding when using the
1011     <type>character</type> type.  Some functions also exist
1012     natively for the bit-string types.
1013    </para>
1014
1015    <para>
1016     <acronym>SQL</acronym> defines some string functions that use
1017     key words, rather than commas, to separate
1018     arguments.  Details are in
1019     <xref linkend="functions-string-sql">.
1020     <productname>PostgreSQL</> also provides versions of these functions
1021     that use the regular function invocation syntax
1022     (see <xref linkend="functions-string-other">).
1023    </para>
1024
1025    <note>
1026     <para>
1027      Before <productname>PostgreSQL</productname> 8.3, these functions would
1028      silently accept values of several non-string data types as well, due to
1029      the presence of implicit coercions from those data types to
1030      <type>text</>.  Those coercions have been removed because they frequently
1031      caused surprising behaviors.  However, the string concatenation operator
1032      (<literal>||</>) still accepts non-string input, so long as at least one
1033      input is of a string type, as shown in <xref
1034      linkend="functions-string-sql">.  For other cases, insert an explicit
1035      coercion to <type>text</> if you need to duplicate the previous behavior.
1036     </para>
1037    </note>
1038
1039    <indexterm>
1040     <primary>bit_length</primary>
1041    </indexterm>
1042    <indexterm>
1043     <primary>char_length</primary>
1044    </indexterm>
1045    <indexterm>
1046     <primary>lower</primary>
1047    </indexterm>
1048    <indexterm>
1049     <primary>octet_length</primary>
1050    </indexterm>
1051    <indexterm>
1052     <primary>overlay</primary>
1053    </indexterm>
1054    <indexterm>
1055     <primary>position</primary>
1056    </indexterm>
1057    <indexterm>
1058     <primary>substring</primary>
1059    </indexterm>
1060    <indexterm>
1061     <primary>trim</primary>
1062    </indexterm>
1063    <indexterm>
1064     <primary>upper</primary>
1065    </indexterm>
1066
1067    <table id="functions-string-sql">
1068     <title><acronym>SQL</acronym> String Functions and Operators</title>
1069     <tgroup cols="5">
1070      <thead>
1071       <row>
1072        <entry>Function</entry>
1073        <entry>Return Type</entry>
1074        <entry>Description</entry>
1075        <entry>Example</entry>
1076        <entry>Result</entry>
1077       </row>
1078      </thead>
1079
1080      <tbody>
1081       <row>
1082        <entry><literal><parameter>string</parameter> <literal>||</literal>
1083         <parameter>string</parameter></literal></entry>
1084        <entry> <type>text</type> </entry>
1085        <entry>
1086         String concatenation
1087         <indexterm>
1088          <primary>character string</primary>
1089          <secondary>concatenation</secondary>
1090         </indexterm>
1091        </entry>
1092        <entry><literal>'Post' || 'greSQL'</literal></entry>
1093        <entry><literal>PostgreSQL</literal></entry>
1094       </row>
1095
1096       <row>
1097        <entry>
1098         <literal><parameter>string</parameter> <literal>||</literal>
1099         <parameter>non-string</parameter></literal>
1100         or
1101         <literal><parameter>non-string</parameter> <literal>||</literal>
1102         <parameter>string</parameter></literal>
1103        </entry>
1104        <entry> <type>text</type> </entry>
1105        <entry>
1106         String concatenation with one non-string input
1107        </entry>
1108        <entry><literal>'Value: ' || 42</literal></entry>
1109        <entry><literal>Value: 42</literal></entry>
1110       </row>
1111
1112       <row>
1113        <entry><literal><function>bit_length</function>(<parameter>string</parameter>)</literal></entry>
1114        <entry><type>int</type></entry>
1115        <entry>Number of bits in string</entry>
1116        <entry><literal>bit_length('jose')</literal></entry>
1117        <entry><literal>32</literal></entry>
1118       </row>
1119
1120       <row>
1121        <entry><literal><function>char_length</function>(<parameter>string</parameter>)</literal> or <literal><function>character_length</function>(<parameter>string</parameter>)</literal></entry>
1122        <entry><type>int</type></entry>
1123        <entry>
1124         Number of characters in string
1125         <indexterm>
1126          <primary>character string</primary>
1127          <secondary>length</secondary>
1128         </indexterm>
1129         <indexterm>
1130          <primary>length</primary>
1131          <secondary sortas="character string">of a character string</secondary>
1132          <see>character string, length</see>
1133         </indexterm>
1134        </entry>
1135        <entry><literal>char_length('jose')</literal></entry>
1136        <entry><literal>4</literal></entry>
1137       </row>
1138
1139       <row>
1140        <entry><literal><function>lower</function>(<parameter>string</parameter>)</literal></entry>
1141        <entry><type>text</type></entry>
1142        <entry>Convert string to lower case</entry>
1143        <entry><literal>lower('TOM')</literal></entry>
1144        <entry><literal>tom</literal></entry>
1145       </row>
1146
1147       <row>
1148        <entry><literal><function>octet_length</function>(<parameter>string</parameter>)</literal></entry>
1149        <entry><type>int</type></entry>
1150        <entry>Number of bytes in string</entry>
1151        <entry><literal>octet_length('jose')</literal></entry>
1152        <entry><literal>4</literal></entry>
1153       </row>
1154
1155       <row>
1156        <entry><literal><function>overlay</function>(<parameter>string</parameter> placing <parameter>string</parameter> from <type>int</type> <optional>for <type>int</type></optional>)</literal></entry>
1157        <entry><type>text</type></entry>
1158        <entry>
1159         Replace substring
1160        </entry>
1161        <entry><literal>overlay('Txxxxas' placing 'hom' from 2 for 4)</literal></entry>
1162        <entry><literal>Thomas</literal></entry>
1163       </row>
1164
1165       <row>
1166        <entry><literal><function>position</function>(<parameter>substring</parameter> in <parameter>string</parameter>)</literal></entry>
1167        <entry><type>int</type></entry>
1168        <entry>Location of specified substring</entry>
1169        <entry><literal>position('om' in 'Thomas')</literal></entry>
1170        <entry><literal>3</literal></entry>
1171       </row>
1172
1173       <row>
1174        <entry><literal><function>substring</function>(<parameter>string</parameter> <optional>from <type>int</type></optional> <optional>for <type>int</type></optional>)</literal></entry>
1175        <entry><type>text</type></entry>
1176        <entry>
1177         Extract substring
1178        </entry>
1179        <entry><literal>substring('Thomas' from 2 for 3)</literal></entry>
1180        <entry><literal>hom</literal></entry>
1181       </row>
1182
1183       <row>
1184        <entry><literal><function>substring</function>(<parameter>string</parameter> from <replaceable>pattern</replaceable>)</literal></entry>
1185        <entry><type>text</type></entry>
1186        <entry>
1187         Extract substring matching POSIX regular expression. See
1188         <xref linkend="functions-matching"> for more information on pattern
1189         matching.
1190        </entry>
1191        <entry><literal>substring('Thomas' from '...$')</literal></entry>
1192        <entry><literal>mas</literal></entry>
1193       </row>
1194
1195       <row>
1196        <entry><literal><function>substring</function>(<parameter>string</parameter> from <replaceable>pattern</replaceable> for <replaceable>escape</replaceable>)</literal></entry>
1197        <entry><type>text</type></entry>
1198        <entry>
1199         Extract substring matching <acronym>SQL</acronym> regular expression.
1200         See <xref linkend="functions-matching"> for more information on
1201         pattern matching.
1202        </entry>
1203        <entry><literal>substring('Thomas' from '%#"o_a#"_' for '#')</literal></entry>
1204        <entry><literal>oma</literal></entry>
1205       </row>
1206
1207       <row>
1208        <entry>
1209         <literal><function>trim</function>(<optional>leading | trailing | both</optional>
1210         <optional><parameter>characters</parameter></optional> from
1211         <parameter>string</parameter>)</literal>
1212        </entry>
1213        <entry><type>text</type></entry>
1214        <entry>
1215         Remove the longest string containing only the
1216         <parameter>characters</parameter> (a space by default) from the
1217         start/end/both ends of the <parameter>string</parameter>
1218        </entry>
1219        <entry><literal>trim(both 'x' from 'xTomxx')</literal></entry>
1220        <entry><literal>Tom</literal></entry>
1221       </row>
1222
1223       <row>
1224        <entry><literal><function>upper</function>(<parameter>string</parameter>)</literal></entry>
1225        <entry><type>text</type></entry>
1226        <entry>Convert string to uppercase</entry>
1227        <entry><literal>upper('tom')</literal></entry>
1228        <entry><literal>TOM</literal></entry>
1229       </row>
1230      </tbody>
1231     </tgroup>
1232    </table>
1233
1234    <para>
1235     Additional string manipulation functions are available and are
1236     listed in <xref linkend="functions-string-other">.  Some of them are used internally to implement the
1237     <acronym>SQL</acronym>-standard string functions listed in <xref linkend="functions-string-sql">.
1238    </para>
1239
1240    <indexterm>
1241     <primary>ascii</primary>
1242    </indexterm>
1243    <indexterm>
1244     <primary>btrim</primary>
1245    </indexterm>
1246    <indexterm>
1247     <primary>chr</primary>
1248    </indexterm>
1249    <indexterm>
1250     <primary>convert</primary>
1251    </indexterm>
1252    <indexterm>
1253     <primary>convert_from</primary>
1254    </indexterm>
1255    <indexterm>
1256     <primary>convert_to</primary>
1257    </indexterm>
1258    <indexterm>
1259     <primary>decode</primary>
1260    </indexterm>
1261    <indexterm>
1262     <primary>encode</primary>
1263    </indexterm>
1264    <indexterm>
1265     <primary>initcap</primary>
1266    </indexterm>
1267    <indexterm>
1268     <primary>lpad</primary>
1269    </indexterm>
1270    <indexterm>
1271     <primary>ltrim</primary>
1272    </indexterm>
1273    <indexterm>
1274     <primary>md5</primary>
1275    </indexterm>
1276    <indexterm>
1277     <primary>pg_client_encoding</primary>
1278    </indexterm>
1279    <indexterm>
1280     <primary>quote_ident</primary>
1281    </indexterm>
1282    <indexterm>
1283     <primary>quote_literal</primary>
1284    </indexterm>
1285    <indexterm>
1286     <primary>quote_nullable</primary>
1287    </indexterm>
1288    <indexterm>
1289     <primary>repeat</primary>
1290    </indexterm>
1291    <indexterm>
1292     <primary>replace</primary>
1293    </indexterm>
1294    <indexterm>
1295     <primary>rpad</primary>
1296    </indexterm>
1297    <indexterm>
1298     <primary>rtrim</primary>
1299    </indexterm>
1300    <indexterm>
1301     <primary>split_part</primary>
1302    </indexterm>
1303    <indexterm>
1304     <primary>strpos</primary>
1305    </indexterm>
1306    <indexterm>
1307     <primary>substr</primary>
1308    </indexterm>
1309    <indexterm>
1310     <primary>to_ascii</primary>
1311    </indexterm>
1312    <indexterm>
1313     <primary>to_hex</primary>
1314    </indexterm>
1315    <indexterm>
1316     <primary>translate</primary>
1317    </indexterm>
1318
1319    <table id="functions-string-other">
1320     <title>Other String Functions</title>
1321     <tgroup cols="5">
1322      <thead>
1323       <row>
1324        <entry>Function</entry>
1325        <entry>Return Type</entry>
1326        <entry>Description</entry>
1327        <entry>Example</entry>
1328        <entry>Result</entry>
1329       </row>
1330      </thead>
1331
1332      <tbody>
1333       <row>
1334        <entry><literal><function>ascii</function>(<parameter>string</parameter>)</literal></entry>
1335        <entry><type>int</type></entry>
1336        <entry>
1337         <acronym>ASCII</acronym> code of the first character of the
1338         argument.  For <acronym>UTF8</acronym> returns the Unicode code
1339         point of the character.  For other multibyte encodings, the
1340         argument must be an <acronym>ASCII</acronym> character.
1341        </entry>
1342        <entry><literal>ascii('x')</literal></entry>
1343        <entry><literal>120</literal></entry>
1344       </row>
1345
1346       <row>
1347        <entry><literal><function>btrim</function>(<parameter>string</parameter> <type>text</type>
1348        <optional>, <parameter>characters</parameter> <type>text</type></optional>)</literal></entry>
1349        <entry><type>text</type></entry>
1350        <entry>
1351         Remove the longest string consisting only of characters
1352         in <parameter>characters</parameter> (a space by default)
1353         from the start and end of <parameter>string</parameter>
1354        </entry>
1355        <entry><literal>btrim('xyxtrimyyx', 'xy')</literal></entry>
1356        <entry><literal>trim</literal></entry>
1357       </row>
1358
1359       <row>
1360        <entry><literal><function>chr</function>(<type>int</type>)</literal></entry>
1361        <entry><type>text</type></entry>
1362        <entry>
1363         Character with the given code. For <acronym>UTF8</acronym> the
1364         argument is treated as a Unicode code point. For other multibyte
1365         encodings the argument must designate an
1366         <acronym>ASCII</acronym> character.  The NULL (0) character is not
1367         allowed because text data types cannot store such bytes.
1368        </entry>
1369        <entry><literal>chr(65)</literal></entry>
1370        <entry><literal>A</literal></entry>
1371       </row>
1372
1373       <row>
1374        <entry>
1375         <literal><function>convert</function>(<parameter>string</parameter> <type>bytea</type>,
1376         <parameter>src_encoding</parameter> <type>name</type>,
1377         <parameter>dest_encoding</parameter> <type>name</type>)</literal>
1378        </entry>
1379        <entry><type>bytea</type></entry>
1380        <entry>
1381         Convert string to <parameter>dest_encoding</parameter>.  The
1382         original encoding is specified by
1383         <parameter>src_encoding</parameter>. The
1384         <parameter>string</parameter> must be valid in this encoding.
1385         Conversions can be defined by <command>CREATE CONVERSION</command>.
1386         Also there are some predefined conversions. See <xref
1387         linkend="conversion-names"> for available conversions.
1388        </entry>
1389        <entry><literal>convert('text_in_utf8', 'UTF8', 'LATIN1')</literal></entry>
1390        <entry><literal>text_in_utf8</literal> represented in Latin-1
1391        encoding (ISO 8859-1)</entry>
1392       </row>
1393
1394       <row>
1395        <entry>
1396         <literal><function>convert_from</function>(<parameter>string</parameter> <type>bytea</type>,
1397         <parameter>src_encoding</parameter> <type>name</type>)</literal>
1398        </entry>
1399        <entry><type>text</type></entry>
1400        <entry>
1401         Convert string to the database encoding.  The original encoding
1402         is specified by <parameter>src_encoding</parameter>. The
1403         <parameter>string</parameter> must be valid in this encoding.
1404        </entry>
1405        <entry><literal>convert_from('text_in_utf8', 'UTF8')</literal></entry>
1406        <entry><literal>text_in_utf8</literal> represented in the current database encoding</entry>
1407       </row>
1408
1409       <row>
1410        <entry>
1411         <literal><function>convert_to</function>(<parameter>string</parameter> <type>text</type>,
1412         <parameter>dest_encoding</parameter> <type>name</type>)</literal>
1413        </entry>
1414        <entry><type>bytea</type></entry>
1415        <entry>
1416         Convert string to <parameter>dest_encoding</parameter>.
1417        </entry>
1418        <entry><literal>convert_to('some text', 'UTF8')</literal></entry>
1419        <entry><literal>some text</literal> represented in the UTF8 encoding</entry>
1420       </row>
1421
1422       <row>
1423        <entry>
1424         <literal><function>decode</function>(<parameter>string</parameter> <type>text</type>,
1425         <parameter>type</parameter> <type>text</type>)</literal>
1426        </entry>
1427        <entry><type>bytea</type></entry>
1428        <entry>
1429         Decode binary data from <parameter>string</parameter> previously
1430         encoded with <function>encode</>.  Parameter type is same as in <function>encode</>.
1431        </entry>
1432        <entry><literal>decode('MTIzAAE=', 'base64')</literal></entry>
1433        <entry><literal>123\000\001</literal></entry>
1434       </row>
1435
1436       <row>
1437        <entry>
1438         <literal><function>encode</function>(<parameter>data</parameter> <type>bytea</type>,
1439         <parameter>type</parameter> <type>text</type>)</literal>
1440        </entry>
1441        <entry><type>text</type></entry>
1442        <entry>
1443         Encode binary data to different representation.  Supported
1444         types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
1445         <literal>Escape</> merely outputs null bytes as <literal>\000</> and
1446         doubles backslashes.
1447        </entry>
1448        <entry><literal>encode(E'123\\000\\001', 'base64')</literal></entry>
1449        <entry><literal>MTIzAAE=</literal></entry>
1450       </row>
1451
1452       <row>
1453        <entry><literal><function>initcap</function>(<parameter>string</parameter>)</literal></entry>
1454        <entry><type>text</type></entry>
1455        <entry>
1456         Convert the first letter of each word to uppercase and the
1457         rest to lowercase. Words are sequences of alphanumeric
1458         characters separated by non-alphanumeric characters.
1459        </entry>
1460        <entry><literal>initcap('hi THOMAS')</literal></entry>
1461        <entry><literal>Hi Thomas</literal></entry>
1462       </row>
1463
1464       <row>
1465        <entry><literal><function>length</function>(<parameter>string</parameter>)</literal></entry>
1466        <entry><type>int</type></entry>
1467        <entry>
1468         Number of characters in <parameter>string</parameter>
1469        </entry>
1470        <entry><literal>length('jose')</literal></entry>
1471        <entry><literal>4</literal></entry>
1472       </row>
1473
1474       <row>
1475        <entry><literal><function>length</function>(<parameter>string</parameter><type>bytea</type>,
1476         <parameter>encoding</parameter> <type>name</type> )</literal></entry>
1477        <entry><type>int</type></entry>
1478        <entry>
1479         Number of characters in <parameter>string</parameter> in the given
1480         <parameter>encoding</parameter>. The <parameter>string</parameter>
1481         must be valid in this encoding.
1482        </entry>
1483        <entry><literal>length('jose', 'UTF8')</literal></entry>
1484        <entry><literal>4</literal></entry>
1485       </row>
1486
1487       <row>
1488        <entry>
1489         <literal><function>lpad</function>(<parameter>string</parameter> <type>text</type>,
1490         <parameter>length</parameter> <type>int</type>
1491         <optional>, <parameter>fill</parameter> <type>text</type></optional>)</literal>
1492        </entry>
1493        <entry><type>text</type></entry>
1494        <entry>
1495         Fill up the <parameter>string</parameter> to length
1496         <parameter>length</parameter> by prepending the characters
1497         <parameter>fill</parameter> (a space by default).  If the
1498         <parameter>string</parameter> is already longer than
1499         <parameter>length</parameter> then it is truncated (on the
1500         right).
1501        </entry>
1502        <entry><literal>lpad('hi', 5, 'xy')</literal></entry>
1503        <entry><literal>xyxhi</literal></entry>
1504       </row>
1505
1506       <row>
1507        <entry><literal><function>ltrim</function>(<parameter>string</parameter> <type>text</type>
1508         <optional>, <parameter>characters</parameter> <type>text</type></optional>)</literal>
1509        </entry>
1510        <entry><type>text</type></entry>
1511        <entry>
1512         Remove the longest string containing only characters from
1513         <parameter>characters</parameter> (a space by default) from the start of
1514         <parameter>string</parameter>
1515        </entry>
1516        <entry><literal>ltrim('zzzytrim', 'xyz')</literal></entry>
1517        <entry><literal>trim</literal></entry>
1518       </row>
1519
1520       <row>
1521        <entry><literal><function>md5</function>(<parameter>string</parameter>)</literal></entry>
1522        <entry><type>text</type></entry>
1523        <entry>
1524         Calculates the MD5 hash of <parameter>string</parameter>,
1525         returning the result in hexadecimal
1526        </entry>
1527        <entry><literal>md5('abc')</literal></entry>
1528        <entry><literal>900150983cd24fb0 d6963f7d28e17f72</literal></entry>
1529       </row>
1530
1531       <row>
1532        <entry><literal><function>pg_client_encoding</function>()</literal></entry>
1533        <entry><type>name</type></entry>
1534        <entry>
1535         Current client encoding name
1536        </entry>
1537        <entry><literal>pg_client_encoding()</literal></entry>
1538        <entry><literal>SQL_ASCII</literal></entry>
1539       </row>
1540
1541       <row>
1542        <entry><literal><function>quote_ident</function>(<parameter>string</parameter> <type>text</type>)</literal></entry>
1543        <entry><type>text</type></entry>
1544        <entry>
1545         Return the given string suitably quoted to be used as an identifier
1546         in an <acronym>SQL</acronym> statement string.
1547         Quotes are added only if necessary (i.e., if the string contains
1548         non-identifier characters or would be case-folded).
1549         Embedded quotes are properly doubled.
1550         See also <xref linkend="plpgsql-quote-literal-example">.
1551        </entry>
1552        <entry><literal>quote_ident('Foo bar')</literal></entry>
1553        <entry><literal>"Foo bar"</literal></entry>
1554       </row>
1555
1556       <row>
1557        <entry><literal><function>quote_literal</function>(<parameter>string</parameter> <type>text</type>)</literal></entry>
1558        <entry><type>text</type></entry>
1559        <entry>
1560         Return the given string suitably quoted to be used as a string literal
1561         in an <acronym>SQL</acronym> statement string.
1562         Embedded single-quotes and backslashes are properly doubled.
1563         Note that <function>quote_literal</function> returns null on null
1564         input; if the argument might be null,
1565         <function>quote_nullable</function> is often more suitable.
1566         See also <xref linkend="plpgsql-quote-literal-example">.
1567        </entry>
1568        <entry><literal>quote_literal('O\'Reilly')</literal></entry>
1569        <entry><literal>'O''Reilly'</literal></entry>
1570       </row>
1571
1572       <row>
1573        <entry><literal><function>quote_literal</function>(<parameter>value</parameter> <type>anyelement</type>)</literal></entry>
1574        <entry><type>text</type></entry>
1575        <entry>
1576         Coerce the given value to text and then quote it as a literal.
1577         Embedded single-quotes and backslashes are properly doubled.
1578        </entry>
1579        <entry><literal>quote_literal(42.5)</literal></entry>
1580        <entry><literal>'42.5'</literal></entry>
1581       </row>
1582
1583       <row>
1584        <entry><literal><function>quote_nullable</function>(<parameter>string</parameter> <type>text</type>)</literal></entry>
1585        <entry><type>text</type></entry>
1586        <entry>
1587         Return the given string suitably quoted to be used as a string literal
1588         in an <acronym>SQL</acronym> statement string; or, if the argument
1589         is null, return <literal>NULL</>.
1590         Embedded single-quotes and backslashes are properly doubled.
1591         See also <xref linkend="plpgsql-quote-literal-example">.
1592        </entry>
1593        <entry><literal>quote_nullable(NULL)</literal></entry>
1594        <entry><literal>NULL</literal></entry>
1595       </row>
1596
1597       <row>
1598        <entry><literal><function>quote_nullable</function>(<parameter>value</parameter> <type>anyelement</type>)</literal></entry>
1599        <entry><type>text</type></entry>
1600        <entry>
1601         Coerce the given value to text and then quote it as a literal;
1602         or, if the argument is null, return <literal>NULL</>.
1603         Embedded single-quotes and backslashes are properly doubled.
1604        </entry>
1605        <entry><literal>quote_nullable(42.5)</literal></entry>
1606        <entry><literal>'42.5'</literal></entry>
1607       </row>
1608
1609       <row>
1610        <entry><literal><function>regexp_matches</function>(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</literal></entry>
1611        <entry><type>setof text[]</type></entry>
1612        <entry>
1613         Return all captured substrings resulting from matching a POSIX regular
1614         expression against the <parameter>string</parameter>. See
1615         <xref linkend="functions-posix-regexp"> for more information.
1616        </entry>
1617        <entry><literal>regexp_matches('foobarbequebaz', '(bar)(beque)')</literal></entry>
1618        <entry><literal>{bar,beque}</literal></entry>
1619       </row>
1620
1621       <row>
1622        <entry><literal><function>regexp_replace</function>(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type>, <parameter>replacement</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</literal></entry>
1623        <entry><type>text</type></entry>
1624        <entry>
1625         Replace substring(s) matching a POSIX regular expression. See
1626         <xref linkend="functions-posix-regexp"> for more information.
1627        </entry>
1628        <entry><literal>regexp_replace('Thomas', '.[mN]a.', 'M')</literal></entry>
1629        <entry><literal>ThM</literal></entry>
1630       </row>
1631
1632       <row>
1633        <entry><literal><function>regexp_split_to_array</function>(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type> ])</literal></entry>
1634        <entry><type>text[]</type></entry>
1635        <entry>
1636         Split <parameter>string</parameter> using a POSIX regular expression as
1637         the delimiter.  See <xref linkend="functions-posix-regexp"> for more
1638         information.
1639        </entry>
1640        <entry><literal>regexp_split_to_array('hello world', E'\\s+')</literal></entry>
1641        <entry><literal>{hello,world}</literal></entry>
1642       </row>
1643
1644       <row>
1645        <entry><literal><function>regexp_split_to_table</function>(<parameter>string</parameter> <type>text</type>, <parameter>pattern</parameter> <type>text</type> [, <parameter>flags</parameter> <type>text</type>])</literal></entry>
1646        <entry><type>setof text</type></entry>
1647        <entry>
1648         Split <parameter>string</parameter> using a POSIX regular expression as
1649         the delimiter.  See <xref linkend="functions-posix-regexp"> for more
1650         information.
1651        </entry>
1652        <entry><literal>regexp_split_to_table('hello world', E'\\s+')</literal></entry>
1653        <entry><literal>hello</literal><para><literal>world</literal></para> (2 rows)</entry>
1654       </row>
1655
1656       <row>
1657        <entry><literal><function>repeat</function>(<parameter>string</parameter> <type>text</type>, <parameter>number</parameter> <type>int</type>)</literal></entry>
1658        <entry><type>text</type></entry>
1659        <entry>Repeat <parameter>string</parameter> the specified
1660        <parameter>number</parameter> of times</entry>
1661        <entry><literal>repeat('Pg', 4)</literal></entry>
1662        <entry><literal>PgPgPgPg</literal></entry>
1663       </row>
1664
1665       <row>
1666        <entry><literal><function>replace</function>(<parameter>string</parameter> <type>text</type>,
1667        <parameter>from</parameter> <type>text</type>,
1668        <parameter>to</parameter> <type>text</type>)</literal></entry>
1669        <entry><type>text</type></entry>
1670        <entry>Replace all occurrences in <parameter>string</parameter> of substring
1671         <parameter>from</parameter> with substring <parameter>to</parameter>
1672        </entry>
1673        <entry><literal>replace('abcdefabcdef', 'cd', 'XX')</literal></entry>
1674        <entry><literal>abXXefabXXef</literal></entry>
1675       </row>
1676
1677       <row>
1678        <entry>
1679         <literal><function>rpad</function>(<parameter>string</parameter> <type>text</type>,
1680         <parameter>length</parameter> <type>int</type>
1681         <optional>, <parameter>fill</parameter> <type>text</type></optional>)</literal>
1682        </entry>
1683        <entry><type>text</type></entry>
1684        <entry>
1685         Fill up the <parameter>string</parameter> to length
1686         <parameter>length</parameter> by appending the characters
1687         <parameter>fill</parameter> (a space by default).  If the
1688         <parameter>string</parameter> is already longer than
1689         <parameter>length</parameter> then it is truncated.
1690        </entry>
1691        <entry><literal>rpad('hi', 5, 'xy')</literal></entry>
1692        <entry><literal>hixyx</literal></entry>
1693       </row>
1694
1695       <row>
1696        <entry><literal><function>rtrim</function>(<parameter>string</parameter> <type>text</type>
1697         <optional>, <parameter>characters</parameter> <type>text</type></optional>)</literal>
1698        </entry>
1699        <entry><type>text</type></entry>
1700        <entry>
1701         Remove the longest string containing only characters from
1702         <parameter>characters</parameter> (a space by default) from the end of
1703         <parameter>string</parameter>
1704        </entry>
1705        <entry><literal>rtrim('trimxxxx', 'x')</literal></entry>
1706        <entry><literal>trim</literal></entry>
1707       </row>
1708
1709       <row>
1710        <entry><literal><function>split_part</function>(<parameter>string</parameter> <type>text</type>,
1711        <parameter>delimiter</parameter> <type>text</type>,
1712        <parameter>field</parameter> <type>int</type>)</literal></entry>
1713        <entry><type>text</type></entry>
1714        <entry>Split <parameter>string</parameter> on <parameter>delimiter</parameter>
1715         and return the given field (counting from one)
1716        </entry>
1717        <entry><literal>split_part('abc~@~def~@~ghi', '~@~', 2)</literal></entry>
1718        <entry><literal>def</literal></entry>
1719       </row>
1720
1721       <row>
1722        <entry><literal><function>strpos</function>(<parameter>string</parameter>, <parameter>substring</parameter>)</literal></entry>
1723        <entry><type>int</type></entry>
1724        <entry>
1725         Location of specified substring (same as
1726         <literal>position(<parameter>substring</parameter> in
1727          <parameter>string</parameter>)</literal>, but note the reversed
1728         argument order)
1729        </entry>
1730        <entry><literal>strpos('high', 'ig')</literal></entry>
1731        <entry><literal>2</literal></entry>
1732       </row>
1733
1734       <row>
1735        <entry><literal><function>substr</function>(<parameter>string</parameter>, <parameter>from</parameter> <optional>, <parameter>count</parameter></optional>)</literal></entry>
1736        <entry><type>text</type></entry>
1737        <entry>
1738         Extract substring (same as
1739         <literal>substring(<parameter>string</parameter> from <parameter>from</parameter> for <parameter>count</parameter>)</literal>)
1740        </entry>
1741        <entry><literal>substr('alphabet', 3, 2)</literal></entry>
1742        <entry><literal>ph</literal></entry>
1743       </row>
1744
1745       <row>
1746        <entry><literal><function>to_ascii</function>(<parameter>string</parameter> <type>text</type>
1747         <optional>, <parameter>encoding</parameter> <type>text</type></optional>)</literal></entry>
1748        <entry><type>text</type></entry>
1749
1750        <entry>
1751        Convert <parameter>string</parameter> to <acronym>ASCII</acronym> from another encoding
1752        (only supports conversion from  <literal>LATIN1</>, <literal>LATIN2</>, <literal>LATIN9</>,
1753        and <literal>WIN1250</> encodings)
1754        </entry>
1755
1756        <entry><literal>to_ascii('Karel')</literal></entry>
1757        <entry><literal>Karel</literal></entry>
1758       </row>
1759
1760       <row>
1761        <entry><literal><function>to_hex</function>(<parameter>number</parameter> <type>int</type>
1762        or <type>bigint</type>)</literal></entry>
1763        <entry><type>text</type></entry>
1764        <entry>Convert <parameter>number</parameter> to its equivalent hexadecimal
1765         representation
1766        </entry>
1767        <entry><literal>to_hex(2147483647)</literal></entry>
1768        <entry><literal>7fffffff</literal></entry>
1769       </row>
1770
1771       <row>
1772        <entry>
1773         <literal><function>translate</function>(<parameter>string</parameter> <type>text</type>,
1774         <parameter>from</parameter> <type>text</type>,
1775         <parameter>to</parameter> <type>text</type>)</literal>
1776        </entry>
1777        <entry><type>text</type></entry>
1778        <entry>
1779         Any character in <parameter>string</parameter> that matches a
1780         character in the <parameter>from</parameter> set is replaced by
1781         the corresponding character in the <parameter>to</parameter>
1782         set
1783        </entry>
1784        <entry><literal>translate('12345', '14', 'ax')</literal></entry>
1785        <entry><literal>a23x5</literal></entry>
1786       </row>
1787
1788      </tbody>
1789     </tgroup>
1790    </table>
1791
1792
1793    <table id="conversion-names">
1794     <title>Built-in Conversions</title>
1795     <tgroup cols="3">
1796      <thead>
1797       <row>
1798        <entry>Conversion Name
1799         <footnote>
1800          <para>
1801           The conversion names follow a standard naming scheme: The
1802           official name of the source encoding with all
1803           non-alphanumeric characters replaced by underscores, followed
1804           by <literal>_to_</literal>, followed by the similarly processed
1805           destination encoding name. Therefore, the names might deviate
1806           from the customary encoding names.
1807          </para>
1808         </footnote>
1809        </entry>
1810        <entry>Source Encoding</entry>
1811        <entry>Destination Encoding</entry>
1812       </row>
1813      </thead>
1814
1815      <tbody>
1816       <row>
1817        <entry><literal>ascii_to_mic</literal></entry>
1818        <entry><literal>SQL_ASCII</literal></entry>
1819        <entry><literal>MULE_INTERNAL</literal></entry>
1820       </row>
1821
1822       <row>
1823        <entry><literal>ascii_to_utf8</literal></entry>
1824        <entry><literal>SQL_ASCII</literal></entry>
1825        <entry><literal>UTF8</literal></entry>
1826       </row>
1827
1828       <row>
1829        <entry><literal>big5_to_euc_tw</literal></entry>
1830        <entry><literal>BIG5</literal></entry>
1831        <entry><literal>EUC_TW</literal></entry>
1832       </row>
1833
1834       <row>
1835        <entry><literal>big5_to_mic</literal></entry>
1836        <entry><literal>BIG5</literal></entry>
1837        <entry><literal>MULE_INTERNAL</literal></entry>
1838       </row>
1839
1840       <row>
1841        <entry><literal>big5_to_utf8</literal></entry>
1842        <entry><literal>BIG5</literal></entry>
1843        <entry><literal>UTF8</literal></entry>
1844       </row>
1845
1846       <row>
1847        <entry><literal>euc_cn_to_mic</literal></entry>
1848        <entry><literal>EUC_CN</literal></entry>
1849        <entry><literal>MULE_INTERNAL</literal></entry>
1850       </row>
1851
1852       <row>
1853        <entry><literal>euc_cn_to_utf8</literal></entry>
1854        <entry><literal>EUC_CN</literal></entry>
1855        <entry><literal>UTF8</literal></entry>
1856       </row>
1857
1858       <row>
1859        <entry><literal>euc_jp_to_mic</literal></entry>
1860        <entry><literal>EUC_JP</literal></entry>
1861        <entry><literal>MULE_INTERNAL</literal></entry>
1862       </row>
1863
1864       <row>
1865        <entry><literal>euc_jp_to_sjis</literal></entry>
1866        <entry><literal>EUC_JP</literal></entry>
1867        <entry><literal>SJIS</literal></entry>
1868       </row>
1869
1870       <row>
1871        <entry><literal>euc_jp_to_utf8</literal></entry>
1872        <entry><literal>EUC_JP</literal></entry>
1873        <entry><literal>UTF8</literal></entry>
1874       </row>
1875
1876       <row>
1877        <entry><literal>euc_kr_to_mic</literal></entry>
1878        <entry><literal>EUC_KR</literal></entry>
1879        <entry><literal>MULE_INTERNAL</literal></entry>
1880       </row>
1881
1882       <row>
1883        <entry><literal>euc_kr_to_utf8</literal></entry>
1884        <entry><literal>EUC_KR</literal></entry>
1885        <entry><literal>UTF8</literal></entry>
1886       </row>
1887
1888       <row>
1889        <entry><literal>euc_tw_to_big5</literal></entry>
1890        <entry><literal>EUC_TW</literal></entry>
1891        <entry><literal>BIG5</literal></entry>
1892       </row>
1893
1894       <row>
1895        <entry><literal>euc_tw_to_mic</literal></entry>
1896        <entry><literal>EUC_TW</literal></entry>
1897        <entry><literal>MULE_INTERNAL</literal></entry>
1898       </row>
1899
1900       <row>
1901        <entry><literal>euc_tw_to_utf8</literal></entry>
1902        <entry><literal>EUC_TW</literal></entry>
1903        <entry><literal>UTF8</literal></entry>
1904       </row>
1905
1906       <row>
1907        <entry><literal>gb18030_to_utf8</literal></entry>
1908        <entry><literal>GB18030</literal></entry>
1909        <entry><literal>UTF8</literal></entry>
1910       </row>
1911
1912       <row>
1913        <entry><literal>gbk_to_utf8</literal></entry>
1914        <entry><literal>GBK</literal></entry>
1915        <entry><literal>UTF8</literal></entry>
1916       </row>
1917
1918       <row>
1919        <entry><literal>iso_8859_10_to_utf8</literal></entry>
1920        <entry><literal>LATIN6</literal></entry>
1921        <entry><literal>UTF8</literal></entry>
1922       </row>
1923
1924       <row>
1925        <entry><literal>iso_8859_13_to_utf8</literal></entry>
1926        <entry><literal>LATIN7</literal></entry>
1927        <entry><literal>UTF8</literal></entry>
1928       </row>
1929
1930       <row>
1931        <entry><literal>iso_8859_14_to_utf8</literal></entry>
1932        <entry><literal>LATIN8</literal></entry>
1933        <entry><literal>UTF8</literal></entry>
1934       </row>
1935
1936       <row>
1937        <entry><literal>iso_8859_15_to_utf8</literal></entry>
1938        <entry><literal>LATIN9</literal></entry>
1939        <entry><literal>UTF8</literal></entry>
1940       </row>
1941
1942       <row>
1943        <entry><literal>iso_8859_16_to_utf8</literal></entry>
1944        <entry><literal>LATIN10</literal></entry>
1945        <entry><literal>UTF8</literal></entry>
1946       </row>
1947
1948       <row>
1949        <entry><literal>iso_8859_1_to_mic</literal></entry>
1950        <entry><literal>LATIN1</literal></entry>
1951        <entry><literal>MULE_INTERNAL</literal></entry>
1952       </row>
1953
1954       <row>
1955        <entry><literal>iso_8859_1_to_utf8</literal></entry>
1956        <entry><literal>LATIN1</literal></entry>
1957        <entry><literal>UTF8</literal></entry>
1958       </row>
1959
1960       <row>
1961        <entry><literal>iso_8859_2_to_mic</literal></entry>
1962        <entry><literal>LATIN2</literal></entry>
1963        <entry><literal>MULE_INTERNAL</literal></entry>
1964       </row>
1965
1966       <row>
1967        <entry><literal>iso_8859_2_to_utf8</literal></entry>
1968        <entry><literal>LATIN2</literal></entry>
1969        <entry><literal>UTF8</literal></entry>
1970       </row>
1971
1972       <row>
1973        <entry><literal>iso_8859_2_to_windows_1250</literal></entry>
1974        <entry><literal>LATIN2</literal></entry>
1975        <entry><literal>WIN1250</literal></entry>
1976       </row>
1977
1978       <row>
1979        <entry><literal>iso_8859_3_to_mic</literal></entry>
1980        <entry><literal>LATIN3</literal></entry>
1981        <entry><literal>MULE_INTERNAL</literal></entry>
1982       </row>
1983
1984       <row>
1985        <entry><literal>iso_8859_3_to_utf8</literal></entry>
1986        <entry><literal>LATIN3</literal></entry>
1987        <entry><literal>UTF8</literal></entry>
1988       </row>
1989
1990       <row>
1991        <entry><literal>iso_8859_4_to_mic</literal></entry>
1992        <entry><literal>LATIN4</literal></entry>
1993        <entry><literal>MULE_INTERNAL</literal></entry>
1994       </row>
1995
1996       <row>
1997        <entry><literal>iso_8859_4_to_utf8</literal></entry>
1998        <entry><literal>LATIN4</literal></entry>
1999        <entry><literal>UTF8</literal></entry>
2000       </row>
2001
2002       <row>
2003        <entry><literal>iso_8859_5_to_koi8_r</literal></entry>
2004        <entry><literal>ISO_8859_5</literal></entry>
2005        <entry><literal>KOI8R</literal></entry>
2006       </row>
2007
2008       <row>
2009        <entry><literal>iso_8859_5_to_mic</literal></entry>
2010        <entry><literal>ISO_8859_5</literal></entry>
2011        <entry><literal>MULE_INTERNAL</literal></entry>
2012       </row>
2013
2014       <row>
2015        <entry><literal>iso_8859_5_to_utf8</literal></entry>
2016        <entry><literal>ISO_8859_5</literal></entry>
2017        <entry><literal>UTF8</literal></entry>
2018       </row>
2019
2020       <row>
2021        <entry><literal>iso_8859_5_to_windows_1251</literal></entry>
2022        <entry><literal>ISO_8859_5</literal></entry>
2023        <entry><literal>WIN1251</literal></entry>
2024       </row>
2025
2026       <row>
2027        <entry><literal>iso_8859_5_to_windows_866</literal></entry>
2028        <entry><literal>ISO_8859_5</literal></entry>
2029        <entry><literal>WIN866</literal></entry>
2030       </row>
2031
2032       <row>
2033        <entry><literal>iso_8859_6_to_utf8</literal></entry>
2034        <entry><literal>ISO_8859_6</literal></entry>
2035        <entry><literal>UTF8</literal></entry>
2036       </row>
2037
2038       <row>
2039        <entry><literal>iso_8859_7_to_utf8</literal></entry>
2040        <entry><literal>ISO_8859_7</literal></entry>
2041        <entry><literal>UTF8</literal></entry>
2042       </row>
2043
2044       <row>
2045        <entry><literal>iso_8859_8_to_utf8</literal></entry>
2046        <entry><literal>ISO_8859_8</literal></entry>
2047        <entry><literal>UTF8</literal></entry>
2048       </row>
2049
2050       <row>
2051        <entry><literal>iso_8859_9_to_utf8</literal></entry>
2052        <entry><literal>LATIN5</literal></entry>
2053        <entry><literal>UTF8</literal></entry>
2054       </row>
2055
2056       <row>
2057        <entry><literal>johab_to_utf8</literal></entry>
2058        <entry><literal>JOHAB</literal></entry>
2059        <entry><literal>UTF8</literal></entry>
2060       </row>
2061
2062       <row>
2063        <entry><literal>koi8_r_to_iso_8859_5</literal></entry>
2064        <entry><literal>KOI8R</literal></entry>
2065        <entry><literal>ISO_8859_5</literal></entry>
2066       </row>
2067
2068       <row>
2069        <entry><literal>koi8_r_to_mic</literal></entry>
2070        <entry><literal>KOI8R</literal></entry>
2071        <entry><literal>MULE_INTERNAL</literal></entry>
2072       </row>
2073
2074       <row>
2075        <entry><literal>koi8_r_to_utf8</literal></entry>
2076        <entry><literal>KOI8R</literal></entry>
2077        <entry><literal>UTF8</literal></entry>
2078       </row>
2079
2080       <row>
2081        <entry><literal>koi8_r_to_windows_1251</literal></entry>
2082        <entry><literal>KOI8R</literal></entry>
2083        <entry><literal>WIN1251</literal></entry>
2084       </row>
2085
2086       <row>
2087        <entry><literal>koi8_r_to_windows_866</literal></entry>
2088        <entry><literal>KOI8R</literal></entry>
2089        <entry><literal>WIN866</literal></entry>
2090       </row>
2091
2092       <row>
2093        <entry><literal>koi8_u_to_utf8</literal></entry>
2094        <entry><literal>KOI8U</literal></entry>
2095        <entry><literal>UTF8</literal></entry>
2096       </row>
2097
2098       <row>
2099        <entry><literal>mic_to_ascii</literal></entry>
2100        <entry><literal>MULE_INTERNAL</literal></entry>
2101        <entry><literal>SQL_ASCII</literal></entry>
2102       </row>
2103
2104       <row>
2105        <entry><literal>mic_to_big5</literal></entry>
2106        <entry><literal>MULE_INTERNAL</literal></entry>
2107        <entry><literal>BIG5</literal></entry>
2108       </row>
2109
2110       <row>
2111        <entry><literal>mic_to_euc_cn</literal></entry>
2112        <entry><literal>MULE_INTERNAL</literal></entry>
2113        <entry><literal>EUC_CN</literal></entry>
2114       </row>
2115
2116       <row>
2117        <entry><literal>mic_to_euc_jp</literal></entry>
2118        <entry><literal>MULE_INTERNAL</literal></entry>
2119        <entry><literal>EUC_JP</literal></entry>
2120       </row>
2121
2122       <row>
2123        <entry><literal>mic_to_euc_kr</literal></entry>
2124        <entry><literal>MULE_INTERNAL</literal></entry>
2125        <entry><literal>EUC_KR</literal></entry>
2126       </row>
2127
2128       <row>
2129        <entry><literal>mic_to_euc_tw</literal></entry>
2130        <entry><literal>MULE_INTERNAL</literal></entry>
2131        <entry><literal>EUC_TW</literal></entry>
2132       </row>
2133
2134       <row>
2135        <entry><literal>mic_to_iso_8859_1</literal></entry>
2136        <entry><literal>MULE_INTERNAL</literal></entry>
2137        <entry><literal>LATIN1</literal></entry>
2138       </row>
2139
2140       <row>
2141        <entry><literal>mic_to_iso_8859_2</literal></entry>
2142        <entry><literal>MULE_INTERNAL</literal></entry>
2143        <entry><literal>LATIN2</literal></entry>
2144       </row>
2145
2146       <row>
2147        <entry><literal>mic_to_iso_8859_3</literal></entry>
2148        <entry><literal>MULE_INTERNAL</literal></entry>
2149        <entry><literal>LATIN3</literal></entry>
2150       </row>
2151
2152       <row>
2153        <entry><literal>mic_to_iso_8859_4</literal></entry>
2154        <entry><literal>MULE_INTERNAL</literal></entry>
2155        <entry><literal>LATIN4</literal></entry>
2156       </row>
2157
2158       <row>
2159        <entry><literal>mic_to_iso_8859_5</literal></entry>
2160        <entry><literal>MULE_INTERNAL</literal></entry>
2161        <entry><literal>ISO_8859_5</literal></entry>
2162       </row>
2163
2164       <row>
2165        <entry><literal>mic_to_koi8_r</literal></entry>
2166        <entry><literal>MULE_INTERNAL</literal></entry>
2167        <entry><literal>KOI8R</literal></entry>
2168       </row>
2169
2170       <row>
2171        <entry><literal>mic_to_sjis</literal></entry>
2172        <entry><literal>MULE_INTERNAL</literal></entry>
2173        <entry><literal>SJIS</literal></entry>
2174       </row>
2175
2176       <row>
2177        <entry><literal>mic_to_windows_1250</literal></entry>
2178        <entry><literal>MULE_INTERNAL</literal></entry>
2179        <entry><literal>WIN1250</literal></entry>
2180       </row>
2181
2182       <row>
2183        <entry><literal>mic_to_windows_1251</literal></entry>
2184        <entry><literal>MULE_INTERNAL</literal></entry>
2185        <entry><literal>WIN1251</literal></entry>
2186       </row>
2187
2188       <row>
2189        <entry><literal>mic_to_windows_866</literal></entry>
2190        <entry><literal>MULE_INTERNAL</literal></entry>
2191        <entry><literal>WIN866</literal></entry>
2192       </row>
2193
2194       <row>
2195        <entry><literal>sjis_to_euc_jp</literal></entry>
2196        <entry><literal>SJIS</literal></entry>
2197        <entry><literal>EUC_JP</literal></entry>
2198       </row>
2199
2200       <row>
2201        <entry><literal>sjis_to_mic</literal></entry>
2202        <entry><literal>SJIS</literal></entry>
2203        <entry><literal>MULE_INTERNAL</literal></entry>
2204       </row>
2205
2206       <row>
2207        <entry><literal>sjis_to_utf8</literal></entry>
2208        <entry><literal>SJIS</literal></entry>
2209        <entry><literal>UTF8</literal></entry>
2210       </row>
2211
2212       <row>
2213        <entry><literal>tcvn_to_utf8</literal></entry>
2214        <entry><literal>WIN1258</literal></entry>
2215        <entry><literal>UTF8</literal></entry>
2216       </row>
2217
2218       <row>
2219        <entry><literal>uhc_to_utf8</literal></entry>
2220        <entry><literal>UHC</literal></entry>
2221        <entry><literal>UTF8</literal></entry>
2222       </row>
2223
2224       <row>
2225        <entry><literal>utf8_to_ascii</literal></entry>
2226        <entry><literal>UTF8</literal></entry>
2227        <entry><literal>SQL_ASCII</literal></entry>
2228       </row>
2229
2230       <row>
2231        <entry><literal>utf8_to_big5</literal></entry>
2232        <entry><literal>UTF8</literal></entry>
2233        <entry><literal>BIG5</literal></entry>
2234       </row>
2235
2236       <row>
2237        <entry><literal>utf8_to_euc_cn</literal></entry>
2238        <entry><literal>UTF8</literal></entry>
2239        <entry><literal>EUC_CN</literal></entry>
2240       </row>
2241
2242       <row>
2243        <entry><literal>utf8_to_euc_jp</literal></entry>
2244        <entry><literal>UTF8</literal></entry>
2245        <entry><literal>EUC_JP</literal></entry>
2246       </row>
2247
2248       <row>
2249        <entry><literal>utf8_to_euc_kr</literal></entry>
2250        <entry><literal>UTF8</literal></entry>
2251        <entry><literal>EUC_KR</literal></entry>
2252       </row>
2253
2254       <row>
2255        <entry><literal>utf8_to_euc_tw</literal></entry>
2256        <entry><literal>UTF8</literal></entry>
2257        <entry><literal>EUC_TW</literal></entry>
2258       </row>
2259
2260       <row>
2261        <entry><literal>utf8_to_gb18030</literal></entry>
2262        <entry><literal>UTF8</literal></entry>
2263        <entry><literal>GB18030</literal></entry>
2264       </row>
2265
2266       <row>
2267        <entry><literal>utf8_to_gbk</literal></entry>
2268        <entry><literal>UTF8</literal></entry>
2269        <entry><literal>GBK</literal></entry>
2270       </row>
2271
2272       <row>
2273        <entry><literal>utf8_to_iso_8859_1</literal></entry>
2274        <entry><literal>UTF8</literal></entry>
2275        <entry><literal>LATIN1</literal></entry>
2276       </row>
2277
2278       <row>
2279        <entry><literal>utf8_to_iso_8859_10</literal></entry>
2280        <entry><literal>UTF8</literal></entry>
2281        <entry><literal>LATIN6</literal></entry>
2282       </row>
2283
2284       <row>
2285        <entry><literal>utf8_to_iso_8859_13</literal></entry>
2286        <entry><literal>UTF8</literal></entry>
2287        <entry><literal>LATIN7</literal></entry>
2288       </row>
2289
2290       <row>
2291        <entry><literal>utf8_to_iso_8859_14</literal></entry>
2292        <entry><literal>UTF8</literal></entry>
2293        <entry><literal>LATIN8</literal></entry>
2294       </row>
2295
2296       <row>
2297        <entry><literal>utf8_to_iso_8859_15</literal></entry>
2298        <entry><literal>UTF8</literal></entry>
2299        <entry><literal>LATIN9</literal></entry>
2300       </row>
2301
2302       <row>
2303        <entry><literal>utf8_to_iso_8859_16</literal></entry>
2304        <entry><literal>UTF8</literal></entry>
2305        <entry><literal>LATIN10</literal></entry>
2306       </row>
2307
2308       <row>
2309        <entry><literal>utf8_to_iso_8859_2</literal></entry>
2310        <entry><literal>UTF8</literal></entry>
2311        <entry><literal>LATIN2</literal></entry>
2312       </row>
2313
2314       <row>
2315        <entry><literal>utf8_to_iso_8859_3</literal></entry>
2316        <entry><literal>UTF8</literal></entry>
2317        <entry><literal>LATIN3</literal></entry>
2318       </row>
2319
2320       <row>
2321        <entry><literal>utf8_to_iso_8859_4</literal></entry>
2322        <entry><literal>UTF8</literal></entry>
2323        <entry><literal>LATIN4</literal></entry>
2324       </row>
2325
2326       <row>
2327        <entry><literal>utf8_to_iso_8859_5</literal></entry>
2328        <entry><literal>UTF8</literal></entry>
2329        <entry><literal>ISO_8859_5</literal></entry>
2330       </row>
2331
2332       <row>
2333        <entry><literal>utf8_to_iso_8859_6</literal></entry>
2334        <entry><literal>UTF8</literal></entry>
2335        <entry><literal>ISO_8859_6</literal></entry>
2336       </row>
2337
2338       <row>
2339        <entry><literal>utf8_to_iso_8859_7</literal></entry>
2340        <entry><literal>UTF8</literal></entry>
2341        <entry><literal>ISO_8859_7</literal></entry>
2342       </row>
2343
2344       <row>
2345        <entry><literal>utf8_to_iso_8859_8</literal></entry>
2346        <entry><literal>UTF8</literal></entry>
2347        <entry><literal>ISO_8859_8</literal></entry>
2348       </row>
2349
2350       <row>
2351        <entry><literal>utf8_to_iso_8859_9</literal></entry>
2352        <entry><literal>UTF8</literal></entry>
2353        <entry><literal>LATIN5</literal></entry>
2354       </row>
2355
2356       <row>
2357        <entry><literal>utf8_to_johab</literal></entry>
2358        <entry><literal>UTF8</literal></entry>
2359        <entry><literal>JOHAB</literal></entry>
2360       </row>
2361
2362       <row>
2363        <entry><literal>utf8_to_koi8_r</literal></entry>
2364        <entry><literal>UTF8</literal></entry>
2365        <entry><literal>KOI8R</literal></entry>
2366       </row>
2367
2368       <row>
2369        <entry><literal>utf8_to_koi8_u</literal></entry>
2370        <entry><literal>UTF8</literal></entry>
2371        <entry><literal>KOI8U</literal></entry>
2372       </row>
2373
2374       <row>
2375        <entry><literal>utf8_to_sjis</literal></entry>
2376        <entry><literal>UTF8</literal></entry>
2377        <entry><literal>SJIS</literal></entry>
2378       </row>
2379
2380       <row>
2381        <entry><literal>utf8_to_tcvn</literal></entry>
2382        <entry><literal>UTF8</literal></entry>
2383        <entry><literal>WIN1258</literal></entry>
2384       </row>
2385
2386       <row>
2387        <entry><literal>utf8_to_uhc</literal></entry>
2388        <entry><literal>UTF8</literal></entry>
2389        <entry><literal>UHC</literal></entry>
2390       </row>
2391
2392       <row>
2393        <entry><literal>utf8_to_windows_1250</literal></entry>
2394        <entry><literal>UTF8</literal></entry>
2395        <entry><literal>WIN1250</literal></entry>
2396       </row>
2397
2398       <row>
2399        <entry><literal>utf8_to_windows_1251</literal></entry>
2400        <entry><literal>UTF8</literal></entry>
2401        <entry><literal>WIN1251</literal></entry>
2402       </row>
2403
2404       <row>
2405        <entry><literal>utf8_to_windows_1252</literal></entry>
2406        <entry><literal>UTF8</literal></entry>
2407        <entry><literal>WIN1252</literal></entry>
2408       </row>
2409
2410       <row>
2411        <entry><literal>utf8_to_windows_1253</literal></entry>
2412        <entry><literal>UTF8</literal></entry>
2413        <entry><literal>WIN1253</literal></entry>
2414       </row>
2415
2416       <row>
2417        <entry><literal>utf8_to_windows_1254</literal></entry>
2418        <entry><literal>UTF8</literal></entry>
2419        <entry><literal>WIN1254</literal></entry>
2420       </row>
2421
2422       <row>
2423        <entry><literal>utf8_to_windows_1255</literal></entry>
2424        <entry><literal>UTF8</literal></entry>
2425        <entry><literal>WIN1255</literal></entry>
2426       </row>
2427
2428       <row>
2429        <entry><literal>utf8_to_windows_1256</literal></entry>
2430        <entry><literal>UTF8</literal></entry>
2431        <entry><literal>WIN1256</literal></entry>
2432       </row>
2433
2434       <row>
2435        <entry><literal>utf8_to_windows_1257</literal></entry>
2436        <entry><literal>UTF8</literal></entry>
2437        <entry><literal>WIN1257</literal></entry>
2438       </row>
2439
2440       <row>
2441        <entry><literal>utf8_to_windows_866</literal></entry>
2442        <entry><literal>UTF8</literal></entry>
2443        <entry><literal>WIN866</literal></entry>
2444       </row>
2445
2446       <row>
2447        <entry><literal>utf8_to_windows_874</literal></entry>
2448        <entry><literal>UTF8</literal></entry>
2449        <entry><literal>WIN874</literal></entry>
2450       </row>
2451
2452       <row>
2453        <entry><literal>windows_1250_to_iso_8859_2</literal></entry>
2454        <entry><literal>WIN1250</literal></entry>
2455        <entry><literal>LATIN2</literal></entry>
2456       </row>
2457
2458       <row>
2459        <entry><literal>windows_1250_to_mic</literal></entry>
2460        <entry><literal>WIN1250</literal></entry>
2461        <entry><literal>MULE_INTERNAL</literal></entry>
2462       </row>
2463
2464       <row>
2465        <entry><literal>windows_1250_to_utf8</literal></entry>
2466        <entry><literal>WIN1250</literal></entry>
2467        <entry><literal>UTF8</literal></entry>
2468       </row>
2469
2470       <row>
2471        <entry><literal>windows_1251_to_iso_8859_5</literal></entry>
2472        <entry><literal>WIN1251</literal></entry>
2473        <entry><literal>ISO_8859_5</literal></entry>
2474       </row>
2475
2476       <row>
2477        <entry><literal>windows_1251_to_koi8_r</literal></entry>
2478        <entry><literal>WIN1251</literal></entry>
2479        <entry><literal>KOI8R</literal></entry>
2480       </row>
2481
2482       <row>
2483        <entry><literal>windows_1251_to_mic</literal></entry>
2484        <entry><literal>WIN1251</literal></entry>
2485        <entry><literal>MULE_INTERNAL</literal></entry>
2486       </row>
2487
2488       <row>
2489        <entry><literal>windows_1251_to_utf8</literal></entry>
2490        <entry><literal>WIN1251</literal></entry>
2491        <entry><literal>UTF8</literal></entry>
2492       </row>
2493
2494       <row>
2495        <entry><literal>windows_1251_to_windows_866</literal></entry>
2496        <entry><literal>WIN1251</literal></entry>
2497        <entry><literal>WIN866</literal></entry>
2498       </row>
2499
2500       <row>
2501        <entry><literal>windows_1252_to_utf8</literal></entry>
2502        <entry><literal>WIN1252</literal></entry>
2503        <entry><literal>UTF8</literal></entry>
2504       </row>
2505
2506       <row>
2507        <entry><literal>windows_1256_to_utf8</literal></entry>
2508        <entry><literal>WIN1256</literal></entry>
2509        <entry><literal>UTF8</literal></entry>
2510       </row>
2511
2512       <row>
2513        <entry><literal>windows_866_to_iso_8859_5</literal></entry>
2514        <entry><literal>WIN866</literal></entry>
2515        <entry><literal>ISO_8859_5</literal></entry>
2516       </row>
2517
2518       <row>
2519        <entry><literal>windows_866_to_koi8_r</literal></entry>
2520        <entry><literal>WIN866</literal></entry>
2521        <entry><literal>KOI8R</literal></entry>
2522       </row>
2523
2524       <row>
2525        <entry><literal>windows_866_to_mic</literal></entry>
2526        <entry><literal>WIN866</literal></entry>
2527        <entry><literal>MULE_INTERNAL</literal></entry>
2528       </row>
2529
2530       <row>
2531        <entry><literal>windows_866_to_utf8</literal></entry>
2532        <entry><literal>WIN866</literal></entry>
2533        <entry><literal>UTF8</literal></entry>
2534       </row>
2535
2536       <row>
2537        <entry><literal>windows_866_to_windows_1251</literal></entry>
2538        <entry><literal>WIN866</literal></entry>
2539        <entry><literal>WIN</literal></entry>
2540       </row>
2541
2542       <row>
2543        <entry><literal>windows_874_to_utf8</literal></entry>
2544        <entry><literal>WIN874</literal></entry>
2545        <entry><literal>UTF8</literal></entry>
2546       </row>
2547
2548       <row>
2549        <entry><literal>euc_jis_2004_to_utf8</literal></entry>
2550        <entry><literal>EUC_JIS_2004</literal></entry>
2551        <entry><literal>UTF8</literal></entry>
2552       </row>
2553
2554       <row>
2555        <entry><literal>ut8_to_euc_jis_2004</literal></entry>
2556        <entry><literal>UTF8</literal></entry>
2557        <entry><literal>EUC_JIS_2004</literal></entry>
2558       </row>
2559
2560       <row>
2561        <entry><literal>shift_jis_2004_to_utf8</literal></entry>
2562        <entry><literal>SHIFT_JIS_2004</literal></entry>
2563        <entry><literal>UTF8</literal></entry>
2564       </row>
2565
2566       <row>
2567        <entry><literal>ut8_to_shift_jis_2004</literal></entry>
2568        <entry><literal>UTF8</literal></entry>
2569        <entry><literal>SHIFT_JIS_2004</literal></entry>
2570       </row>
2571
2572       <row>
2573        <entry><literal>euc_jis_2004_to_shift_jis_2004</literal></entry>
2574        <entry><literal>EUC_JIS_2004</literal></entry>
2575        <entry><literal>SHIFT_JIS_2004</literal></entry>
2576       </row>
2577
2578       <row>
2579        <entry><literal>shift_jis_2004_to_euc_jis_2004</literal></entry>
2580        <entry><literal>SHIFT_JIS_2004</literal></entry>
2581        <entry><literal>EUC_JIS_2004</literal></entry>
2582       </row>
2583
2584      </tbody>
2585     </tgroup>
2586    </table>
2587
2588   </sect1>
2589
2590
2591   <sect1 id="functions-binarystring">
2592    <title>Binary String Functions and Operators</title>
2593
2594    <indexterm zone="functions-binarystring">
2595     <primary>binary data</primary>
2596     <secondary>functions</secondary>
2597    </indexterm>
2598
2599    <para>
2600     This section describes functions and operators for examining and
2601     manipulating values of type <type>bytea</type>.
2602    </para>
2603
2604    <para>
2605     <acronym>SQL</acronym> defines some string functions that use
2606     key words, rather than commas, to separate
2607     arguments.  Details are in
2608     <xref linkend="functions-binarystring-sql">.
2609     <productname>PostgreSQL</> also provides versions of these functions
2610     that use the regular function invocation syntax
2611     (see <xref linkend="functions-binarystring-other">).
2612    </para>
2613
2614    <table id="functions-binarystring-sql">
2615     <title><acronym>SQL</acronym> Binary String Functions and Operators</title>
2616     <tgroup cols="5">
2617      <thead>
2618       <row>
2619        <entry>Function</entry>
2620        <entry>Return Type</entry>
2621        <entry>Description</entry>
2622        <entry>Example</entry>
2623        <entry>Result</entry>
2624       </row>
2625      </thead>
2626
2627      <tbody>
2628       <row>
2629        <entry><literal><parameter>string</parameter> <literal>||</literal>
2630         <parameter>string</parameter></literal></entry>
2631        <entry> <type>bytea</type> </entry>
2632        <entry>
2633         String concatenation
2634         <indexterm>
2635          <primary>binary string</primary>
2636          <secondary>concatenation</secondary>
2637         </indexterm>
2638        </entry>
2639        <entry><literal>E'\\\\Post'::bytea || E'\\047gres\\000'::bytea</literal></entry>
2640        <entry><literal>\\Post'gres\000</literal></entry>
2641       </row>
2642
2643       <row>
2644        <entry><function>get_bit</function>(<parameter>string</parameter>, <parameter>offset</parameter>)</entry>
2645        <entry><type>int</type></entry>
2646        <entry>
2647         Extract bit from string
2648         <indexterm>
2649          <primary>get_bit</primary>
2650         </indexterm>
2651        </entry>
2652        <entry><literal>get_bit(E'Th\\000omas'::bytea, 45)</literal></entry>
2653        <entry><literal>1</literal></entry>
2654       </row>
2655
2656       <row>
2657        <entry><function>get_byte</function>(<parameter>string</parameter>, <parameter>offset</parameter>)</entry>
2658        <entry><type>int</type></entry>
2659        <entry>
2660         Extract byte from string
2661         <indexterm>
2662          <primary>get_byte</primary>
2663         </indexterm>
2664        </entry>
2665        <entry><literal>get_byte(E'Th\\000omas'::bytea, 4)</literal></entry>
2666        <entry><literal>109</literal></entry>
2667       </row>
2668
2669       <row>
2670        <entry><literal><function>octet_length</function>(<parameter>string</parameter>)</literal></entry>
2671        <entry><type>int</type></entry>
2672        <entry>Number of bytes in binary string</entry>
2673        <entry><literal>octet_length(E'jo\\000se'::bytea)</literal></entry>
2674        <entry><literal>5</literal></entry>
2675       </row>
2676
2677       <row>
2678        <entry><literal><function>position</function>(<parameter>substring</parameter> in <parameter>string</parameter>)</literal></entry>
2679        <entry><type>int</type></entry>
2680        <entry>Location of specified substring</entry>
2681       <entry><literal>position(E'\\000om'::bytea in E'Th\\000omas'::bytea)</literal></entry>
2682        <entry><literal>3</literal></entry>
2683       </row>
2684
2685       <row>
2686        <entry><function>set_bit</function>(<parameter>string</parameter>,
2687        <parameter>offset</parameter>, <parameter>newvalue</>)</entry>
2688        <entry><type>bytea</type></entry>
2689        <entry>
2690         Set bit in string
2691         <indexterm>
2692          <primary>set_bit</primary>
2693         </indexterm>
2694        </entry>
2695        <entry><literal>set_bit(E'Th\\000omas'::bytea, 45, 0)</literal></entry>
2696        <entry><literal>Th\000omAs</literal></entry>
2697       </row>
2698
2699       <row>
2700        <entry><function>set_byte</function>(<parameter>string</parameter>,
2701        <parameter>offset</parameter>, <parameter>newvalue</>)</entry>
2702        <entry><type>bytea</type></entry>
2703        <entry>
2704         Set byte in string
2705         <indexterm>
2706          <primary>set_byte</primary>
2707         </indexterm>
2708        </entry>
2709        <entry><literal>set_byte(E'Th\\000omas'::bytea, 4, 64)</literal></entry>
2710        <entry><literal>Th\000o@as</literal></entry>
2711       </row>
2712
2713       <row>
2714        <entry><literal><function>substring</function>(<parameter>string</parameter> <optional>from <type>int</type></optional> <optional>for <type>int</type></optional>)</literal></entry>
2715        <entry><type>bytea</type></entry>
2716        <entry>
2717         Extract substring
2718         <indexterm>
2719          <primary>substring</primary>
2720         </indexterm>
2721        </entry>
2722        <entry><literal>substring(E'Th\\000omas'::bytea from 2 for 3)</literal></entry>
2723        <entry><literal>h\000o</literal></entry>
2724       </row>
2725
2726       <row>
2727        <entry>
2728         <literal><function>trim</function>(<optional>both</optional>
2729         <parameter>bytes</parameter> from
2730         <parameter>string</parameter>)</literal>
2731        </entry>
2732        <entry><type>bytea</type></entry>
2733        <entry>
2734         Remove the longest string containing only the bytes in
2735         <parameter>bytes</parameter> from the start
2736         and end of <parameter>string</parameter>
2737        </entry>
2738        <entry><literal>trim(E'\\000'::bytea from E'\\000Tom\\000'::bytea)</literal></entry>
2739        <entry><literal>Tom</literal></entry>
2740       </row>
2741      </tbody>
2742     </tgroup>
2743    </table>
2744
2745    <para>
2746     Additional binary string manipulation functions are available and
2747     are listed in <xref linkend="functions-binarystring-other">.  Some
2748     of them are used internally to implement the
2749     <acronym>SQL</acronym>-standard string functions listed in <xref
2750     linkend="functions-binarystring-sql">.
2751    </para>
2752
2753    <table id="functions-binarystring-other">
2754     <title>Other Binary String Functions</title>
2755     <tgroup cols="5">
2756      <thead>
2757       <row>
2758        <entry>Function</entry>
2759        <entry>Return Type</entry>
2760        <entry>Description</entry>
2761        <entry>Example</entry>
2762        <entry>Result</entry>
2763       </row>
2764      </thead>
2765
2766      <tbody>
2767       <row>
2768        <entry><literal><function>btrim</function>(<parameter>string</parameter>
2769         <type>bytea</type>, <parameter>bytes</parameter> <type>bytea</type>)</literal></entry>
2770        <entry><type>bytea</type></entry>
2771        <entry>
2772         Remove the longest string consisting only of bytes
2773         in <parameter>bytes</parameter> from the start and end of
2774         <parameter>string</parameter>
2775       </entry>
2776       <entry><literal>btrim(E'\\000trim\\000'::bytea, E'\\000'::bytea)</literal></entry>
2777       <entry><literal>trim</literal></entry>
2778      </row>
2779
2780      <row>
2781       <entry>
2782        <literal><function>decode</function>(<parameter>string</parameter> <type>text</type>,
2783               <parameter>type</parameter> <type>text</type>)</literal>
2784       </entry>
2785       <entry><type>bytea</type></entry>
2786       <entry>
2787        Decode binary string from <parameter>string</parameter> previously
2788        encoded with <function>encode</>.  Parameter type is same as in <function>encode</>.
2789       </entry>
2790       <entry><literal>decode(E'123\\000456', 'escape')</literal></entry>
2791       <entry><literal>123\000456</literal></entry>
2792      </row>
2793
2794      <row>
2795       <entry>
2796        <literal><function>encode</function>(<parameter>string</parameter> <type>bytea</type>,
2797               <parameter>type</parameter> <type>text</type>)</literal>
2798       </entry>
2799       <entry><type>text</type></entry>
2800       <entry>
2801        Encode binary string to <acronym>ASCII</acronym>-only representation.  Supported
2802        types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
2803       </entry>
2804       <entry><literal>encode(E'123\\000456'::bytea, 'escape')</literal></entry>
2805       <entry><literal>123\000456</literal></entry>
2806      </row>
2807
2808      <row>
2809       <entry><literal><function>length</function>(<parameter>string</parameter>)</literal></entry>
2810       <entry><type>int</type></entry>
2811       <entry>
2812        Length of binary string
2813        <indexterm>
2814         <primary>binary string</primary>
2815         <secondary>length</secondary>
2816        </indexterm>
2817        <indexterm>
2818         <primary>length</primary>
2819         <secondary sortas="binary string">of a binary string</secondary>
2820         <see>binary strings, length</see>
2821        </indexterm>
2822       </entry>
2823       <entry><literal>length(E'jo\\000se'::bytea)</literal></entry>
2824       <entry><literal>5</literal></entry>
2825      </row>
2826
2827      <row>
2828       <entry><literal><function>md5</function>(<parameter>string</parameter>)</literal></entry>
2829       <entry><type>text</type></entry>
2830       <entry>
2831        Calculates the MD5 hash of <parameter>string</parameter>,
2832        returning the result in hexadecimal
2833       </entry>
2834       <entry><literal>md5(E'Th\\000omas'::bytea)</literal></entry>
2835       <entry><literal>8ab2d3c9689aaf18 b4958c334c82d8b1</literal></entry>
2836      </row>
2837     </tbody>
2838    </tgroup>
2839   </table>
2840
2841  </sect1>
2842
2843
2844   <sect1 id="functions-bitstring">
2845    <title>Bit String Functions and Operators</title>
2846
2847    <indexterm zone="functions-bitstring">
2848     <primary>bit strings</primary>
2849     <secondary>functions</secondary>
2850    </indexterm>
2851
2852    <para>
2853     This section describes functions and operators for examining and
2854     manipulating bit strings, that is values of the types
2855     <type>bit</type> and <type>bit varying</type>.  Aside from the
2856     usual comparison operators, the operators
2857     shown in <xref linkend="functions-bit-string-op-table"> can be used.
2858     Bit string operands of <literal>&amp;</literal>, <literal>|</literal>,
2859     and <literal>#</literal> must be of equal length.  When bit
2860     shifting, the original length of the string is preserved, as shown
2861     in the examples.
2862    </para>
2863
2864    <table id="functions-bit-string-op-table">
2865     <title>Bit String Operators</title>
2866
2867     <tgroup cols="4">
2868      <thead>
2869       <row>
2870        <entry>Operator</entry>
2871        <entry>Description</entry>
2872        <entry>Example</entry>
2873        <entry>Result</entry>
2874       </row>
2875      </thead>
2876
2877      <tbody>
2878       <row>
2879        <entry> <literal>||</literal> </entry>
2880        <entry>concatenation</entry>
2881        <entry><literal>B'10001' || B'011'</literal></entry>
2882        <entry><literal>10001011</literal></entry>
2883       </row>
2884
2885       <row>
2886        <entry> <literal>&amp;</literal> </entry>
2887        <entry>bitwise AND</entry>
2888        <entry><literal>B'10001' &amp; B'01101'</literal></entry>
2889        <entry><literal>00001</literal></entry>
2890       </row>
2891
2892       <row>
2893        <entry> <literal>|</literal> </entry>
2894        <entry>bitwise OR</entry>
2895        <entry><literal>B'10001' | B'01101'</literal></entry>
2896        <entry><literal>11101</literal></entry>
2897       </row>
2898
2899       <row>
2900        <entry> <literal>#</literal> </entry>
2901        <entry>bitwise XOR</entry>
2902        <entry><literal>B'10001' # B'01101'</literal></entry>
2903        <entry><literal>11100</literal></entry>
2904       </row>
2905
2906       <row>
2907        <entry> <literal>~</literal> </entry>
2908        <entry>bitwise NOT</entry>
2909        <entry><literal>~ B'10001'</literal></entry>
2910        <entry><literal>01110</literal></entry>
2911       </row>
2912
2913       <row>
2914        <entry> <literal>&lt;&lt;</literal> </entry>
2915        <entry>bitwise shift left</entry>
2916        <entry><literal>B'10001' &lt;&lt; 3</literal></entry>
2917        <entry><literal>01000</literal></entry>
2918       </row>
2919
2920       <row>
2921        <entry> <literal>&gt;&gt;</literal> </entry>
2922        <entry>bitwise shift right</entry>
2923        <entry><literal>B'10001' &gt;&gt; 2</literal></entry>
2924        <entry><literal>00100</literal></entry>
2925       </row>
2926      </tbody>
2927     </tgroup>
2928    </table>
2929
2930    <para>
2931     The following <acronym>SQL</acronym>-standard functions work on bit
2932     strings as well as character strings:
2933     <literal><function>length</function></literal>,
2934     <literal><function>bit_length</function></literal>,
2935     <literal><function>octet_length</function></literal>,
2936     <literal><function>position</function></literal>,
2937     <literal><function>substring</function></literal>.
2938    </para>
2939
2940    <para>
2941     In addition, it is possible to cast integral values to and from type
2942     <type>bit</>.
2943     Some examples:
2944 <programlisting>
2945 44::bit(10)                    <lineannotation>0000101100</lineannotation>
2946 44::bit(3)                     <lineannotation>100</lineannotation>
2947 cast(-44 as bit(12))           <lineannotation>111111010100</lineannotation>
2948 '1110'::bit(4)::integer        <lineannotation>14</lineannotation>
2949 </programlisting>
2950     Note that casting to just <quote>bit</> means casting to
2951     <literal>bit(1)</>, and so will deliver only the least significant
2952     bit of the integer.
2953    </para>
2954
2955     <note>
2956      <para>
2957       Prior to <productname>PostgreSQL</productname> 8.0, casting an
2958       integer to <type>bit(n)</> would copy the leftmost <literal>n</>
2959       bits of the integer, whereas now it copies the rightmost <literal>n</>
2960       bits.  Also, casting an integer to a bit string width wider than
2961       the integer itself will sign-extend on the left.
2962      </para>
2963     </note>
2964
2965   </sect1>
2966
2967
2968  <sect1 id="functions-matching">
2969   <title>Pattern Matching</title>
2970
2971   <indexterm zone="functions-matching">
2972    <primary>pattern matching</primary>
2973   </indexterm>
2974
2975    <para>
2976     There are three separate approaches to pattern matching provided
2977     by <productname>PostgreSQL</productname>: the traditional
2978     <acronym>SQL</acronym> <function>LIKE</function> operator, the
2979     more recent <function>SIMILAR TO</function> operator (added in
2980     SQL:1999), and <acronym>POSIX</acronym>-style regular
2981     expressions.  Aside from the basic <quote>does this string match
2982     this pattern?</> operators, functions are available to extract
2983     or replace matching substrings and to split a string at matching
2984     locations.
2985    </para>
2986
2987    <tip>
2988     <para>
2989      If you have pattern matching needs that go beyond this,
2990      consider writing a user-defined function in Perl or Tcl.
2991     </para>
2992    </tip>
2993
2994   <sect2 id="functions-like">
2995    <title><function>LIKE</function></title>
2996
2997    <indexterm>
2998     <primary>LIKE</primary>
2999    </indexterm>
3000
3001 <synopsis>
3002 <replaceable>string</replaceable> LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
3003 <replaceable>string</replaceable> NOT LIKE <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
3004 </synopsis>
3005
3006     <para>
3007      The <function>LIKE</function> expression returns true if the
3008      <replaceable>string</replaceable> matches the supplied
3009      <replaceable>pattern</replaceable>.  (As
3010      expected, the <function>NOT LIKE</function> expression returns
3011      false if <function>LIKE</function> returns true, and vice versa.
3012      An equivalent expression is
3013      <literal>NOT (<replaceable>string</replaceable> LIKE
3014       <replaceable>pattern</replaceable>)</literal>.)
3015     </para>
3016
3017     <para>
3018      If <replaceable>pattern</replaceable> does not contain percent
3019      signs or underscores, then the pattern only represents the string
3020      itself; in that case <function>LIKE</function> acts like the
3021      equals operator.  An underscore (<literal>_</literal>) in
3022      <replaceable>pattern</replaceable> stands for (matches) any single
3023      character; a percent sign (<literal>%</literal>) matches any sequence
3024      of zero or more characters.
3025     </para>
3026
3027    <para>
3028     Some examples:
3029 <programlisting>
3030 'abc' LIKE 'abc'    <lineannotation>true</lineannotation>
3031 'abc' LIKE 'a%'     <lineannotation>true</lineannotation>
3032 'abc' LIKE '_b_'    <lineannotation>true</lineannotation>
3033 'abc' LIKE 'c'      <lineannotation>false</lineannotation>
3034 </programlisting>
3035    </para>
3036
3037    <para>
3038     <function>LIKE</function> pattern matching always covers the entire
3039     string.  Therefore, to match a sequence anywhere within a string, the
3040     pattern must start and end with a percent sign.
3041    </para>
3042
3043    <para>
3044     To match a literal underscore or percent sign without matching
3045     other characters, the respective character in
3046     <replaceable>pattern</replaceable> must be
3047     preceded by the escape character.  The default escape
3048     character is the backslash but a different one can be selected by
3049     using the <literal>ESCAPE</literal> clause.  To match the escape
3050     character itself, write two escape characters.
3051    </para>
3052
3053    <para>
3054     Note that the backslash already has a special meaning in string literals,
3055     so to write a pattern constant that contains a backslash you must write two
3056     backslashes in an SQL statement (assuming escape string syntax is used, see
3057     <xref linkend="sql-syntax-strings">).  Thus, writing a pattern that
3058     actually matches a literal backslash means writing four backslashes in the
3059     statement.  You can avoid this by selecting a different escape character
3060     with <literal>ESCAPE</literal>; then a backslash is not special to
3061     <function>LIKE</function> anymore. (But backslash is still special to the
3062     string literal parser, so you still need two of them to match a backslash.)
3063    </para>
3064
3065    <para>
3066     It's also possible to select no escape character by writing
3067     <literal>ESCAPE ''</literal>.  This effectively disables the
3068     escape mechanism, which makes it impossible to turn off the
3069     special meaning of underscore and percent signs in the pattern.
3070    </para>
3071
3072    <para>
3073     The key word <token>ILIKE</token> can be used instead of
3074     <token>LIKE</token> to make the match case-insensitive according
3075     to the active locale.  This is not in the <acronym>SQL</acronym> standard but is a
3076     <productname>PostgreSQL</productname> extension.
3077    </para>
3078
3079    <para>
3080     The operator <literal>~~</literal> is equivalent to
3081     <function>LIKE</function>, and <literal>~~*</literal> corresponds to
3082     <function>ILIKE</function>.  There are also
3083     <literal>!~~</literal> and <literal>!~~*</literal> operators that
3084     represent <function>NOT LIKE</function> and <function>NOT
3085     ILIKE</function>, respectively.  All of these operators are
3086     <productname>PostgreSQL</productname>-specific.
3087    </para>
3088   </sect2>
3089
3090
3091   <sect2 id="functions-similarto-regexp">
3092    <title><function>SIMILAR TO</function> Regular Expressions</title>
3093
3094    <indexterm>
3095     <primary>regular expression</primary>
3096     <!-- <seealso>pattern matching</seealso> breaks index build -->
3097    </indexterm>
3098
3099    <indexterm>
3100     <primary>SIMILAR TO</primary>
3101    </indexterm>
3102    <indexterm>
3103     <primary>substring</primary>
3104    </indexterm>
3105
3106 <synopsis>
3107 <replaceable>string</replaceable> SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
3108 <replaceable>string</replaceable> NOT SIMILAR TO <replaceable>pattern</replaceable> <optional>ESCAPE <replaceable>escape-character</replaceable></optional>
3109 </synopsis>
3110
3111    <para>
3112     The <function>SIMILAR TO</function> operator returns true or
3113     false depending on whether its pattern matches the given string.
3114     It is similar to <function>LIKE</function>, except that it
3115     interprets the pattern using the SQL standard's definition of a
3116     regular expression.  SQL regular expressions are a curious cross
3117     between <function>LIKE</function> notation and common regular
3118     expression notation.
3119    </para>
3120
3121    <para>
3122     Like <function>LIKE</function>, the <function>SIMILAR TO</function>
3123     operator succeeds only if its pattern matches the entire string;
3124     this is unlike common regular expression behavior where the pattern
3125     can match any part of the string.
3126     Also like
3127     <function>LIKE</function>, <function>SIMILAR TO</function> uses
3128     <literal>_</> and <literal>%</> as wildcard characters denoting
3129     any single character and any string, respectively (these are
3130     comparable to <literal>.</> and <literal>.*</> in POSIX regular
3131     expressions).
3132    </para>
3133
3134    <para>
3135     In addition to these facilities borrowed from <function>LIKE</function>,
3136     <function>SIMILAR TO</function> supports these pattern-matching
3137     metacharacters borrowed from POSIX regular expressions:
3138
3139    <itemizedlist>
3140     <listitem>
3141      <para>
3142       <literal>|</literal> denotes alternation (either of two alternatives).
3143      </para>
3144     </listitem>
3145     <listitem>
3146      <para>
3147       <literal>*</literal> denotes repetition of the previous item zero
3148       or more times.
3149      </para>
3150     </listitem>
3151     <listitem>
3152      <para>
3153       <literal>+</literal> denotes repetition of the previous item one
3154       or more times.
3155      </para>
3156     </listitem>
3157     <listitem>
3158      <para>
3159       Parentheses <literal>()</literal> can be used to group items into
3160       a single logical item.
3161      </para>
3162     </listitem>
3163     <listitem>
3164      <para>
3165       A bracket expression <literal>[...]</literal> specifies a character
3166       class, just as in POSIX regular expressions.
3167      </para>
3168     </listitem>
3169    </itemizedlist>
3170
3171     Notice that bounded repetition operators (<literal>?</> and
3172     <literal>{...}</>) are not provided, though they exist in POSIX.
3173     Also, the period (<literal>.</>) is not a metacharacter.
3174    </para>
3175
3176    <para>
3177     As with <function>LIKE</>, a backslash disables the special meaning
3178     of any of these metacharacters; or a different escape character can
3179     be specified with <literal>ESCAPE</>.
3180    </para>
3181
3182    <para>
3183     Some examples:
3184 <programlisting>
3185 'abc' SIMILAR TO 'abc'      <lineannotation>true</lineannotation>
3186 'abc' SIMILAR TO 'a'        <lineannotation>false</lineannotation>
3187 'abc' SIMILAR TO '%(b|d)%'  <lineannotation>true</lineannotation>
3188 'abc' SIMILAR TO '(b|c)%'   <lineannotation>false</lineannotation>
3189 </programlisting>
3190    </para>
3191
3192    <para>
3193     The <function>substring</> function with three parameters,
3194     <function>substring(<replaceable>string</replaceable> from
3195     <replaceable>pattern</replaceable> for
3196     <replaceable>escape-character</replaceable>)</function>, provides
3197     extraction of a substring that matches an SQL
3198     regular expression pattern.  As with <literal>SIMILAR TO</>, the
3199     specified pattern must match the entire data string, or else the
3200     function fails and returns null.  To indicate the part of the
3201     pattern that should be returned on success, the pattern must contain
3202     two occurrences of the escape character followed by a double quote
3203     (<literal>"</>). <!-- " font-lock sanity -->
3204     The text matching the portion of the pattern
3205     between these markers is returned.
3206    </para>
3207
3208    <para>
3209     Some examples, with <literal>#"</> delimiting the return string:
3210 <programlisting>
3211 substring('foobar' from '%#"o_b#"%' for '#')   <lineannotation>oob</lineannotation>
3212 substring('foobar' from '#"o_b#"%' for '#')    <lineannotation>NULL</lineannotation>
3213 </programlisting>
3214    </para>
3215   </sect2>
3216
3217   <sect2 id="functions-posix-regexp">
3218    <title><acronym>POSIX</acronym> Regular Expressions</title>
3219
3220    <indexterm zone="functions-posix-regexp">
3221     <primary>regular expression</primary>
3222     <seealso>pattern matching</seealso>
3223    </indexterm>
3224    <indexterm>
3225     <primary>substring</primary>
3226    </indexterm>
3227    <indexterm>
3228     <primary>regexp_replace</primary>
3229    </indexterm>
3230    <indexterm>
3231     <primary>regexp_matches</primary>
3232    </indexterm>
3233    <indexterm>
3234     <primary>regexp_split_to_table</primary>
3235    </indexterm>
3236    <indexterm>
3237     <primary>regexp_split_to_array</primary>
3238    </indexterm>
3239
3240    <para>
3241     <xref linkend="functions-posix-table"> lists the available
3242     operators for pattern matching using POSIX regular expressions.
3243    </para>
3244
3245    <table id="functions-posix-table">
3246     <title>Regular Expression Match Operators</title>
3247
3248     <tgroup cols="3">
3249      <thead>
3250       <row>
3251        <entry>Operator</entry>
3252        <entry>Description</entry>
3253        <entry>Example</entry>
3254       </row>
3255      </thead>
3256
3257       <tbody>
3258        <row>
3259         <entry> <literal>~</literal> </entry>
3260         <entry>Matches regular expression, case sensitive</entry>
3261         <entry><literal>'thomas' ~ '.*thomas.*'</literal></entry>
3262        </row>
3263
3264        <row>
3265         <entry> <literal>~*</literal> </entry>
3266         <entry>Matches regular expression, case insensitive</entry>
3267         <entry><literal>'thomas' ~* '.*Thomas.*'</literal></entry>
3268        </row>
3269
3270        <row>
3271         <entry> <literal>!~</literal> </entry>
3272         <entry>Does not match regular expression, case sensitive</entry>
3273         <entry><literal>'thomas' !~ '.*Thomas.*'</literal></entry>
3274        </row>
3275
3276        <row>
3277         <entry> <literal>!~*</literal> </entry>
3278         <entry>Does not match regular expression, case insensitive</entry>
3279         <entry><literal>'thomas' !~* '.*vadim.*'</literal></entry>
3280        </row>
3281       </tbody>
3282      </tgroup>
3283     </table>
3284
3285     <para>
3286      <acronym>POSIX</acronym> regular expressions provide a more
3287      powerful means for
3288      pattern matching than the <function>LIKE</function> and
3289      <function>SIMILAR TO</> operators.
3290      Many Unix tools such as <command>egrep</command>,
3291      <command>sed</command>, or <command>awk</command> use a pattern
3292      matching language that is similar to the one described here.
3293     </para>
3294
3295     <para>
3296      A regular expression is a character sequence that is an
3297      abbreviated definition of a set of strings (a <firstterm>regular
3298      set</firstterm>).  A string is said to match a regular expression
3299      if it is a member of the regular set described by the regular
3300      expression.  As with <function>LIKE</function>, pattern characters
3301      match string characters exactly unless they are special characters
3302      in the regular expression language &mdash; but regular expressions use
3303      different special characters than <function>LIKE</function> does.
3304      Unlike <function>LIKE</function> patterns, a
3305      regular expression is allowed to match anywhere within a string, unless
3306      the regular expression is explicitly anchored to the beginning or
3307      end of the string.
3308     </para>
3309
3310     <para>
3311      Some examples:
3312 <programlisting>
3313 'abc' ~ 'abc'    <lineannotation>true</lineannotation>
3314 'abc' ~ '^a'     <lineannotation>true</lineannotation>
3315 'abc' ~ '(b|d)'  <lineannotation>true</lineannotation>
3316 'abc' ~ '^(b|c)' <lineannotation>false</lineannotation>
3317 </programlisting>
3318     </para>
3319
3320     <para>
3321      The <acronym>POSIX</acronym> pattern language is described in much
3322      greater detail below.
3323     </para>
3324
3325     <para>
3326      The <function>substring</> function with two parameters,
3327      <function>substring(<replaceable>string</replaceable> from
3328      <replaceable>pattern</replaceable>)</function>, provides extraction of a
3329      substring
3330      that matches a POSIX regular expression pattern.  It returns null if
3331      there is no match, otherwise the portion of the text that matched the
3332      pattern.  But if the pattern contains any parentheses, the portion
3333      of the text that matched the first parenthesized subexpression (the
3334      one whose left parenthesis comes first) is
3335      returned.  You can put parentheses around the whole expression
3336      if you want to use parentheses within it without triggering this
3337      exception.  If you need parentheses in the pattern before the
3338      subexpression you want to extract, see the non-capturing parentheses
3339      described below.
3340     </para>
3341
3342    <para>
3343     Some examples:
3344 <programlisting>
3345 substring('foobar' from 'o.b')     <lineannotation>oob</lineannotation>
3346 substring('foobar' from 'o(.)b')   <lineannotation>o</lineannotation>
3347 </programlisting>
3348    </para>
3349
3350     <para>
3351      The <function>regexp_replace</> function provides substitution of
3352      new text for substrings that match POSIX regular expression patterns.
3353      It has the syntax
3354      <function>regexp_replace</function>(<replaceable>source</>,
3355      <replaceable>pattern</>, <replaceable>replacement</>
3356      <optional>, <replaceable>flags</> </optional>).
3357      The <replaceable>source</> string is returned unchanged if
3358      there is no match to the <replaceable>pattern</>.  If there is a
3359      match, the <replaceable>source</> string is returned with the
3360      <replaceable>replacement</> string substituted for the matching
3361      substring.  The <replaceable>replacement</> string can contain
3362      <literal>\</><replaceable>n</>, where <replaceable>n</> is <literal>1</>
3363      through <literal>9</>, to indicate that the source substring matching the
3364      <replaceable>n</>'th parenthesized subexpression of the pattern should be
3365      inserted, and it can contain <literal>\&amp;</> to indicate that the
3366      substring matching the entire pattern should be inserted.  Write
3367      <literal>\\</> if you need to put a literal backslash in the replacement
3368      text.  (As always, remember to double backslashes written in literal
3369      constant strings, assuming escape string syntax is used.)
3370      The <replaceable>flags</> parameter is an optional text
3371      string containing zero or more single-letter flags that change the
3372      function's behavior.  Flag <literal>i</> specifies case-insensitive
3373      matching, while flag <literal>g</> specifies replacement of each matching
3374      substring rather than only the first one.  Other supported flags are
3375      described in <xref linkend="posix-embedded-options-table">.
3376     </para>
3377
3378    <para>
3379     Some examples:
3380 <programlisting>
3381 regexp_replace('foobarbaz', 'b..', 'X')
3382                                    <lineannotation>fooXbaz</lineannotation>
3383 regexp_replace('foobarbaz', 'b..', 'X', 'g')
3384                                    <lineannotation>fooXX</lineannotation>
3385 regexp_replace('foobarbaz', 'b(..)', E'X\\1Y', 'g')
3386                                    <lineannotation>fooXarYXazY</lineannotation>
3387 </programlisting>
3388    </para>
3389
3390     <para>
3391      The <function>regexp_matches</> function returns all of the captured
3392      substrings resulting from matching a POSIX regular expression pattern.
3393      It has the syntax
3394      <function>regexp_matches</function>(<replaceable>string</>, <replaceable>pattern</>
3395      <optional>, <replaceable>flags</> </optional>).
3396      If there is no match to the <replaceable>pattern</>, the function returns
3397      no rows.  If there is a match, the function returns a text array whose
3398      <replaceable>n</>'th element is the substring matching the
3399      <replaceable>n</>'th parenthesized subexpression of the pattern
3400      (not counting <quote>non-capturing</> parentheses; see below for
3401      details).  If the pattern does not contain any parenthesized
3402      subexpressions, then the result is a single-element text array containing
3403      the substring matching the whole pattern.
3404      The <replaceable>flags</> parameter is an optional text
3405      string containing zero or more single-letter flags that change the
3406      function's behavior.  Flag <literal>g</> causes the function to find
3407      each match in the string, not only the first one, and return a row for
3408      each such match.  Other supported
3409      flags are described in <xref linkend="posix-embedded-options-table">.
3410     </para>
3411
3412    <para>
3413     Some examples:
3414 <programlisting>
3415 SELECT regexp_matches('foobarbequebaz', '(bar)(beque)');
3416  regexp_matches
3417 ----------------
3418  {bar,beque}
3419 (1 row)
3420
3421 SELECT regexp_matches('foobarbequebazilbarfbonk', '(b[^b]+)(b[^b]+)', 'g');
3422  regexp_matches
3423 ----------------
3424  {bar,beque}
3425  {bazil,barf}
3426 (2 rows)
3427
3428 SELECT regexp_matches('foobarbequebaz', 'barbeque');
3429  regexp_matches
3430 ----------------
3431  {barbeque}
3432 (1 row)
3433 </programlisting>
3434    </para>
3435
3436     <para>
3437      The <function>regexp_split_to_table</> function splits a string using a POSIX
3438      regular expression pattern as a delimiter.  It has the syntax
3439      <function>regexp_split_to_table</function>(<replaceable>string</>, <replaceable>pattern</>
3440      <optional>, <replaceable>flags</> </optional>).
3441      If there is no match to the <replaceable>pattern</>, the function returns the
3442      <replaceable>string</>.  If there is at least one match, for each match it returns
3443      the text from the end of the last match (or the beginning of the string)
3444      to the beginning of the match.  When there are no more matches, it
3445      returns the text from the end of the last match to the end of the string.
3446      The <replaceable>flags</> parameter is an optional text string containing
3447      zero or more single-letter flags that change the function's behavior.
3448      <function>regexp_split_to_table</function> supports the flags described in
3449      <xref linkend="posix-embedded-options-table">.
3450     </para>
3451
3452     <para>
3453      The <function>regexp_split_to_array</> function behaves the same as
3454      <function>regexp_split_to_table</>, except that <function>regexp_split_to_array</>
3455      returns its result as an array of <type>text</>.  It has the syntax
3456      <function>regexp_split_to_array</function>(<replaceable>string</>, <replaceable>pattern</>
3457      <optional>, <replaceable>flags</> </optional>).
3458      The parameters are the same as for <function>regexp_split_to_table</>.
3459     </para>
3460
3461    <para>
3462     Some examples:
3463 <programlisting>
3464
3465 SELECT foo FROM regexp_split_to_table('the quick brown fox jumped over the lazy dog', E'\\s+') AS foo;
3466   foo
3467 --------
3468  the
3469  quick
3470  brown
3471  fox
3472  jumped
3473  over
3474  the
3475  lazy
3476  dog
3477 (9 rows)
3478
3479 SELECT regexp_split_to_array('the quick brown fox jumped over the lazy dog', E'\\s+');
3480               regexp_split_to_array
3481 ------------------------------------------------
3482  {the,quick,brown,fox,jumped,over,the,lazy,dog}
3483 (1 row)
3484
3485 SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
3486  foo
3487 -----
3488  t
3489  h
3490  e
3491  q
3492  u
3493  i
3494  c
3495  k
3496  b
3497  r
3498  o
3499  w
3500  n
3501  f
3502  o
3503  x
3504 (16 rows)
3505 </programlisting>
3506    </para>
3507
3508    <para>
3509     As the last example demonstrates, the regexp split functions ignore
3510     zero-length matches that occur at the start or end of the string
3511     or immediately after a previous match.  This is contrary to the strict
3512     definition of regexp matching that is implemented by
3513     <function>regexp_matches</>, but is usually the most convenient behavior
3514     in practice.  Other software systems such as Perl use similar definitions.
3515    </para>
3516
3517 <!-- derived from the re_syntax.n man page -->
3518
3519    <sect3 id="posix-syntax-details">
3520     <title>Regular Expression Details</title>
3521
3522    <para>
3523     <productname>PostgreSQL</productname>'s regular expressions are implemented
3524     using a software package written by Henry Spencer.  Much of
3525     the description of regular expressions below is copied verbatim from his
3526     manual.
3527    </para>
3528
3529    <para>
3530     Regular expressions (<acronym>RE</acronym>s), as defined in
3531     <acronym>POSIX</acronym> 1003.2, come in two forms:
3532     <firstterm>extended</> <acronym>RE</acronym>s or <acronym>ERE</>s
3533     (roughly those of <command>egrep</command>), and
3534     <firstterm>basic</> <acronym>RE</acronym>s or <acronym>BRE</>s
3535     (roughly those of <command>ed</command>).
3536     <productname>PostgreSQL</productname> supports both forms, and
3537     also implements some extensions
3538     that are not in the POSIX standard, but have become widely used
3539     due to their availability in programming languages such as Perl and Tcl.
3540     <acronym>RE</acronym>s using these non-POSIX extensions are called
3541     <firstterm>advanced</> <acronym>RE</acronym>s or <acronym>ARE</>s
3542     in this documentation.  AREs are almost an exact superset of EREs,
3543     but BREs have several notational incompatibilities (as well as being
3544     much more limited).
3545     We first describe the ARE and ERE forms, noting features that apply
3546     only to AREs, and then describe how BREs differ.
3547    </para>
3548
3549    <note>
3550     <para>
3551      The form of regular expressions accepted by
3552      <productname>PostgreSQL</> can be chosen by setting the <xref
3553      linkend="guc-regex-flavor"> run-time parameter.  The usual
3554      setting is <literal>advanced</>, but one might choose
3555      <literal>extended</> for backwards compatibility with
3556      pre-7.4 releases of <productname>PostgreSQL</>.
3557     </para>
3558    </note>
3559
3560    <para>
3561     A regular expression is defined as one or more
3562     <firstterm>branches</firstterm>, separated by
3563     <literal>|</literal>.  It matches anything that matches one of the
3564     branches.
3565    </para>
3566
3567    <para>
3568     A branch is zero or more <firstterm>quantified atoms</> or
3569     <firstterm>constraints</>, concatenated.
3570     It matches a match for the first, followed by a match for the second, etc;
3571     an empty branch matches the empty string.
3572    </para>
3573
3574    <para>
3575     A quantified atom is an <firstterm>atom</> possibly followed
3576     by a single <firstterm>quantifier</>.
3577     Without a quantifier, it matches a match for the atom.
3578     With a quantifier, it can match some number of matches of the atom.
3579     An <firstterm>atom</firstterm> can be any of the possibilities
3580     shown in <xref linkend="posix-atoms-table">.
3581     The possible quantifiers and their meanings are shown in
3582     <xref linkend="posix-quantifiers-table">.
3583    </para>
3584
3585    <para>
3586     A <firstterm>constraint</> matches an empty string, but matches only when
3587     specific conditions are met.  A constraint can be used where an atom
3588     could be used, except it cannot be followed by a quantifier.
3589     The simple constraints are shown in
3590     <xref linkend="posix-constraints-table">;
3591     some more constraints are described later.
3592    </para>
3593
3594
3595    <table id="posix-atoms-table">
3596     <title>Regular Expression Atoms</title>
3597
3598     <tgroup cols="2">
3599      <thead>
3600       <row>
3601        <entry>Atom</entry>
3602        <entry>Description</entry>
3603       </row>
3604      </thead>
3605
3606       <tbody>
3607        <row>
3608        <entry> <literal>(</><replaceable>re</><literal>)</> </entry>
3609        <entry> (where <replaceable>re</> is any regular expression)
3610        matches a match for
3611        <replaceable>re</>, with the match noted for possible reporting </entry>
3612        </row>
3613
3614        <row>
3615        <entry> <literal>(?:</><replaceable>re</><literal>)</> </entry>
3616        <entry> as above, but the match is not noted for reporting
3617        (a <quote>non-capturing</> set of parentheses)
3618        (AREs only) </entry>
3619        </row>
3620
3621        <row>
3622        <entry> <literal>.</> </entry>
3623        <entry> matches any single character </entry>
3624        </row>
3625
3626        <row>
3627        <entry> <literal>[</><replaceable>chars</><literal>]</> </entry>
3628        <entry> a <firstterm>bracket expression</>,
3629        matching any one of the <replaceable>chars</> (see
3630        <xref linkend="posix-bracket-expressions"> for more detail) </entry>
3631        </row>
3632
3633        <row>
3634        <entry> <literal>\</><replaceable>k</> </entry>
3635        <entry> (where <replaceable>k</> is a non-alphanumeric character)
3636        matches that character taken as an ordinary character,
3637        e.g., <literal>\\</> matches a backslash character </entry>
3638        </row>
3639
3640        <row>
3641        <entry> <literal>\</><replaceable>c</> </entry>
3642        <entry> where <replaceable>c</> is alphanumeric
3643        (possibly followed by other characters)
3644        is an <firstterm>escape</>, see <xref linkend="posix-escape-sequences">
3645        (AREs only; in EREs and BREs, this matches <replaceable>c</>) </entry>
3646        </row>
3647
3648        <row>
3649        <entry> <literal>{</> </entry>
3650        <entry> when followed by a character other than a digit,
3651        matches the left-brace character <literal>{</>;
3652        when followed by a digit, it is the beginning of a
3653        <replaceable>bound</> (see below) </entry>
3654        </row>
3655
3656        <row>
3657        <entry> <replaceable>x</> </entry>
3658        <entry> where <replaceable>x</> is a single character with no other
3659        significance, matches that character </entry>
3660        </row>
3661       </tbody>
3662      </tgroup>
3663     </table>
3664
3665    <para>
3666     An RE cannot end with <literal>\</>.
3667    </para>
3668
3669    <note>
3670     <para>
3671      Remember that the backslash (<literal>\</literal>) already has a special
3672      meaning in <productname>PostgreSQL</> string literals.
3673      To write a pattern constant that contains a backslash,
3674      you must write two backslashes in the statement, assuming escape
3675      string syntax is used (see <xref linkend="sql-syntax-strings">).
3676     </para>
3677    </note>
3678
3679    <table id="posix-quantifiers-table">
3680     <title>Regular Expression Quantifiers</title>
3681
3682     <tgroup cols="2">
3683      <thead>
3684       <row>
3685        <entry>Quantifier</entry>
3686        <entry>Matches</entry>
3687       </row>
3688      </thead>
3689
3690       <tbody>
3691        <row>
3692        <entry> <literal>*</> </entry>
3693        <entry> a sequence of 0 or more matches of the atom </entry>
3694        </row>
3695
3696        <row>
3697        <entry> <literal>+</> </entry>
3698        <entry> a sequence of 1 or more matches of the atom </entry>
3699        </row>
3700
3701        <row>
3702        <entry> <literal>?</> </entry>
3703        <entry> a sequence of 0 or 1 matches of the atom </entry>
3704        </row>
3705
3706        <row>
3707        <entry> <literal>{</><replaceable>m</><literal>}</> </entry>
3708        <entry> a sequence of exactly <replaceable>m</> matches of the atom </entry>
3709        </row>
3710
3711        <row>
3712        <entry> <literal>{</><replaceable>m</><literal>,}</> </entry>
3713        <entry> a sequence of <replaceable>m</> or more matches of the atom </entry>
3714        </row>
3715
3716        <row>
3717        <entry>
3718        <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}</> </entry>
3719        <entry> a sequence of <replaceable>m</> through <replaceable>n</>
3720        (inclusive) matches of the atom; <replaceable>m</> cannot exceed
3721        <replaceable>n</> </entry>
3722        </row>
3723
3724        <row>
3725        <entry> <literal>*?</> </entry>
3726        <entry> non-greedy version of <literal>*</> </entry>
3727        </row>
3728
3729        <row>
3730        <entry> <literal>+?</> </entry>
3731        <entry> non-greedy version of <literal>+</> </entry>
3732        </row>
3733
3734        <row>
3735        <entry> <literal>??</> </entry>
3736        <entry> non-greedy version of <literal>?</> </entry>
3737        </row>
3738
3739        <row>
3740        <entry> <literal>{</><replaceable>m</><literal>}?</> </entry>
3741        <entry> non-greedy version of <literal>{</><replaceable>m</><literal>}</> </entry>
3742        </row>
3743
3744        <row>
3745        <entry> <literal>{</><replaceable>m</><literal>,}?</> </entry>
3746        <entry> non-greedy version of <literal>{</><replaceable>m</><literal>,}</> </entry>
3747        </row>
3748
3749        <row>
3750        <entry>
3751        <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}?</> </entry>
3752        <entry> non-greedy version of <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}</> </entry>
3753        </row>
3754       </tbody>
3755      </tgroup>
3756     </table>
3757
3758    <para>
3759     The forms using <literal>{</><replaceable>...</><literal>}</>
3760     are known as <firstterm>bounds</>.
3761     The numbers <replaceable>m</> and <replaceable>n</> within a bound are
3762     unsigned decimal integers with permissible values from 0 to 255 inclusive.
3763    </para>
3764
3765     <para>
3766      <firstterm>Non-greedy</> quantifiers (available in AREs only) match the
3767      same possibilities as their corresponding normal (<firstterm>greedy</>)
3768      counterparts, but prefer the smallest number rather than the largest
3769      number of matches.
3770      See <xref linkend="posix-matching-rules"> for more detail.
3771    </para>
3772
3773    <note>
3774     <para>
3775      A quantifier cannot immediately follow another quantifier, e.g.,
3776      <literal>**</> is invalid.
3777      A quantifier cannot
3778      begin an expression or subexpression or follow
3779      <literal>^</literal> or <literal>|</literal>.
3780     </para>
3781    </note>
3782
3783    <table id="posix-constraints-table">
3784     <title>Regular Expression Constraints</title>
3785
3786     <tgroup cols="2">
3787      <thead>
3788       <row>
3789        <entry>Constraint</entry>
3790        <entry>Description</entry>
3791       </row>
3792      </thead>
3793
3794       <tbody>
3795        <row>
3796        <entry> <literal>^</> </entry>
3797        <entry> matches at the beginning of the string </entry>
3798        </row>
3799
3800        <row>
3801        <entry> <literal>$</> </entry>
3802        <entry> matches at the end of the string </entry>
3803        </row>
3804
3805        <row>
3806        <entry> <literal>(?=</><replaceable>re</><literal>)</> </entry>
3807        <entry> <firstterm>positive lookahead</> matches at any point
3808        where a substring matching <replaceable>re</> begins
3809        (AREs only) </entry>
3810        </row>
3811
3812        <row>
3813        <entry> <literal>(?!</><replaceable>re</><literal>)</> </entry>
3814        <entry> <firstterm>negative lookahead</> matches at any point
3815        where no substring matching <replaceable>re</> begins
3816        (AREs only) </entry>
3817        </row>
3818       </tbody>
3819      </tgroup>
3820     </table>
3821
3822    <para>
3823     Lookahead constraints cannot contain <firstterm>back references</>
3824     (see <xref linkend="posix-escape-sequences">),
3825     and all parentheses within them are considered non-capturing.
3826    </para>
3827    </sect3>
3828
3829    <sect3 id="posix-bracket-expressions">
3830     <title>Bracket Expressions</title>
3831
3832    <para>
3833     A <firstterm>bracket expression</firstterm> is a list of
3834     characters enclosed in <literal>[]</literal>.  It normally matches
3835     any single character from the list (but see below).  If the list
3836     begins with <literal>^</literal>, it matches any single character
3837     <emphasis>not</> from the rest of the list.
3838     If two characters
3839     in the list are separated by <literal>-</literal>, this is
3840     shorthand for the full range of characters between those two
3841     (inclusive) in the collating sequence,
3842     e.g., <literal>[0-9]</literal> in <acronym>ASCII</acronym> matches
3843     any decimal digit.  It is illegal for two ranges to share an
3844     endpoint, e.g.,  <literal>a-c-e</literal>.  Ranges are very
3845     collating-sequence-dependent, so portable programs should avoid
3846     relying on them.
3847    </para>
3848
3849    <para>
3850     To include a literal <literal>]</literal> in the list, make it the
3851     first character (after <literal>^</literal>, if that is used).  To
3852     include a literal <literal>-</literal>, make it the first or last
3853     character, or the second endpoint of a range.  To use a literal
3854     <literal>-</literal> as the first endpoint of a range, enclose it
3855     in <literal>[.</literal> and <literal>.]</literal> to make it a
3856     collating element (see below).  With the exception of these characters,
3857     some combinations using <literal>[</literal>
3858     (see next paragraphs), and escapes (AREs only), all other special
3859     characters lose their special significance within a bracket expression.
3860     In particular, <literal>\</literal> is not special when following
3861     ERE or BRE rules, though it is special (as introducing an escape)
3862     in AREs.
3863    </para>
3864
3865    <para>
3866     Within a bracket expression, a collating element (a character, a
3867     multiple-character sequence that collates as if it were a single
3868     character, or a collating-sequence name for either) enclosed in
3869     <literal>[.</literal> and <literal>.]</literal> stands for the
3870     sequence of characters of that collating element.  The sequence is
3871     treated as a single element of the bracket expression's list.  This
3872     allows a bracket
3873     expression containing a multiple-character collating element to
3874     match more than one character, e.g., if the collating sequence
3875     includes a <literal>ch</literal> collating element, then the RE
3876     <literal>[[.ch.]]*c</literal> matches the first five characters of
3877     <literal>chchcc</literal>.
3878    </para>
3879
3880    <note>
3881     <para>
3882      <productname>PostgreSQL</> currently does not support multi-character collating
3883      elements. This information describes possible future behavior.
3884     </para>
3885    </note>
3886
3887    <para>
3888     Within a bracket expression, a collating element enclosed in
3889     <literal>[=</literal> and <literal>=]</literal> is an <firstterm>equivalence
3890     class</>, standing for the sequences of characters of all collating
3891     elements equivalent to that one, including itself.  (If there are
3892     no other equivalent collating elements, the treatment is as if the
3893     enclosing delimiters were <literal>[.</literal> and
3894     <literal>.]</literal>.)  For example, if <literal>o</literal> and
3895     <literal>^</literal> are the members of an equivalence class, then
3896     <literal>[[=o=]]</literal>, <literal>[[=^=]]</literal>, and
3897     <literal>[o^]</literal> are all synonymous.  An equivalence class
3898     cannot be an endpoint of a range.
3899    </para>
3900
3901    <para>
3902     Within a bracket expression, the name of a character class
3903     enclosed in <literal>[:</literal> and <literal>:]</literal> stands
3904     for the list of all characters belonging to that class.  Standard
3905     character class names are: <literal>alnum</literal>,
3906     <literal>alpha</literal>, <literal>blank</literal>,
3907     <literal>cntrl</literal>, <literal>digit</literal>,
3908     <literal>graph</literal>, <literal>lower</literal>,
3909     <literal>print</literal>, <literal>punct</literal>,
3910     <literal>space</literal>, <literal>upper</literal>,
3911     <literal>xdigit</literal>.  These stand for the character classes
3912     defined in
3913     <citerefentry><refentrytitle>ctype</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
3914     A locale can provide others.  A character class cannot be used as
3915     an endpoint of a range.
3916    </para>
3917
3918    <para>
3919     There are two special cases of bracket expressions:  the bracket
3920     expressions <literal>[[:&lt;:]]</literal> and
3921     <literal>[[:&gt;:]]</literal> are constraints,
3922     matching empty strings at the beginning
3923     and end of a word respectively.  A word is defined as a sequence
3924     of word characters that is neither preceded nor followed by word
3925     characters.  A word character is an <literal>alnum</> character (as
3926     defined by
3927     <citerefentry><refentrytitle>ctype</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
3928     or an underscore.  This is an extension, compatible with but not
3929     specified by <acronym>POSIX</acronym> 1003.2, and should be used with
3930     caution in software intended to be portable to other systems.
3931     The constraint escapes described below are usually preferable; they
3932     are no more standard, but are easier to type.
3933    </para>
3934    </sect3>
3935
3936    <sect3 id="posix-escape-sequences">
3937     <title>Regular Expression Escapes</title>
3938
3939    <para>
3940     <firstterm>Escapes</> are special sequences beginning with <literal>\</>
3941     followed by an alphanumeric character. Escapes come in several varieties:
3942     character entry, class shorthands, constraint escapes, and back references.
3943     A <literal>\</> followed by an alphanumeric character but not constituting
3944     a valid escape is illegal in AREs.
3945     In EREs, there are no escapes: outside a bracket expression,
3946     a <literal>\</> followed by an alphanumeric character merely stands for
3947     that character as an ordinary character, and inside a bracket expression,
3948     <literal>\</> is an ordinary character.
3949     (The latter is the one actual incompatibility between EREs and AREs.)
3950    </para>
3951
3952    <para>
3953     <firstterm>Character-entry escapes</> exist to make it easier to specify
3954     non-printing and other inconvenient characters in REs.  They are
3955     shown in <xref linkend="posix-character-entry-escapes-table">.
3956    </para>
3957
3958    <para>
3959     <firstterm>Class-shorthand escapes</> provide shorthands for certain
3960     commonly-used character classes.  They are
3961     shown in <xref linkend="posix-class-shorthand-escapes-table">.
3962    </para>
3963
3964    <para>
3965     A <firstterm>constraint escape</> is a constraint,
3966     matching the empty string if specific conditions are met,
3967     written as an escape.  They are
3968     shown in <xref linkend="posix-constraint-escapes-table">.
3969    </para>
3970
3971    <para>
3972     A <firstterm>back reference</> (<literal>\</><replaceable>n</>) matches the
3973     same string matched by the previous parenthesized subexpression specified
3974     by the number <replaceable>n</>
3975     (see <xref linkend="posix-constraint-backref-table">).  For example,
3976     <literal>([bc])\1</> matches <literal>bb</> or <literal>cc</>
3977     but not <literal>bc</> or <literal>cb</>.
3978     The subexpression must entirely precede the back reference in the RE.
3979     Subexpressions are numbered in the order of their leading parentheses.
3980     Non-capturing parentheses do not define subexpressions.
3981    </para>
3982
3983    <note>
3984     <para>
3985      Keep in mind that an escape's leading <literal>\</> will need to be
3986      doubled when entering the pattern as an SQL string constant.  For example:
3987 <programlisting>
3988 '123' ~ E'^\\d{3}' <lineannotation>true</lineannotation>
3989 </programlisting>
3990     </para>
3991    </note>
3992
3993    <table id="posix-character-entry-escapes-table">
3994     <title>Regular Expression Character-Entry Escapes</title>
3995
3996     <tgroup cols="2">
3997      <thead>
3998       <row>
3999        <entry>Escape</entry>
4000        <entry>Description</entry>
4001       </row>
4002      </thead>
4003
4004       <tbody>
4005        <row>
4006        <entry> <literal>\a</> </entry>
4007        <entry> alert (bell) character, as in C </entry>
4008        </row>
4009
4010        <row>
4011        <entry> <literal>\b</> </entry>
4012        <entry> backspace, as in C </entry>
4013        </row>
4014
4015        <row>
4016        <entry> <literal>\B</> </entry>
4017        <entry> synonym for backslash (<literal>\</>) to help reduce the need for backslash
4018        doubling </entry>
4019        </row>
4020
4021        <row>
4022        <entry> <literal>\c</><replaceable>X</> </entry>
4023        <entry> (where <replaceable>X</> is any character) the character whose
4024        low-order 5 bits are the same as those of
4025        <replaceable>X</>, and whose other bits are all zero </entry>
4026        </row>
4027
4028        <row>
4029        <entry> <literal>\e</> </entry>
4030        <entry> the character whose collating-sequence name
4031        is <literal>ESC</>,
4032        or failing that, the character with octal value 033 </entry>
4033        </row>
4034
4035        <row>
4036        <entry> <literal>\f</> </entry>
4037        <entry> form feed, as in C </entry>
4038        </row>
4039
4040        <row>
4041        <entry> <literal>\n</> </entry>
4042        <entry> newline, as in C </entry>
4043        </row>
4044
4045        <row>
4046        <entry> <literal>\r</> </entry>
4047        <entry> carriage return, as in C </entry>
4048        </row>
4049
4050        <row>
4051        <entry> <literal>\t</> </entry>
4052        <entry> horizontal tab, as in C </entry>
4053        </row>
4054
4055        <row>
4056        <entry> <literal>\u</><replaceable>wxyz</> </entry>
4057        <entry> (where <replaceable>wxyz</> is exactly four hexadecimal digits)
4058        the UTF16 (Unicode, 16-bit) character <literal>U+</><replaceable>wxyz</>
4059        in the local byte ordering </entry>
4060        </row>
4061
4062        <row>
4063        <entry> <literal>\U</><replaceable>stuvwxyz</> </entry>
4064        <entry> (where <replaceable>stuvwxyz</> is exactly eight hexadecimal
4065        digits)
4066        reserved for a hypothetical Unicode extension to 32 bits
4067        </entry>
4068        </row>
4069
4070        <row>
4071        <entry> <literal>\v</> </entry>
4072        <entry> vertical tab, as in C </entry>
4073        </row>
4074
4075        <row>
4076        <entry> <literal>\x</><replaceable>hhh</> </entry>
4077        <entry> (where <replaceable>hhh</> is any sequence of hexadecimal
4078        digits)
4079        the character whose hexadecimal value is
4080        <literal>0x</><replaceable>hhh</>
4081        (a single character no matter how many hexadecimal digits are used)
4082        </entry>
4083        </row>
4084
4085        <row>
4086        <entry> <literal>\0</> </entry>
4087        <entry> the character whose value is <literal>0</> (the null byte)</entry>
4088        </row>
4089
4090        <row>
4091        <entry> <literal>\</><replaceable>xy</> </entry>
4092        <entry> (where <replaceable>xy</> is exactly two octal digits,
4093        and is not a <firstterm>back reference</>)
4094        the character whose octal value is
4095        <literal>0</><replaceable>xy</> </entry>
4096        </row>
4097
4098        <row>
4099        <entry> <literal>\</><replaceable>xyz</> </entry>
4100        <entry> (where <replaceable>xyz</> is exactly three octal digits,
4101        and is not a <firstterm>back reference</>)
4102        the character whose octal value is
4103        <literal>0</><replaceable>xyz</> </entry>
4104        </row>
4105       </tbody>
4106      </tgroup>
4107     </table>
4108
4109    <para>
4110     Hexadecimal digits are <literal>0</>-<literal>9</>,
4111     <literal>a</>-<literal>f</>, and <literal>A</>-<literal>F</>.
4112     Octal digits are <literal>0</>-<literal>7</>.
4113    </para>
4114
4115    <para>
4116     The character-entry escapes are always taken as ordinary characters.
4117     For example, <literal>\135</> is <literal>]</> in ASCII, but
4118     <literal>\135</> does not terminate a bracket expression.
4119    </para>
4120
4121    <table id="posix-class-shorthand-escapes-table">
4122     <title>Regular Expression Class-Shorthand Escapes</title>
4123
4124     <tgroup cols="2">
4125      <thead>
4126       <row>
4127        <entry>Escape</entry>
4128        <entry>Description</entry>
4129       </row>
4130      </thead>
4131
4132       <tbody>
4133        <row>
4134        <entry> <literal>\d</> </entry>
4135        <entry> <literal>[[:digit:]]</> </entry>
4136        </row>
4137
4138        <row>
4139        <entry> <literal>\s</> </entry>
4140        <entry> <literal>[[:space:]]</> </entry>
4141        </row>
4142
4143        <row>
4144        <entry> <literal>\w</> </entry>
4145        <entry> <literal>[[:alnum:]_]</>
4146        (note underscore is included) </entry>
4147        </row>
4148
4149        <row>
4150        <entry> <literal>\D</> </entry>
4151        <entry> <literal>[^[:digit:]]</> </entry>
4152        </row>
4153
4154        <row>
4155        <entry> <literal>\S</> </entry>
4156        <entry> <literal>[^[:space:]]</> </entry>
4157        </row>
4158
4159        <row>
4160        <entry> <literal>\W</> </entry>
4161        <entry> <literal>[^[:alnum:]_]</>
4162        (note underscore is included) </entry>
4163        </row>
4164       </tbody>
4165      </tgroup>
4166     </table>
4167
4168    <para>
4169     Within bracket expressions, <literal>\d</>, <literal>\s</>,
4170     and <literal>\w</> lose their outer brackets,
4171     and <literal>\D</>, <literal>\S</>, and <literal>\W</> are illegal.
4172     (So, for example, <literal>[a-c\d]</> is equivalent to
4173     <literal>[a-c[:digit:]]</>.
4174     Also, <literal>[a-c\D]</>, which is equivalent to
4175     <literal>[a-c^[:digit:]]</>, is illegal.)
4176    </para>
4177
4178    <table id="posix-constraint-escapes-table">
4179     <title>Regular Expression Constraint Escapes</title>
4180
4181     <tgroup cols="2">
4182      <thead>
4183       <row>
4184        <entry>Escape</entry>
4185        <entry>Description</entry>
4186       </row>
4187      </thead>
4188
4189       <tbody>
4190        <row>
4191        <entry> <literal>\A</> </entry>
4192        <entry> matches only at the beginning of the string
4193        (see <xref linkend="posix-matching-rules"> for how this differs from
4194        <literal>^</>) </entry>
4195        </row>
4196
4197        <row>
4198        <entry> <literal>\m</> </entry>
4199        <entry> matches only at the beginning of a word </entry>
4200        </row>
4201
4202        <row>
4203        <entry> <literal>\M</> </entry>
4204        <entry> matches only at the end of a word </entry>
4205        </row>
4206
4207        <row>
4208        <entry> <literal>\y</> </entry>
4209        <entry> matches only at the beginning or end of a word </entry>
4210        </row>
4211
4212        <row>
4213        <entry> <literal>\Y</> </entry>
4214        <entry> matches only at a point that is not the beginning or end of a
4215        word </entry>
4216        </row>
4217
4218        <row>
4219        <entry> <literal>\Z</> </entry>
4220        <entry> matches only at the end of the string
4221        (see <xref linkend="posix-matching-rules"> for how this differs from
4222        <literal>$</>) </entry>
4223        </row>
4224       </tbody>
4225      </tgroup>
4226     </table>
4227
4228    <para>
4229     A word is defined as in the specification of
4230     <literal>[[:&lt;:]]</> and <literal>[[:&gt;:]]</> above.
4231     Constraint escapes are illegal within bracket expressions.
4232    </para>
4233
4234    <table id="posix-constraint-backref-table">
4235     <title>Regular Expression Back References</title>
4236
4237     <tgroup cols="2">
4238      <thead>
4239       <row>
4240        <entry>Escape</entry>
4241        <entry>Description</entry>
4242       </row>
4243      </thead>
4244
4245       <tbody>
4246        <row>
4247        <entry> <literal>\</><replaceable>m</> </entry>
4248        <entry> (where <replaceable>m</> is a nonzero digit)
4249        a back reference to the <replaceable>m</>'th subexpression </entry>
4250        </row>
4251
4252        <row>
4253        <entry> <literal>\</><replaceable>mnn</> </entry>
4254        <entry> (where <replaceable>m</> is a nonzero digit, and
4255        <replaceable>nn</> is some more digits, and the decimal value
4256        <replaceable>mnn</> is not greater than the number of closing capturing
4257        parentheses seen so far)
4258        a back reference to the <replaceable>mnn</>'th subexpression </entry>
4259        </row>
4260       </tbody>
4261      </tgroup>
4262     </table>
4263
4264    <note>
4265     <para>
4266      There is an inherent ambiguity between octal character-entry
4267      escapes and back references, which is resolved by the following heuristics,
4268      as hinted at above.
4269      A leading zero always indicates an octal escape.
4270      A single non-zero digit, not followed by another digit,
4271      is always taken as a back reference.
4272      A multi-digit sequence not starting with a zero is taken as a back
4273      reference if it comes after a suitable subexpression
4274      (i.e., the number is in the legal range for a back reference),
4275      and otherwise is taken as octal.
4276     </para>
4277    </note>
4278    </sect3>
4279
4280    <sect3 id="posix-metasyntax">
4281     <title>Regular Expression Metasyntax</title>
4282
4283    <para>
4284     In addition to the main syntax described above, there are some special
4285     forms and miscellaneous syntactic facilities available.
4286    </para>
4287
4288    <para>
4289     Normally the flavor of RE being used is determined by
4290     <varname>regex_flavor</>.
4291     However, this can be overridden by a <firstterm>director</> prefix.
4292     If an RE begins with <literal>***:</>,
4293     the rest of the RE is taken as an ARE regardless of
4294     <varname>regex_flavor</>.
4295     If an RE begins with <literal>***=</>,
4296     the rest of the RE is taken to be a literal string,
4297     with all characters considered ordinary characters.
4298    </para>
4299
4300    <para>
4301     An ARE can begin with <firstterm>embedded options</>:
4302     a sequence <literal>(?</><replaceable>xyz</><literal>)</>
4303     (where <replaceable>xyz</> is one or more alphabetic characters)
4304     specifies options affecting the rest of the RE.
4305     These options override any previously determined options (including
4306     both the RE flavor and case sensitivity).
4307     The available option letters are
4308     shown in <xref linkend="posix-embedded-options-table">.
4309    </para>
4310
4311    <table id="posix-embedded-options-table">
4312     <title>ARE Embedded-Option Letters</title>
4313
4314     <tgroup cols="2">
4315      <thead>
4316       <row>
4317        <entry>Option</entry>
4318        <entry>Description</entry>
4319       </row>
4320      </thead>
4321
4322       <tbody>
4323        <row>
4324        <entry> <literal>b</> </entry>
4325        <entry> rest of RE is a BRE </entry>
4326        </row>
4327
4328        <row>
4329        <entry> <literal>c</> </entry>
4330        <entry> case-sensitive matching (overrides operator type) </entry>
4331        </row>
4332
4333        <row>
4334        <entry> <literal>e</> </entry>
4335        <entry> rest of RE is an ERE </entry>
4336        </row>
4337
4338        <row>
4339        <entry> <literal>i</> </entry>
4340        <entry> case-insensitive matching (see
4341        <xref linkend="posix-matching-rules">) (overrides operator type) </entry>
4342        </row>
4343
4344        <row>
4345        <entry> <literal>m</> </entry>
4346        <entry> historical synonym for <literal>n</> </entry>
4347        </row>
4348
4349        <row>
4350        <entry> <literal>n</> </entry>
4351        <entry> newline-sensitive matching (see
4352        <xref linkend="posix-matching-rules">) </entry>
4353        </row>
4354
4355        <row>
4356        <entry> <literal>p</> </entry>
4357        <entry> partial newline-sensitive matching (see
4358        <xref linkend="posix-matching-rules">) </entry>
4359        </row>
4360
4361        <row>
4362        <entry> <literal>q</> </entry>
4363        <entry> rest of RE is a literal (<quote>quoted</>) string, all ordinary
4364        characters </entry>
4365        </row>
4366
4367        <row>
4368        <entry> <literal>s</> </entry>
4369        <entry> non-newline-sensitive matching (default) </entry>
4370        </row>
4371
4372        <row>
4373        <entry> <literal>t</> </entry>
4374        <entry> tight syntax (default; see below) </entry>
4375        </row>
4376
4377        <row>
4378        <entry> <literal>w</> </entry>
4379        <entry> inverse partial newline-sensitive (<quote>weird</>) matching
4380        (see <xref linkend="posix-matching-rules">) </entry>
4381        </row>
4382
4383        <row>
4384        <entry> <literal>x</> </entry>
4385        <entry> expanded syntax (see below) </entry>
4386        </row>
4387       </tbody>
4388      </tgroup>
4389     </table>
4390
4391    <para>
4392     Embedded options take effect at the <literal>)</> terminating the sequence.
4393     They can appear only at the start of an ARE (after the
4394     <literal>***:</> director if any).
4395    </para>
4396
4397    <para>
4398     In addition to the usual (<firstterm>tight</>) RE syntax, in which all
4399     characters are significant, there is an <firstterm>expanded</> syntax,
4400     available by specifying the embedded <literal>x</> option.
4401     In the expanded syntax,
4402     white-space characters in the RE are ignored, as are
4403     all characters between a <literal>#</>
4404     and the following newline (or the end of the RE).  This
4405     permits paragraphing and commenting a complex RE.
4406     There are three exceptions to that basic rule:
4407
4408     <itemizedlist>
4409      <listitem>
4410       <para>
4411        a white-space character or <literal>#</> preceded by <literal>\</> is
4412        retained
4413       </para>
4414      </listitem>
4415      <listitem>
4416       <para>
4417        white space or <literal>#</> within a bracket expression is retained
4418       </para>
4419      </listitem>
4420      <listitem>
4421       <para>
4422        white space and comments cannot appear within multi-character symbols,
4423        such as <literal>(?:</>
4424       </para>
4425      </listitem>
4426     </itemizedlist>
4427
4428     For this purpose, white-space characters are blank, tab, newline, and
4429     any character that belongs to the <replaceable>space</> character class.
4430    </para>
4431
4432    <para>
4433     Finally, in an ARE, outside bracket expressions, the sequence
4434     <literal>(?#</><replaceable>ttt</><literal>)</>
4435     (where <replaceable>ttt</> is any text not containing a <literal>)</>)
4436     is a comment, completely ignored.
4437     Again, this is not allowed between the characters of
4438     multi-character symbols, like <literal>(?:</>.
4439     Such comments are more a historical artifact than a useful facility,
4440     and their use is deprecated; use the expanded syntax instead.
4441    </para>
4442
4443    <para>
4444     <emphasis>None</> of these metasyntax extensions is available if
4445     an initial <literal>***=</> director
4446     has specified that the user's input be treated as a literal string
4447     rather than as an RE.
4448    </para>
4449    </sect3>
4450
4451    <sect3 id="posix-matching-rules">
4452     <title>Regular Expression Matching Rules</title>
4453
4454    <para>
4455     In the event that an RE could match more than one substring of a given
4456     string, the RE matches the one starting earliest in the string.
4457     If the RE could match more than one substring starting at that point,
4458     either the longest possible match or the shortest possible match will
4459     be taken, depending on whether the RE is <firstterm>greedy</> or
4460     <firstterm>non-greedy</>.
4461    </para>
4462
4463    <para>
4464     Whether an RE is greedy or not is determined by the following rules:
4465     <itemizedlist>
4466      <listitem>
4467       <para>
4468        Most atoms, and all constraints, have no greediness attribute (because
4469        they cannot match variable amounts of text anyway).
4470       </para>
4471      </listitem>
4472      <listitem>
4473       <para>
4474        Adding parentheses around an RE does not change its greediness.
4475       </para>
4476      </listitem>
4477      <listitem>
4478       <para>
4479        A quantified atom with a fixed-repetition quantifier
4480        (<literal>{</><replaceable>m</><literal>}</>
4481        or
4482        <literal>{</><replaceable>m</><literal>}?</>)
4483        has the same greediness (possibly none) as the atom itself.
4484       </para>
4485      </listitem>
4486      <listitem>
4487       <para>
4488        A quantified atom with other normal quantifiers (including
4489        <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}</>
4490        with <replaceable>m</> equal to <replaceable>n</>)
4491        is greedy (prefers longest match).
4492       </para>
4493      </listitem>
4494      <listitem>
4495       <para>
4496        A quantified atom with a non-greedy quantifier (including
4497        <literal>{</><replaceable>m</><literal>,</><replaceable>n</><literal>}?</>
4498        with <replaceable>m</> equal to <replaceable>n</>)
4499        is non-greedy (prefers shortest match).
4500       </para>
4501      </listitem>
4502      <listitem>
4503       <para>
4504        A branch &mdash; that is, an RE that has no top-level
4505        <literal>|</> operator &mdash; has the same greediness as the first
4506        quantified atom in it that has a greediness attribute.
4507       </para>
4508      </listitem>
4509      <listitem>
4510       <para>
4511        An RE consisting of two or more branches connected by the
4512        <literal>|</> operator is always greedy.
4513       </para>
4514      </listitem>
4515     </itemizedlist>
4516    </para>
4517
4518    <para>
4519     The above rules associate greediness attributes not only with individual
4520     quantified atoms, but with branches and entire REs that contain quantified
4521     atoms.  What that means is that the matching is done in such a way that
4522     the branch, or whole RE, matches the longest or shortest possible
4523     substring <emphasis>as a whole</>.  Once the length of the entire match
4524     is determined, the part of it that matches any particular subexpression
4525     is determined on the basis of the greediness attribute of that
4526     subexpression, with subexpressions starting earlier in the RE taking
4527     priority over ones starting later.
4528    </para>
4529
4530    <para>
4531     An example of what this means:
4532 <screen>
4533 SELECT SUBSTRING('XY1234Z', 'Y*([0-9]{1,3})');
4534 <lineannotation>Result: </lineannotation><computeroutput>123</computeroutput>
4535 SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
4536 <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput>
4537 </screen>
4538     In the first case, the RE as a whole is greedy because <literal>Y*</>
4539     is greedy.  It can match beginning at the <literal>Y</>, and it matches
4540     the longest possible string starting there, i.e., <literal>Y123</>.
4541     The output is the parenthesized part of that, or <literal>123</>.
4542     In the second case, the RE as a whole is non-greedy because <literal>Y*?</>
4543     is non-greedy.  It can match beginning at the <literal>Y</>, and it matches
4544     the shortest possible string starting there, i.e., <literal>Y1</>.
4545     The subexpression <literal>[0-9]{1,3}</> is greedy but it cannot change
4546     the decision as to the overall match length; so it is forced to match
4547     just <literal>1</>.
4548    </para>
4549
4550    <para>
4551     In short, when an RE contains both greedy and non-greedy subexpressions,
4552     the total match length is either as long as possible or as short as
4553     possible, according to the attribute assigned to the whole RE.  The
4554     attributes assigned to the subexpressions only affect how much of that
4555     match they are allowed to <quote>eat</> relative to each other.
4556    </para>
4557
4558    <para>
4559     The quantifiers <literal>{1,1}</> and <literal>{1,1}?</>
4560     can be used to force greediness or non-greediness, respectively,
4561     on a subexpression or a whole RE.
4562    </para>
4563
4564    <para>
4565     Match lengths are measured in characters, not collating elements.
4566     An empty string is considered longer than no match at all.
4567     For example:
4568     <literal>bb*</>
4569     matches the three middle characters of <literal>abbbc</>;
4570     <literal>(week|wee)(night|knights)</>
4571     matches all ten characters of <literal>weeknights</>;
4572     when <literal>(.*).*</>
4573     is matched against <literal>abc</> the parenthesized subexpression
4574     matches all three characters; and when
4575     <literal>(a*)*</> is matched against <literal>bc</>
4576     both the whole RE and the parenthesized
4577     subexpression match an empty string.
4578    </para>
4579
4580    <para>
4581     If case-independent matching is specified,
4582     the effect is much as if all case distinctions had vanished from the
4583     alphabet.
4584     When an alphabetic that exists in multiple cases appears as an
4585     ordinary character outside a bracket expression, it is effectively
4586     transformed into a bracket expression containing both cases,
4587     e.g., <literal>x</> becomes <literal>[xX]</>.
4588     When it appears inside a bracket expression, all case counterparts
4589     of it are added to the bracket expression, e.g.,
4590     <literal>[x]</> becomes <literal>[xX]</>
4591     and <literal>[^x]</> becomes <literal>[^xX]</>.
4592    </para>
4593
4594    <para>
4595     If newline-sensitive matching is specified, <literal>.</>
4596     and bracket expressions using <literal>^</>
4597     will never match the newline character
4598     (so that matches will never cross newlines unless the RE
4599     explicitly arranges it)
4600     and <literal>^</>and <literal>$</>
4601     will match the empty string after and before a newline
4602     respectively, in addition to matching at beginning and end of string
4603     respectively.
4604     But the ARE escapes <literal>\A</> and <literal>\Z</>
4605     continue to match beginning or end of string <emphasis>only</>.
4606    </para>
4607
4608    <para>
4609     If partial newline-sensitive matching is specified,
4610     this affects <literal>.</> and bracket expressions
4611     as with newline-sensitive matching, but not <literal>^</>
4612     and <literal>$</>.
4613    </para>
4614
4615    <para>
4616     If inverse partial newline-sensitive matching is specified,
4617     this affects <literal>^</> and <literal>$</>
4618     as with newline-sensitive matching, but not <literal>.</>
4619     and bracket expressions.
4620     This isn't very useful but is provided for symmetry.
4621    </para>
4622    </sect3>
4623
4624    <sect3 id="posix-limits-compatibility">
4625     <title>Limits and Compatibility</title>
4626
4627    <para>
4628     No particular limit is imposed on the length of REs in this
4629     implementation.  However,
4630     programs intended to be highly portable should not employ REs longer
4631     than 256 bytes,
4632     as a POSIX-compliant implementation can refuse to accept such REs.
4633    </para>
4634
4635    <para>
4636     The only feature of AREs that is actually incompatible with
4637     POSIX EREs is that <literal>\</> does not lose its special
4638     significance inside bracket expressions.
4639     All other ARE features use syntax which is illegal or has
4640     undefined or unspecified effects in POSIX EREs;
4641     the <literal>***</> syntax of directors likewise is outside the POSIX
4642     syntax for both BREs and EREs.
4643    </para>
4644
4645    <para>
4646     Many of the ARE extensions are borrowed from Perl, but some have
4647     been changed to clean them up, and a few Perl extensions are not present.
4648     Incompatibilities of note include <literal>\b</>, <literal>\B</>,
4649     the lack of special treatment for a trailing newline,
4650     the addition of complemented bracket expressions to the things
4651     affected by newline-sensitive matching,
4652     the restrictions on parentheses and back references in lookahead
4653     constraints, and the longest/shortest-match (rather than first-match)
4654     matching semantics.
4655    </para>
4656
4657    <para>
4658     Two significant incompatibilities exist between AREs and the ERE syntax
4659     recognized by pre-7.4 releases of <productname>PostgreSQL</>:
4660
4661     <itemizedlist>
4662      <listitem>
4663       <para>
4664        In AREs, <literal>\</> followed by an alphanumeric character is either
4665        an escape or an error, while in previous releases, it was just another
4666        way of writing the alphanumeric.
4667        This should not be much of a problem because there was no reason to
4668        write such a sequence in earlier releases.
4669       </para>
4670      </listitem>
4671      <listitem>
4672       <para>
4673        In AREs, <literal>\</> remains a special character within
4674        <literal>[]</>, so a literal <literal>\</> within a bracket
4675        expression must be written <literal>\\</>.
4676       </para>
4677      </listitem>
4678     </itemizedlist>
4679
4680     While these differences are unlikely to create a problem for most
4681     applications, you can avoid them if necessary by
4682     setting <varname>regex_flavor</> to <literal>extended</>.
4683    </para>
4684    </sect3>
4685
4686    <sect3 id="posix-basic-regexes">
4687     <title>Basic Regular Expressions</title>
4688
4689    <para>
4690     BREs differ from EREs in several respects.
4691     In BREs, <literal>|</>, <literal>+</>, and <literal>?</>
4692     are ordinary characters and there is no equivalent
4693     for their functionality.
4694     The delimiters for bounds are
4695     <literal>\{</> and <literal>\}</>,
4696     with <literal>{</> and <literal>}</>
4697     by themselves ordinary characters.
4698     The parentheses for nested subexpressions are
4699     <literal>\(</> and <literal>\)</>,
4700     with <literal>(</> and <literal>)</> by themselves ordinary characters.
4701     <literal>^</> is an ordinary character except at the beginning of the
4702     RE or the beginning of a parenthesized subexpression,
4703     <literal>$</> is an ordinary character except at the end of the
4704     RE or the end of a parenthesized subexpression,
4705     and <literal>*</> is an ordinary character if it appears at the beginning
4706     of the RE or the beginning of a parenthesized subexpression
4707     (after a possible leading <literal>^</>).
4708     Finally, single-digit back references are available, and
4709     <literal>\&lt;</> and <literal>\&gt;</>
4710     are synonyms for
4711     <literal>[[:&lt;:]]</> and <literal>[[:&gt;:]]</>
4712     respectively; no other escapes are available in BREs.
4713    </para>
4714    </sect3>
4715
4716 <!-- end re_syntax.n man page -->
4717
4718   </sect2>
4719  </sect1>
4720
4721
4722   <sect1 id="functions-formatting">
4723    <title>Data Type Formatting Functions</title>
4724
4725    <indexterm>
4726     <primary>formatting</primary>
4727    </indexterm>
4728
4729    <indexterm>
4730     <primary>to_char</primary>
4731    </indexterm>
4732    <indexterm>
4733     <primary>to_date</primary>
4734    </indexterm>
4735    <indexterm>
4736     <primary>to_number</primary>
4737    </indexterm>
4738    <indexterm>
4739     <primary>to_timestamp</primary>
4740    </indexterm>
4741
4742    <para>
4743     The <productname>PostgreSQL</productname> formatting functions
4744     provide a powerful set of tools for converting various data types
4745     (date/time, integer, floating point, numeric) to formatted strings
4746     and for converting from formatted strings to specific data types.
4747     <xref linkend="functions-formatting-table"> lists them.
4748     These functions all follow a common calling convention: the first
4749     argument is the value to be formatted and the second argument is a
4750     template that defines the output or input format.
4751    </para>
4752    <para>
4753     A single-argument <function>to_timestamp</function> function is also
4754     available;  it accepts a
4755     <type>double precision</type> argument and converts from Unix epoch
4756     (seconds since 1970-01-01 00:00:00+00) to
4757     <type>timestamp with time zone</type>.
4758     (<type>Integer</type> Unix epochs are implicitly cast to
4759     <type>double precision</type>.)
4760    </para>
4761
4762     <table id="functions-formatting-table">
4763      <title>Formatting Functions</title>
4764      <tgroup cols="4">
4765       <thead>
4766        <row>
4767         <entry>Function</entry>
4768         <entry>Return Type</entry>
4769         <entry>Description</entry>
4770         <entry>Example</entry>
4771        </row>
4772       </thead>
4773       <tbody>
4774        <row>
4775         <entry><literal><function>to_char</function>(<type>timestamp</type>, <type>text</type>)</literal></entry>
4776         <entry><type>text</type></entry>
4777         <entry>convert time stamp to string</entry>
4778         <entry><literal>to_char(current_timestamp, 'HH12:MI:SS')</literal></entry>
4779        </row>
4780        <row>
4781         <entry><literal><function>to_char</function>(<type>interval</type>, <type>text</type>)</literal></entry>
4782         <entry><type>text</type></entry>
4783         <entry>convert interval to string</entry>
4784         <entry><literal>to_char(interval '15h&nbsp;2m&nbsp;12s', 'HH24:MI:SS')</literal></entry>
4785        </row>
4786        <row>
4787         <entry><literal><function>to_char</function>(<type>int</type>, <type>text</type>)</literal></entry>
4788         <entry><type>text</type></entry>
4789         <entry>convert integer to string</entry>
4790         <entry><literal>to_char(125, '999')</literal></entry>
4791        </row>
4792        <row>
4793         <entry><literal><function>to_char</function>(<type>double precision</type>,
4794         <type>text</type>)</literal></entry>
4795         <entry><type>text</type></entry>
4796         <entry>convert real/double precision to string</entry>
4797         <entry><literal>to_char(125.8::real, '999D9')</literal></entry>
4798        </row>
4799        <row>
4800         <entry><literal><function>to_char</function>(<type>numeric</type>, <type>text</type>)</literal></entry>
4801         <entry><type>text</type></entry>
4802         <entry>convert numeric to string</entry>
4803         <entry><literal>to_char(-125.8, '999D99S')</literal></entry>
4804        </row>
4805        <row>
4806         <entry><literal><function>to_date</function>(<type>text</type>, <type>text</type>)</literal></entry>
4807         <entry><type>date</type></entry>
4808         <entry>convert string to date</entry>
4809         <entry><literal>to_date('05&nbsp;Dec&nbsp;2000', 'DD&nbsp;Mon&nbsp;YYYY')</literal></entry>
4810        </row>
4811        <row>
4812         <entry><literal><function>to_number</function>(<type>text</type>, <type>text</type>)</literal></entry>
4813         <entry><type>numeric</type></entry>
4814         <entry>convert string to numeric</entry>
4815         <entry><literal>to_number('12,454.8-', '99G999D9S')</literal></entry>
4816        </row>
4817        <row>
4818         <entry><literal><function>to_timestamp</function>(<type>text</type>, <type>text</type>)</literal></entry>
4819         <entry><type>timestamp with time zone</type></entry>
4820         <entry>convert string to time stamp</entry>
4821         <entry><literal>to_timestamp('05&nbsp;Dec&nbsp;2000', 'DD&nbsp;Mon&nbsp;YYYY')</literal></entry>
4822        </row>
4823        <row>
4824         <entry><literal><function>to_timestamp</function>(<type>double precision</type>)</literal></entry>
4825         <entry><type>timestamp with time zone</type></entry>
4826         <entry>convert Unix epoch to time stamp</entry>
4827         <entry><literal>to_timestamp(1284352323)</literal></entry>
4828        </row>
4829       </tbody>
4830      </tgroup>
4831     </table>
4832
4833    <para>
4834     In a <function>to_char</> output template string, there are certain
4835     patterns that are recognized and replaced with appropriately-formatted
4836     data based on the given value.  Any text that is not a template pattern is
4837     simply copied verbatim.  Similarly, in an input template string (for the
4838     other functions), template patterns identify the values to be supplied by
4839     the input data string.
4840    </para>
4841
4842   <para>
4843    <xref linkend="functions-formatting-datetime-table"> shows the
4844    template patterns available for formatting date and time values.
4845   </para>
4846
4847     <table id="functions-formatting-datetime-table">
4848      <title>Template Patterns for Date/Time Formatting</title>
4849      <tgroup cols="2">
4850       <thead>
4851        <row>
4852         <entry>Pattern</entry>
4853         <entry>Description</entry>
4854        </row>
4855       </thead>
4856       <tbody>
4857        <row>
4858         <entry><literal>HH</literal></entry>
4859         <entry>hour of day (01-12)</entry>
4860        </row>
4861        <row>
4862         <entry><literal>HH12</literal></entry>
4863         <entry>hour of day (01-12)</entry>
4864        </row>
4865        <row>
4866         <entry><literal>HH24</literal></entry>
4867         <entry>hour of day (00-23)</entry>
4868        </row>
4869        <row>
4870         <entry><literal>MI</literal></entry>
4871         <entry>minute (00-59)</entry>
4872        </row>
4873        <row>
4874         <entry><literal>SS</literal></entry>
4875         <entry>second (00-59)</entry>
4876        </row>
4877        <row>
4878         <entry><literal>MS</literal></entry>
4879         <entry>millisecond (000-999)</entry>
4880        </row>
4881        <row>
4882         <entry><literal>US</literal></entry>
4883         <entry>microsecond (000000-999999)</entry>
4884        </row>
4885        <row>
4886         <entry><literal>SSSS</literal></entry>
4887         <entry>seconds past midnight (0-86399)</entry>
4888        </row>
4889        <row>
4890         <entry><literal>AM</literal>, <literal>am</literal>,
4891         <literal>PM</literal> or <literal>pm</literal></entry>
4892         <entry>meridiem indicator (without periods)</entry>
4893        </row>
4894        <row>
4895         <entry><literal>A.M.</literal>, <literal>a.m.</literal>,
4896         <literal>P.M.</literal> or <literal>p.m.</literal></entry>
4897         <entry>meridiem indicator (with periods)</entry>
4898        </row>
4899        <row>
4900         <entry><literal>Y,YYY</literal></entry>
4901         <entry>year (4 and more digits) with comma</entry>
4902        </row>
4903        <row>
4904         <entry><literal>YYYY</literal></entry>
4905         <entry>year (4 and more digits)</entry>
4906        </row>
4907        <row>
4908         <entry><literal>YYY</literal></entry>
4909         <entry>last 3 digits of year</entry>
4910        </row>
4911        <row>
4912         <entry><literal>YY</literal></entry>
4913         <entry>last 2 digits of year</entry>
4914        </row>
4915        <row>
4916         <entry><literal>Y</literal></entry>
4917         <entry>last digit of year</entry>
4918        </row>
4919        <row>
4920         <entry><literal>IYYY</literal></entry>
4921         <entry>ISO year (4 and more digits)</entry>
4922        </row>
4923        <row>
4924         <entry><literal>IYY</literal></entry>
4925         <entry>last 3 digits of ISO year</entry>
4926        </row>
4927        <row>
4928         <entry><literal>IY</literal></entry>
4929         <entry>last 2 digits of ISO year</entry>
4930        </row>
4931        <row>
4932         <entry><literal>I</literal></entry>
4933         <entry>last digit of ISO year</entry>
4934        </row>
4935        <row>
4936         <entry><literal>BC</literal>, <literal>bc</literal>,
4937         <literal>AD</literal> or <literal>ad</literal></entry>
4938         <entry>era indicator (without periods)</entry>
4939        </row>
4940        <row>
4941         <entry><literal>B.C.</literal>, <literal>b.c.</literal>,
4942         <literal>A.D.</literal> or <literal>a.d.</literal></entry>
4943         <entry>era indicator (with periods)</entry>
4944        </row>
4945        <row>
4946         <entry><literal>MONTH</literal></entry>
4947         <entry>full uppercase month name (blank-padded to 9 chars)</entry>
4948        </row>
4949        <row>
4950         <entry><literal>Month</literal></entry>
4951         <entry>full capitalized month name (blank-padded to 9 chars)</entry>
4952        </row>
4953        <row>
4954         <entry><literal>month</literal></entry>
4955         <entry>full lowercase month name (blank-padded to 9 chars)</entry>
4956        </row>
4957        <row>
4958         <entry><literal>MON</literal></entry>
4959         <entry>abbreviated uppercase month name (3 chars in English, localized lengths vary)</entry>
4960        </row>
4961        <row>
4962         <entry><literal>Mon</literal></entry>
4963         <entry>abbreviated capitalized month name (3 chars in English, localized lengths vary)</entry>
4964        </row>
4965        <row>
4966         <entry><literal>mon</literal></entry>
4967         <entry>abbreviated lowercase month name (3 chars in English, localized lengths vary)</entry>
4968        </row>
4969        <row>
4970         <entry><literal>MM</literal></entry>
4971         <entry>month number (01-12)</entry>
4972        </row>
4973        <row>
4974         <entry><literal>DAY</literal></entry>
4975         <entry>full uppercase day name (blank-padded to 9 chars)</entry>
4976        </row>
4977        <row>
4978         <entry><literal>Day</literal></entry>
4979         <entry>full capitalized day name (blank-padded to 9 chars)</entry>
4980        </row>
4981        <row>
4982         <entry><literal>day</literal></entry>
4983         <entry>full lowercase day name (blank-padded to 9 chars)</entry>
4984        </row>
4985        <row>
4986         <entry><literal>DY</literal></entry>
4987         <entry>abbreviated uppercase day name (3 chars in English, localized lengths vary)</entry>
4988        </row>
4989        <row>
4990         <entry><literal>Dy</literal></entry>
4991         <entry>abbreviated capitalized day name (3 chars in English, localized lengths vary)</entry>
4992        </row>
4993        <row>
4994         <entry><literal>dy</literal></entry>
4995         <entry>abbreviated lowercase day name (3 chars in English, localized lengths vary)</entry>
4996        </row>
4997        <row>
4998         <entry><literal>DDD</literal></entry>
4999         <entry>day of year (001-366)</entry>
5000        </row>
5001        <row>
5002         <entry><literal>IDDD</literal></entry>
5003         <entry>ISO day of year (001-371; day 1 of the year is Monday of the first ISO week.)</entry>
5004        </row>
5005        <row>
5006         <entry><literal>DD</literal></entry>
5007         <entry>day of month (01-31)</entry>
5008        </row>
5009        <row>
5010         <entry><literal>D</literal></entry>
5011         <entry>day of the week, Sunday(<literal>1</>) to Saturday(<literal>7</>)</entry>
5012        </row>
5013        <row>
5014         <entry><literal>ID</literal></entry>
5015         <entry>ISO day of the week, Monday(<literal>1</>) to Sunday(<literal>7</>)</entry>
5016        </row>
5017        <row>
5018         <entry><literal>W</literal></entry>
5019         <entry>week of month (1-5) (The first week starts on the first day of the month.)</entry>
5020        </row>
5021        <row>
5022         <entry><literal>WW</literal></entry>
5023         <entry>week number of year (1-53) (The first week starts on the first day of the year.)</entry>
5024        </row>
5025        <row>
5026         <entry><literal>IW</literal></entry>
5027         <entry>ISO week number of year (01 - 53; the first Thursday of the new year is in week 1.)</entry>
5028        </row>
5029        <row>
5030         <entry><literal>CC</literal></entry>
5031         <entry>century (2 digits) (The twenty-first century starts on 2001-01-01.)</entry>
5032        </row>
5033        <row>
5034         <entry><literal>J</literal></entry>
5035         <entry>Julian Day (days since November 24, 4714 BC at midnight)</entry>
5036        </row>
5037        <row>
5038         <entry><literal>Q</literal></entry>
5039         <entry>quarter</entry>
5040        </row>
5041        <row>
5042         <entry><literal>RM</literal></entry>
5043         <entry>month in uppercase Roman numerals (I-XII; I=January)</entry>
5044        </row>
5045        <row>
5046         <entry><literal>rm</literal></entry>
5047         <entry>month in lowercase Roman numerals (i-xii; i=January)</entry>
5048        </row>
5049        <row>
5050         <entry><literal>TZ</literal></entry>
5051         <entry>uppercase time-zone name</entry>
5052        </row>
5053        <row>
5054         <entry><literal>tz</literal></entry>
5055         <entry>lowercase time-zone name</entry>
5056        </row>
5057       </tbody>
5058      </tgroup>
5059     </table>
5060
5061    <para>
5062     Modifiers can be applied to any template pattern to alter its
5063     behavior.  For example, <literal>FMMonth</literal>
5064     is the <literal>Month</literal> pattern with the
5065     <literal>FM</literal> modifier.
5066     <xref linkend="functions-formatting-datetimemod-table"> shows the
5067     modifier patterns for date/time formatting.
5068    </para>
5069
5070     <table id="functions-formatting-datetimemod-table">
5071      <title>Template Pattern Modifiers for Date/Time Formatting</title>
5072      <tgroup cols="3">
5073       <thead>
5074        <row>
5075         <entry>Modifier</entry>
5076         <entry>Description</entry>
5077         <entry>Example</entry>
5078        </row>
5079       </thead>
5080       <tbody>
5081        <row>
5082         <entry><literal>FM</literal> prefix</entry>
5083         <entry>fill mode (suppress padding blanks and zeroes)</entry>
5084         <entry><literal>FMMonth</literal></entry>
5085        </row>
5086        <row>
5087         <entry><literal>TH</literal> suffix</entry>
5088         <entry>uppercase ordinal number suffix</entry>
5089         <entry><literal>DDTH</literal>, e.g., <literal>12TH</></entry>
5090        </row>
5091        <row>
5092         <entry><literal>th</literal> suffix</entry>
5093         <entry>lowercase ordinal number suffix</entry>
5094         <entry><literal>DDth</literal>, e.g., <literal>12th</></entry>
5095        </row>
5096        <row>
5097         <entry><literal>FX</literal> prefix</entry>
5098         <entry>fixed format global option (see usage notes)</entry>
5099         <entry><literal>FX&nbsp;Month&nbsp;DD&nbsp;Day</literal></entry>
5100        </row>
5101        <row>
5102         <entry><literal>TM</literal> prefix</entry>
5103         <entry>translation mode (print localized day and month names based on
5104          <xref linkend="guc-lc-time">)</entry>
5105         <entry><literal>TMMonth</literal></entry>
5106        </row>
5107        <row>
5108         <entry><literal>SP</literal> suffix</entry>
5109         <entry>spell mode (not implemented)</entry>
5110         <entry><literal>DDSP</literal></entry>
5111        </row>
5112       </tbody>
5113      </tgroup>
5114     </table>
5115
5116    <para>
5117     Usage notes for date/time formatting:
5118
5119     <itemizedlist>
5120      <listitem>
5121       <para>
5122        <literal>FM</literal> suppresses leading zeroes and trailing blanks
5123        that would otherwise be added to make the output of a pattern be
5124        fixed-width.
5125       </para>
5126      </listitem>
5127
5128      <listitem>
5129       <para>
5130        <literal>TM</literal> does not include trailing blanks.
5131       </para>
5132      </listitem>
5133
5134      <listitem>
5135       <para>
5136        <function>to_timestamp</function> and <function>to_date</function>
5137        skip multiple blank spaces in the input string unless the
5138        <literal>FX</literal> option is used. For example,
5139        <literal>to_timestamp('2000&nbsp;&nbsp;&nbsp;&nbsp;JUN', 'YYYY MON')</literal> works, but
5140        <literal>to_timestamp('2000&nbsp;&nbsp;&nbsp;&nbsp;JUN', 'FXYYYY MON')</literal> returns an error
5141        because <function>to_timestamp</function> expects one space only.
5142        <literal>FX</literal> must be specified as the first item in
5143        the template.
5144       </para>
5145      </listitem>
5146
5147      <listitem>
5148       <para>
5149        Ordinary text is allowed in <function>to_char</function>
5150        templates and will be output literally.  You can put a substring
5151        in double quotes to force it to be interpreted as literal text
5152        even if it contains pattern key words.  For example, in
5153        <literal>'"Hello Year "YYYY'</literal>, the <literal>YYYY</literal>
5154        will be replaced by the year data, but the single <literal>Y</literal> in <literal>Year</literal>
5155        will not be.
5156       </para>
5157      </listitem>
5158
5159      <listitem>
5160       <para>
5161        If you want to have a double quote in the output you must
5162        precede it with a backslash, for example <literal>E'\\"YYYY
5163        Month\\"'</literal>. <!-- "" font-lock sanity :-) -->
5164        (Two backslashes are necessary because the backslash
5165        has special meaning when using the escape string syntax.)
5166       </para>
5167      </listitem>
5168
5169      <listitem>
5170       <para>
5171        The <literal>YYYY</literal> conversion from string to <type>timestamp</type> or
5172        <type>date</type> has a restriction when processing years with more than 4 digits. You must
5173        use some non-digit character or template after <literal>YYYY</literal>,
5174        otherwise the year is always interpreted as 4 digits. For example
5175        (with the year 20000):
5176        <literal>to_date('200001131', 'YYYYMMDD')</literal> will be
5177        interpreted as a 4-digit year; instead use a non-digit
5178        separator after the year, like
5179        <literal>to_date('20000-1131', 'YYYY-MMDD')</literal> or
5180        <literal>to_date('20000Nov31', 'YYYYMonDD')</literal>.
5181       </para>
5182      </listitem>
5183
5184      <listitem>
5185       <para>
5186        In conversions from string to <type>timestamp</type> or
5187        <type>date</type>, the <literal>CC</literal> (century) field is ignored
5188        if there is a <literal>YYY</literal>, <literal>YYYY</literal> or
5189        <literal>Y,YYY</literal> field. If <literal>CC</literal> is used with
5190        <literal>YY</literal> or <literal>Y</literal> then the year is computed
5191        as <literal>(CC-1)*100+YY</literal>.
5192       </para>
5193      </listitem>
5194
5195      <listitem>
5196       <para>
5197        An ISO week date (as distinct from a Gregorian date) can be
5198        specified to <function>to_timestamp</function> and
5199        <function>to_date</function> in one of two ways:
5200        <itemizedlist>
5201         <listitem>
5202          <para>
5203           Year, week, and weekday:  for example <literal>to_date('2006-42-4',
5204           'IYYY-IW-ID')</literal> returns the date
5205           <literal>2006-10-19</literal>.  If you omit the weekday it
5206           is assumed to be 1 (Monday).
5207          </para>
5208         </listitem>
5209         <listitem>
5210          <para>
5211           Year and day of year:  for example <literal>to_date('2006-291',
5212           'IYYY-IDDD')</literal> also returns <literal>2006-10-19</literal>.
5213          </para>
5214         </listitem>
5215        </itemizedlist>
5216       </para>
5217       <para>
5218        Attempting to construct a date using a mixture of ISO week and
5219        Gregorian date fields is nonsensical, and will cause an error.  In the
5220        context of an ISO year, the concept of a <quote>month</> or <quote>day
5221        of month</> has no meaning.  In the context of a Gregorian year, the
5222        ISO week has no meaning.  Users should avoid mixing Gregorian and
5223        ISO date specifications.
5224       </para>
5225      </listitem>
5226
5227      <listitem>
5228       <para>
5229        In a conversion from string to <type>timestamp</type>, millisecond
5230        (<literal>MS</literal>) or microsecond (<literal>US</literal>)
5231        values are used as the
5232        seconds digits after the decimal point. For example
5233        <literal>to_timestamp('12:3', 'SS:MS')</literal> is not 3 milliseconds,
5234        but 300, because the conversion counts it as 12 + 0.3 seconds.
5235        This means for the format <literal>SS:MS</literal>, the input values
5236        <literal>12:3</literal>, <literal>12:30</literal>, and <literal>12:300</literal> specify the
5237        same number of milliseconds. To get three milliseconds, one must use
5238        <literal>12:003</literal>, which the conversion counts as
5239        12 + 0.003 = 12.003 seconds.
5240       </para>
5241
5242       <para>
5243        Here is a more
5244        complex example:
5245        <literal>to_timestamp('15:12:02.020.001230', 'HH:MI:SS.MS.US')</literal>
5246        is 15 hours, 12 minutes, and 2 seconds + 20 milliseconds +
5247        1230 microseconds = 2.021230 seconds.
5248       </para>
5249      </listitem>
5250
5251      <listitem>
5252       <para>
5253         <function>to_char(..., 'ID')</function>'s day of the week numbering
5254         matches the <function>extract('isodow', ...)</function> function, but
5255         <function>to_char(..., 'D')</function>'s does not match
5256         <function>extract('dow', ...)</function>'s day numbering.
5257       </para>
5258      </listitem>
5259
5260      <listitem>
5261       <para>
5262         <function>to_char(interval)</function> formats <literal>HH</> and
5263         <literal>HH12</> as hours in a single day, while <literal>HH24</>
5264         can output hours exceeding a single day, e.g., &gt;24.
5265       </para>
5266      </listitem>
5267
5268     </itemizedlist>
5269    </para>
5270
5271   <para>
5272    <xref linkend="functions-formatting-numeric-table"> shows the
5273    template patterns available for formatting numeric values.
5274   </para>
5275
5276     <table id="functions-formatting-numeric-table">
5277      <title>Template Patterns for Numeric Formatting</title>
5278      <tgroup cols="2">
5279       <thead>
5280        <row>
5281         <entry>Pattern</entry>
5282         <entry>Description</entry>
5283        </row>
5284       </thead>
5285       <tbody>
5286        <row>
5287         <entry><literal>9</literal></entry>
5288         <entry>value with the specified number of digits</entry>
5289        </row>
5290        <row>
5291         <entry><literal>0</literal></entry>
5292         <entry>value with leading zeros</entry>
5293        </row>
5294        <row>
5295         <entry><literal>.</literal> (period)</entry>
5296         <entry>decimal point</entry>
5297        </row>
5298        <row>
5299         <entry><literal>,</literal> (comma)</entry>
5300         <entry>group (thousand) separator</entry>
5301        </row>
5302        <row>
5303         <entry><literal>PR</literal></entry>
5304         <entry>negative value in angle brackets</entry>
5305        </row>
5306        <row>
5307         <entry><literal>S</literal></entry>
5308         <entry>sign anchored to number (uses locale)</entry>
5309        </row>
5310        <row>
5311         <entry><literal>L</literal></entry>
5312         <entry>currency symbol (uses locale)</entry>
5313        </row>
5314        <row>
5315         <entry><literal>D</literal></entry>
5316         <entry>decimal point (uses locale)</entry>
5317        </row>
5318        <row>
5319         <entry><literal>G</literal></entry>
5320         <entry>group separator (uses locale)</entry>
5321        </row>
5322        <row>
5323         <entry><literal>MI</literal></entry>
5324         <entry>minus sign in specified position (if number &lt; 0)</entry>
5325        </row>
5326        <row>
5327         <entry><literal>PL</literal></entry>
5328         <entry>plus sign in specified position (if number &gt; 0)</entry>
5329        </row>
5330        <row>
5331         <entry><literal>SG</literal></entry>
5332         <entry>plus/minus sign in specified position</entry>
5333        </row>
5334        <row>
5335         <entry><literal>RN</literal></entry>
5336         <entry>Roman numeral (input between 1 and 3999)</entry>
5337        </row>
5338        <row>
5339         <entry><literal>TH</literal> or <literal>th</literal></entry>
5340         <entry>ordinal number suffix</entry>
5341        </row>
5342        <row>
5343         <entry><literal>V</literal></entry>
5344         <entry>shift specified number of digits (see notes)</entry>
5345        </row>
5346        <row>
5347         <entry><literal>EEEE</literal></entry>
5348         <entry>scientific notation (not implemented)</entry>
5349        </row>
5350       </tbody>
5351      </tgroup>
5352     </table>
5353
5354    <para>
5355     Usage notes for numeric formatting:
5356
5357     <itemizedlist>
5358      <listitem>
5359       <para>
5360        A sign formatted using <literal>SG</literal>, <literal>PL</literal>, or
5361        <literal>MI</literal> is not anchored to
5362        the number; for example,
5363        <literal>to_char(-12, 'MI9999')</literal> produces <literal>'-&nbsp;&nbsp;12'</literal>
5364        but <literal>to_char(-12, 'S9999')</literal> produces <literal>'&nbsp;&nbsp;-12'</literal>.
5365        The Oracle implementation does not allow the use of
5366        <literal>MI</literal> before <literal>9</literal>, but rather
5367        requires that <literal>9</literal> precede
5368        <literal>MI</literal>.
5369       </para>
5370      </listitem>
5371
5372      <listitem>
5373       <para>
5374        <literal>9</literal> results in a value with the same number of
5375        digits as there are <literal>9</literal>s. If a digit is
5376        not available it outputs a space.
5377       </para>
5378      </listitem>
5379
5380      <listitem>
5381       <para>
5382        <literal>TH</literal> does not convert values less than zero
5383        and does not convert fractional numbers.
5384       </para>
5385      </listitem>
5386
5387      <listitem>
5388       <para>
5389        <literal>PL</literal>, <literal>SG</literal>, and
5390        <literal>TH</literal> are <productname>PostgreSQL</productname>
5391        extensions.
5392       </para>
5393      </listitem>
5394
5395      <listitem>
5396       <para>
5397        <literal>V</literal> effectively
5398        multiplies the input values by
5399        <literal>10^<replaceable>n</replaceable></literal>, where
5400        <replaceable>n</replaceable> is the number of digits following
5401        <literal>V</literal>.
5402        <function>to_char</function> does not support the use of
5403        <literal>V</literal> combined with a decimal point
5404        (e.g., <literal>99.9V99</literal> is not allowed).
5405       </para>
5406      </listitem>
5407     </itemizedlist>
5408    </para>
5409
5410    <para>
5411     Certain modifiers can be applied to any template pattern to alter its
5412     behavior.  For example, <literal>FM9999</literal>
5413     is the <literal>9999</literal> pattern with the
5414     <literal>FM</literal> modifier.
5415     <xref linkend="functions-formatting-numericmod-table"> shows the
5416     modifier patterns for numeric formatting.
5417    </para>
5418
5419     <table id="functions-formatting-numericmod-table">
5420      <title>Template Pattern Modifiers for Numeric Formatting</title>
5421      <tgroup cols="3">
5422       <thead>
5423        <row>
5424         <entry>Modifier</entry>
5425         <entry>Description</entry>
5426         <entry>Example</entry>
5427        </row>
5428       </thead>
5429       <tbody>
5430        <row>
5431         <entry><literal>FM</literal> prefix</entry>
5432         <entry>fill mode (suppress padding blanks and zeroes)</entry>
5433         <entry><literal>FM9999</literal></entry>
5434        </row>
5435        <row>
5436         <entry><literal>TH</literal> suffix</entry>
5437         <entry>uppercase ordinal number suffix</entry>
5438         <entry><literal>999TH</literal></entry>
5439        </row>
5440        <row>
5441         <entry><literal>th</literal> suffix</entry>
5442         <entry>lowercase ordinal number suffix</entry>
5443         <entry><literal>999th</literal></entry>
5444        </row>
5445       </tbody>
5446      </tgroup>
5447     </table>
5448
5449   <para>
5450    <xref linkend="functions-formatting-examples-table"> shows some
5451    examples of the use of the <function>to_char</function> function.
5452   </para>
5453
5454     <table id="functions-formatting-examples-table">
5455      <title><function>to_char</function> Examples</title>
5456      <tgroup cols="2">
5457       <thead>
5458        <row>
5459         <entry>Expression</entry>
5460         <entry>Result</entry>
5461        </row>
5462       </thead>
5463       <tbody>
5464        <row>
5465         <entry><literal>to_char(current_timestamp, 'Day,&nbsp;DD&nbsp;&nbsp;HH12:MI:SS')</literal></entry>
5466         <entry><literal>'Tuesday&nbsp;&nbsp;,&nbsp;06&nbsp;&nbsp;05:39:18'</literal></entry>
5467        </row>
5468        <row>
5469         <entry><literal>to_char(current_timestamp, 'FMDay,&nbsp;FMDD&nbsp;&nbsp;HH12:MI:SS')</literal></entry>
5470         <entry><literal>'Tuesday,&nbsp;6&nbsp;&nbsp;05:39:18'</literal></entry>
5471        </row>
5472        <row>
5473         <entry><literal>to_char(-0.1, '99.99')</literal></entry>
5474         <entry><literal>'&nbsp;&nbsp;-.10'</literal></entry>
5475        </row>
5476        <row>
5477         <entry><literal>to_char(-0.1, 'FM9.99')</literal></entry>
5478         <entry><literal>'-.1'</literal></entry>
5479        </row>
5480        <row>
5481         <entry><literal>to_char(0.1, '0.9')</literal></entry>
5482         <entry><literal>'&nbsp;0.1'</literal></entry>
5483        </row>
5484        <row>
5485         <entry><literal>to_char(12, '9990999.9')</literal></entry>
5486         <entry><literal>'&nbsp;&nbsp;&nbsp;&nbsp;0012.0'</literal></entry>
5487        </row>
5488        <row>
5489         <entry><literal>to_char(12, 'FM9990999.9')</literal></entry>
5490         <entry><literal>'0012.'</literal></entry>
5491        </row>
5492        <row>
5493         <entry><literal>to_char(485, '999')</literal></entry>
5494         <entry><literal>'&nbsp;485'</literal></entry>
5495        </row>
5496        <row>
5497         <entry><literal>to_char(-485, '999')</literal></entry>
5498         <entry><literal>'-485'</literal></entry>
5499        </row>
5500        <row>
5501         <entry><literal>to_char(485, '9&nbsp;9&nbsp;9')</literal></entry>
5502         <entry><literal>'&nbsp;4&nbsp;8&nbsp;5'</literal></entry>
5503        </row>
5504        <row>
5505         <entry><literal>to_char(1485, '9,999')</literal></entry>
5506         <entry><literal>'&nbsp;1,485'</literal></entry>
5507        </row>
5508        <row>
5509         <entry><literal>to_char(1485, '9G999')</literal></entry>
5510         <entry><literal>'&nbsp;1&nbsp;485'</literal></entry>
5511        </row>
5512        <row>
5513         <entry><literal>to_char(148.5, '999.999')</literal></entry>
5514         <entry><literal>'&nbsp;148.500'</literal></entry>
5515        </row>
5516        <row>
5517         <entry><literal>to_char(148.5, 'FM999.999')</literal></entry>
5518         <entry><literal>'148.5'</literal></entry>
5519        </row>
5520        <row>
5521         <entry><literal>to_char(148.5, 'FM999.990')</literal></entry>
5522         <entry><literal>'148.500'</literal></entry>
5523        </row>
5524        <row>
5525         <entry><literal>to_char(148.5, '999D999')</literal></entry>
5526         <entry><literal>'&nbsp;148,500'</literal></entry>
5527        </row>
5528        <row>
5529         <entry><literal>to_char(3148.5, '9G999D999')</literal></entry>
5530         <entry><literal>'&nbsp;3&nbsp;148,500'</literal></entry>
5531        </row>
5532        <row>
5533         <entry><literal>to_char(-485, '999S')</literal></entry>
5534         <entry><literal>'485-'</literal></entry>
5535        </row>
5536        <row>
5537         <entry><literal>to_char(-485, '999MI')</literal></entry>
5538         <entry><literal>'485-'</literal></entry>
5539        </row>
5540        <row>
5541         <entry><literal>to_char(485, '999MI')</literal></entry>
5542         <entry><literal>'485&nbsp;'</literal></entry>
5543        </row>
5544        <row>
5545         <entry><literal>to_char(485, 'FM999MI')</literal></entry>
5546         <entry><literal>'485'</literal></entry>
5547        </row>
5548        <row>
5549         <entry><literal>to_char(485, 'PL999')</literal></entry>
5550         <entry><literal>'+485'</literal></entry>
5551        </row>
5552        <row>
5553         <entry><literal>to_char(485, 'SG999')</literal></entry>
5554         <entry><literal>'+485'</literal></entry>
5555        </row>
5556        <row>
5557         <entry><literal>to_char(-485, 'SG999')</literal></entry>
5558         <entry><literal>'-485'</literal></entry>
5559        </row>
5560        <row>
5561         <entry><literal>to_char(-485, '9SG99')</literal></entry>
5562         <entry><literal>'4-85'</literal></entry>
5563        </row>
5564        <row>
5565         <entry><literal>to_char(-485, '999PR')</literal></entry>
5566         <entry><literal>'&lt;485&gt;'</literal></entry>
5567        </row>
5568        <row>
5569         <entry><literal>to_char(485, 'L999')</literal></entry>
5570         <entry><literal>'DM&nbsp;485</literal></entry>
5571        </row>
5572        <row>
5573         <entry><literal>to_char(485, 'RN')</literal></entry>
5574         <entry><literal>'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;CDLXXXV'</literal></entry>
5575        </row>
5576        <row>
5577         <entry><literal>to_char(485, 'FMRN')</literal></entry>
5578         <entry><literal>'CDLXXXV'</literal></entry>
5579        </row>
5580        <row>
5581         <entry><literal>to_char(5.2, 'FMRN')</literal></entry>
5582         <entry><literal>'V'</literal></entry>
5583        </row>
5584        <row>
5585         <entry><literal>to_char(482, '999th')</literal></entry>
5586         <entry><literal>'&nbsp;482nd'</literal></entry>
5587        </row>
5588        <row>
5589         <entry><literal>to_char(485, '"Good&nbsp;number:"999')</literal></entry>
5590         <entry><literal>'Good&nbsp;number:&nbsp;485'</literal></entry>
5591        </row>
5592        <row>
5593         <entry><literal>to_char(485.8, '"Pre:"999"&nbsp;Post:"&nbsp;.999')</literal></entry>
5594         <entry><literal>'Pre:&nbsp;485&nbsp;Post:&nbsp;.800'</literal></entry>
5595        </row>
5596        <row>
5597         <entry><literal>to_char(12, '99V999')</literal></entry>
5598         <entry><literal>'&nbsp;12000'</literal></entry>
5599        </row>
5600        <row>
5601         <entry><literal>to_char(12.4, '99V999')</literal></entry>
5602         <entry><literal>'&nbsp;12400'</literal></entry>
5603        </row>
5604        <row>
5605         <entry><literal>to_char(12.45, '99V9')</literal></entry>
5606         <entry><literal>'&nbsp;125'</literal></entry>
5607        </row>
5608       </tbody>
5609      </tgroup>
5610     </table>
5611
5612   </sect1>
5613
5614
5615   <sect1 id="functions-datetime">
5616    <title>Date/Time Functions and Operators</title>
5617
5618   <para>
5619    <xref linkend="functions-datetime-table"> shows the available
5620    functions for date/time value processing, with details appearing in
5621    the following subsections.  <xref
5622    linkend="operators-datetime-table"> illustrates the behaviors of
5623    the basic arithmetic operators (<literal>+</literal>,
5624    <literal>*</literal>, etc.).  For formatting functions, refer to
5625    <xref linkend="functions-formatting">.  You should be familiar with
5626    the background information on date/time data types from <xref
5627    linkend="datatype-datetime">.
5628   </para>
5629
5630   <para>
5631    All the functions and operators described below that take <type>time</type> or <type>timestamp</type>
5632    inputs actually come in two variants: one that takes <type>time with time zone</type> or <type>timestamp
5633    with time zone</type>, and one that takes <type>time without time zone</type> or <type>timestamp without time zone</type>.
5634    For brevity, these variants are not shown separately.  Also, the
5635    <literal>+</> and <literal>*</> operators come in commutative pairs (for
5636    example both date + integer and integer + date); we show only one of each
5637    such pair.
5638   </para>
5639
5640     <table id="operators-datetime-table">
5641      <title>Date/Time Operators</title>
5642
5643      <tgroup cols="3">
5644       <thead>
5645        <row>
5646         <entry>Operator</entry>
5647         <entry>Example</entry>
5648         <entry>Result</entry>
5649        </row>
5650       </thead>
5651
5652       <tbody>
5653        <row>
5654         <entry> <literal>+</literal> </entry>
5655         <entry><literal>date '2001-09-28' + integer '7'</literal></entry>
5656         <entry><literal>date '2001-10-05'</literal></entry>
5657        </row>
5658
5659        <row>
5660         <entry> <literal>+</literal> </entry>
5661         <entry><literal>date '2001-09-28' + interval '1 hour'</literal></entry>
5662         <entry><literal>timestamp '2001-09-28 01:00:00'</literal></entry>
5663        </row>
5664
5665        <row>
5666         <entry> <literal>+</literal> </entry>
5667         <entry><literal>date '2001-09-28' + time '03:00'</literal></entry>
5668         <entry><literal>timestamp '2001-09-28 03:00:00'</literal></entry>
5669        </row>
5670
5671        <row>
5672         <entry> <literal>+</literal> </entry>
5673         <entry><literal>interval '1 day' + interval '1 hour'</literal></entry>
5674         <entry><literal>interval '1 day 01:00:00'</literal></entry>
5675        </row>
5676
5677        <row>
5678         <entry> <literal>+</literal> </entry>
5679         <entry><literal>timestamp '2001-09-28 01:00' + interval '23 hours'</literal></entry>
5680         <entry><literal>timestamp '2001-09-29 00:00:00'</literal></entry>
5681        </row>
5682
5683        <row>
5684         <entry> <literal>+</literal> </entry>
5685         <entry><literal>time '01:00' + interval '3 hours'</literal></entry>
5686         <entry><literal>time '04:00:00'</literal></entry>
5687        </row>
5688
5689        <row>
5690         <entry> <literal>-</literal> </entry>
5691         <entry><literal>- interval '23 hours'</literal></entry>
5692         <entry><literal>interval '-23:00:00'</literal></entry>
5693        </row>
5694
5695        <row>
5696         <entry> <literal>-</literal> </entry>
5697         <entry><literal>date '2001-10-01' - date '2001-09-28'</literal></entry>
5698         <entry><literal>integer '3'</literal> (days)</entry>
5699        </row>
5700
5701        <row>
5702         <entry> <literal>-</literal> </entry>
5703         <entry><literal>date '2001-10-01' - integer '7'</literal></entry>
5704         <entry><literal>date '2001-09-24'</literal></entry>
5705        </row>
5706
5707        <row>
5708         <entry> <literal>-</literal> </entry>
5709         <entry><literal>date '2001-09-28' - interval '1 hour'</literal></entry>
5710         <entry><literal>timestamp '2001-09-27 23:00:00'</literal></entry>
5711        </row>
5712
5713        <row>
5714         <entry> <literal>-</literal> </entry>
5715         <entry><literal>time '05:00' - time '03:00'</literal></entry>
5716         <entry><literal>interval '02:00:00'</literal></entry>
5717        </row>
5718
5719        <row>
5720         <entry> <literal>-</literal> </entry>
5721         <entry><literal>time '05:00' - interval '2 hours'</literal></entry>
5722         <entry><literal>time '03:00:00'</literal></entry>
5723        </row>
5724
5725        <row>
5726         <entry> <literal>-</literal> </entry>
5727         <entry><literal>timestamp '2001-09-28 23:00' - interval '23 hours'</literal></entry>
5728         <entry><literal>timestamp '2001-09-28 00:00:00'</literal></entry>
5729        </row>
5730
5731        <row>
5732         <entry> <literal>-</literal> </entry>
5733         <entry><literal>interval '1 day' - interval '1 hour'</literal></entry>
5734         <entry><literal>interval '1 day -01:00:00'</literal></entry>
5735        </row>
5736
5737        <row>
5738         <entry> <literal>-</literal> </entry>
5739         <entry><literal>timestamp '2001-09-29 03:00' - timestamp '2001-09-27 12:00'</literal></entry>
5740         <entry><literal>interval '1 day 15:00:00'</literal></entry>
5741        </row>
5742
5743        <row>
5744         <entry> <literal>*</literal> </entry>
5745         <entry><literal>900 * interval '1 second'</literal></entry>
5746         <entry><literal>interval '00:15:00'</literal></entry>
5747        </row>
5748
5749        <row>
5750         <entry> <literal>*</literal> </entry>
5751         <entry><literal>21 * interval '1 day'</literal></entry>
5752         <entry><literal>interval '21 days'</literal></entry>
5753        </row>
5754
5755        <row>
5756         <entry> <literal>*</literal> </entry>
5757         <entry><literal>double precision '3.5' * interval '1 hour'</literal></entry>
5758         <entry><literal>interval '03:30:00'</literal></entry>
5759        </row>
5760
5761        <row>
5762         <entry> <literal>/</literal> </entry>
5763         <entry><literal>interval '1 hour' / double precision '1.5'</literal></entry>
5764         <entry><literal>interval '00:40:00'</literal></entry>
5765        </row>
5766       </tbody>
5767      </tgroup>
5768     </table>
5769
5770    <indexterm>
5771     <primary>age</primary>
5772    </indexterm>
5773    <indexterm>
5774     <primary>clock_timestamp</primary>
5775    </indexterm>
5776    <indexterm>
5777     <primary>current_date</primary>
5778    </indexterm>
5779    <indexterm>
5780     <primary>current_time</primary>
5781    </indexterm>
5782    <indexterm>
5783     <primary>current_timestamp</primary>
5784    </indexterm>
5785    <indexterm>
5786     <primary>date_part</primary>
5787    </indexterm>
5788    <indexterm>
5789     <primary>date_trunc</primary>
5790    </indexterm>
5791    <indexterm>
5792     <primary>extract</primary>
5793    </indexterm>
5794    <indexterm>
5795     <primary>isfinite</primary>
5796    </indexterm>
5797    <indexterm>
5798     <primary>justify_days</primary>
5799    </indexterm>
5800    <indexterm>
5801     <primary>justify_hours</primary>
5802    </indexterm>
5803    <indexterm>
5804     <primary>justify_interval</primary>
5805    </indexterm>
5806    <indexterm>
5807     <primary>localtime</primary>
5808    </indexterm>
5809    <indexterm>
5810     <primary>localtimestamp</primary>
5811    </indexterm>
5812    <indexterm>
5813     <primary>now</primary>
5814    </indexterm>
5815    <indexterm>
5816     <primary>statement_timestamp</primary>
5817    </indexterm>
5818    <indexterm>
5819     <primary>timeofday</primary>
5820    </indexterm>
5821    <indexterm>
5822     <primary>transaction_timestamp</primary>
5823    </indexterm>
5824
5825     <table id="functions-datetime-table">
5826      <title>Date/Time Functions</title>
5827      <tgroup cols="5">
5828       <thead>
5829        <row>
5830         <entry>Function</entry>
5831         <entry>Return Type</entry>
5832         <entry>Description</entry>
5833         <entry>Example</entry>
5834         <entry>Result</entry>
5835        </row>
5836       </thead>
5837
5838       <tbody>
5839        <row>
5840         <entry><literal><function>age</function>(<type>timestamp</type>, <type>timestamp</type>)</literal></entry>
5841         <entry><type>interval</type></entry>
5842         <entry>Subtract arguments, producing a <quote>symbolic</> result that
5843         uses years and months</entry>
5844         <entry><literal>age(timestamp '2001-04-10', timestamp '1957-06-13')</literal></entry>
5845         <entry><literal>43 years 9 mons 27 days</literal></entry>
5846        </row>
5847
5848        <row>
5849         <entry><literal><function>age</function>(<type>timestamp</type>)</literal></entry>
5850         <entry><type>interval</type></entry>
5851         <entry>Subtract from <function>current_date</function> (at midnight)</entry>
5852         <entry><literal>age(timestamp '1957-06-13')</literal></entry>
5853         <entry><literal>43 years 8 mons 3 days</literal></entry>
5854        </row>
5855
5856        <row>
5857         <entry><literal><function>clock_timestamp</function>()</literal></entry>
5858         <entry><type>timestamp with time zone</type></entry>
5859         <entry>Current date and time (changes during statement execution);
5860          see <xref linkend="functions-datetime-current">
5861         </entry>
5862         <entry></entry>
5863         <entry></entry>
5864        </row>
5865
5866        <row>
5867         <entry><literal><function>current_date</function></literal></entry>
5868         <entry><type>date</type></entry>
5869         <entry>Current date;
5870          see <xref linkend="functions-datetime-current">
5871         </entry>
5872         <entry></entry>
5873         <entry></entry>
5874        </row>
5875
5876        <row>
5877         <entry><literal><function>current_time</function></literal></entry>
5878         <entry><type>time with time zone</type></entry>
5879         <entry>Current time of day;
5880          see <xref linkend="functions-datetime-current">
5881         </entry>
5882         <entry></entry>
5883         <entry></entry>
5884        </row>
5885
5886        <row>
5887         <entry><literal><function>current_timestamp</function></literal></entry>
5888         <entry><type>timestamp with time zone</type></entry>
5889         <entry>Current date and time (start of current transaction);
5890          see <xref linkend="functions-datetime-current">
5891         </entry>
5892         <entry></entry>
5893         <entry></entry>
5894        </row>
5895
5896        <row>
5897         <entry><literal><function>date_part</function>(<type>text</type>, <type>timestamp</type>)</literal></entry>
5898         <entry><type>double precision</type></entry>
5899         <entry>Get subfield (equivalent to <function>extract</function>);
5900          see <xref linkend="functions-datetime-extract">
5901         </entry>
5902         <entry><literal>date_part('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
5903         <entry><literal>20</literal></entry>
5904        </row>
5905
5906        <row>
5907         <entry><literal><function>date_part</function>(<type>text</type>, <type>interval</type>)</literal></entry>
5908         <entry><type>double precision</type></entry>
5909         <entry>Get subfield (equivalent to
5910          <function>extract</function>); see <xref linkend="functions-datetime-extract">
5911         </entry>
5912         <entry><literal>date_part('month', interval '2 years 3 months')</literal></entry>
5913         <entry><literal>3</literal></entry>
5914        </row>
5915
5916        <row>
5917         <entry><literal><function>date_trunc</function>(<type>text</type>, <type>timestamp</type>)</literal></entry>
5918         <entry><type>timestamp</type></entry>
5919         <entry>Truncate to specified precision; see also <xref linkend="functions-datetime-trunc">
5920         </entry>
5921         <entry><literal>date_trunc('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
5922         <entry><literal>2001-02-16 20:00:00</literal></entry>
5923        </row>
5924
5925        <row>
5926         <entry><literal><function>extract</function>(<parameter>field</parameter> from
5927          <type>timestamp</type>)</literal></entry>
5928         <entry><type>double precision</type></entry>
5929         <entry>Get subfield; see <xref linkend="functions-datetime-extract">
5930         </entry>
5931         <entry><literal>extract(hour from timestamp '2001-02-16 20:38:40')</literal></entry>
5932         <entry><literal>20</literal></entry>
5933        </row>
5934
5935        <row>
5936         <entry><literal><function>extract</function>(<parameter>field</parameter> from
5937          <type>interval</type>)</literal></entry>
5938         <entry><type>double precision</type></entry>
5939         <entry>Get subfield; see <xref linkend="functions-datetime-extract">
5940         </entry>
5941         <entry><literal>extract(month from interval '2 years 3 months')</literal></entry>
5942         <entry><literal>3</literal></entry>
5943        </row>
5944
5945        <row>
5946         <entry><literal><function>isfinite</function>(<type>date</type>)</literal></entry>
5947         <entry><type>boolean</type></entry>
5948         <entry>Test for finite date (not +/-infinity)</entry>
5949         <entry><literal>isfinite(date '2001-02-16')</literal></entry>
5950         <entry><literal>true</literal></entry>
5951        </row>
5952
5953        <row>
5954         <entry><literal><function>isfinite</function>(<type>timestamp</type>)</literal></entry>
5955         <entry><type>boolean</type></entry>
5956         <entry>Test for finite time stamp (not +/-infinity)</entry>
5957         <entry><literal>isfinite(timestamp '2001-02-16 21:28:30')</literal></entry>
5958         <entry><literal>true</literal></entry>
5959        </row>
5960
5961        <row>
5962         <entry><literal><function>isfinite</function>(<type>interval</type>)</literal></entry>
5963         <entry><type>boolean</type></entry>
5964         <entry>Test for finite interval</entry>
5965         <entry><literal>isfinite(interval '4 hours')</literal></entry>
5966         <entry><literal>true</literal></entry>
5967        </row>
5968
5969        <row>
5970         <entry><literal><function>justify_days</function>(<type>interval</type>)</literal></entry>
5971         <entry><type>interval</type></entry>
5972         <entry>Adjust interval so 30-day time periods are represented as months</entry>
5973         <entry><literal>justify_days(interval '35 days')</literal></entry>
5974         <entry><literal>1 mon 5 days</literal></entry>
5975        </row>
5976
5977        <row>
5978         <entry><literal><function>justify_hours</function>(<type>interval</type>)</literal></entry>
5979         <entry><type>interval</type></entry>
5980         <entry>Adjust interval so 24-hour time periods are represented as days</entry>
5981         <entry><literal>justify_hours(interval '27 hours')</literal></entry>
5982         <entry><literal>1 day 03:00:00</literal></entry>
5983        </row>
5984
5985        <row>
5986         <entry><literal><function>justify_interval</function>(<type>interval</type>)</literal></entry>
5987         <entry><type>interval</type></entry>
5988         <entry>Adjust interval using <function>justify_days</> and <function>justify_hours</>, with additional sign adjustments</entry>
5989         <entry><literal>justify_interval(interval '1 mon -1 hour')</literal></entry>
5990         <entry><literal>29 days 23:00:00</literal></entry>
5991        </row>
5992
5993        <row>
5994         <entry><literal><function>localtime</function></literal></entry>
5995         <entry><type>time</type></entry>
5996         <entry>Current time of day;
5997          see <xref linkend="functions-datetime-current">
5998         </entry>
5999         <entry></entry>
6000         <entry></entry>
6001        </row>
6002
6003        <row>
6004         <entry><literal><function>localtimestamp</function></literal></entry>
6005         <entry><type>timestamp</type></entry>
6006         <entry>Current date and time (start of current transaction);
6007          see <xref linkend="functions-datetime-current">
6008         </entry>
6009         <entry></entry>
6010         <entry></entry>
6011        </row>
6012
6013        <row>
6014         <entry><literal><function>now</function>()</literal></entry>
6015         <entry><type>timestamp with time zone</type></entry>
6016         <entry>Current date and time (start of current transaction);
6017          see <xref linkend="functions-datetime-current">
6018         </entry>
6019         <entry></entry>
6020         <entry></entry>
6021        </row>
6022
6023        <row>
6024         <entry><literal><function>statement_timestamp</function>()</literal></entry>
6025         <entry><type>timestamp with time zone</type></entry>
6026         <entry>Current date and time (start of current statement);
6027          see <xref linkend="functions-datetime-current">
6028         </entry>
6029         <entry></entry>
6030         <entry></entry>
6031        </row>
6032
6033        <row>
6034         <entry><literal><function>timeofday</function>()</literal></entry>
6035         <entry><type>text</type></entry>
6036         <entry>Current date and time
6037          (like <function>clock_timestamp</>, but as a <type>text</> string);
6038          see <xref linkend="functions-datetime-current">
6039         </entry>
6040         <entry></entry>
6041         <entry></entry>
6042        </row>
6043
6044        <row>
6045         <entry><literal><function>transaction_timestamp</function>()</literal></entry>
6046         <entry><type>timestamp with time zone</type></entry>
6047         <entry>Current date and time (start of current transaction);
6048          see <xref linkend="functions-datetime-current">
6049         </entry>
6050         <entry></entry>
6051         <entry></entry>
6052        </row>
6053       </tbody>
6054      </tgroup>
6055     </table>
6056
6057    <para>
6058     In addition to these functions, the SQL <literal>OVERLAPS</> operator is
6059     supported:
6060 <synopsis>
6061 (<replaceable>start1</replaceable>, <replaceable>end1</replaceable>) OVERLAPS (<replaceable>start2</replaceable>, <replaceable>end2</replaceable>)
6062 (<replaceable>start1</replaceable>, <replaceable>length1</replaceable>) OVERLAPS (<replaceable>start2</replaceable>, <replaceable>length2</replaceable>)
6063 </synopsis>
6064     This expression yields true when two time periods (defined by their
6065     endpoints) overlap, false when they do not overlap.  The endpoints
6066     can be specified as pairs of dates, times, or time stamps; or as
6067     a date, time, or time stamp followed by an interval.
6068    </para>
6069
6070 <screen>
6071 SELECT (DATE '2001-02-16', DATE '2001-12-21') OVERLAPS
6072        (DATE '2001-10-30', DATE '2002-10-30');
6073 <lineannotation>Result: </lineannotation><computeroutput>true</computeroutput>
6074 SELECT (DATE '2001-02-16', INTERVAL '100 days') OVERLAPS
6075        (DATE '2001-10-30', DATE '2002-10-30');
6076 <lineannotation>Result: </lineannotation><computeroutput>false</computeroutput>
6077 </screen>
6078
6079   <para>
6080    When adding an <type>interval</type> value to (or subtracting an
6081    <type>interval</type> value from) a <type>timestamp with time zone</type>
6082    value, the days component advances (or decrements) the date of the
6083    <type>timestamp with time zone</type> by the indicated number of days.
6084    Across daylight saving time changes (with the session time zone set to a
6085    time zone that recognizes DST), this means <literal>interval '1 day'</literal>
6086    does not necessarily equal <literal>interval '24 hours'</literal>.
6087    For example, with the session time zone set to <literal>CST7CDT</literal>,
6088    <literal>timestamp with time zone '2005-04-02 12:00-07' + interval '1 day' </literal>
6089    will produce <literal>timestamp with time zone '2005-04-03 12:00-06'</literal>,
6090    while adding <literal>interval '24 hours'</literal> to the same initial
6091    <type>timestamp with time zone</type> produces
6092    <literal>timestamp with time zone '2005-04-03 13:00-06'</literal>, as there is
6093    a change in daylight saving time at <literal>2005-04-03 02:00</literal> in time zone
6094    <literal>CST7CDT</literal>.
6095   </para>
6096
6097   <para>
6098    Note there can be ambiguity in the <literal>months</> returned by
6099    <function>age</> because different months have a different number of
6100    days.  <productname>PostgreSQL</>'s approach uses the month from the
6101    earlier of the two dates when calculating partial months.  For example,
6102    <literal>age('2004-06-01', '2004-04-30')</> uses April to yield
6103    <literal>1 mon 1 day</>, while using May would yield <literal>1 mon 2
6104    days</> because May has 31 days, while April has only 30.
6105   </para>
6106
6107   <sect2 id="functions-datetime-extract">
6108    <title><function>EXTRACT</function>, <function>date_part</function></title>
6109
6110    <indexterm>
6111     <primary>date_part</primary>
6112    </indexterm>
6113    <indexterm>
6114     <primary>extract</primary>
6115    </indexterm>
6116
6117 <synopsis>
6118 EXTRACT(<replaceable>field</replaceable> FROM <replaceable>source</replaceable>)
6119 </synopsis>
6120
6121    <para>
6122     The <function>extract</function> function retrieves subfields
6123     such as year or hour from date/time values.
6124     <replaceable>source</replaceable> must be a value expression of
6125     type <type>timestamp</type>, <type>time</type>, or <type>interval</type>.
6126     (Expressions of type <type>date</type> are
6127     cast to <type>timestamp</type> and can therefore be used as
6128     well.)  <replaceable>field</replaceable> is an identifier or
6129     string that selects what field to extract from the source value.
6130     The <function>extract</function> function returns values of type
6131     <type>double precision</type>.
6132     The following are valid field names:
6133
6134     <!-- alphabetical -->
6135     <variablelist>
6136      <varlistentry>
6137       <term><literal>century</literal></term>
6138       <listitem>
6139        <para>
6140         The century
6141        </para>
6142
6143 <screen>
6144 SELECT EXTRACT(CENTURY FROM TIMESTAMP '2000-12-16 12:21:13');
6145 <lineannotation>Result: </lineannotation><computeroutput>20</computeroutput>
6146 SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40');
6147 <lineannotation>Result: </lineannotation><computeroutput>21</computeroutput>
6148 </screen>
6149
6150        <para>
6151         The first century starts at 0001-01-01 00:00:00 AD, although
6152         they did not know it at the time. This definition applies to all
6153         Gregorian calendar countries. There is no century number 0,
6154         you go from -1 century to 1 century.
6155
6156         If you disagree with this, please write your complaint to:
6157         Pope, Cathedral Saint-Peter of Roma, Vatican.
6158        </para>
6159
6160        <para>
6161         <productname>PostgreSQL</productname> releases before 8.0 did not
6162         follow the conventional numbering of centuries, but just returned
6163         the year field divided by 100.
6164        </para>
6165       </listitem>
6166      </varlistentry>
6167
6168      <varlistentry>
6169       <term><literal>day</literal></term>
6170       <listitem>
6171        <para>
6172         The day (of the month) field (1 - 31)
6173        </para>
6174
6175 <screen>
6176 SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40');
6177 <lineannotation>Result: </lineannotation><computeroutput>16</computeroutput>
6178 </screen>
6179       </listitem>
6180      </varlistentry>
6181
6182      <varlistentry>
6183       <term><literal>decade</literal></term>
6184       <listitem>
6185        <para>
6186         The year field divided by 10
6187        </para>
6188
6189 <screen>
6190 SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40');
6191 <lineannotation>Result: </lineannotation><computeroutput>200</computeroutput>
6192 </screen>
6193       </listitem>
6194      </varlistentry>
6195
6196      <varlistentry>
6197       <term><literal>dow</literal></term>
6198       <listitem>
6199        <para>
6200         The day of the week as Sunday(<literal>0</>) to
6201         Saturday(<literal>6</>)
6202        </para>
6203
6204 <screen>
6205 SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40');
6206 <lineannotation>Result: </lineannotation><computeroutput>5</computeroutput>
6207 </screen>
6208        <para>
6209         Note that <function>extract</function>'s day of the week numbering
6210         differs from that of the <function>to_char(...,
6211         'D')</function> function.
6212        </para>
6213
6214       </listitem>
6215      </varlistentry>
6216
6217      <varlistentry>
6218       <term><literal>doy</literal></term>
6219       <listitem>
6220        <para>
6221         The day of the year (1 - 365/366)
6222        </para>
6223
6224 <screen>
6225 SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
6226 <lineannotation>Result: </lineannotation><computeroutput>47</computeroutput>
6227 </screen>
6228       </listitem>
6229      </varlistentry>
6230
6231      <varlistentry>
6232       <term><literal>epoch</literal></term>
6233       <listitem>
6234        <para>
6235         For <type>date</type> and <type>timestamp</type> values, the
6236         number of seconds since 1970-01-01 00:00:00 UTC (can be negative);
6237         for <type>interval</type> values, the total number
6238         of seconds in the interval
6239        </para>
6240
6241 <screen>
6242 SELECT EXTRACT(EPOCH FROM TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-08');
6243 <lineannotation>Result: </lineannotation><computeroutput>982384720</computeroutput>
6244
6245 SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours');
6246 <lineannotation>Result: </lineannotation><computeroutput>442800</computeroutput>
6247 </screen>
6248
6249        <para>
6250         Here is how you can convert an epoch value back to a time
6251         stamp:
6252        </para>
6253
6254 <screen>
6255 SELECT TIMESTAMP WITH TIME ZONE 'epoch' + 982384720 * INTERVAL '1 second';
6256 </screen>
6257       </listitem>
6258      </varlistentry>
6259
6260      <varlistentry>
6261       <term><literal>hour</literal></term>
6262       <listitem>
6263        <para>
6264         The hour field (0 - 23)
6265        </para>
6266
6267 <screen>
6268 SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40');
6269 <lineannotation>Result: </lineannotation><computeroutput>20</computeroutput>
6270 </screen>
6271       </listitem>
6272      </varlistentry>
6273
6274      <varlistentry>
6275       <term><literal>isodow</literal></term>
6276       <listitem>
6277        <para>
6278         The day of the week as Monday(<literal>1</>) to
6279         Sunday(<literal>7</>)
6280        </para>
6281
6282 <screen>
6283 SELECT EXTRACT(ISODOW FROM TIMESTAMP '2001-02-18 20:38:40');
6284 <lineannotation>Result: </lineannotation><computeroutput>7</computeroutput>
6285 </screen>
6286        <para>
6287         This is identical to <literal>dow</> except for Sunday.  This
6288         matches the <acronym>ISO</> 8601 day of the week numbering.
6289        </para>
6290
6291       </listitem>
6292      </varlistentry>
6293
6294      <varlistentry>
6295       <term><literal>isoyear</literal></term>
6296       <listitem>
6297        <para>
6298         The <acronym>ISO</acronym> 8601 year that the date falls in (not applicable to intervals)
6299        </para>
6300
6301 <screen>
6302 SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-01');
6303 <lineannotation>Result: </lineannotation><computeroutput>2005</computeroutput>
6304 SELECT EXTRACT(ISOYEAR FROM DATE '2006-01-02');
6305 <lineannotation>Result: </lineannotation><computeroutput>2006</computeroutput>
6306 </screen>
6307
6308        <para>
6309         Each <acronym>ISO</acronym> year begins with the Monday of the week containing the 4th of January, so in early January or late December the <acronym>ISO</acronym> year may be different from the Gregorian year.  See the <literal>week</literal> field for more information.
6310        </para>
6311        <para>
6312         This field is not available in PostgreSQL releases prior to 8.3.
6313        </para>
6314       </listitem>
6315      </varlistentry>
6316
6317      <varlistentry>
6318       <term><literal>microseconds</literal></term>
6319       <listitem>
6320        <para>
6321         The seconds field, including fractional parts, multiplied by 1
6322         000 000;  note that this includes full seconds
6323        </para>
6324
6325 <screen>
6326 SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5');
6327 <lineannotation>Result: </lineannotation><computeroutput>28500000</computeroutput>
6328 </screen>
6329       </listitem>
6330      </varlistentry>
6331
6332      <varlistentry>
6333       <term><literal>millennium</literal></term>
6334       <listitem>
6335        <para>
6336         The millennium
6337        </para>
6338
6339 <screen>
6340 SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40');
6341 <lineannotation>Result: </lineannotation><computeroutput>3</computeroutput>
6342 </screen>
6343
6344        <para>
6345         Years in the 1900s are in the second millennium.
6346         The third millennium started January 1, 2001.
6347        </para>
6348
6349        <para>
6350         <productname>PostgreSQL</productname> releases before 8.0 did not
6351         follow the conventional numbering of millennia, but just returned
6352         the year field divided by 1000.
6353        </para>
6354       </listitem>
6355      </varlistentry>
6356
6357      <varlistentry>
6358       <term><literal>milliseconds</literal></term>
6359       <listitem>
6360        <para>
6361         The seconds field, including fractional parts, multiplied by
6362         1000.  Note that this includes full seconds.
6363        </para>
6364
6365 <screen>
6366 SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5');
6367 <lineannotation>Result: </lineannotation><computeroutput>28500</computeroutput>
6368 </screen>
6369       </listitem>
6370      </varlistentry>
6371
6372      <varlistentry>
6373       <term><literal>minute</literal></term>
6374       <listitem>
6375        <para>
6376         The minutes field (0 - 59)
6377        </para>
6378
6379 <screen>
6380 SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40');
6381 <lineannotation>Result: </lineannotation><computeroutput>38</computeroutput>
6382 </screen>
6383       </listitem>
6384      </varlistentry>
6385
6386      <varlistentry>
6387       <term><literal>month</literal></term>
6388       <listitem>
6389        <para>
6390         For <type>timestamp</type> values, the number of the month
6391         within the year (1 - 12) ; for <type>interval</type> values
6392         the number of months, modulo 12 (0 - 11)
6393        </para>
6394
6395 <screen>
6396 SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40');
6397 <lineannotation>Result: </lineannotation><computeroutput>2</computeroutput>
6398
6399 SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months');
6400 <lineannotation>Result: </lineannotation><computeroutput>3</computeroutput>
6401
6402 SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months');
6403 <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput>
6404 </screen>
6405       </listitem>
6406      </varlistentry>
6407
6408      <varlistentry>
6409       <term><literal>quarter</literal></term>
6410       <listitem>
6411        <para>
6412         The quarter of the year (1 - 4) that the date is in
6413        </para>
6414
6415 <screen>
6416 SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40');
6417 <lineannotation>Result: </lineannotation><computeroutput>1</computeroutput>
6418 </screen>
6419       </listitem>
6420      </varlistentry>
6421
6422      <varlistentry>
6423       <term><literal>second</literal></term>
6424       <listitem>
6425        <para>
6426         The seconds field, including fractional parts (0 -
6427         59<footnote><simpara>60 if leap seconds are
6428         implemented by the operating system</simpara></footnote>)
6429        </para>
6430
6431 <screen>
6432 SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40');
6433 <lineannotation>Result: </lineannotation><computeroutput>40</computeroutput>
6434
6435 SELECT EXTRACT(SECOND FROM TIME '17:12:28.5');
6436 <lineannotation>Result: </lineannotation><computeroutput>28.5</computeroutput>
6437 </screen>
6438       </listitem>
6439      </varlistentry>
6440      <varlistentry>
6441       <term><literal>timezone</literal></term>
6442       <listitem>
6443        <para>
6444         The time zone offset from UTC, measured in seconds.  Positive values
6445         correspond to time zones east of UTC, negative values to
6446         zones west of UTC.
6447        </para>
6448       </listitem>
6449      </varlistentry>
6450
6451      <varlistentry>
6452       <term><literal>timezone_hour</literal></term>
6453       <listitem>
6454        <para>
6455         The hour component of the time zone offset
6456        </para>
6457       </listitem>
6458      </varlistentry>
6459
6460      <varlistentry>
6461       <term><literal>timezone_minute</literal></term>
6462       <listitem>
6463        <para>
6464         The minute component of the time zone offset
6465        </para>
6466       </listitem>
6467      </varlistentry>
6468
6469      <varlistentry>
6470       <term><literal>week</literal></term>
6471       <listitem>
6472        <para>
6473         The number of the week of the year that the day is in.  By definition
6474         (<acronym>ISO</acronym> 8601), the first week of a year
6475         contains January 4 of that year.  (The <acronym>ISO</acronym>-8601
6476         week starts on Monday.)  In other words, the first Thursday of
6477         a year is in week 1 of that year.
6478        </para>
6479        <para>
6480         Because of this, it is possible for early January dates to be part of the
6481         52nd or 53rd week of the previous year.  For example, <literal>2005-01-01</>
6482         is part of the 53rd week of year 2004, and <literal>2006-01-01</> is part of
6483         the 52nd week of year 2005.
6484        </para>
6485
6486 <screen>
6487 SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40');
6488 <lineannotation>Result: </lineannotation><computeroutput>7</computeroutput>
6489 </screen>
6490       </listitem>
6491      </varlistentry>
6492
6493      <varlistentry>
6494       <term><literal>year</literal></term>
6495       <listitem>
6496        <para>
6497         The year field.  Keep in mind there is no <literal>0 AD</>, so subtracting
6498         <literal>BC</> years from <literal>AD</> years should be done with care.
6499        </para>
6500
6501 <screen>
6502 SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40');
6503 <lineannotation>Result: </lineannotation><computeroutput>2001</computeroutput>
6504 </screen>
6505       </listitem>
6506      </varlistentry>
6507
6508     </variablelist>
6509    </para>
6510
6511    <para>
6512     The <function>extract</function> function is primarily intended
6513     for computational processing.  For formatting date/time values for
6514     display, see <xref linkend="functions-formatting">.
6515    </para>
6516
6517    <para>
6518     The <function>date_part</function> function is modeled on the traditional
6519     <productname>Ingres</productname> equivalent to the
6520     <acronym>SQL</acronym>-standard function <function>extract</function>:
6521 <synopsis>
6522 date_part('<replaceable>field</replaceable>', <replaceable>source</replaceable>)
6523 </synopsis>
6524     Note that here the <replaceable>field</replaceable> parameter needs to
6525     be a string value, not a name.  The valid field names for
6526     <function>date_part</function> are the same as for
6527     <function>extract</function>.
6528    </para>
6529
6530 <screen>
6531 SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40');
6532 <lineannotation>Result: </lineannotation><computeroutput>16</computeroutput>
6533
6534 SELECT date_part('hour', INTERVAL '4 hours 3 minutes');
6535 <lineannotation>Result: </lineannotation><computeroutput>4</computeroutput>
6536 </screen>
6537
6538   </sect2>
6539
6540   <sect2 id="functions-datetime-trunc">
6541    <title><function>date_trunc</function></title>
6542
6543    <indexterm>
6544     <primary>date_trunc</primary>
6545    </indexterm>
6546
6547    <para>
6548     The function <function>date_trunc</function> is conceptually
6549     similar to the <function>trunc</function> function for numbers.
6550    </para>
6551
6552    <para>
6553 <synopsis>
6554 date_trunc('<replaceable>field</replaceable>', <replaceable>source</replaceable>)
6555 </synopsis>
6556     <replaceable>source</replaceable> is a value expression of type
6557     <type>timestamp</type> or <type>interval</>.
6558     (Values of type <type>date</type> and
6559     <type>time</type> are cast automatically to <type>timestamp</type> or
6560     <type>interval</>, respectively.)
6561     <replaceable>field</replaceable> selects to which precision to
6562     truncate the input value.  The return value is of type
6563     <type>timestamp</type> or <type>interval</>
6564     with all fields that are less significant than the
6565     selected one set to zero (or one, for day and month).
6566    </para>
6567
6568    <para>
6569     Valid values for <replaceable>field</replaceable> are:
6570     <simplelist>
6571      <member><literal>microseconds</literal></member>
6572      <member><literal>milliseconds</literal></member>
6573      <member><literal>second</literal></member>
6574      <member><literal>minute</literal></member>
6575      <member><literal>hour</literal></member>
6576      <member><literal>day</literal></member>
6577      <member><literal>week</literal></member>
6578      <member><literal>month</literal></member>
6579      <member><literal>quarter</literal></member>
6580      <member><literal>year</literal></member>
6581      <member><literal>decade</literal></member>
6582      <member><literal>century</literal></member>
6583      <member><literal>millennium</literal></member>
6584     </simplelist>
6585    </para>
6586
6587    <para>
6588     Examples:
6589 <screen>
6590 SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40');
6591 <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 20:00:00</computeroutput>
6592
6593 SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
6594 <lineannotation>Result: </lineannotation><computeroutput>2001-01-01 00:00:00</computeroutput>
6595 </screen>
6596    </para>
6597   </sect2>
6598
6599   <sect2 id="functions-datetime-zoneconvert">
6600    <title><literal>AT TIME ZONE</literal></title>
6601
6602    <indexterm>
6603     <primary>time zone</primary>
6604     <secondary>conversion</secondary>
6605    </indexterm>
6606
6607    <indexterm>
6608     <primary>AT TIME ZONE</primary>
6609    </indexterm>
6610
6611    <para>
6612     The <literal>AT TIME ZONE</literal> construct allows conversions
6613     of time stamps to different time zones.  <xref
6614     linkend="functions-datetime-zoneconvert-table"> shows its
6615     variants.
6616    </para>
6617
6618     <table id="functions-datetime-zoneconvert-table">
6619      <title><literal>AT TIME ZONE</literal> Variants</title>
6620      <tgroup cols="3">
6621       <thead>
6622        <row>
6623         <entry>Expression</entry>
6624         <entry>Return Type</entry>
6625         <entry>Description</entry>
6626        </row>
6627       </thead>
6628
6629       <tbody>
6630        <row>
6631         <entry>
6632          <literal><type>timestamp without time zone</type> AT TIME ZONE <replaceable>zone</></literal>
6633         </entry>
6634         <entry><type>timestamp with time zone</type></entry>
6635         <entry>Treat given time stamp <emphasis>without time zone</> as located in the specified time zone</entry>
6636        </row>
6637
6638        <row>
6639         <entry>
6640          <literal><type>timestamp with time zone</type> AT TIME ZONE <replaceable>zone</></literal>
6641         </entry>
6642         <entry><type>timestamp without time zone</type></entry>
6643         <entry>Convert given time stamp <emphasis>with time zone</> to the new time
6644         zone, with no time zone designation</entry>
6645        </row>
6646
6647        <row>
6648         <entry>
6649          <literal><type>time with time zone</type> AT TIME ZONE <replaceable>zone</></literal>
6650         </entry>
6651         <entry><type>time with time zone</type></entry>
6652         <entry>Convert given time <emphasis>with time zone</> to the new time zone</entry>
6653        </row>
6654       </tbody>
6655      </tgroup>
6656     </table>
6657
6658    <para>
6659     In these expressions, the desired time zone <replaceable>zone</> can be
6660     specified either as a text string (e.g., <literal>'PST'</literal>)
6661     or as an interval (e.g., <literal>INTERVAL '-08:00'</literal>).
6662     In the text case, a time zone name can be specified in any of the ways
6663     described in <xref linkend="datatype-timezones">.
6664    </para>
6665
6666    <para>
6667     Examples (assuming the local time zone is <literal>PST8PDT</>):
6668 <screen>
6669 SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'MST';
6670 <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 19:38:40-08</computeroutput>
6671
6672 SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE 'MST';
6673 <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 18:38:40</computeroutput>
6674 </screen>
6675     The first example takes a time stamp without time zone and interprets it as MST time
6676     (UTC-7), which is then converted to PST (UTC-8) for display.  The second example takes
6677     a time stamp specified in EST (UTC-5) and converts it to local time in MST (UTC-7).
6678    </para>
6679
6680    <para>
6681     The function <literal><function>timezone</function>(<replaceable>zone</>,
6682     <replaceable>timestamp</>)</literal> is equivalent to the SQL-conforming construct
6683     <literal><replaceable>timestamp</> AT TIME ZONE
6684     <replaceable>zone</></literal>.
6685    </para>
6686   </sect2>
6687
6688   <sect2 id="functions-datetime-current">
6689    <title>Current Date/Time</title>
6690
6691    <indexterm>
6692     <primary>date</primary>
6693     <secondary>current</secondary>
6694    </indexterm>
6695
6696    <indexterm>
6697     <primary>time</primary>
6698     <secondary>current</secondary>
6699    </indexterm>
6700
6701    <para>
6702     <productname>PostgreSQL</productname> provides a number of functions
6703     that return values related to the current date and time.  These
6704     SQL-standard functions all return values based on the start time of
6705     the current transaction:
6706 <synopsis>
6707 CURRENT_DATE
6708 CURRENT_TIME
6709 CURRENT_TIMESTAMP
6710 CURRENT_TIME(<replaceable>precision</replaceable>)
6711 CURRENT_TIMESTAMP(<replaceable>precision</replaceable>)
6712 LOCALTIME
6713 LOCALTIMESTAMP
6714 LOCALTIME(<replaceable>precision</replaceable>)
6715 LOCALTIMESTAMP(<replaceable>precision</replaceable>)
6716 </synopsis>
6717     </para>
6718
6719     <para>
6720      <function>CURRENT_TIME</function> and
6721      <function>CURRENT_TIMESTAMP</function> deliver values with time zone;
6722      <function>LOCALTIME</function> and
6723      <function>LOCALTIMESTAMP</function> deliver values without time zone.
6724     </para>
6725
6726     <para>
6727      <function>CURRENT_TIME</function>,
6728      <function>CURRENT_TIMESTAMP</function>,
6729      <function>LOCALTIME</function>, and
6730      <function>LOCALTIMESTAMP</function>
6731      can optionally take
6732      a precision parameter, which causes the result to be rounded
6733      to that many fractional digits in the seconds field.  Without a precision parameter,
6734      the result is given to the full available precision.
6735     </para>
6736
6737    <para>
6738     Some examples:
6739 <screen>
6740 SELECT CURRENT_TIME;
6741 <lineannotation>Result: </lineannotation><computeroutput>14:39:53.662522-05</computeroutput>
6742
6743 SELECT CURRENT_DATE;
6744 <lineannotation>Result: </lineannotation><computeroutput>2001-12-23</computeroutput>
6745
6746 SELECT CURRENT_TIMESTAMP;
6747 <lineannotation>Result: </lineannotation><computeroutput>2001-12-23 14:39:53.662522-05</computeroutput>
6748
6749 SELECT CURRENT_TIMESTAMP(2);
6750 <lineannotation>Result: </lineannotation><computeroutput>2001-12-23 14:39:53.66-05</computeroutput>
6751
6752 SELECT LOCALTIMESTAMP;
6753 <lineannotation>Result: </lineannotation><computeroutput>2001-12-23 14:39:53.662522</computeroutput>
6754 </screen>
6755    </para>
6756
6757    <para>
6758     Since these functions return
6759     the start time of the current transaction, their values do not
6760     change during the transaction. This is considered a feature:
6761     the intent is to allow a single transaction to have a consistent
6762     notion of the <quote>current</quote> time, so that multiple
6763     modifications within the same transaction bear the same
6764     time stamp.
6765    </para>
6766
6767    <note>
6768     <para>
6769      Other database systems might advance these values more
6770      frequently.
6771     </para>
6772    </note>
6773
6774    <para>
6775     <productname>PostgreSQL</productname> also provides functions that
6776     return the start time of the current statement, as well as the actual
6777     current time at the instant the function is called.  The complete list
6778     of non-SQL-standard time functions is:
6779 <synopsis>
6780 transaction_timestamp()
6781 statement_timestamp()
6782 clock_timestamp()
6783 timeofday()
6784 now()
6785 </synopsis>
6786    </para>
6787
6788    <para>
6789     <function>transaction_timestamp()</> is equivalent to
6790     <function>CURRENT_TIMESTAMP</function>, but is named to clearly reflect
6791     what it returns.
6792     <function>statement_timestamp()</> returns the start time of the current
6793     statement (more specifically, the time of receipt of the latest command
6794     message from the client).
6795     <function>statement_timestamp()</> and <function>transaction_timestamp()</>
6796     return the same value during the first command of a transaction, but might
6797     differ during subsequent commands.
6798     <function>clock_timestamp()</> returns the actual current time, and
6799     therefore its value changes even within a single SQL command.
6800     <function>timeofday()</> is a historical
6801     <productname>PostgreSQL</productname> function.  Like
6802     <function>clock_timestamp()</>, it returns the actual current time,
6803     but as a formatted <type>text</> string rather than a <type>timestamp
6804     with time zone</> value.
6805     <function>now()</> is a traditional <productname>PostgreSQL</productname>
6806     equivalent to <function>transaction_timestamp()</function>.
6807    </para>
6808
6809    <para>
6810     All the date/time data types also accept the special literal value
6811     <literal>now</literal> to specify the current date and time (again,
6812     interpreted as the transaction start time).  Thus,
6813     the following three all return the same result:
6814 <programlisting>
6815 SELECT CURRENT_TIMESTAMP;
6816 SELECT now();
6817 SELECT TIMESTAMP 'now';  -- incorrect for use with DEFAULT
6818 </programlisting>
6819    </para>
6820
6821     <tip>
6822      <para>
6823       You do not want to use the third form when specifying a <literal>DEFAULT</>
6824       clause while creating a table.  The system will convert <literal>now</literal>
6825       to a <type>timestamp</type> as soon as the constant is parsed, so that when
6826       the default value is needed,
6827       the time of the table creation would be used!  The first two
6828       forms will not be evaluated until the default value is used,
6829       because they are function calls.  Thus they will give the desired
6830       behavior of defaulting to the time of row insertion.
6831      </para>
6832     </tip>
6833   </sect2>
6834
6835   <sect2 id="functions-datetime-delay">
6836    <title>Delaying Execution</title>
6837
6838    <indexterm>
6839     <primary>pg_sleep</primary>
6840    </indexterm>
6841    <indexterm>
6842     <primary>sleep</primary>
6843    </indexterm>
6844    <indexterm>
6845     <primary>delay</primary>
6846    </indexterm>
6847
6848    <para>
6849     The following function is available to delay execution of the server
6850     process:
6851 <synopsis>
6852 pg_sleep(<replaceable>seconds</replaceable>)
6853 </synopsis>
6854
6855     <function>pg_sleep</function> makes the current session's process
6856     sleep until <replaceable>seconds</replaceable> seconds have
6857     elapsed.  <replaceable>seconds</replaceable> is a value of type
6858     <type>double precision</>, so fractional-second delays can be specified.
6859     For example:
6860
6861 <programlisting>
6862 SELECT pg_sleep(1.5);
6863 </programlisting>
6864    </para>
6865
6866    <note>
6867      <para>
6868       The effective resolution of the sleep interval is platform-specific;
6869       0.01 seconds is a common value.  The sleep delay will be at least as long
6870       as specified. It might be longer depending on factors such as server load.
6871      </para>
6872    </note>
6873
6874    <warning>
6875      <para>
6876       Make sure that your session does not hold more locks than necessary
6877       when calling <function>pg_sleep</function>.  Otherwise other sessions
6878       might have to wait for your sleeping process, slowing down the entire
6879       system.
6880      </para>
6881    </warning>
6882   </sect2>
6883
6884  </sect1>
6885
6886
6887  <sect1 id="functions-enum">
6888   <title>Enum Support Functions</title>
6889
6890   <para>
6891    For enum types (described in <xref linkend="datatype-enum">),
6892    there are several functions that allow cleaner programming without
6893    hard-coding particular values of an enum type.
6894    These are listed in <xref linkend="functions-enum-table">. The examples
6895    assume an enum type created as:
6896
6897 <programlisting>
6898 CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple');
6899 </programlisting>
6900
6901   </para>
6902
6903   <table id="functions-enum-table">
6904     <title>Enum Support Functions</title>
6905     <tgroup cols="4">
6906      <thead>
6907       <row>
6908        <entry>Function</entry>
6909        <entry>Description</entry>
6910        <entry>Example</entry>
6911        <entry>Example Result</entry>
6912       </row>
6913      </thead>
6914      <tbody>
6915       <row>
6916        <entry><literal>enum_first(anyenum)</literal></entry>
6917        <entry>Returns the first value of the input enum type</entry>
6918        <entry><literal>enum_first(null::rainbow)</literal></entry>
6919        <entry><literal>red</literal></entry>
6920       </row>
6921       <row>
6922        <entry><literal>enum_last(anyenum)</literal></entry>
6923        <entry>Returns the last value of the input enum type</entry>
6924        <entry><literal>enum_last(null::rainbow)</literal></entry>
6925        <entry><literal>purple</literal></entry>
6926       </row>
6927       <row>
6928        <entry><literal>enum_range(anyenum)</literal></entry>
6929        <entry>Returns all values of the input enum type in an ordered array</entry>
6930        <entry><literal>enum_range(null::rainbow)</literal></entry>
6931        <entry><literal>{red,orange,yellow,green,blue,purple}</literal></entry>
6932       </row>
6933       <row>
6934        <entry morerows="2"><literal>enum_range(anyenum, anyenum)</literal></entry>
6935        <entry morerows="2">
6936         Returns the range between the two given enum values, as an ordered
6937         array. The values must be from the same enum type. If the first
6938         parameter is null, the result will start with the first value of
6939         the enum type.
6940         If the second parameter is null, the result will end with the last
6941         value of the enum type.
6942        </entry>
6943        <entry><literal>enum_range('orange'::rainbow, 'green'::rainbow)</literal></entry>
6944        <entry><literal>{orange,yellow,green}</literal></entry>
6945       </row>
6946       <row>
6947        <entry><literal>enum_range(NULL, 'green'::rainbow)</literal></entry>
6948        <entry><literal>{red,orange,yellow,green}</literal></entry>
6949       </row>
6950       <row>
6951        <entry><literal>enum_range('orange'::rainbow, NULL)</literal></entry>
6952        <entry><literal>{orange,yellow,green,blue,purple}</literal></entry>
6953       </row>
6954      </tbody>
6955     </tgroup>
6956    </table>
6957
6958    <para>
6959     Notice that except for the two-argument form of <function>enum_range</>,
6960     these functions disregard the specific value passed to them; they care
6961     only about its declared data type.  Either null or a specific value of
6962     the type can be passed, with the same result.  It is more common to
6963     apply these functions to a table column or function argument than to
6964     a hardwired type name as suggested by the examples.
6965    </para>
6966  </sect1>
6967
6968  <sect1 id="functions-geometry">
6969   <title>Geometric Functions and Operators</title>
6970
6971    <para>
6972     The geometric types <type>point</type>, <type>box</type>,
6973     <type>lseg</type>, <type>line</type>, <type>path</type>,
6974     <type>polygon</type>, and <type>circle</type> have a large set of
6975     native support functions and operators, shown in <xref
6976     linkend="functions-geometry-op-table">, <xref
6977     linkend="functions-geometry-func-table">, and <xref
6978     linkend="functions-geometry-conv-table">.
6979    </para>
6980
6981    <caution>
6982     <para>
6983      Note that the <quote>same as</> operator, <literal>~=</>, represents
6984      the usual notion of equality for the <type>point</type>,
6985      <type>box</type>, <type>polygon</type>, and <type>circle</type> types.
6986      Some of these types also have an <literal>=</> operator, but
6987      <literal>=</> compares
6988      for equal <emphasis>areas</> only.  The other scalar comparison operators
6989      (<literal>&lt;=</> and so on) likewise compare areas for these types.
6990     </para>
6991    </caution>
6992
6993    <table id="functions-geometry-op-table">
6994      <title>Geometric Operators</title>
6995      <tgroup cols="3">
6996       <thead>
6997        <row>
6998         <entry>Operator</entry>
6999         <entry>Description</entry>
7000         <entry>Example</entry>
7001        </row>
7002       </thead>
7003       <tbody>
7004        <row>
7005         <entry> <literal>+</literal> </entry>
7006         <entry>Translation</entry>
7007         <entry><literal>box '((0,0),(1,1))' + point '(2.0,0)'</literal></entry>
7008        </row>
7009        <row>
7010         <entry> <literal>-</literal> </entry>
7011         <entry>Translation</entry>
7012         <entry><literal>box '((0,0),(1,1))' - point '(2.0,0)'</literal></entry>
7013        </row>
7014        <row>
7015         <entry> <literal>*</literal> </entry>
7016         <entry>Scaling/rotation</entry>
7017         <entry><literal>box '((0,0),(1,1))' * point '(2.0,0)'</literal></entry>
7018        </row>
7019        <row>
7020         <entry> <literal>/</literal> </entry>
7021         <entry>Scaling/rotation</entry>
7022         <entry><literal>box '((0,0),(2,2))' / point '(2.0,0)'</literal></entry>
7023        </row>
7024        <row>
7025         <entry> <literal>#</literal> </entry>
7026         <entry>Point or box of intersection</entry>
7027         <entry><literal>'((1,-1),(-1,1))' # '((1,1),(-1,-1))'</literal></entry>
7028        </row>
7029        <row>
7030         <entry> <literal>#</literal> </entry>
7031         <entry>Number of points in path or polygon</entry>
7032         <entry><literal># '((1,0),(0,1),(-1,0))'</literal></entry>
7033        </row>
7034        <row>
7035         <entry> <literal>@-@</literal> </entry>
7036         <entry>Length or circumference</entry>
7037         <entry><literal>@-@ path '((0,0),(1,0))'</literal></entry>
7038        </row>
7039        <row>
7040         <entry> <literal>@@</literal> </entry>
7041         <entry>Center</entry>
7042         <entry><literal>@@ circle '((0,0),10)'</literal></entry>
7043        </row>
7044        <row>
7045         <entry> <literal>##</literal> </entry>
7046         <entry>Closest point to first operand on second operand</entry>
7047         <entry><literal>point '(0,0)' ## lseg '((2,0),(0,2))'</literal></entry>
7048        </row>
7049        <row>
7050         <entry> <literal>&lt;-&gt;</literal> </entry>
7051         <entry>Distance between</entry>
7052         <entry><literal>circle '((0,0),1)' &lt;-&gt; circle '((5,0),1)'</literal></entry>
7053        </row>
7054        <row>
7055         <entry> <literal>&amp;&amp;</literal> </entry>
7056         <entry>Overlaps?</entry>
7057         <entry><literal>box '((0,0),(1,1))' &amp;&amp; box '((0,0),(2,2))'</literal></entry>
7058        </row>
7059        <row>
7060         <entry> <literal>&lt;&lt;</literal> </entry>
7061         <entry>Is strictly left of?</entry>
7062         <entry><literal>circle '((0,0),1)' &lt;&lt; circle '((5,0),1)'</literal></entry>
7063        </row>
7064        <row>
7065         <entry> <literal>&gt;&gt;</literal> </entry>
7066         <entry>Is strictly right of?</entry>
7067         <entry><literal>circle '((5,0),1)' &gt;&gt; circle '((0,0),1)'</literal></entry>
7068        </row>
7069        <row>
7070         <entry> <literal>&amp;&lt;</literal> </entry>
7071         <entry>Does not extend to the right of?</entry>
7072         <entry><literal>box '((0,0),(1,1))' &amp;&lt; box '((0,0),(2,2))'</literal></entry>
7073        </row>
7074        <row>
7075         <entry> <literal>&amp;&gt;</literal> </entry>
7076         <entry>Does not extend to the left of?</entry>
7077         <entry><literal>box '((0,0),(3,3))' &amp;&gt; box '((0,0),(2,2))'</literal></entry>
7078        </row>
7079        <row>
7080         <entry> <literal>&lt;&lt;|</literal> </entry>
7081         <entry>Is strictly below?</entry>
7082         <entry><literal>box '((0,0),(3,3))' &lt;&lt;| box '((3,4),(5,5))'</literal></entry>
7083        </row>
7084        <row>
7085         <entry> <literal>|&gt;&gt;</literal> </entry>
7086         <entry>Is strictly above?</entry>
7087         <entry><literal>box '((3,4),(5,5))' |&gt;&gt; box '((0,0),(3,3))'</literal></entry>
7088        </row>
7089        <row>
7090         <entry> <literal>&amp;&lt;|</literal> </entry>
7091         <entry>Does not extend above?</entry>
7092         <entry><literal>box '((0,0),(1,1))' &amp;&lt;| box '((0,0),(2,2))'</literal></entry>
7093        </row>
7094        <row>
7095         <entry> <literal>|&amp;&gt;</literal> </entry>
7096         <entry>Does not extend below?</entry>
7097         <entry><literal>box '((0,0),(3,3))' |&amp;&gt; box '((0,0),(2,2))'</literal></entry>
7098        </row>
7099        <row>
7100         <entry> <literal>&lt;^</literal> </entry>
7101         <entry>Is below (allows touching)?</entry>
7102         <entry><literal>circle '((0,0),1)' &lt;^ circle '((0,5),1)'</literal></entry>
7103        </row>
7104        <row>
7105         <entry> <literal>&gt;^</literal> </entry>
7106         <entry>Is above (allows touching)?</entry>
7107         <entry><literal>circle '((0,5),1)' &gt;^ circle '((0,0),1)'</literal></entry>
7108        </row>
7109        <row>
7110         <entry> <literal>?#</literal> </entry>
7111         <entry>Intersects?</entry>
7112         <entry><literal>lseg '((-1,0),(1,0))' ?# box '((-2,-2),(2,2))'</literal></entry>
7113        </row>
7114        <row>
7115         <entry> <literal>?-</literal> </entry>
7116         <entry>Is horizontal?</entry>
7117         <entry><literal>?- lseg '((-1,0),(1,0))'</literal></entry>
7118        </row>
7119        <row>
7120         <entry> <literal>?-</literal> </entry>
7121         <entry>Are horizontally aligned?</entry>
7122         <entry><literal>point '(1,0)' ?- point '(0,0)'</literal></entry>
7123        </row>
7124        <row>
7125         <entry> <literal>?|</literal> </entry>
7126         <entry>Is vertical?</entry>
7127         <entry><literal>?| lseg '((-1,0),(1,0))'</literal></entry>
7128        </row>
7129        <row>
7130         <entry> <literal>?|</literal> </entry>
7131         <entry>Are vertically aligned?</entry>
7132         <entry><literal>point '(0,1)' ?| point '(0,0)'</literal></entry>
7133        </row>
7134        <row>
7135         <entry> <literal>?-|</literal> </entry>
7136         <entry>Is perpendicular?</entry>
7137         <entry><literal>lseg '((0,0),(0,1))' ?-| lseg '((0,0),(1,0))'</literal></entry>
7138        </row>
7139        <row>
7140         <entry> <literal>?||</literal> </entry>
7141         <entry>Are parallel?</entry>
7142         <entry><literal>lseg '((-1,0),(1,0))' ?|| lseg '((-1,2),(1,2))'</literal></entry>
7143        </row>
7144        <row>
7145         <entry> <literal>@&gt;</literal> </entry>
7146         <entry>Contains?</entry>
7147         <entry><literal>circle '((0,0),2)' @&gt; point '(1,1)'</literal></entry>
7148        </row>
7149        <row>
7150         <entry> <literal>&lt;@</literal> </entry>
7151         <entry>Contained in or on?</entry>
7152         <entry><literal>point '(1,1)' &lt;@ circle '((0,0),2)'</literal></entry>
7153        </row>
7154        <row>
7155         <entry> <literal>~=</literal> </entry>
7156         <entry>Same as?</entry>
7157         <entry><literal>polygon '((0,0),(1,1))' ~= polygon '((1,1),(0,0))'</literal></entry>
7158        </row>
7159       </tbody>
7160      </tgroup>
7161    </table>
7162
7163    <note>
7164     <para>
7165      Before <productname>PostgreSQL</productname> 8.2, the containment
7166      operators <literal>@&gt;</> and <literal>&lt;@</> were respectively
7167      called <literal>~</> and <literal>@</>.  These names are still
7168      available, but are deprecated and will eventually be removed.
7169     </para>
7170    </note>
7171
7172    <indexterm>
7173     <primary>area</primary>
7174    </indexterm>
7175    <indexterm>
7176     <primary>center</primary>
7177    </indexterm>
7178    <indexterm>
7179     <primary>diameter</primary>
7180    </indexterm>
7181    <indexterm>
7182     <primary>height</primary>
7183    </indexterm>
7184    <indexterm>
7185     <primary>isclosed</primary>
7186    </indexterm>
7187    <indexterm>
7188     <primary>isopen</primary>
7189    </indexterm>
7190    <indexterm>
7191     <primary>length</primary>
7192    </indexterm>
7193    <indexterm>
7194     <primary>npoints</primary>
7195    </indexterm>
7196    <indexterm>
7197     <primary>pclose</primary>
7198    </indexterm>
7199    <indexterm>
7200     <primary>popen</primary>
7201    </indexterm>
7202    <indexterm>
7203     <primary>radius</primary>
7204    </indexterm>
7205    <indexterm>
7206     <primary>width</primary>
7207    </indexterm>
7208
7209    <table id="functions-geometry-func-table">
7210      <title>Geometric Functions</title>
7211      <tgroup cols="4">
7212       <thead>
7213        <row>
7214         <entry>Function</entry>
7215         <entry>Return Type</entry>
7216         <entry>Description</entry>
7217         <entry>Example</entry>
7218        </row>
7219       </thead>
7220       <tbody>
7221        <row>
7222         <entry><literal><function>area</function>(<replaceable>object</>)</literal></entry>
7223         <entry><type>double precision</type></entry>
7224         <entry>area</entry>
7225         <entry><literal>area(box '((0,0),(1,1))')</literal></entry>
7226        </row>
7227        <row>
7228         <entry><literal><function>center</function>(<replaceable>object</>)</literal></entry>
7229         <entry><type>point</type></entry>
7230         <entry>center</entry>
7231         <entry><literal>center(box '((0,0),(1,2))')</literal></entry>
7232        </row>
7233        <row>
7234         <entry><literal><function>diameter</function>(<type>circle</>)</literal></entry>
7235         <entry><type>double precision</type></entry>
7236         <entry>diameter of circle</entry>
7237         <entry><literal>diameter(circle '((0,0),2.0)')</literal></entry>
7238        </row>
7239        <row>
7240         <entry><literal><function>height</function>(<type>box</>)</literal></entry>
7241         <entry><type>double precision</type></entry>
7242         <entry>vertical size of box</entry>
7243         <entry><literal>height(box '((0,0),(1,1))')</literal></entry>
7244        </row>
7245        <row>
7246         <entry><literal><function>isclosed</function>(<type>path</>)</literal></entry>
7247         <entry><type>boolean</type></entry>
7248         <entry>a closed path?</entry>
7249         <entry><literal>isclosed(path '((0,0),(1,1),(2,0))')</literal></entry>
7250        </row>
7251        <row>
7252         <entry><literal><function>isopen</function>(<type>path</>)</literal></entry>
7253         <entry><type>boolean</type></entry>
7254         <entry>an open path?</entry>
7255         <entry><literal>isopen(path '[(0,0),(1,1),(2,0)]')</literal></entry>
7256        </row>
7257        <row>
7258         <entry><literal><function>length</function>(<replaceable>object</>)</literal></entry>
7259         <entry><type>double precision</type></entry>
7260         <entry>length</entry>
7261         <entry><literal>length(path '((-1,0),(1,0))')</literal></entry>
7262        </row>
7263        <row>
7264         <entry><literal><function>npoints</function>(<type>path</>)</literal></entry>
7265         <entry><type>int</type></entry>
7266         <entry>number of points</entry>
7267         <entry><literal>npoints(path '[(0,0),(1,1),(2,0)]')</literal></entry>
7268        </row>
7269        <row>
7270         <entry><literal><function>npoints</function>(<type>polygon</>)</literal></entry>
7271         <entry><type>int</type></entry>
7272         <entry>number of points</entry>
7273         <entry><literal>npoints(polygon '((1,1),(0,0))')</literal></entry>
7274        </row>
7275        <row>
7276         <entry><literal><function>pclose</function>(<type>path</>)</literal></entry>
7277         <entry><type>path</type></entry>
7278         <entry>convert path to closed</entry>
7279         <entry><literal>pclose(path '[(0,0),(1,1),(2,0)]')</literal></entry>
7280        </row>
7281 <![IGNORE[
7282 <!-- Not defined by this name. Implements the intersection operator '#' -->
7283        <row>
7284         <entry><literal><function>point</function>(<type>lseg</>, <type>lseg</>)</literal></entry>
7285         <entry><type>point</type></entry>
7286         <entry>intersection</entry>
7287         <entry><literal>point(lseg '((-1,0),(1,0))',lseg '((-2,-2),(2,2))')</literal></entry>
7288        </row>
7289 ]]>
7290        <row>
7291         <entry><literal><function>popen</function>(<type>path</>)</literal></entry>
7292         <entry><type>path</type></entry>
7293         <entry>convert path to open</entry>
7294         <entry><literal>popen(path '((0,0),(1,1),(2,0))')</literal></entry>
7295        </row>
7296        <row>
7297         <entry><literal><function>radius</function>(<type>circle</type>)</literal></entry>
7298         <entry><type>double precision</type></entry>
7299         <entry>radius of circle</entry>
7300         <entry><literal>radius(circle '((0,0),2.0)')</literal></entry>
7301        </row>
7302        <row>
7303         <entry><literal><function>width</function>(<type>box</>)</literal></entry>
7304         <entry><type>double precision</type></entry>
7305         <entry>horizontal size of box</entry>
7306         <entry><literal>width(box '((0,0),(1,1))')</literal></entry>
7307        </row>
7308       </tbody>
7309      </tgroup>
7310    </table>
7311
7312    <table id="functions-geometry-conv-table">
7313      <title>Geometric Type Conversion Functions</title>
7314      <tgroup cols="4">
7315       <thead>
7316        <row>
7317         <entry>Function</entry>
7318         <entry>Return Type</entry>
7319         <entry>Description</entry>
7320         <entry>Example</entry>
7321        </row>
7322       </thead>
7323       <tbody>
7324        <row>
7325         <entry><literal><function>box</function>(<type>circle</type>)</literal></entry>
7326         <entry><type>box</type></entry>
7327         <entry>circle to box</entry>
7328         <entry><literal>box(circle '((0,0),2.0)')</literal></entry>
7329        </row>
7330        <row>
7331         <entry><literal><function>box</function>(<type>point</type>, <type>point</type>)</literal></entry>
7332         <entry><type>box</type></entry>
7333         <entry>points to box</entry>
7334         <entry><literal>box(point '(0,0)', point '(1,1)')</literal></entry>
7335        </row>
7336        <row>
7337         <entry><literal><function>box</function>(<type>polygon</type>)</literal></entry>
7338         <entry><type>box</type></entry>
7339         <entry>polygon to box</entry>
7340         <entry><literal>box(polygon '((0,0),(1,1),(2,0))')</literal></entry>
7341        </row>
7342        <row>
7343         <entry><literal><function>circle</function>(<type>box</type>)</literal></entry>
7344         <entry><type>circle</type></entry>
7345         <entry>box to circle</entry>
7346         <entry><literal>circle(box '((0,0),(1,1))')</literal></entry>
7347        </row>
7348        <row>
7349         <entry><literal><function>circle</function>(<type>point</type>, <type>double precision</type>)</literal></entry>
7350         <entry><type>circle</type></entry>
7351         <entry>center and radius to circle</entry>
7352         <entry><literal>circle(point '(0,0)', 2.0)</literal></entry>
7353        </row>
7354        <row>
7355         <entry><literal><function>circle</function>(<type>polygon</type>)</literal></entry>
7356         <entry><type>circle</type></entry>
7357         <entry>polygon to circle</entry>
7358         <entry><literal>circle(polygon '((0,0),(1,1),(2,0))')</literal></entry>
7359        </row>
7360        <row>
7361         <entry><literal><function>lseg</function>(<type>box</type>)</literal></entry>
7362         <entry><type>lseg</type></entry>
7363         <entry>box diagonal to line segment</entry>
7364         <entry><literal>lseg(box '((-1,0),(1,0))')</literal></entry>
7365        </row>
7366        <row>
7367         <entry><literal><function>lseg</function>(<type>point</type>, <type>point</type>)</literal></entry>
7368         <entry><type>lseg</type></entry>
7369         <entry>points to line segment</entry>
7370         <entry><literal>lseg(point '(-1,0)', point '(1,0)')</literal></entry>
7371        </row>
7372        <row>
7373         <entry><literal><function>path</function>(<type>polygon</type>)</literal></entry>
7374         <entry><type>point</type></entry>
7375         <entry>polygon to path</entry>
7376         <entry><literal>path(polygon '((0,0),(1,1),(2,0))')</literal></entry>
7377        </row>
7378        <row>
7379         <entry><literal><function>point</function>(<type>double
7380          precision</type>, <type>double precision</type>)</literal></entry>
7381         <entry><type>point</type></entry>
7382         <entry>construct point</entry>
7383         <entry><literal>point(23.4, -44.5)</literal></entry>
7384        </row>
7385        <row>
7386         <entry><literal><function>point</function>(<type>box</type>)</literal></entry>
7387         <entry><type>point</type></entry>
7388         <entry>center of box</entry>
7389         <entry><literal>point(box '((-1,0),(1,0))')</literal></entry>
7390        </row>
7391        <row>
7392         <entry><literal><function>point</function>(<type>circle</type>)</literal></entry>
7393         <entry><type>point</type></entry>
7394         <entry>center of circle</entry>
7395         <entry><literal>point(circle '((0,0),2.0)')</literal></entry>
7396        </row>
7397        <row>
7398         <entry><literal><function>point</function>(<type>lseg</type>)</literal></entry>
7399         <entry><type>point</type></entry>
7400         <entry>center of line segment</entry>
7401         <entry><literal>point(lseg '((-1,0),(1,0))')</literal></entry>
7402        </row>
7403        <row>
7404         <entry><literal><function>point</function>(<type>polygon</type>)</literal></entry>
7405         <entry><type>point</type></entry>
7406         <entry>center of polygon</entry>
7407         <entry><literal>point(polygon '((0,0),(1,1),(2,0))')</literal></entry>
7408        </row>
7409        <row>
7410         <entry><literal><function>polygon</function>(<type>box</type>)</literal></entry>
7411         <entry><type>polygon</type></entry>
7412         <entry>box to 4-point polygon</entry>
7413         <entry><literal>polygon(box '((0,0),(1,1))')</literal></entry>
7414        </row>
7415        <row>
7416         <entry><literal><function>polygon</function>(<type>circle</type>)</literal></entry>
7417         <entry><type>polygon</type></entry>
7418         <entry>circle to 12-point polygon</entry>
7419         <entry><literal>polygon(circle '((0,0),2.0)')</literal></entry>
7420        </row>
7421        <row>
7422         <entry><literal><function>polygon</function>(<replaceable class="parameter">npts</replaceable>, <type>circle</type>)</literal></entry>
7423         <entry><type>polygon</type></entry>
7424         <entry>circle to <replaceable class="parameter">npts</replaceable>-point polygon</entry>
7425         <entry><literal>polygon(12, circle '((0,0),2.0)')</literal></entry>
7426        </row>
7427        <row>
7428         <entry><literal><function>polygon</function>(<type>path</type>)</literal></entry>
7429         <entry><type>polygon</type></entry>
7430         <entry>path to polygon</entry>
7431         <entry><literal>polygon(path '((0,0),(1,1),(2,0))')</literal></entry>
7432        </row>
7433       </tbody>
7434      </tgroup>
7435    </table>
7436
7437     <para>
7438      It is possible to access the two component numbers of a <type>point</>
7439      as though the point were an array with indexes 0 and 1.  For example, if
7440      <literal>t.p</> is a <type>point</> column then
7441      <literal>SELECT p[0] FROM t</> retrieves the X coordinate and
7442      <literal>UPDATE t SET p[1] = ...</> changes the Y coordinate.
7443      In the same way, a value of type <type>box</> or <type>lseg</> can be treated
7444      as an array of two <type>point</> values.
7445     </para>
7446
7447     <para>
7448      The <function>area</function> function works for the types
7449      <type>box</type>, <type>circle</type>, and <type>path</type>.
7450      The <function>area</function> function only works on the
7451      <type>path</type> data type if the points in the
7452      <type>path</type> are non-intersecting.  For example, the
7453      <type>path</type>
7454      <literal>'((0,0),(0,1),(2,1),(2,2),(1,2),(1,0),(0,0))'::PATH</literal>
7455      will not work;  however, the following visually identical
7456      <type>path</type>
7457      <literal>'((0,0),(0,1),(1,1),(1,2),(2,2),(2,1),(1,1),(1,0),(0,0))'::PATH</literal>
7458      will work.  If the concept of an intersecting versus
7459      non-intersecting <type>path</type> is confusing, draw both of the
7460      above <type>path</type>s side by side on a piece of graph paper.
7461     </para>
7462
7463   </sect1>
7464
7465
7466  <sect1 id="functions-net">
7467   <title>Network Address Functions and Operators</title>
7468
7469   <para>
7470    <xref linkend="cidr-inet-operators-table"> shows the operators
7471    available for the <type>cidr</type> and <type>inet</type> types.
7472    The operators <literal>&lt;&lt;</literal>,
7473    <literal>&lt;&lt;=</literal>, <literal>&gt;&gt;</literal>, and
7474    <literal>&gt;&gt;=</literal> test for subnet inclusion.  They
7475    consider only the network parts of the two addresses (ignoring any
7476    host part) and determine whether one network is identical to
7477    or a subnet of the other.
7478   </para>
7479
7480     <table id="cidr-inet-operators-table">
7481      <title><type>cidr</type> and <type>inet</type> Operators</title>
7482      <tgroup cols="3">
7483       <thead>
7484        <row>
7485         <entry>Operator</entry>
7486         <entry>Description</entry>
7487         <entry>Example</entry>
7488        </row>
7489       </thead>
7490       <tbody>
7491        <row>
7492         <entry> <literal>&lt;</literal> </entry>
7493         <entry>is less than</entry>
7494         <entry><literal>inet '192.168.1.5' &lt; inet '192.168.1.6'</literal></entry>
7495        </row>
7496        <row>
7497         <entry> <literal>&lt;=</literal> </entry>
7498         <entry>is less than or equal</entry>
7499         <entry><literal>inet '192.168.1.5' &lt;= inet '192.168.1.5'</literal></entry>
7500        </row>
7501        <row>
7502         <entry> <literal>=</literal> </entry>
7503         <entry>equals</entry>
7504         <entry><literal>inet '192.168.1.5' = inet '192.168.1.5'</literal></entry>
7505        </row>
7506        <row>
7507         <entry> <literal>&gt;=</literal> </entry>
7508         <entry>is greater or equal</entry>
7509         <entry><literal>inet '192.168.1.5' &gt;= inet '192.168.1.5'</literal></entry>
7510        </row>
7511        <row>
7512         <entry> <literal>&gt;</literal> </entry>
7513         <entry>is greater than</entry>
7514         <entry><literal>inet '192.168.1.5' &gt; inet '192.168.1.4'</literal></entry>
7515        </row>
7516        <row>
7517         <entry> <literal>&lt;&gt;</literal> </entry>
7518         <entry>is not equal</entry>
7519         <entry><literal>inet '192.168.1.5' &lt;&gt; inet '192.168.1.4'</literal></entry>
7520        </row>
7521        <row>
7522         <entry> <literal>&lt;&lt;</literal> </entry>
7523         <entry>is contained within</entry>
7524         <entry><literal>inet '192.168.1.5' &lt;&lt; inet '192.168.1/24'</literal></entry>
7525        </row>
7526        <row>
7527         <entry> <literal>&lt;&lt;=</literal> </entry>
7528         <entry>is contained within or equals</entry>
7529         <entry><literal>inet '192.168.1/24' &lt;&lt;= inet '192.168.1/24'</literal></entry>
7530        </row>
7531        <row>
7532         <entry> <literal>&gt;&gt;</literal> </entry>
7533         <entry>contains</entry>
7534         <entry><literal>inet '192.168.1/24' &gt;&gt; inet '192.168.1.5'</literal></entry>
7535        </row>
7536        <row>
7537         <entry> <literal>&gt;&gt;=</literal> </entry>
7538         <entry>contains or equals</entry>
7539         <entry><literal>inet '192.168.1/24' &gt;&gt;= inet '192.168.1/24'</literal></entry>
7540        </row>
7541        <row>
7542         <entry> <literal>~</literal> </entry>
7543         <entry>bitwise NOT</entry>
7544         <entry><literal>~ inet '192.168.1.6'</literal></entry>
7545        </row>
7546        <row>
7547         <entry> <literal>&amp;</literal> </entry>
7548         <entry>bitwise AND</entry>
7549         <entry><literal>inet '192.168.1.6' &amp; inet '0.0.0.255'</literal></entry>
7550        </row>
7551        <row>
7552         <entry> <literal>|</literal> </entry>
7553         <entry>bitwise OR</entry>
7554         <entry><literal>inet '192.168.1.6' | inet '0.0.0.255'</literal></entry>
7555        </row>
7556        <row>
7557         <entry> <literal>+</literal> </entry>
7558         <entry>addition</entry>
7559         <entry><literal>inet '192.168.1.6' + 25</literal></entry>
7560        </row>
7561        <row>
7562         <entry> <literal>-</literal> </entry>
7563         <entry>subtraction</entry>
7564         <entry><literal>inet '192.168.1.43' - 36</literal></entry>
7565        </row>
7566        <row>
7567         <entry> <literal>-</literal> </entry>
7568         <entry>subtraction</entry>
7569         <entry><literal>inet '192.168.1.43' - inet '192.168.1.19'</literal></entry>
7570        </row>
7571       </tbody>
7572      </tgroup>
7573     </table>
7574
7575   <para>
7576    <xref linkend="cidr-inet-functions-table"> shows the functions
7577    available for use with the <type>cidr</type> and <type>inet</type>
7578    types.  The <function>abbrev</function>, <function>host</function>,
7579    and <function>text</function>
7580    functions are primarily intended to offer alternative display
7581    formats.
7582   </para>
7583
7584     <table id="cidr-inet-functions-table">
7585      <title><type>cidr</type> and <type>inet</type> Functions</title>
7586      <tgroup cols="5">
7587       <thead>
7588        <row>
7589         <entry>Function</entry>
7590         <entry>Return Type</entry>
7591         <entry>Description</entry>
7592         <entry>Example</entry>
7593         <entry>Result</entry>
7594        </row>
7595       </thead>
7596       <tbody>
7597        <row>
7598         <entry><literal><function>abbrev</function>(<type>inet</type>)</literal></entry>
7599         <entry><type>text</type></entry>
7600         <entry>abbreviated display format as text</entry>
7601         <entry><literal>abbrev(inet '10.1.0.0/16')</literal></entry>
7602         <entry><literal>10.1.0.0/16</literal></entry>
7603        </row>
7604        <row>
7605         <entry><literal><function>abbrev</function>(<type>cidr</type>)</literal></entry>
7606         <entry><type>text</type></entry>
7607         <entry>abbreviated display format as text</entry>
7608         <entry><literal>abbrev(cidr '10.1.0.0/16')</literal></entry>
7609         <entry><literal>10.1/16</literal></entry>
7610        </row>
7611        <row>
7612         <entry><literal><function>broadcast</function>(<type>inet</type>)</literal></entry>
7613         <entry><type>inet</type></entry>
7614         <entry>broadcast address for network</entry>
7615         <entry><literal>broadcast('192.168.1.5/24')</literal></entry>
7616         <entry><literal>192.168.1.255/24</literal></entry>
7617        </row>
7618        <row>
7619         <entry><literal><function>family</function>(<type>inet</type>)</literal></entry>
7620         <entry><type>int</type></entry>
7621         <entry>extract family of address; <literal>4</literal> for IPv4,
7622          <literal>6</literal> for IPv6</entry>
7623         <entry><literal>family('::1')</literal></entry>
7624         <entry><literal>6</literal></entry>
7625        </row>
7626        <row>
7627         <entry><literal><function>host</function>(<type>inet</type>)</literal></entry>
7628         <entry><type>text</type></entry>
7629         <entry>extract IP address as text</entry>
7630         <entry><literal>host('192.168.1.5/24')</literal></entry>
7631         <entry><literal>192.168.1.5</literal></entry>
7632        </row>
7633        <row>
7634         <entry><literal><function>hostmask</function>(<type>inet</type>)</literal></entry>
7635         <entry><type>inet</type></entry>
7636         <entry>construct host mask for network</entry>
7637         <entry><literal>hostmask('192.168.23.20/30')</literal></entry>
7638         <entry><literal>0.0.0.3</literal></entry>
7639        </row>
7640        <row>
7641         <entry><literal><function>masklen</function>(<type>inet</type>)</literal></entry>
7642         <entry><type>int</type></entry>
7643         <entry>extract netmask length</entry>
7644         <entry><literal>masklen('192.168.1.5/24')</literal></entry>
7645         <entry><literal>24</literal></entry>
7646        </row>
7647        <row>
7648         <entry><literal><function>netmask</function>(<type>inet</type>)</literal></entry>
7649         <entry><type>inet</type></entry>
7650         <entry>construct netmask for network</entry>
7651         <entry><literal>netmask('192.168.1.5/24')</literal></entry>
7652         <entry><literal>255.255.255.0</literal></entry>
7653        </row>
7654        <row>
7655         <entry><literal><function>network</function>(<type>inet</type>)</literal></entry>
7656         <entry><type>cidr</type></entry>
7657         <entry>extract network part of address</entry>
7658         <entry><literal>network('192.168.1.5/24')</literal></entry>
7659         <entry><literal>192.168.1.0/24</literal></entry>
7660        </row>
7661        <row>
7662         <entry><literal><function>set_masklen</function>(<type>inet</type>, <type>int</type>)</literal></entry>
7663         <entry><type>inet</type></entry>
7664         <entry>set netmask length for <type>inet</type> value</entry>
7665         <entry><literal>set_masklen('192.168.1.5/24', 16)</literal></entry>
7666         <entry><literal>192.168.1.5/16</literal></entry>
7667        </row>
7668        <row>
7669         <entry><literal><function>set_masklen</function>(<type>cidr</type>, <type>int</type>)</literal></entry>
7670         <entry><type>cidr</type></entry>
7671         <entry>set netmask length for <type>cidr</type> value</entry>
7672         <entry><literal>set_masklen('192.168.1.0/24'::cidr, 16)</literal></entry>
7673         <entry><literal>192.168.0.0/16</literal></entry>
7674        </row>
7675        <row>
7676         <entry><literal><function>text</function>(<type>inet</type>)</literal></entry>
7677         <entry><type>text</type></entry>
7678         <entry>extract IP address and netmask length as text</entry>
7679         <entry><literal>text(inet '192.168.1.5')</literal></entry>
7680         <entry><literal>192.168.1.5/32</literal></entry>
7681        </row>
7682       </tbody>
7683      </tgroup>
7684     </table>
7685
7686   <para>
7687    Any <type>cidr</> value can be cast to <type>inet</> implicitly
7688    or explicitly; therefore, the functions shown above as operating on
7689    <type>inet</> also work on <type>cidr</> values.  (Where there are
7690    separate functions for <type>inet</> and <type>cidr</>, it is because
7691    the behavior should be different for the two cases.)
7692    Also, it is permitted to cast an <type>inet</> value to <type>cidr</>.
7693    When this is done, any bits to the right of the netmask are silently zeroed
7694    to create a valid <type>cidr</> value.
7695    In addition,
7696    you can cast a text value to <type>inet</> or <type>cidr</>
7697    using normal casting syntax: for example,
7698    <literal>inet(<replaceable>expression</>)</literal> or
7699    <literal><replaceable>colname</>::cidr</literal>.
7700   </para>
7701
7702   <para>
7703    <xref linkend="macaddr-functions-table"> shows the functions
7704    available for use with the <type>macaddr</type> type.  The function
7705    <literal><function>trunc</function>(<type>macaddr</type>)</literal> returns a MAC
7706    address with the last 3 bytes set to zero.  This can be used to
7707    associate the remaining prefix with a manufacturer.
7708   </para>
7709
7710     <table id="macaddr-functions-table">
7711      <title><type>macaddr</type> Functions</title>
7712      <tgroup cols="5">
7713       <thead>
7714        <row>
7715         <entry>Function</entry>
7716         <entry>Return Type</entry>
7717         <entry>Description</entry>
7718         <entry>Example</entry>
7719         <entry>Result</entry>
7720        </row>
7721       </thead>
7722       <tbody>
7723        <row>
7724         <entry><literal><function>trunc</function>(<type>macaddr</type>)</literal></entry>
7725         <entry><type>macaddr</type></entry>
7726         <entry>set last 3 bytes to zero</entry>
7727         <entry><literal>trunc(macaddr '12:34:56:78:90:ab')</literal></entry>
7728         <entry><literal>12:34:56:00:00:00</literal></entry>
7729        </row>
7730       </tbody>
7731      </tgroup>
7732     </table>
7733
7734    <para>
7735     The <type>macaddr</type> type also supports the standard relational
7736     operators (<literal>&gt;</literal>, <literal>&lt;=</literal>, etc.) for
7737     lexicographical ordering.
7738    </para>
7739
7740   </sect1>
7741
7742
7743  <sect1 id="functions-textsearch">
7744   <title>Text Search Functions and Operators</title>
7745
7746    <indexterm zone="datatype-textsearch">
7747     <primary>full text search</primary>
7748     <secondary>functions and operators</secondary>
7749    </indexterm>
7750
7751    <indexterm zone="datatype-textsearch">
7752     <primary>text search</primary>
7753     <secondary>functions and operators</secondary>
7754    </indexterm>
7755
7756   <para>
7757    <xref linkend="textsearch-operators-table">,
7758    <xref linkend="textsearch-functions-table"> and
7759    <xref linkend="textsearch-functions-debug-table">
7760    summarize the functions and operators that are provided
7761    for full text searching.  See <xref linkend="textsearch"> for a detailed
7762    explanation of <productname>PostgreSQL</productname>'s text search
7763    facility.
7764   </para>
7765
7766     <table id="textsearch-operators-table">
7767      <title>Text Search Operators</title>
7768      <tgroup cols="4">
7769       <thead>
7770        <row>
7771         <entry>Operator</entry>
7772         <entry>Description</entry>
7773         <entry>Example</entry>
7774         <entry>Result</entry>
7775        </row>
7776       </thead>
7777       <tbody>
7778        <row>
7779         <entry> <literal>@@</literal> </entry>
7780         <entry><type>tsvector</> matches <type>tsquery</> ?</entry>
7781         <entry><literal>to_tsvector('fat cats ate rats') @@ to_tsquery('cat &amp; rat')</literal></entry>
7782         <entry><literal>t</literal></entry>
7783        </row>
7784        <row>
7785         <entry> <literal>@@@</literal> </entry>
7786         <entry>deprecated synonym for <literal>@@</></entry>
7787         <entry><literal>to_tsvector('fat cats ate rats') @@@ to_tsquery('cat &amp; rat')</literal></entry>
7788         <entry><literal>t</literal></entry>
7789        </row>
7790        <row>
7791         <entry> <literal>||</literal> </entry>
7792         <entry>concatenate <type>tsvector</>s</entry>
7793         <entry><literal>'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector</literal></entry>
7794         <entry><literal>'a':1 'b':2,5 'c':3 'd':4</literal></entry>
7795        </row>
7796        <row>
7797         <entry> <literal>&amp;&amp;</literal> </entry>
7798         <entry>AND <type>tsquery</>s together</entry>
7799         <entry><literal>'fat | rat'::tsquery &amp;&amp; 'cat'::tsquery</literal></entry>
7800         <entry><literal>( 'fat' | 'rat' ) &amp; 'cat'</literal></entry>
7801        </row>
7802        <row>
7803         <entry> <literal>||</literal> </entry>
7804         <entry>OR <type>tsquery</>s together</entry>
7805         <entry><literal>'fat | rat'::tsquery || 'cat'::tsquery</literal></entry>
7806         <entry><literal>( 'fat' | 'rat' ) | 'cat'</literal></entry>
7807        </row>
7808        <row>
7809         <entry> <literal>!!</literal> </entry>
7810         <entry>negate a <type>tsquery</></entry>
7811         <entry><literal>!! 'cat'::tsquery</literal></entry>
7812         <entry><literal>!'cat'</literal></entry>
7813        </row>
7814        <row>
7815         <entry> <literal>@&gt;</literal> </entry>
7816         <entry><type>tsquery</> contains another ?</entry>
7817         <entry><literal>'cat'::tsquery @&gt; 'cat &amp; rat'::tsquery</literal></entry>
7818         <entry><literal>f</literal></entry>
7819        </row>
7820        <row>
7821         <entry> <literal>&lt;@</literal> </entry>
7822         <entry><type>tsquery</> is contained in ?</entry>
7823         <entry><literal>'cat'::tsquery &lt;@ 'cat &amp; rat'::tsquery</literal></entry>
7824         <entry><literal>t</literal></entry>
7825        </row>
7826       </tbody>
7827      </tgroup>
7828     </table>
7829
7830     <note>
7831      <para>
7832       The <type>tsquery</> containment operators consider only the lexemes
7833       listed in the two queries, ignoring the combining operators.
7834      </para>
7835     </note>
7836
7837     <para>
7838      In addition to the operators shown in the table, the ordinary B-tree
7839      comparison operators (<literal>=</>, <literal>&lt;</>, etc) are defined
7840      for types <type>tsvector</> and <type>tsquery</>.  These are not very
7841      useful for text searching but allow, for example, unique indexes to be
7842      built on columns of these types.
7843     </para>
7844
7845     <table id="textsearch-functions-table">
7846      <title>Text Search Functions</title>
7847      <tgroup cols="5">
7848       <thead>
7849        <row>
7850         <entry>Function</entry>
7851         <entry>Return Type</entry>
7852         <entry>Description</entry>
7853         <entry>Example</entry>
7854         <entry>Result</entry>
7855        </row>
7856       </thead>
7857       <tbody>
7858        <row>
7859         <entry><literal><function>to_tsvector</function>(<optional> <replaceable class="PARAMETER">config</> <type>regconfig</> , </optional> <replaceable class="PARAMETER">document</> <type>text</type>)</literal></entry>
7860         <entry><type>tsvector</type></entry>
7861         <entry>reduce document text to <type>tsvector</></entry>
7862         <entry><literal>to_tsvector('english', 'The Fat Rats')</literal></entry>
7863         <entry><literal>'fat':2 'rat':3</literal></entry>
7864        </row>
7865        <row>
7866         <entry><literal><function>length</function>(<type>tsvector</>)</literal></entry>
7867         <entry><type>integer</type></entry>
7868         <entry>number of lexemes in <type>tsvector</></entry>
7869         <entry><literal>length('fat:2,4 cat:3 rat:5A'::tsvector)</literal></entry>
7870         <entry><literal>3</literal></entry>
7871        </row>
7872        <row>
7873         <entry><literal><function>setweight</function>(<type>tsvector</>, <type>"char"</>)</literal></entry>
7874         <entry><type>tsvector</type></entry>
7875         <entry>assign weight to each element of <type>tsvector</></entry>
7876         <entry><literal>setweight('fat:2,4 cat:3 rat:5B'::tsvector, 'A')</literal></entry>
7877         <entry><literal>'cat':3A 'fat':2A,4A 'rat':5A</literal></entry>
7878        </row>
7879        <row>
7880         <entry><literal><function>strip</function>(<type>tsvector</>)</literal></entry>
7881         <entry><type>tsvector</type></entry>
7882         <entry>remove positions and weights from <type>tsvector</></entry>
7883         <entry><literal>strip('fat:2,4 cat:3 rat:5A'::tsvector)</literal></entry>
7884         <entry><literal>'cat' 'fat' 'rat'</literal></entry>
7885        </row>
7886        <row>
7887         <entry><literal><function>to_tsquery</function>(<optional> <replaceable class="PARAMETER">config</> <type>regconfig</> , </optional> <replaceable class="PARAMETER">query</> <type>text</type>)</literal></entry>
7888         <entry><type>tsquery</type></entry>
7889         <entry>normalize words and convert to <type>tsquery</></entry>
7890         <entry><literal>to_tsquery('english', 'The &amp; Fat &amp; Rats')</literal></entry>
7891         <entry><literal>'fat' &amp; 'rat'</literal></entry>
7892        </row>
7893        <row>
7894         <entry><literal><function>plainto_tsquery</function>(<optional> <replaceable class="PARAMETER">config</> <type>regconfig</> , </optional> <replaceable class="PARAMETER">query</> <type>text</type>)</literal></entry>
7895         <entry><type>tsquery</type></entry>
7896         <entry>produce <type>tsquery</> ignoring punctuation</entry>
7897         <entry><literal>plainto_tsquery('english', 'The Fat Rats')</literal></entry>
7898         <entry><literal>'fat' &amp; 'rat'</literal></entry>
7899        </row>
7900        <row>
7901         <entry><literal><function>numnode</function>(<type>tsquery</>)</literal></entry>
7902         <entry><type>integer</type></entry>
7903         <entry>number of lexemes plus operators in <type>tsquery</></entry>
7904         <entry><literal> numnode('(fat &amp; rat) | cat'::tsquery)</literal></entry>
7905         <entry><literal>5</literal></entry>
7906        </row>
7907        <row>
7908         <entry><literal><function>querytree</function>(<replaceable class="PARAMETER">query</replaceable> <type>tsquery</>)</literal></entry>
7909         <entry><type>text</type></entry>
7910         <entry>get indexable part of a <type>tsquery</></entry>
7911         <entry><literal>querytree('foo &amp; ! bar'::tsquery)</literal></entry>
7912         <entry><literal>'foo'</literal></entry>
7913        </row>
7914        <row>
7915         <entry><literal><function>ts_rank</function>(<optional> <replaceable class="PARAMETER">weights</replaceable> <type>float4[]</>, </optional> <replaceable class="PARAMETER">vector</replaceable> <type>tsvector</>, <replaceable class="PARAMETER">query</replaceable> <type>tsquery</> <optional>, <replaceable class="PARAMETER">normalization</replaceable> <type>integer</> </optional>)</literal></entry>
7916         <entry><type>float4</type></entry>
7917         <entry>rank document for query</entry>
7918         <entry><literal>ts_rank(textsearch, query)</literal></entry>
7919         <entry><literal>0.818</literal></entry>
7920        </row>
7921        <row>
7922         <entry><literal><function>ts_rank_cd</function>(<optional> <replaceable class="PARAMETER">weights</replaceable> <type>float4[]</>, </optional> <replaceable class="PARAMETER">vector</replaceable> <type>tsvector</>, <replaceable class="PARAMETER">query</replaceable> <type>tsquery</> <optional>, <replaceable class="PARAMETER">normalization</replaceable> <type>integer</> </optional>)</literal></entry>
7923         <entry><type>float4</type></entry>
7924         <entry>rank document for query using cover density</entry>
7925         <entry><literal>ts_rank_cd('{0.1, 0.2, 0.4, 1.0}', textsearch, query)</literal></entry>
7926         <entry><literal>2.01317</literal></entry>
7927        </row>
7928        <row>
7929         <entry><literal><function>ts_headline</function>(<optional> <replaceable class="PARAMETER">config</replaceable> <type>regconfig</>, </optional> <replaceable class="PARAMETER">document</replaceable> <type>text</>, <replaceable class="PARAMETER">query</replaceable> <type>tsquery</> <optional>, <replaceable class="PARAMETER">options</replaceable> <type>text</> </optional>)</literal></entry>
7930         <entry><type>text</type></entry>
7931         <entry>display a query match</entry>
7932         <entry><literal>ts_headline('x y z', 'z'::tsquery)</literal></entry>
7933         <entry><literal>x y &lt;b&gt;z&lt;/b&gt;</literal></entry>
7934        </row>
7935        <row>
7936         <entry><literal><function>ts_rewrite</function>(<replaceable class="PARAMETER">query</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">target</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">substitute</replaceable> <type>tsquery</>)</literal></entry>
7937         <entry><type>tsquery</type></entry>
7938         <entry>replace target with substitute within query</entry>
7939         <entry><literal>ts_rewrite('a &amp; b'::tsquery, 'a'::tsquery, 'foo|bar'::tsquery)</literal></entry>
7940         <entry><literal>'b' &amp; ( 'foo' | 'bar' )</literal></entry>
7941        </row>
7942        <row>
7943         <entry><literal><function>ts_rewrite</function>(<replaceable class="PARAMETER">query</replaceable> <type>tsquery</>, <replaceable class="PARAMETER">select</replaceable> <type>text</>)</literal></entry>
7944         <entry><type>tsquery</type></entry>
7945         <entry>replace using targets and substitutes from a <command>SELECT</> command</entry>
7946         <entry><literal>SELECT ts_rewrite('a &amp; b'::tsquery, 'SELECT t,s FROM aliases')</literal></entry>
7947         <entry><literal>'b' &amp; ( 'foo' | 'bar' )</literal></entry>
7948        </row>
7949        <row>
7950         <entry><literal><function>get_current_ts_config</function>()</literal></entry>
7951         <entry><type>regconfig</type></entry>
7952         <entry>get default text search configuration</entry>
7953         <entry><literal>get_current_ts_config()</literal></entry>
7954         <entry><literal>english</literal></entry>
7955        </row>
7956        <row>
7957         <entry><literal><function>tsvector_update_trigger</function>()</literal></entry>
7958         <entry><type>trigger</type></entry>
7959         <entry>trigger function for automatic <type>tsvector</> column update</entry>
7960         <entry><literal>CREATE TRIGGER ... tsvector_update_trigger(tsvcol, 'pg_catalog.swedish', title, body)</literal></entry>
7961         <entry><literal></literal></entry>
7962        </row>
7963        <row>
7964         <entry><literal><function>tsvector_update_trigger_column</function>()</literal></entry>
7965         <entry><type>trigger</type></entry>
7966         <entry>trigger function for automatic <type>tsvector</> column update</entry>
7967         <entry><literal>CREATE TRIGGER ... tsvector_update_trigger_column(tsvcol, configcol, title, body)</literal></entry>
7968         <entry><literal></literal></entry>
7969         <entry><literal></literal></entry>
7970        </row>
7971       </tbody>
7972      </tgroup>
7973     </table>
7974
7975   <note>
7976    <para>
7977     All the text search functions that accept an optional <type>regconfig</>
7978     argument will use the configuration specified by
7979     <xref linkend="guc-default-text-search-config">
7980     when that argument is omitted.
7981    </para>
7982   </note>
7983
7984   <para>
7985    The functions in
7986    <xref linkend="textsearch-functions-debug-table">
7987    are listed separately because they are not usually used in everyday text
7988    searching operations.  They are helpful for development and debugging
7989    of new text search configurations.
7990   </para>
7991
7992     <table id="textsearch-functions-debug-table">
7993      <title>Text Search Debugging Functions</title>
7994      <tgroup cols="5">
7995       <thead>
7996        <row>
7997         <entry>Function</entry>
7998         <entry>Return Type</entry>
7999         <entry>Description</entry>
8000         <entry>Example</entry>
8001         <entry>Result</entry>
8002        </row>
8003       </thead>
8004       <tbody>
8005        <row>
8006         <entry><literal><function>ts_debug</function>(<optional> <replaceable class="PARAMETER">config</replaceable> <type>regconfig</>, </optional> <replaceable class="PARAMETER">document</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">alias</> <type>text</>, OUT <replaceable class="PARAMETER">description</> <type>text</>, OUT <replaceable class="PARAMETER">token</> <type>text</>, OUT <replaceable class="PARAMETER">dictionaries</> <type>regdictionary[]</>, OUT <replaceable class="PARAMETER">dictionary</> <type>regdictionary</>, OUT <replaceable class="PARAMETER">lexemes</> <type>text[]</>)</literal></entry>
8007         <entry><type>setof record</type></entry>
8008         <entry>test a configuration</entry>
8009         <entry><literal>ts_debug('english', 'The Brightest supernovaes')</literal></entry>
8010         <entry><literal>(asciiword,"Word, all ASCII",The,{english_stem},english_stem,{}) ...</literal></entry>
8011        </row>
8012        <row>
8013         <entry><literal><function>ts_lexize</function>(<replaceable class="PARAMETER">dict</replaceable> <type>regdictionary</>, <replaceable class="PARAMETER">token</replaceable> <type>text</>)</literal></entry>
8014         <entry><type>text[]</type></entry>
8015         <entry>test a dictionary</entry>
8016         <entry><literal>ts_lexize('english_stem', 'stars')</literal></entry>
8017         <entry><literal>{star}</literal></entry>
8018        </row>
8019        <row>
8020         <entry><literal><function>ts_parse</function>(<replaceable class="PARAMETER">parser_name</replaceable> <type>text</>, <replaceable class="PARAMETER">document</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">tokid</> <type>integer</>, OUT <replaceable class="PARAMETER">token</> <type>text</>)</literal></entry>
8021         <entry><type>setof record</type></entry>
8022         <entry>test a parser</entry>
8023         <entry><literal>ts_parse('default', 'foo - bar')</literal></entry>
8024         <entry><literal>(1,foo) ...</literal></entry>
8025        </row>
8026        <row>
8027         <entry><literal><function>ts_parse</function>(<replaceable class="PARAMETER">parser_oid</replaceable> <type>oid</>, <replaceable class="PARAMETER">document</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">tokid</> <type>integer</>, OUT <replaceable class="PARAMETER">token</> <type>text</>)</literal></entry>
8028         <entry><type>setof record</type></entry>
8029         <entry>test a parser</entry>
8030         <entry><literal>ts_parse(3722, 'foo - bar')</literal></entry>
8031         <entry><literal>(1,foo) ...</literal></entry>
8032        </row>
8033        <row>
8034         <entry><literal><function>ts_token_type</function>(<replaceable class="PARAMETER">parser_name</> <type>text</>, OUT <replaceable class="PARAMETER">tokid</> <type>integer</>, OUT <replaceable class="PARAMETER">alias</> <type>text</>, OUT <replaceable class="PARAMETER">description</> <type>text</>)</literal></entry>
8035         <entry><type>setof record</type></entry>
8036         <entry>get token types defined by parser</entry>
8037         <entry><literal>ts_token_type('default')</literal></entry>
8038         <entry><literal>(1,asciiword,"Word, all ASCII") ...</literal></entry>
8039        </row>
8040        <row>
8041         <entry><literal><function>ts_token_type</function>(<replaceable class="PARAMETER">parser_oid</> <type>oid</>, OUT <replaceable class="PARAMETER">tokid</> <type>integer</>, OUT <replaceable class="PARAMETER">alias</> <type>text</>, OUT <replaceable class="PARAMETER">description</> <type>text</>)</literal></entry>
8042         <entry><type>setof record</type></entry>
8043         <entry>get token types defined by parser</entry>
8044         <entry><literal>ts_token_type(3722)</literal></entry>
8045         <entry><literal>(1,asciiword,"Word, all ASCII") ...</literal></entry>
8046        </row>
8047        <row>
8048         <entry><literal><function>ts_stat</function>(<replaceable class="PARAMETER">sqlquery</replaceable> <type>text</>, <optional> <replaceable class="PARAMETER">weights</replaceable> <type>text</>, </optional> OUT <replaceable class="PARAMETER">word</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">ndoc</replaceable> <type>integer</>, OUT <replaceable class="PARAMETER">nentry</replaceable> <type>integer</>)</literal></entry>
8049         <entry><type>setof record</type></entry>
8050         <entry>get statistics of a <type>tsvector</> column</entry>
8051         <entry><literal>ts_stat('SELECT vector from apod')</literal></entry>
8052         <entry><literal>(foo,10,15) ...</literal></entry>
8053        </row>
8054       </tbody>
8055      </tgroup>
8056     </table>
8057
8058  </sect1>
8059
8060
8061  <sect1 id="functions-xml">
8062   <title>XML Functions</title>
8063
8064   <para>
8065    The functions and function-like expressions described in this
8066    section operate on values of type <type>xml</type>.  Check <xref
8067    linkend="datatype-xml"> for information about the <type>xml</type>
8068    type.  The function-like expressions <function>xmlparse</function>
8069    and <function>xmlserialize</function> for converting to and from
8070    type <type>xml</type> are not repeated here.  Use of many of these
8071    functions requires the installation to have been built
8072    with <command>configure --with-libxml</>.
8073   </para>
8074
8075   <sect2>
8076    <title>Producing XML Content</title>
8077
8078    <para>
8079     A set of functions and function-like expressions are available for
8080     producing XML content from SQL data.  As such, they are
8081     particularly suitable for formatting query results into XML
8082     documents for processing in client applications.
8083    </para>
8084
8085    <sect3>
8086     <title><literal>xmlcomment</literal></title>
8087
8088     <indexterm>
8089      <primary>xmlcomment</primary>
8090     </indexterm>
8091
8092 <synopsis>
8093 <function>xmlcomment</function>(<replaceable>text</replaceable>)
8094 </synopsis>
8095
8096     <para>
8097      The function <function>xmlcomment</function> creates an XML value
8098      containing an XML comment with the specified text as content.
8099      The text cannot contain <quote><literal>--</literal></quote> or end with a
8100      <quote><literal>-</literal></quote> so that the resulting construct is a valid
8101      XML comment.  If the argument is null, the result is null.
8102     </para>
8103
8104     <para>
8105      Example:
8106 <screen><![CDATA[
8107 SELECT xmlcomment('hello');
8108
8109   xmlcomment
8110 --------------
8111  <!--hello-->
8112 ]]></screen>
8113     </para>
8114    </sect3>
8115
8116    <sect3>
8117     <title><literal>xmlconcat</literal></title>
8118
8119     <indexterm>
8120      <primary>xmlconcat</primary>
8121     </indexterm>
8122
8123  <synopsis>
8124  <function>xmlconcat</function>(<replaceable>xml</replaceable><optional>, ...</optional>)
8125  </synopsis>
8126
8127     <para>
8128      The function <function>xmlconcat</function> concatenates a list
8129      of individual XML values to create a single value containing an
8130      XML content fragment.  Null values are omitted; the result is
8131      only null if there are no nonnull arguments.
8132     </para>
8133
8134     <para>
8135      Example:
8136 <screen><![CDATA[
8137 SELECT xmlconcat('<abc/>', '<bar>foo</bar>');
8138
8139       xmlconcat
8140 ----------------------
8141  <abc/><bar>foo</bar>
8142 ]]></screen>
8143     </para>
8144
8145     <para>
8146      XML declarations, if present, are combined as follows.  If all
8147      argument values have the same XML version declaration, that
8148      version is used in the result, else no version is used.  If all
8149      argument values have the standalone declaration value
8150      <quote>yes</quote>, then that value is used in the result.  If
8151      all argument values have a standalone declaration value and at
8152      least one is <quote>no</quote>, then that is used in the result.
8153      Else the result will have no standalone declaration.  If the
8154      result is determined to require a standalone declaration but no
8155      version declaration, a version declaration with version 1.0 will
8156      be used because XML requires an XML declaration to contain a
8157      version declaration.  Encoding declarations are ignored and
8158      removed in all cases.
8159     </para>
8160
8161     <para>
8162      Example:
8163 <screen><![CDATA[
8164 SELECT xmlconcat('<?xml version="1.1"?><foo/>', '<?xml version="1.1" standalone="no"?><bar/>');
8165
8166              xmlconcat
8167 -----------------------------------
8168  <?xml version="1.1"?><foo/><bar/>
8169 ]]></screen>
8170     </para>
8171    </sect3>
8172
8173    <sect3>
8174     <title><literal>xmlelement</literal></title>
8175
8176    <indexterm>
8177     <primary>xmlelement</primary>
8178    </indexterm>
8179
8180 <synopsis>
8181  <function>xmlelement</function>(name <replaceable>name</replaceable> <optional>, xmlattributes(<replaceable>value</replaceable> <optional>AS <replaceable>attname</replaceable></optional> <optional>, ... </optional>)</optional> <optional><replaceable>, content, ...</replaceable></optional>)
8182  </synopsis>
8183
8184     <para>
8185      The <function>xmlelement</function> expression produces an XML
8186      element with the given name, attributes, and content.
8187     </para>
8188
8189     <para>
8190      Examples:
8191 <screen><![CDATA[
8192 SELECT xmlelement(name foo);
8193
8194  xmlelement
8195 ------------
8196  <foo/>
8197
8198 SELECT xmlelement(name foo, xmlattributes('xyz' as bar));
8199
8200     xmlelement
8201 ------------------
8202  <foo bar="xyz"/>
8203
8204 SELECT xmlelement(name foo, xmlattributes(current_date as bar), 'cont', 'ent');
8205
8206              xmlelement
8207 -------------------------------------
8208  <foo bar="2007-01-26">content</foo>
8209 ]]></screen>
8210     </para>
8211
8212     <para>
8213      Element and attribute names that are not valid XML names are
8214      escaped by replacing the offending characters by the sequence
8215      <literal>_x<replaceable>HHHH</replaceable>_</literal>, where
8216      <replaceable>HHHH</replaceable> is the character's Unicode
8217      codepoint in hexadecimal notation.  For example:
8218 <screen><![CDATA[
8219 SELECT xmlelement(name "foo$bar", xmlattributes('xyz' as "a&b"));
8220
8221             xmlelement
8222 ----------------------------------
8223  <foo_x0024_bar a_x0026_b="xyz"/>
8224 ]]></screen>
8225     </para>
8226
8227     <para>
8228      An explicit attribute name need not be specified if the attribute
8229      value is a column reference, in which case the column's name will
8230      be used as the attribute name by default.  In other cases, the
8231      attribute must be given an explicit name.  So this example is
8232      valid:
8233 <screen>
8234 CREATE TABLE test (a xml, b xml);
8235 SELECT xmlelement(name test, xmlattributes(a, b)) FROM test;
8236 </screen>
8237      But these are not:
8238 <screen>
8239 SELECT xmlelement(name test, xmlattributes('constant'), a, b) FROM test;
8240 SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;
8241 </screen>
8242     </para>
8243
8244     <para>
8245      Element content, if specified, will be formatted according to
8246      its data type.  If the content is itself of type <type>xml</type>,
8247      complex XML documents can be constructed.  For example:
8248 <screen><![CDATA[
8249 SELECT xmlelement(name foo, xmlattributes('xyz' as bar),
8250                             xmlelement(name abc),
8251                             xmlcomment('test'),
8252                             xmlelement(name xyz));
8253
8254                   xmlelement
8255 ----------------------------------------------
8256  <foo bar="xyz"><abc/><!--test--><xyz/></foo>
8257 ]]></screen>
8258
8259      Content of other types will be formatted into valid XML character
8260      data.  This means in particular that the characters &lt;, &gt;,
8261      and &amp; will be converted to entities.  Binary data (data type
8262      <type>bytea</type>) will be represented in base64 or hex
8263      encoding, depending on the setting of the configuration parameter
8264      <xref linkend="guc-xmlbinary">.  The particular behavior for
8265      individual data types is expected to evolve in order to align the
8266      SQL and PostgreSQL data types with the XML Schema specification,
8267      at which point a more precise description will appear.
8268     </para>
8269    </sect3>
8270
8271    <sect3>
8272     <title><literal>xmlforest</literal></title>
8273
8274    <indexterm>
8275     <primary>xmlforest</primary>
8276    </indexterm>
8277
8278  <synopsis>
8279  <function>xmlforest</function>(<replaceable>content</replaceable> <optional>AS <replaceable>name</replaceable></optional> <optional>, ...</optional>)
8280  </synopsis>
8281
8282     <para>
8283      The <function>xmlforest</function> expression produces an XML
8284      forest (sequence) of elements using the given names and content.
8285     </para>
8286
8287     <para>
8288      Examples:
8289 <screen><![CDATA[
8290 SELECT xmlforest('abc' AS foo, 123 AS bar);
8291
8292           xmlforest
8293 ------------------------------
8294  <foo>abc</foo><bar>123</bar>
8295
8296
8297 SELECT xmlforest(table_name, column_name)
8298 FROM information_schema.columns
8299 WHERE table_schema = 'pg_catalog';
8300
8301                                          xmlforest
8302 -------------------------------------------------------------------------------------------
8303  <table_name>pg_authid</table_name><column_name>rolname</column_name>
8304  <table_name>pg_authid</table_name><column_name>rolsuper</column_name>
8305  ...
8306 ]]></screen>
8307
8308      As seen in the second example, the element name can be omitted if
8309      the content value is a column reference, in which case the column
8310      name is used by default.  Otherwise, a name must be specified.
8311     </para>
8312
8313     <para>
8314      Element names that are not valid XML names are escaped as shown
8315      for <function>xmlelement</function> above.  Similarly, content
8316      data is escaped to make valid XML content, unless it is already
8317      of type <type>xml</type>.
8318     </para>
8319
8320     <para>
8321      Note that XML forests are not valid XML documents if they consist
8322      of more than one element, so it might be useful to wrap
8323      <function>xmlforest</function> expressions in
8324      <function>xmlelement</function>.
8325     </para>
8326    </sect3>
8327
8328    <sect3>
8329     <title><literal>xmlpi</literal></title>
8330
8331    <indexterm>
8332     <primary>xmlpi</primary>
8333    </indexterm>
8334
8335  <synopsis>
8336  <function>xmlpi</function>(name <replaceable>target</replaceable> <optional>, <replaceable>content</replaceable></optional>)
8337  </synopsis>
8338
8339     <para>
8340      The <function>xmlpi</function> expression creates an XML
8341      processing instruction.  The content, if present, must not
8342      contain the character sequence <literal>?&gt;</literal>.
8343     </para>
8344
8345     <para>
8346      Example:
8347 <screen><![CDATA[
8348 SELECT xmlpi(name php, 'echo "hello world";');
8349
8350             xmlpi
8351 -----------------------------
8352  <?php echo "hello world";?>
8353 ]]></screen>
8354     </para>
8355    </sect3>
8356
8357    <sect3>
8358     <title><literal>xmlroot</literal></title>
8359
8360    <indexterm>
8361     <primary>xmlroot</primary>
8362    </indexterm>
8363
8364  <synopsis>
8365  <function>xmlroot</function>(<replaceable>xml</replaceable>, version <replaceable>text</replaceable> | no value <optional>, standalone yes|no|no value</optional>)
8366  </synopsis>
8367
8368     <para>
8369      The <function>xmlroot</function> expression alters the properties
8370      of the root node of an XML value.  If a version is specified,
8371      it replaces the value in the root node's version declaration; if a
8372      standalone setting is specified, it replaces the value in the
8373      root node's standalone declaration.
8374     </para>
8375
8376     <para>
8377 <screen><![CDATA[
8378 SELECT xmlroot(xmlparse(document '<?xml version="1.1"?><content>abc</content>'),
8379                version '1.0', standalone yes);
8380
8381                 xmlroot
8382 ----------------------------------------
8383  <?xml version="1.0" standalone="yes"?>
8384  <content>abc</content>
8385 ]]></screen>
8386     </para>
8387    </sect3>
8388
8389    <sect3 id="functions-xml-xmlagg">
8390     <title><literal>xmlagg</literal></title>
8391
8392     <indexterm>
8393      <primary>xmlagg</primary>
8394     </indexterm>
8395
8396 <synopsis>
8397 <function>xmlagg</function>(<replaceable>xml</replaceable>)
8398 </synopsis>
8399
8400     <para>
8401      The function <function>xmlagg</function> is, unlike the other
8402      functions described here, an aggregate function.  It concatenates the
8403      input values to the aggregate function call,
8404      like <function>xmlconcat</function> does.
8405      See <xref linkend="functions-aggregate"> for additional information
8406      about aggregate functions.
8407     </para>
8408
8409     <para>
8410      Example:
8411 <screen><![CDATA[
8412 CREATE TABLE test (y int, x xml);
8413 INSERT INTO test VALUES (1, '<foo>abc</foo>');
8414 INSERT INTO test VALUES (2, '<bar/>');
8415 SELECT xmlagg(x) FROM test;
8416         xmlagg
8417 ----------------------
8418  <foo>abc</foo><bar/>
8419 ]]></screen>
8420     </para>
8421
8422     <para>
8423      To determine the order of the concatenation, something like the
8424      following approach can be used:
8425
8426 <screen><![CDATA[
8427 SELECT xmlagg(x) FROM (SELECT * FROM test ORDER BY y DESC) AS tab;
8428         xmlagg
8429 ----------------------
8430  <bar/><foo>abc</foo>
8431 ]]></screen>
8432
8433      Again, see <xref linkend="functions-aggregate"> for additional
8434      information.
8435     </para>
8436    </sect3>
8437
8438    <sect3>
8439     <title>XML Predicates</title>
8440
8441     <indexterm>
8442      <primary>IS DOCUMENT</primary>
8443     </indexterm>
8444
8445 <synopsis>
8446 <replaceable>xml</replaceable> IS DOCUMENT
8447 </synopsis>
8448
8449     <para>
8450      The expression <literal>IS DOCUMENT</literal> returns true if the
8451      argument XML value is a proper XML document, false if it is not
8452      (that is, it is a content fragment), or null if the argument is
8453      null.  See <xref linkend="datatype-xml"> about the difference
8454      between documents and content fragments.
8455     </para>
8456    </sect3>
8457   </sect2>
8458
8459   <sect2 id="functions-xml-processing">
8460    <title>Processing XML</title>
8461
8462    <indexterm>
8463     <primary>XPath</primary>
8464    </indexterm>
8465
8466    <para>
8467     To process values of data type <type>xml</type>, PostgreSQL offers
8468     the function <function>xpath</function>, which evaluates XPath 1.0
8469     expressions.
8470    </para>
8471
8472 <synopsis>
8473 <function>xpath</function>(<replaceable>xpath</replaceable>, <replaceable>xml</replaceable><optional>, <replaceable>nsarray</replaceable></optional>)
8474 </synopsis>
8475
8476    <para>
8477     The function <function>xpath</function> evaluates the XPath
8478     expression <replaceable>xpath</replaceable> against the XML value
8479     <replaceable>xml</replaceable>.  It returns an array of XML values
8480     corresponding to the node set produced by the XPath expression.
8481    </para>
8482
8483   <para>
8484     The second argument must be a well formed XML document. In particular,
8485     it must have a single root node element.
8486   </para>
8487
8488    <para>
8489     The third argument of the function is an array of namespace
8490     mappings.  This array should be a two-dimensional array with the
8491     length of the second axis being equal to 2 (i.e., it should be an
8492     array of arrays, each of which consists of exactly 2 elements).
8493     The first element of each array entry is the namespace name, the
8494     second the namespace URI.
8495    </para>
8496
8497    <para>
8498     Example:
8499 <screen><![CDATA[
8500 SELECT xpath('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>',
8501              ARRAY[ARRAY['my', 'http://example.com']]);
8502
8503  xpath
8504 --------
8505  {test}
8506 (1 row)
8507 ]]></screen>
8508    </para>
8509   </sect2>
8510
8511   <sect2 id="functions-xml-mapping">
8512    <title>Mapping Tables to XML</title>
8513
8514    <indexterm zone="functions-xml-mapping">
8515     <primary>XML export</primary>
8516    </indexterm>
8517
8518    <para>
8519     The following functions map the contents of relational tables to
8520     XML values.  They can be thought of as XML export functionality:
8521 <synopsis>
8522 table_to_xml(tbl regclass, nulls boolean, tableforest boolean, targetns text)
8523 query_to_xml(query text, nulls boolean, tableforest boolean, targetns text)
8524 cursor_to_xml(cursor refcursor, count int, nulls boolean,
8525               tableforest boolean, targetns text)
8526 </synopsis>
8527     The return type of each function is <type>xml</type>.
8528    </para>
8529
8530    <para>
8531     <function>table_to_xml</function> maps the content of the named
8532     table, passed as parameter <parameter>tbl</parameter>.  The
8533     <type>regclass</type> type accepts strings identifying tables using the
8534     usual notation, including optional schema qualifications and
8535     double quotes.  <function>query_to_xml</function> executes the
8536     query whose text is passed as parameter
8537     <parameter>query</parameter> and maps the result set.
8538     <function>cursor_to_xml</function> fetches the indicated number of
8539     rows from the cursor specified by the parameter
8540     <parameter>cursor</parameter>.  This variant is recommended if
8541     large tables have to be mapped, because the result value is built
8542     up in memory by each function.
8543    </para>
8544
8545    <para>
8546     If <parameter>tableforest</parameter> is false, then the resulting
8547     XML document looks like this:
8548 <screen><![CDATA[
8549 <tablename>
8550   <row>
8551     <columnname1>data</columnname1>
8552     <columnname2>data</columnname2>
8553   </row>
8554
8555   <row>
8556     ...
8557   </row>
8558
8559   ...
8560 </tablename>
8561 ]]></screen>
8562
8563     If <parameter>tableforest</parameter> is true, the result is an
8564     XML content fragment that looks like this:
8565 <screen><![CDATA[
8566 <tablename>
8567   <columnname1>data</columnname1>
8568   <columnname2>data</columnname2>
8569 </tablename>
8570
8571 <tablename>
8572   ...
8573 </tablename>
8574
8575 ...
8576 ]]></screen>
8577
8578     If no table name is available, that is, when mapping a query or a
8579     cursor, the string <literal>table</literal> is used in the first
8580     format, <literal>row</literal> in the second format.
8581    </para>
8582
8583    <para>
8584     The choice between these formats is up to the user.  The first
8585     format is a proper XML document, which will be important in many
8586     applications.  The second format tends to be more useful in the
8587     <function>cursor_to_xml</function> function if the result values are to be
8588     reassembled into one document later on.  The functions for
8589     producing XML content discussed above, in particular
8590     <function>xmlelement</function>, can be used to alter the results
8591     to taste.
8592    </para>
8593
8594    <para>
8595     The data values are mapped in the same way as described for the
8596     function <function>xmlelement</function> above.
8597    </para>
8598
8599    <para>
8600     The parameter <parameter>nulls</parameter> determines whether null
8601     values should be included in the output.  If true, null values in
8602     columns are represented as:
8603 <screen><![CDATA[
8604 <columnname xsi:nil="true"/>
8605 ]]></screen>
8606     where <literal>xsi</literal> is the XML namespace prefix for XML
8607     Schema Instance.  An appropriate namespace declaration will be
8608     added to the result value.  If false, columns containing null
8609     values are simply omitted from the output.
8610    </para>
8611
8612    <para>
8613     The parameter <parameter>targetns</parameter> specifies the
8614     desired XML namespace of the result.  If no particular namespace
8615     is wanted, an empty string should be passed.
8616    </para>
8617
8618    <para>
8619     The following functions return XML Schema documents describing the
8620     mappings performed by the corresponding functions above:
8621 <synopsis>
8622 table_to_xmlschema(tbl regclass, nulls boolean, tableforest boolean, targetns text)
8623 query_to_xmlschema(query text, nulls boolean, tableforest boolean, targetns text)
8624 cursor_to_xmlschema(cursor refcursor, nulls boolean, tableforest boolean, targetns text)
8625 </synopsis>
8626     It is essential that the same parameters are passed in order to
8627     obtain matching XML data mappings and XML Schema documents.
8628    </para>
8629
8630    <para>
8631     The following functions produce XML data mappings and the
8632     corresponding XML Schema in one document (or forest), linked
8633     together.  They can be useful where self-contained and
8634     self-describing results are wanted:
8635 <synopsis>
8636 table_to_xml_and_xmlschema(tbl regclass, nulls boolean, tableforest boolean, targetns text)
8637 query_to_xml_and_xmlschema(query text, nulls boolean, tableforest boolean, targetns text)
8638 </synopsis>
8639    </para>
8640
8641    <para>
8642     In addition, the following functions are available to produce
8643     analogous mappings of entire schemas or the entire current
8644     database:
8645 <synopsis>
8646 schema_to_xml(schema name, nulls boolean, tableforest boolean, targetns text)
8647 schema_to_xmlschema(schema name, nulls boolean, tableforest boolean, targetns text)
8648 schema_to_xml_and_xmlschema(schema name, nulls boolean, tableforest boolean, targetns text)
8649
8650 database_to_xml(nulls boolean, tableforest boolean, targetns text)
8651 database_to_xmlschema(nulls boolean, tableforest boolean, targetns text)
8652 database_to_xml_and_xmlschema(nulls boolean, tableforest boolean, targetns text)
8653 </synopsis>
8654
8655     Note that these potentially produce a lot of data, which needs to
8656     be built up in memory.  When requesting content mappings of large
8657     schemas or databases, it might be worthwhile to consider mapping the
8658     tables separately instead, possibly even through a cursor.
8659    </para>
8660
8661    <para>
8662     The result of a schema content mapping looks like this:
8663
8664 <screen><![CDATA[
8665 <schemaname>
8666
8667 table1-mapping
8668
8669 table2-mapping
8670
8671 ...
8672
8673 </schemaname>]]></screen>
8674
8675     where the format of a table mapping depends on the
8676     <parameter>tableforest</parameter> parameter as explained above.
8677    </para>
8678
8679    <para>
8680     The result of a database content mapping looks like this:
8681
8682 <screen><![CDATA[
8683 <dbname>
8684
8685 <schema1name>
8686   ...
8687 </schema1name>
8688
8689 <schema2name>
8690   ...
8691 </schema2name>
8692
8693 ...
8694
8695 </dbname>]]></screen>
8696
8697     where the schema mapping is as above.
8698    </para>
8699
8700    <para>
8701     As an example of using the output produced by these functions,
8702     <xref linkend="xslt-xml-html"> shows an XSLT stylesheet that
8703     converts the output of
8704     <function>table_to_xml_and_xmlschema</function> to an HTML
8705     document containing a tabular rendition of the table data.  In a
8706     similar manner, the results from these functions can be
8707     converted into other XML-based formats.
8708    </para>
8709
8710    <figure id="xslt-xml-html">
8711     <title>XSLT stylesheet for converting SQL/XML output to HTML</title>
8712 <programlisting><![CDATA[
8713 <?xml version="1.0"?>
8714 <xsl:stylesheet version="1.0"
8715     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
8716     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
8717     xmlns="http://www.w3.org/1999/xhtml"
8718 >
8719
8720   <xsl:output method="xml"
8721       doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
8722       doctype-public="-//W3C/DTD XHTML 1.0 Strict//EN"
8723       indent="yes"/>
8724
8725   <xsl:template match="/*">
8726     <xsl:variable name="schema" select="//xsd:schema"/>
8727     <xsl:variable name="tabletypename"
8728                   select="$schema/xsd:element[@name=name(current())]/@type"/>
8729     <xsl:variable name="rowtypename"
8730                   select="$schema/xsd:complexType[@name=$tabletypename]/xsd:sequence/xsd:element[@name='row']/@type"/>
8731
8732     <html>
8733       <head>
8734         <title><xsl:value-of select="name(current())"/></title>
8735       </head>
8736       <body>
8737         <table>
8738           <tr>
8739             <xsl:for-each select="$schema/xsd:complexType[@name=$rowtypename]/xsd:sequence/xsd:element/@name">
8740               <th><xsl:value-of select="."/></th>
8741             </xsl:for-each>
8742           </tr>
8743
8744           <xsl:for-each select="row">
8745             <tr>
8746               <xsl:for-each select="*">
8747                 <td><xsl:value-of select="."/></td>
8748               </xsl:for-each>
8749             </tr>
8750           </xsl:for-each>
8751         </table>
8752       </body>
8753     </html>
8754   </xsl:template>
8755
8756 </xsl:stylesheet>
8757 ]]></programlisting>
8758    </figure>
8759   </sect2>
8760  </sect1>
8761
8762
8763  <sect1 id="functions-sequence">
8764   <title>Sequence Manipulation Functions</title>
8765
8766   <indexterm>
8767    <primary>sequence</primary>
8768   </indexterm>
8769   <indexterm>
8770    <primary>nextval</primary>
8771   </indexterm>
8772   <indexterm>
8773    <primary>currval</primary>
8774   </indexterm>
8775   <indexterm>
8776    <primary>lastval</primary>
8777   </indexterm>
8778   <indexterm>
8779    <primary>setval</primary>
8780   </indexterm>
8781
8782   <para>
8783    This section describes <productname>PostgreSQL</productname>'s
8784    functions for operating on <firstterm>sequence objects</firstterm>.
8785    Sequence objects (also called sequence generators or just
8786    sequences) are special single-row tables created with <xref
8787    linkend="sql-createsequence" endterm="sql-createsequence-title">.
8788    A sequence object is usually used to generate unique identifiers
8789    for rows of a table.  The sequence functions, listed in <xref
8790    linkend="functions-sequence-table">, provide simple, multiuser-safe
8791    methods for obtaining successive sequence values from sequence
8792    objects.
8793   </para>
8794
8795    <table id="functions-sequence-table">
8796     <title>Sequence Functions</title>
8797     <tgroup cols="3">
8798      <thead>
8799       <row><entry>Function</entry> <entry>Return Type</entry> <entry>Description</entry></row>
8800      </thead>
8801
8802      <tbody>
8803       <row>
8804         <entry><literal><function>currval</function>(<type>regclass</type>)</literal></entry>
8805         <entry><type>bigint</type></entry>
8806         <entry>Return value most recently obtained with
8807         <function>nextval</function> for specified sequence</entry>
8808       </row>
8809       <row>
8810         <entry><literal><function>lastval</function>()</literal></entry>
8811         <entry><type>bigint</type></entry>
8812         <entry>Return value most recently obtained with
8813         <function>nextval</function> for any sequence</entry>
8814       </row>
8815       <row>
8816         <entry><literal><function>nextval</function>(<type>regclass</type>)</literal></entry>
8817         <entry><type>bigint</type></entry>
8818         <entry>Advance sequence and return new value</entry>
8819       </row>
8820       <row>
8821         <entry><literal><function>setval</function>(<type>regclass</type>, <type>bigint</type>)</literal></entry>
8822         <entry><type>bigint</type></entry>
8823         <entry>Set sequence's current value</entry>
8824       </row>
8825       <row>
8826         <entry><literal><function>setval</function>(<type>regclass</type>, <type>bigint</type>, <type>boolean</type>)</literal></entry>
8827         <entry><type>bigint</type></entry>
8828         <entry>Set sequence's current value and <literal>is_called</literal> flag</entry>
8829       </row>
8830      </tbody>
8831     </tgroup>
8832    </table>
8833
8834   <para>
8835    The sequence to be operated on by a sequence function is specified by
8836    a <type>regclass</> argument, which is simply the OID of the sequence in the
8837    <structname>pg_class</> system catalog.  You do not have to look up the
8838    OID by hand, however, since the <type>regclass</> data type's input
8839    converter will do the work for you.  Just write the sequence name enclosed
8840    in single quotes so that it looks like a literal constant.  For
8841    compatibility with the handling of ordinary
8842    <acronym>SQL</acronym> names, the string will be converted to lowercase
8843    unless it contains double quotes around the sequence name.  Thus:
8844 <programlisting>
8845 nextval('foo')      <lineannotation>operates on sequence <literal>foo</literal></>
8846 nextval('FOO')      <lineannotation>operates on sequence <literal>foo</literal></>
8847 nextval('"Foo"')    <lineannotation>operates on sequence <literal>Foo</literal></>
8848 </programlisting>
8849    The sequence name can be schema-qualified if necessary:
8850 <programlisting>
8851 nextval('myschema.foo')     <lineannotation>operates on <literal>myschema.foo</literal></>
8852 nextval('"myschema".foo')   <lineannotation>same as above</lineannotation>
8853 nextval('foo')              <lineannotation>searches search path for <literal>foo</literal></>
8854 </programlisting>
8855    See <xref linkend="datatype-oid"> for more information about
8856    <type>regclass</>.
8857   </para>
8858
8859   <note>
8860    <para>
8861     Before <productname>PostgreSQL</productname> 8.1, the arguments of the
8862     sequence functions were of type <type>text</>, not <type>regclass</>, and
8863     the above-described conversion from a text string to an OID value would
8864     happen at run time during each call.  For backwards compatibility, this
8865     facility still exists, but internally it is now handled as an implicit
8866     coercion from <type>text</> to <type>regclass</> before the function is
8867     invoked.
8868    </para>
8869
8870    <para>
8871     When you write the argument of a sequence function as an unadorned
8872     literal string, it becomes a constant of type <type>regclass</>.
8873     Since this is really just an OID, it will track the originally
8874     identified sequence despite later renaming, schema reassignment,
8875     etc.  This <quote>early binding</> behavior is usually desirable for
8876     sequence references in column defaults and views.  But sometimes you might
8877     want <quote>late binding</> where the sequence reference is resolved
8878     at run time.  To get late-binding behavior, force the constant to be
8879     stored as a <type>text</> constant instead of <type>regclass</>:
8880 <programlisting>
8881 nextval('foo'::text)      <lineannotation><literal>foo</literal> is looked up at runtime</>
8882 </programlisting>
8883     Note that late binding was the only behavior supported in
8884     <productname>PostgreSQL</productname> releases before 8.1, so you
8885     might need to do this to preserve the semantics of old applications.
8886    </para>
8887
8888    <para>
8889     Of course, the argument of a sequence function can be an expression
8890     as well as a constant.  If it is a text expression then the implicit
8891     coercion will result in a run-time lookup.
8892    </para>
8893   </note>
8894
8895   <para>
8896    The available sequence functions are:
8897
8898     <variablelist>
8899      <varlistentry>
8900       <term><function>nextval</function></term>
8901       <listitem>
8902        <para>
8903         Advance the sequence object to its next value and return that
8904         value.  This is done atomically: even if multiple sessions
8905         execute <function>nextval</function> concurrently, each will safely receive
8906         a distinct sequence value.
8907        </para>
8908       </listitem>
8909      </varlistentry>
8910
8911      <varlistentry>
8912       <term><function>currval</function></term>
8913       <listitem>
8914        <para>
8915         Return the value most recently obtained by <function>nextval</function>
8916         for this sequence in the current session.  (An error is
8917         reported if <function>nextval</function> has never been called for this
8918         sequence in this session.)  Because this is returning
8919         a session-local value, it gives a predictable answer whether or not
8920         other sessions have executed <function>nextval</function> since the
8921         current session did.
8922        </para>
8923       </listitem>
8924      </varlistentry>
8925
8926      <varlistentry>
8927       <term><function>lastval</function></term>
8928       <listitem>
8929        <para>
8930         Return the value most recently returned by
8931         <function>nextval</> in the current session. This function is
8932         identical to <function>currval</function>, except that instead
8933         of taking the sequence name as an argument it fetches the
8934         value of the last sequence used by <function>nextval</function>
8935         in the current session. It is an error to call
8936         <function>lastval</function> if <function>nextval</function>
8937         has not yet been called in the current session.
8938        </para>
8939       </listitem>
8940      </varlistentry>
8941
8942      <varlistentry>
8943       <term><function>setval</function></term>
8944       <listitem>
8945        <para>
8946         Reset the sequence object's counter value.  The two-parameter
8947         form sets the sequence's <literal>last_value</literal> field to the
8948         specified value and sets its <literal>is_called</literal> field to
8949         <literal>true</literal>, meaning that the next
8950         <function>nextval</function> will advance the sequence before
8951         returning a value.  The value reported by <function>currval</> is
8952         also set to the specified value.  In the three-parameter form,
8953         <literal>is_called</literal> can be set to either <literal>true</literal>
8954         or <literal>false</literal>.  <literal>true</> has the same effect as
8955         the two-parameter form. If it is set to <literal>false</literal>, the
8956         next <function>nextval</function> will return exactly the specified
8957         value, and sequence advancement commences with the following
8958         <function>nextval</function>.  Furthermore, the value reported by
8959         <function>currval</> is not changed in this case (this is a change
8960         from pre-8.3 behavior).  For example,
8961
8962 <screen>
8963 SELECT setval('foo', 42);           <lineannotation>Next <function>nextval</> will return 43</lineannotation>
8964 SELECT setval('foo', 42, true);     <lineannotation>Same as above</lineannotation>
8965 SELECT setval('foo', 42, false);    <lineannotation>Next <function>nextval</> will return 42</lineannotation>
8966 </screen>
8967
8968         The result returned by <function>setval</function> is just the value of its
8969         second argument.
8970        </para>
8971       </listitem>
8972      </varlistentry>
8973     </variablelist>
8974   </para>
8975
8976   <para>
8977    If a sequence object has been created with default parameters,
8978    successive <function>nextval</function> calls will return successive values
8979    beginning with 1.  Other behaviors can be obtained by using
8980    special parameters in the <xref linkend="sql-createsequence" endterm="sql-createsequence-title"> command;
8981    see its command reference page for more information.
8982   </para>
8983
8984   <important>
8985    <para>
8986     To avoid blocking concurrent transactions that obtain numbers from the
8987     same sequence, a <function>nextval</function> operation is never rolled back;
8988     that is, once a value has been fetched it is considered used, even if the
8989     transaction that did the <function>nextval</function> later aborts.  This means
8990     that aborted transactions might leave unused <quote>holes</quote> in the
8991     sequence of assigned values.  <function>setval</function> operations are never
8992     rolled back, either.
8993    </para>
8994   </important>
8995
8996  </sect1>
8997
8998
8999  <sect1 id="functions-conditional">
9000   <title>Conditional Expressions</title>
9001
9002   <indexterm>
9003    <primary>CASE</primary>
9004   </indexterm>
9005
9006   <indexterm>
9007    <primary>conditional expression</primary>
9008   </indexterm>
9009
9010   <para>
9011    This section describes the <acronym>SQL</acronym>-compliant conditional expressions
9012    available in <productname>PostgreSQL</productname>.
9013   </para>
9014
9015   <tip>
9016    <para>
9017     If your needs go beyond the capabilities of these conditional
9018     expressions, you might want to consider writing a stored procedure
9019     in a more expressive programming language.
9020    </para>
9021   </tip>
9022
9023   <sect2>
9024    <title><literal>CASE</></title>
9025
9026   <para>
9027    The <acronym>SQL</acronym> <token>CASE</token> expression is a
9028    generic conditional expression, similar to if/else statements in
9029    other programming languages:
9030
9031 <synopsis>
9032 CASE WHEN <replaceable>condition</replaceable> THEN <replaceable>result</replaceable>
9033      <optional>WHEN ...</optional>
9034      <optional>ELSE <replaceable>result</replaceable></optional>
9035 END
9036 </synopsis>
9037
9038    <token>CASE</token> clauses can be used wherever
9039    an expression is valid.  Each <replaceable>condition</replaceable> is an
9040    expression that returns a <type>boolean</type> result.  If the condition's
9041    result is true, the value of the <token>CASE</token> expression is the
9042    <replaceable>result</replaceable> that follows the condition, and the
9043    remainder of the <token>CASE</token> expression is not processed.  If the
9044    condition's result is not true, any subsequent <token>WHEN</token> clauses
9045    are examined in the same manner.  If no <token>WHEN</token>
9046    <replaceable>condition</replaceable> yields true, the value of the
9047    <token>CASE</> expression is the <replaceable>result</replaceable> of the
9048    <token>ELSE</token> clause.  If the <token>ELSE</token> clause is
9049    omitted and no condition is true, the result is null.
9050   </para>
9051
9052    <para>
9053     An example:
9054 <screen>
9055 SELECT * FROM test;
9056
9057  a
9058 ---
9059  1
9060  2
9061  3
9062
9063
9064 SELECT a,
9065        CASE WHEN a=1 THEN 'one'
9066             WHEN a=2 THEN 'two'
9067             ELSE 'other'
9068        END
9069     FROM test;
9070
9071  a | case
9072 ---+-------
9073  1 | one
9074  2 | two
9075  3 | other
9076 </screen>
9077    </para>
9078
9079   <para>
9080    The data types of all the <replaceable>result</replaceable>
9081    expressions must be convertible to a single output type.
9082    See <xref linkend="typeconv-union-case"> for more details.
9083   </para>
9084
9085   <para>
9086    There is a <quote>simple</> form of <token>CASE</token> expression
9087    that is a variant of the general form above:
9088
9089 <synopsis>
9090 CASE <replaceable>expression</replaceable>
9091     WHEN <replaceable>value</replaceable> THEN <replaceable>result</replaceable>
9092     <optional>WHEN ...</optional>
9093     <optional>ELSE <replaceable>result</replaceable></optional>
9094 END
9095 </synopsis>
9096
9097    The first
9098    <replaceable>expression</replaceable> is computed, then compared to
9099    each of the <replaceable>value</replaceable> expressions in the
9100    <token>WHEN</token> clauses until one is found that is equal to it.  If
9101    no match is found, the <replaceable>result</replaceable> of the
9102    <token>ELSE</token> clause (or a null value) is returned.  This is similar
9103    to the <function>switch</function> statement in C.
9104   </para>
9105
9106    <para>
9107     The example above can be written using the simple
9108     <token>CASE</token> syntax:
9109 <screen>
9110 SELECT a,
9111        CASE a WHEN 1 THEN 'one'
9112               WHEN 2 THEN 'two'
9113               ELSE 'other'
9114        END
9115     FROM test;
9116
9117  a | case
9118 ---+-------
9119  1 | one
9120  2 | two
9121  3 | other
9122 </screen>
9123    </para>
9124
9125    <para>
9126     A <token>CASE</token> expression does not evaluate any subexpressions
9127     that are not needed to determine the result.  For example, this is a
9128     possible way of avoiding a division-by-zero failure:
9129 <programlisting>
9130 SELECT ... WHERE CASE WHEN x &lt;&gt; 0 THEN y/x &gt; 1.5 ELSE false END;
9131 </programlisting>
9132    </para>
9133   </sect2>
9134
9135   <sect2>
9136    <title><literal>COALESCE</></title>
9137
9138   <indexterm>
9139    <primary>COALESCE</primary>
9140   </indexterm>
9141
9142   <indexterm>
9143    <primary>NVL</primary>
9144   </indexterm>
9145
9146   <indexterm>
9147    <primary>IFNULL</primary>
9148   </indexterm>
9149
9150 <synopsis>
9151 <function>COALESCE</function>(<replaceable>value</replaceable> <optional>, ...</optional>)
9152 </synopsis>
9153
9154   <para>
9155    The <function>COALESCE</function> function returns the first of its
9156    arguments that is not null.  Null is returned only if all arguments
9157    are null.  It is often used to substitute a default value for
9158    null values when data is retrieved for display, for example:
9159 <programlisting>
9160 SELECT COALESCE(description, short_description, '(none)') ...
9161 </programlisting>
9162   </para>
9163
9164    <para>
9165     Like a <token>CASE</token> expression, <function>COALESCE</function> only
9166     evaluates the arguments that are needed to determine the result;
9167     that is, arguments to the right of the first non-null argument are
9168     not evaluated.  This SQL-standard function provides capabilities similar
9169     to <function>NVL</> and <function>IFNULL</>, which are used in some other
9170     database systems.
9171    </para>
9172   </sect2>
9173
9174   <sect2>
9175    <title><literal>NULLIF</></title>
9176
9177   <indexterm>
9178    <primary>NULLIF</primary>
9179   </indexterm>
9180
9181 <synopsis>
9182 <function>NULLIF</function>(<replaceable>value1</replaceable>, <replaceable>value2</replaceable>)
9183 </synopsis>
9184
9185   <para>
9186    The <function>NULLIF</function> function returns a null value if
9187    <replaceable>value1</replaceable> equals <replaceable>value2</replaceable>;
9188    otherwise it returns <replaceable>value1</replaceable>.
9189    This can be used to perform the inverse operation of the
9190    <function>COALESCE</function> example given above:
9191 <programlisting>
9192 SELECT NULLIF(value, '(none)') ...
9193 </programlisting>
9194   </para>
9195   <para>
9196    If <replaceable>value1</replaceable> is <literal>(none)</>, return a null,
9197    otherwise return <replaceable>value1</replaceable>.
9198   </para>
9199
9200   </sect2>
9201
9202   <sect2>
9203    <title><literal>GREATEST</literal> and <literal>LEAST</literal></title>
9204
9205   <indexterm>
9206    <primary>GREATEST</primary>
9207   </indexterm>
9208   <indexterm>
9209    <primary>LEAST</primary>
9210   </indexterm>
9211
9212 <synopsis>
9213 <function>GREATEST</function>(<replaceable>value</replaceable> <optional>, ...</optional>)
9214 </synopsis>
9215 <synopsis>
9216 <function>LEAST</function>(<replaceable>value</replaceable> <optional>, ...</optional>)
9217 </synopsis>
9218
9219    <para>
9220     The <function>GREATEST</> and <function>LEAST</> functions select the
9221     largest or smallest value from a list of any number of expressions.
9222     The expressions must all be convertible to a common data type, which
9223     will be the type of the result
9224     (see <xref linkend="typeconv-union-case"> for details).  NULL values
9225     in the list are ignored.  The result will be NULL only if all the
9226     expressions evaluate to NULL.
9227    </para>
9228
9229    <para>
9230     Note that <function>GREATEST</> and <function>LEAST</> are not in
9231     the SQL standard, but are a common extension.  Some other databases
9232     make them return NULL if any argument is NULL, rather than only when
9233     all are NULL.
9234    </para>
9235   </sect2>
9236  </sect1>
9237
9238  <sect1 id="functions-array">
9239   <title>Array Functions and Operators</title>
9240
9241   <para>
9242    <xref linkend="array-operators-table"> shows the operators
9243    available for array types.
9244   </para>
9245
9246     <table id="array-operators-table">
9247      <title>Array Operators</title>
9248      <tgroup cols="4">
9249       <thead>
9250        <row>
9251         <entry>Operator</entry>
9252         <entry>Description</entry>
9253         <entry>Example</entry>
9254         <entry>Result</entry>
9255        </row>
9256       </thead>
9257       <tbody>
9258        <row>
9259         <entry> <literal>=</literal> </entry>
9260         <entry>equal</entry>
9261         <entry><literal>ARRAY[1.1,2.1,3.1]::int[] = ARRAY[1,2,3]</literal></entry>
9262         <entry><literal>t</literal></entry>
9263        </row>
9264
9265        <row>
9266         <entry> <literal>&lt;&gt;</literal> </entry>
9267         <entry>not equal</entry>
9268         <entry><literal>ARRAY[1,2,3] &lt;&gt; ARRAY[1,2,4]</literal></entry>
9269         <entry><literal>t</literal></entry>
9270        </row>
9271
9272        <row>
9273         <entry> <literal>&lt;</literal> </entry>
9274         <entry>less than</entry>
9275         <entry><literal>ARRAY[1,2,3] &lt; ARRAY[1,2,4]</literal></entry>
9276         <entry><literal>t</literal></entry>
9277        </row>
9278
9279        <row>
9280         <entry> <literal>&gt;</literal> </entry>
9281         <entry>greater than</entry>
9282         <entry><literal>ARRAY[1,4,3] &gt; ARRAY[1,2,4]</literal></entry>
9283         <entry><literal>t</literal></entry>
9284        </row>
9285
9286        <row>
9287         <entry> <literal>&lt;=</literal> </entry>
9288         <entry>less than or equal</entry>
9289         <entry><literal>ARRAY[1,2,3] &lt;= ARRAY[1,2,3]</literal></entry>
9290         <entry><literal>t</literal></entry>
9291        </row>
9292
9293        <row>
9294         <entry> <literal>&gt;=</literal> </entry>
9295         <entry>greater than or equal</entry>
9296         <entry><literal>ARRAY[1,4,3] &gt;= ARRAY[1,4,3]</literal></entry>
9297         <entry><literal>t</literal></entry>
9298        </row>
9299
9300        <row>
9301         <entry> <literal>@&gt;</literal> </entry>
9302         <entry>contains</entry>
9303         <entry><literal>ARRAY[1,4,3] @&gt; ARRAY[3,1]</literal></entry>
9304         <entry><literal>t</literal></entry>
9305        </row>
9306
9307        <row>
9308         <entry> <literal>&lt;@</literal> </entry>
9309         <entry>is contained by</entry>
9310         <entry><literal>ARRAY[2,7] &lt;@ ARRAY[1,7,4,2,6]</literal></entry>
9311         <entry><literal>t</literal></entry>
9312        </row>
9313
9314        <row>
9315         <entry> <literal>&amp;&amp;</literal> </entry>
9316         <entry>overlap (have elements in common)</entry>
9317         <entry><literal>ARRAY[1,4,3] &amp;&amp; ARRAY[2,1]</literal></entry>
9318         <entry><literal>t</literal></entry>
9319        </row>
9320
9321        <row>
9322         <entry> <literal>||</literal> </entry>
9323         <entry>array-to-array concatenation</entry>
9324         <entry><literal>ARRAY[1,2,3] || ARRAY[4,5,6]</literal></entry>
9325         <entry><literal>{1,2,3,4,5,6}</literal></entry>
9326        </row>
9327
9328        <row>
9329         <entry> <literal>||</literal> </entry>
9330         <entry>array-to-array concatenation</entry>
9331         <entry><literal>ARRAY[1,2,3] || ARRAY[[4,5,6],[7,8,9]]</literal></entry>
9332         <entry><literal>{{1,2,3},{4,5,6},{7,8,9}}</literal></entry>
9333        </row>
9334
9335        <row>
9336         <entry> <literal>||</literal> </entry>
9337         <entry>element-to-array concatenation</entry>
9338         <entry><literal>3 || ARRAY[4,5,6]</literal></entry>
9339         <entry><literal>{3,4,5,6}</literal></entry>
9340        </row>
9341
9342        <row>
9343         <entry> <literal>||</literal> </entry>
9344         <entry>array-to-element concatenation</entry>
9345         <entry><literal>ARRAY[4,5,6] || 7</literal></entry>
9346         <entry><literal>{4,5,6,7}</literal></entry>
9347        </row>
9348       </tbody>
9349      </tgroup>
9350     </table>
9351
9352   <para>
9353    Array comparisons compare the array contents element-by-element,
9354    using the default B-Tree comparison function for the element data type.
9355    In multidimensional arrays the elements are visited in row-major order
9356    (last subscript varies most rapidly).
9357    If the contents of two arrays are equal but the dimensionality is
9358    different, the first difference in the dimensionality information
9359    determines the sort order.  (This is a change from versions of
9360    <productname>PostgreSQL</> prior to 8.2: older versions would claim
9361    that two arrays with the same contents were equal, even if the
9362    number of dimensions or subscript ranges were different.)
9363   </para>
9364
9365   <para>
9366    See <xref linkend="arrays"> for more details about array operator
9367    behavior.
9368   </para>
9369
9370   <para>
9371    <xref linkend="array-functions-table"> shows the functions
9372    available for use with array types. See <xref linkend="arrays">
9373    for more information  and examples of the use of these functions.
9374   </para>
9375
9376   <indexterm>
9377     <primary>array_append</primary>
9378   </indexterm>
9379   <indexterm>
9380     <primary>array_cat</primary>
9381   </indexterm>
9382   <indexterm>
9383     <primary>array_ndims</primary>
9384   </indexterm>
9385   <indexterm>
9386     <primary>array_dims</primary>
9387   </indexterm>
9388   <indexterm>
9389     <primary>array_fill</primary>
9390   </indexterm>
9391   <indexterm>
9392     <primary>array_length</primary>
9393   </indexterm>
9394   <indexterm>
9395     <primary>array_lower</primary>
9396   </indexterm>
9397   <indexterm>
9398     <primary>array_prepend</primary>
9399   </indexterm>
9400   <indexterm>
9401     <primary>array_to_string</primary>
9402   </indexterm>
9403  <indexterm>
9404     <primary>array_upper</primary>
9405   </indexterm>
9406   <indexterm>
9407     <primary>string_to_array</primary>
9408   </indexterm>
9409   <indexterm>
9410     <primary>unnest</primary>
9411   </indexterm>
9412
9413     <table id="array-functions-table">
9414      <title>Array Functions</title>
9415      <tgroup cols="5">
9416       <thead>
9417        <row>
9418         <entry>Function</entry>
9419         <entry>Return Type</entry>
9420         <entry>Description</entry>
9421         <entry>Example</entry>
9422         <entry>Result</entry>
9423        </row>
9424       </thead>
9425       <tbody>
9426        <row>
9427         <entry>
9428          <literal>
9429           <function>array_append</function>(<type>anyarray</type>, <type>anyelement</type>)
9430          </literal>
9431         </entry>
9432         <entry><type>anyarray</type></entry>
9433         <entry>append an element to the end of an array</entry>
9434         <entry><literal>array_append(ARRAY[1,2], 3)</literal></entry>
9435         <entry><literal>{1,2,3}</literal></entry>
9436        </row>
9437        <row>
9438         <entry>
9439          <literal>
9440           <function>array_cat</function>(<type>anyarray</type>, <type>anyarray</type>)
9441          </literal>
9442         </entry>
9443         <entry><type>anyarray</type></entry>
9444         <entry>concatenate two arrays</entry>
9445         <entry><literal>array_cat(ARRAY[1,2,3], ARRAY[4,5])</literal></entry>
9446         <entry><literal>{1,2,3,4,5}</literal></entry>
9447        </row>
9448        <row>
9449         <entry>
9450          <literal>
9451           <function>array_ndims</function>(<type>anyarray</type>)
9452          </literal>
9453         </entry>
9454         <entry><type>int</type></entry>
9455         <entry>returns the number of dimensions of the array</entry>
9456         <entry><literal>array_ndims(ARRAY[[1,2,3], [4,5,6]])</literal></entry>
9457         <entry><literal>2</literal></entry>
9458        </row>
9459        <row>
9460         <entry>
9461          <literal>
9462           <function>array_dims</function>(<type>anyarray</type>)
9463          </literal>
9464         </entry>
9465         <entry><type>text</type></entry>
9466         <entry>returns a text representation of array's dimensions</entry>
9467         <entry><literal>array_dims(ARRAY[[1,2,3], [4,5,6]])</literal></entry>
9468         <entry><literal>[1:2][1:3]</literal></entry>
9469        </row>
9470        <row>
9471         <entry>
9472          <literal>
9473           <function>array_fill</function>(<type>anyelement</type>, <type>int[]</type>,
9474           <optional>, <type>int[]</type></optional>)
9475          </literal>
9476         </entry>
9477         <entry><type>anyarray</type></entry>
9478         <entry>returns an array initialized with supplied value and
9479          dimensions, optionally with lower bounds other than 1</entry>
9480         <entry><literal>array_fill(7, ARRAY[3], ARRAY[2])</literal></entry>
9481         <entry><literal>[2:4]={7,7,7}</literal></entry>
9482        </row>
9483        <row>
9484         <entry>
9485          <literal>
9486           <function>array_length</function>(<type>anyarray</type>, <type>int</type>)
9487          </literal>
9488         </entry>
9489         <entry><type>int</type></entry>
9490         <entry>returns the length of the requested array dimension</entry>
9491         <entry><literal>array_length(array[1,2,3], 1)</literal></entry>
9492         <entry><literal>3</literal></entry>
9493        </row>
9494        <row>
9495         <entry>
9496          <literal>
9497           <function>array_lower</function>(<type>anyarray</type>, <type>int</type>)
9498          </literal>
9499         </entry>
9500         <entry><type>int</type></entry>
9501         <entry>returns lower bound of the requested array dimension</entry>
9502         <entry><literal>array_lower('[0:2]={1,2,3}'::int[], 1)</literal></entry>
9503         <entry><literal>0</literal></entry>
9504        </row>
9505        <row>
9506         <entry>
9507          <literal>
9508           <function>array_prepend</function>(<type>anyelement</type>, <type>anyarray</type>)
9509          </literal>
9510         </entry>
9511         <entry><type>anyarray</type></entry>
9512         <entry>append an element to the beginning of an array</entry>
9513         <entry><literal>array_prepend(1, ARRAY[2,3])</literal></entry>
9514         <entry><literal>{1,2,3}</literal></entry>
9515        </row>
9516        <row>
9517         <entry>
9518          <literal>
9519           <function>array_to_string</function>(<type>anyarray</type>, <type>text</type>)
9520          </literal>
9521         </entry>
9522         <entry><type>text</type></entry>
9523         <entry>concatenates array elements using supplied delimiter</entry>
9524         <entry><literal>array_to_string(ARRAY[1, 2, 3], '~^~')</literal></entry>
9525         <entry><literal>1~^~2~^~3</literal></entry>
9526        </row>
9527        <row>
9528         <entry>
9529          <literal>
9530           <function>array_upper</function>(<type>anyarray</type>, <type>int</type>)
9531          </literal>
9532         </entry>
9533         <entry><type>int</type></entry>
9534         <entry>returns upper bound of the requested array dimension</entry>
9535         <entry><literal>array_upper(ARRAY[1,2,3,4], 1)</literal></entry>
9536         <entry><literal>4</literal></entry>
9537        </row>
9538        <row>
9539         <entry>
9540          <literal>
9541           <function>string_to_array</function>(<type>text</type>, <type>text</type>)
9542          </literal>
9543         </entry>
9544         <entry><type>text[]</type></entry>
9545         <entry>splits string into array elements using supplied delimiter</entry>
9546         <entry><literal>string_to_array('xx~^~yy~^~zz', '~^~')</literal></entry>
9547         <entry><literal>{xx,yy,zz}</literal></entry>
9548        </row>
9549        <row>
9550         <entry>
9551          <literal>
9552           <function>unnest</function>(<type>anyarray</type>)
9553          </literal>
9554         </entry>
9555         <entry><type>setof anyelement</type></entry>
9556         <entry>expand an array to a set of rows</entry>
9557         <entry><literal>unnest(ARRAY[1,2])</literal></entry>
9558         <entry><literal>1</literal><para><literal>2</literal></para> (2 rows)</entry>
9559        </row>
9560       </tbody>
9561      </tgroup>
9562     </table>
9563
9564    <para>
9565     See also <xref linkend="functions-aggregate"> about the aggregate
9566     function <function>array_agg</function> for use with arrays.
9567    </para>
9568   </sect1>
9569
9570  <sect1 id="functions-aggregate">
9571   <title>Aggregate Functions</title>
9572
9573   <indexterm zone="functions-aggregate">
9574    <primary>aggregate function</primary>
9575    <secondary>built-in</secondary>
9576   </indexterm>
9577
9578   <para>
9579    <firstterm>Aggregate functions</firstterm> compute a single result
9580    from a set of input values.  The built-in aggregate functions
9581    are listed in
9582    <xref linkend="functions-aggregate-table"> and
9583    <xref linkend="functions-aggregate-statistics-table">.
9584    The special syntax considerations for aggregate
9585    functions are explained in <xref linkend="syntax-aggregates">.
9586    Consult <xref linkend="tutorial-agg"> for additional introductory
9587    information.
9588   </para>
9589
9590   <table id="functions-aggregate-table">
9591    <title>General-Purpose Aggregate Functions</title>
9592
9593    <tgroup cols="4">
9594     <thead>
9595      <row>
9596       <entry>Function</entry>
9597       <entry>Argument Type</entry>
9598       <entry>Return Type</entry>
9599       <entry>Description</entry>
9600      </row>
9601     </thead>
9602
9603     <tbody>
9604      <row>
9605       <entry>
9606        <indexterm>
9607         <primary>array_agg</primary>
9608        </indexterm>
9609        <function>array_agg(<replaceable class="parameter">expression</replaceable>)</function>
9610       </entry>
9611       <entry>
9612        any
9613       </entry>
9614       <entry>
9615        array of the argument type
9616       </entry>
9617       <entry>input values concatenated into an array</entry>
9618      </row>
9619
9620      <row>
9621       <entry>
9622        <indexterm>
9623         <primary>average</primary>
9624        </indexterm>
9625        <function>avg(<replaceable class="parameter">expression</replaceable>)</function>
9626       </entry>
9627       <entry>
9628        <type>smallint</type>, <type>int</type>,
9629        <type>bigint</type>, <type>real</type>, <type>double
9630        precision</type>, <type>numeric</type>, or <type>interval</type>
9631       </entry>
9632       <entry>
9633        <type>numeric</type> for any integer-type argument,
9634        <type>double precision</type> for a floating-point argument,
9635        otherwise the same as the argument data type
9636       </entry>
9637       <entry>the average (arithmetic mean) of all input values</entry>
9638      </row>
9639
9640      <row>
9641       <entry>
9642        <indexterm>
9643         <primary>bit_and</primary>
9644        </indexterm>
9645        <function>bit_and(<replaceable class="parameter">expression</replaceable>)</function>
9646       </entry>
9647       <entry>
9648        <type>smallint</type>, <type>int</type>, <type>bigint</type>, or
9649        <type>bit</type>
9650       </entry>
9651       <entry>
9652         same as argument data type
9653       </entry>
9654       <entry>the bitwise AND of all non-null input values, or null if none</entry>
9655      </row>
9656
9657      <row>
9658       <entry>
9659        <indexterm>
9660         <primary>bit_or</primary>
9661        </indexterm>
9662        <function>bit_or(<replaceable class="parameter">expression</replaceable>)</function>
9663       </entry>
9664       <entry>
9665        <type>smallint</type>, <type>int</type>, <type>bigint</type>, or
9666        <type>bit</type>
9667       </entry>
9668       <entry>
9669         same as argument data type
9670       </entry>
9671       <entry>the bitwise OR of all non-null input values, or null if none</entry>
9672      </row>
9673
9674      <row>
9675       <entry>
9676        <indexterm>
9677         <primary>bool_and</primary>
9678        </indexterm>
9679        <function>bool_and(<replaceable class="parameter">expression</replaceable>)</function>
9680       </entry>
9681       <entry>
9682        <type>bool</type>
9683       </entry>
9684       <entry>
9685        <type>bool</type>
9686       </entry>
9687       <entry>true if all input values are true, otherwise false</entry>
9688      </row>
9689
9690      <row>
9691       <entry>
9692        <indexterm>
9693         <primary>bool_or</primary>
9694        </indexterm>
9695        <function>bool_or(<replaceable class="parameter">expression</replaceable>)</function>
9696       </entry>
9697       <entry>
9698        <type>bool</type>
9699       </entry>
9700       <entry>
9701        <type>bool</type>
9702       </entry>
9703       <entry>true if at least one input value is true, otherwise false</entry>
9704      </row>
9705
9706      <row>
9707       <entry><function>count(*)</function></entry>
9708       <entry></entry>
9709       <entry><type>bigint</type></entry>
9710       <entry>number of input rows</entry>
9711      </row>
9712
9713      <row>
9714       <entry><function>count(<replaceable class="parameter">expression</replaceable>)</function></entry>
9715       <entry>any</entry>
9716       <entry><type>bigint</type></entry>
9717       <entry>
9718        number of input rows for which the value of <replaceable
9719        class="parameter">expression</replaceable> is not null
9720       </entry>
9721      </row>
9722
9723      <row>
9724       <entry>
9725        <indexterm>
9726         <primary>every</primary>
9727        </indexterm>
9728        <function>every(<replaceable class="parameter">expression</replaceable>)</function>
9729       </entry>
9730       <entry>
9731        <type>bool</type>
9732       </entry>
9733       <entry>
9734        <type>bool</type>
9735       </entry>
9736       <entry>equivalent to <function>bool_and</function></entry>
9737      </row>
9738
9739      <row>
9740       <entry><function>max(<replaceable class="parameter">expression</replaceable>)</function></entry>
9741       <entry>any array, numeric, string, or date/time type</entry>
9742       <entry>same as argument type</entry>
9743       <entry>
9744        maximum value of <replaceable
9745        class="parameter">expression</replaceable> across all input
9746        values
9747       </entry>
9748      </row>
9749
9750      <row>
9751       <entry><function>min(<replaceable class="parameter">expression</replaceable>)</function></entry>
9752       <entry>any array, numeric, string, or date/time type</entry>
9753       <entry>same as argument type</entry>
9754       <entry>
9755        minimum value of <replaceable
9756        class="parameter">expression</replaceable> across all input
9757        values
9758       </entry>
9759      </row>
9760
9761      <row>
9762       <entry><function>sum(<replaceable class="parameter">expression</replaceable>)</function></entry>
9763       <entry>
9764        <type>smallint</type>, <type>int</type>,
9765        <type>bigint</type>, <type>real</type>, <type>double
9766        precision</type>, <type>numeric</type>, or
9767        <type>interval</type>
9768       </entry>
9769       <entry>
9770        <type>bigint</type> for <type>smallint</type> or
9771        <type>int</type> arguments, <type>numeric</type> for
9772        <type>bigint</type> arguments, <type>double precision</type>
9773        for floating-point arguments, otherwise the same as the
9774        argument data type
9775       </entry>
9776       <entry>sum of <replaceable class="parameter">expression</replaceable> across all input values</entry>
9777      </row>
9778
9779      <row>
9780       <entry>
9781        <indexterm>
9782         <primary>xmlagg</primary>
9783        </indexterm>
9784        <function>xmlagg(<replaceable class="parameter">expression</replaceable>)</function>
9785       </entry>
9786       <entry>
9787        <type>xml</type>
9788       </entry>
9789       <entry>
9790        <type>xml</type>
9791       </entry>
9792       <entry>concatenation of XML values (see also <xref linkend="functions-xml-xmlagg">)</entry>
9793      </row>
9794     </tbody>
9795    </tgroup>
9796   </table>
9797
9798   <para>
9799    It should be noted that except for <function>count</function>,
9800    these functions return a null value when no rows are selected.  In
9801    particular, <function>sum</function> of no rows returns null, not
9802    zero as one might expect, and <function>array_agg</function>
9803    returns null rather than an empty array when there are no input
9804    rows.  The <function>coalesce</function> function can be used to
9805    substitute zero or an empty array for null when necessary.
9806   </para>
9807
9808   <note>
9809     <indexterm>
9810       <primary>ANY</primary>
9811     </indexterm>
9812     <indexterm>
9813       <primary>SOME</primary>
9814     </indexterm>
9815     <para>
9816       Boolean aggregates <function>bool_and</function> and
9817       <function>bool_or</function> correspond to standard SQL aggregates
9818       <function>every</function> and <function>any</function> or
9819       <function>some</function>.
9820       As for <function>any</function> and <function>some</function>,
9821       it seems that there is an ambiguity built into the standard syntax:
9822 <programlisting>
9823 SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...;
9824 </programlisting>
9825       Here <function>ANY</function> can be considered either as introducing
9826       a subquery, or as being an aggregate function, if the sub-select
9827       returns one row with a boolean value.
9828       Thus the standard name cannot be given to these aggregates.
9829     </para>
9830   </note>
9831
9832   <note>
9833    <para>
9834     Users accustomed to working with other SQL database management
9835     systems might be disappointed by the performance of the
9836     <function>count</function> aggregate when it is applied to the
9837     entire table. A query like:
9838 <programlisting>
9839 SELECT count(*) FROM sometable;
9840 </programlisting>
9841     will be executed by <productname>PostgreSQL</productname> using a
9842     sequential scan of the entire table.
9843    </para>
9844   </note>
9845
9846   <para>
9847    The aggregate functions <function>array_agg</function>
9848    and <function>xmlagg</function>, as well as similar user-defined
9849    aggregate functions, produce meaningfully different result values
9850    depending on the order of the input values.  In the current
9851    implementation, the order of the input is in principle unspecified.
9852    Supplying the input values from a sorted subquery
9853    will usually work, however.  For example:
9854
9855 <screen><![CDATA[
9856 SELECT xmlagg(x) FROM (SELECT x FROM test ORDER BY y DESC) AS tab;
9857 ]]></screen>
9858
9859    But this syntax is not allowed in the SQL standard, and is
9860    not portable to other database systems.  A future version of
9861    <productname>PostgreSQL</> might provide an additional feature to control
9862    the order in a better-defined way (<literal>xmlagg(expr ORDER BY expr, expr,
9863    ...)</literal>).
9864   </para>
9865
9866   <para>
9867    <xref linkend="functions-aggregate-statistics-table"> shows
9868    aggregate functions typically used in statistical analysis.
9869    (These are separated out merely to avoid cluttering the listing
9870    of more-commonly-used aggregates.)  Where the description mentions
9871    <replaceable class="parameter">N</replaceable>, it means the
9872    number of input rows for which all the input expressions are non-null.
9873    In all cases, null is returned if the computation is meaningless,
9874    for example when <replaceable class="parameter">N</replaceable> is zero.
9875   </para>
9876
9877   <indexterm>
9878    <primary>statistics</primary>
9879   </indexterm>
9880   <indexterm>
9881    <primary>linear regression</primary>
9882   </indexterm>
9883
9884   <table id="functions-aggregate-statistics-table">
9885    <title>Aggregate Functions for Statistics</title>
9886
9887    <tgroup cols="4">
9888     <thead>
9889      <row>
9890       <entry>Function</entry>
9891       <entry>Argument Type</entry>
9892       <entry>Return Type</entry>
9893       <entry>Description</entry>
9894      </row>
9895     </thead>
9896
9897     <tbody>
9898
9899      <row>
9900       <entry>
9901        <indexterm>
9902         <primary>correlation</primary>
9903        </indexterm>
9904        <function>corr(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
9905       </entry>
9906       <entry>
9907        <type>double precision</type>
9908       </entry>
9909       <entry>
9910        <type>double precision</type>
9911       </entry>
9912       <entry>correlation coefficient</entry>
9913      </row>
9914
9915      <row>
9916       <entry>
9917        <indexterm>
9918         <primary>covariance</primary>
9919         <secondary>population</secondary>
9920        </indexterm>
9921        <function>covar_pop(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
9922       </entry>
9923       <entry>
9924        <type>double precision</type>
9925       </entry>
9926       <entry>
9927        <type>double precision</type>
9928       </entry>
9929       <entry>population covariance</entry>
9930      </row>
9931
9932      <row>
9933       <entry>
9934        <indexterm>
9935         <primary>covariance</primary>
9936         <secondary>sample</secondary>
9937        </indexterm>
9938        <function>covar_samp(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
9939       </entry>
9940       <entry>
9941        <type>double precision</type>
9942       </entry>
9943       <entry>
9944        <type>double precision</type>
9945       </entry>
9946       <entry>sample covariance</entry>
9947      </row>
9948
9949      <row>
9950       <entry>
9951        <function>regr_avgx(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
9952       </entry>
9953       <entry>
9954        <type>double precision</type>
9955       </entry>
9956       <entry>
9957        <type>double precision</type>
9958       </entry>
9959       <entry>average of the independent variable
9960       (<literal>sum(<replaceable class="parameter">X</replaceable>)/<replaceable class="parameter">N</replaceable></literal>)</entry>
9961      </row>
9962
9963      <row>
9964       <entry>
9965        <function>regr_avgy(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
9966       </entry>
9967       <entry>
9968        <type>double precision</type>
9969       </entry>
9970       <entry>
9971        <type>double precision</type>
9972       </entry>
9973       <entry>average of the dependent variable
9974       (<literal>sum(<replaceable class="parameter">Y</replaceable>)/<replaceable class="parameter">N</replaceable></literal>)</entry>
9975      </row>
9976
9977      <row>
9978       <entry>
9979        <function>regr_count(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
9980       </entry>
9981       <entry>
9982        <type>double precision</type>
9983       </entry>
9984       <entry>
9985        <type>bigint</type>
9986       </entry>
9987       <entry>number of input rows in which both expressions are nonnull</entry>
9988      </row>
9989
9990      <row>
9991       <entry>
9992        <indexterm>
9993         <primary>regression intercept</primary>
9994        </indexterm>
9995        <function>regr_intercept(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
9996       </entry>
9997       <entry>
9998        <type>double precision</type>
9999       </entry>
10000       <entry>
10001        <type>double precision</type>
10002       </entry>
10003       <entry>y-intercept of the least-squares-fit linear equation
10004       determined by the (<replaceable
10005       class="parameter">X</replaceable>, <replaceable
10006       class="parameter">Y</replaceable>) pairs</entry>
10007      </row>
10008
10009      <row>
10010       <entry>
10011        <function>regr_r2(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10012       </entry>
10013       <entry>
10014        <type>double precision</type>
10015       </entry>
10016       <entry>
10017        <type>double precision</type>
10018       </entry>
10019       <entry>square of the correlation coefficient</entry>
10020      </row>
10021
10022      <row>
10023       <entry>
10024        <indexterm>
10025         <primary>regression slope</primary>
10026        </indexterm>
10027        <function>regr_slope(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10028       </entry>
10029       <entry>
10030        <type>double precision</type>
10031       </entry>
10032       <entry>
10033        <type>double precision</type>
10034       </entry>
10035       <entry>slope of the least-squares-fit linear equation determined
10036       by the (<replaceable class="parameter">X</replaceable>,
10037       <replaceable class="parameter">Y</replaceable>) pairs</entry>
10038      </row>
10039
10040      <row>
10041       <entry>
10042        <function>regr_sxx(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10043       </entry>
10044       <entry>
10045        <type>double precision</type>
10046       </entry>
10047       <entry>
10048        <type>double precision</type>
10049       </entry>
10050       <entry><literal>sum(<replaceable
10051       class="parameter">X</replaceable>^2) - sum(<replaceable
10052       class="parameter">X</replaceable>)^2/<replaceable
10053       class="parameter">N</replaceable></literal> (<quote>sum of
10054       squares</quote> of the independent variable)</entry>
10055      </row>
10056
10057      <row>
10058       <entry>
10059        <function>regr_sxy(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10060       </entry>
10061       <entry>
10062        <type>double precision</type>
10063       </entry>
10064       <entry>
10065        <type>double precision</type>
10066       </entry>
10067       <entry><literal>sum(<replaceable
10068       class="parameter">X</replaceable>*<replaceable
10069       class="parameter">Y</replaceable>) - sum(<replaceable
10070       class="parameter">X</replaceable>) * sum(<replaceable
10071       class="parameter">Y</replaceable>)/<replaceable
10072       class="parameter">N</replaceable></literal> (<quote>sum of
10073       products</quote> of independent times dependent
10074       variable)</entry>
10075      </row>
10076
10077      <row>
10078       <entry>
10079        <function>regr_syy(<replaceable class="parameter">Y</replaceable>, <replaceable class="parameter">X</replaceable>)</function>
10080       </entry>
10081       <entry>
10082        <type>double precision</type>
10083       </entry>
10084       <entry>
10085        <type>double precision</type>
10086       </entry>
10087       <entry><literal>sum(<replaceable
10088       class="parameter">Y</replaceable>^2) - sum(<replaceable
10089       class="parameter">Y</replaceable>)^2/<replaceable
10090       class="parameter">N</replaceable></literal> (<quote>sum of
10091       squares</quote> of the dependent variable)</entry>
10092      </row>
10093
10094      <row>
10095       <entry>
10096        <indexterm>
10097         <primary>standard deviation</primary>
10098        </indexterm>
10099        <function>stddev(<replaceable class="parameter">expression</replaceable>)</function>
10100       </entry>
10101       <entry>
10102        <type>smallint</type>, <type>int</type>,
10103        <type>bigint</type>, <type>real</type>, <type>double
10104        precision</type>, or <type>numeric</type>
10105       </entry>
10106       <entry>
10107        <type>double precision</type> for floating-point arguments,
10108        otherwise <type>numeric</type>
10109       </entry>
10110       <entry>historical alias for <function>stddev_samp</function></entry>
10111      </row>
10112
10113      <row>
10114       <entry>
10115        <indexterm>
10116         <primary>standard deviation</primary>
10117         <secondary>population</secondary>
10118        </indexterm>
10119        <function>stddev_pop(<replaceable class="parameter">expression</replaceable>)</function>
10120       </entry>
10121       <entry>
10122        <type>smallint</type>, <type>int</type>,
10123        <type>bigint</type>, <type>real</type>, <type>double
10124        precision</type>, or <type>numeric</type>
10125       </entry>
10126       <entry>
10127        <type>double precision</type> for floating-point arguments,
10128        otherwise <type>numeric</type>
10129       </entry>
10130       <entry>population standard deviation of the input values</entry>
10131      </row>
10132
10133      <row>
10134       <entry>
10135        <indexterm>
10136         <primary>standard deviation</primary>
10137         <secondary>sample</secondary>
10138        </indexterm>
10139        <function>stddev_samp(<replaceable class="parameter">expression</replaceable>)</function>
10140       </entry>
10141       <entry>
10142        <type>smallint</type>, <type>int</type>,
10143        <type>bigint</type>, <type>real</type>, <type>double
10144        precision</type>, or <type>numeric</type>
10145       </entry>
10146       <entry>
10147        <type>double precision</type> for floating-point arguments,
10148        otherwise <type>numeric</type>
10149       </entry>
10150       <entry>sample standard deviation of the input values</entry>
10151      </row>
10152
10153      <row>
10154       <entry>
10155        <indexterm>
10156         <primary>variance</primary>
10157        </indexterm>
10158        <function>variance</function>(<replaceable class="parameter">expression</replaceable>)
10159       </entry>
10160       <entry>
10161        <type>smallint</type>, <type>int</type>,
10162        <type>bigint</type>, <type>real</type>, <type>double
10163        precision</type>, or <type>numeric</type>
10164       </entry>
10165       <entry>
10166        <type>double precision</type> for floating-point arguments,
10167        otherwise <type>numeric</type>
10168       </entry>
10169       <entry>historical alias for <function>var_samp</function></entry>
10170      </row>
10171
10172      <row>
10173       <entry>
10174        <indexterm>
10175         <primary>variance</primary>
10176         <secondary>population</secondary>
10177        </indexterm>
10178        <function>var_pop</function>(<replaceable class="parameter">expression</replaceable>)
10179       </entry>
10180       <entry>
10181        <type>smallint</type>, <type>int</type>,
10182        <type>bigint</type>, <type>real</type>, <type>double
10183        precision</type>, or <type>numeric</type>
10184       </entry>
10185       <entry>
10186        <type>double precision</type> for floating-point arguments,
10187        otherwise <type>numeric</type>
10188       </entry>
10189       <entry>population variance of the input values (square of the population standard deviation)</entry>
10190      </row>
10191
10192      <row>
10193       <entry>
10194        <indexterm>
10195         <primary>variance</primary>
10196         <secondary>sample</secondary>
10197        </indexterm>
10198        <function>var_samp</function>(<replaceable class="parameter">expression</replaceable>)
10199       </entry>
10200       <entry>
10201        <type>smallint</type>, <type>int</type>,
10202        <type>bigint</type>, <type>real</type>, <type>double
10203        precision</type>, or <type>numeric</type>
10204       </entry>
10205       <entry>
10206        <type>double precision</type> for floating-point arguments,
10207        otherwise <type>numeric</type>
10208       </entry>
10209       <entry>sample variance of the input values (square of the sample standard deviation)</entry>
10210      </row>
10211     </tbody>
10212    </tgroup>
10213   </table>
10214
10215  </sect1>
10216
10217  <sect1 id="functions-window">
10218   <title>Window Functions</title>
10219
10220   <indexterm zone="functions-window">
10221    <primary>window function</primary>
10222    <secondary>built-in</secondary>
10223   </indexterm>
10224
10225   <para>
10226    <firstterm>Window functions</firstterm> provide the ability to perform
10227    calculations across sets of rows that are related to the current query
10228    row.  See <xref linkend="tutorial-window"> for an introduction to this
10229    feature.
10230   </para>
10231
10232   <para>
10233    The built-in window functions are listed in
10234    <xref linkend="functions-window-table">.  Note that these functions
10235    <emphasis>must</> be invoked using window function syntax; that is an
10236    <literal>OVER</> clause is required.
10237   </para>
10238
10239   <para>
10240    In addition to these functions, any built-in or user-defined aggregate
10241    function can be used as a window function (see
10242    <xref linkend="functions-aggregate"> for a list of the built-in aggregates).
10243    Aggregate functions act as window functions only when an <literal>OVER</>
10244    clause follows the call; otherwise they act as regular aggregates.
10245   </para>
10246
10247   <table id="functions-window-table">
10248    <title>General-Purpose Window Functions</title>
10249
10250    <tgroup cols="3">
10251     <thead>
10252      <row>
10253       <entry>Function</entry>
10254       <entry>Return Type</entry>
10255       <entry>Description</entry>
10256      </row>
10257     </thead>
10258
10259     <tbody>
10260      <row>
10261       <entry>
10262        <indexterm>
10263         <primary>row_number</primary>
10264        </indexterm>
10265        <function>row_number()</function>
10266       </entry>
10267       <entry>
10268        <type>bigint</type>
10269       </entry>
10270       <entry>number of the current row within its partition, counting from 1</entry>
10271      </row>
10272
10273      <row>
10274       <entry>
10275        <indexterm>
10276         <primary>rank</primary>
10277        </indexterm>
10278        <function>rank()</function>
10279       </entry>
10280       <entry>
10281        <type>bigint</type>
10282       </entry>
10283       <entry>rank of the current row with gaps; same as <function>row_number</> of its first peer</entry>
10284      </row>
10285
10286      <row>
10287       <entry>
10288        <indexterm>
10289         <primary>dense_rank</primary>
10290        </indexterm>
10291        <function>dense_rank()</function>
10292       </entry>
10293       <entry>
10294        <type>bigint</type>
10295       </entry>
10296       <entry>rank of the current row without gaps; this function counts peer groups</entry>
10297      </row>
10298
10299      <row>
10300       <entry>
10301        <indexterm>
10302         <primary>percent_rank</primary>
10303        </indexterm>
10304        <function>percent_rank()</function>
10305       </entry>
10306       <entry>
10307        <type>double precision</type>
10308       </entry>
10309       <entry>relative rank of the current row: (<function>rank</> - 1) / (total rows - 1)</entry>
10310      </row>
10311
10312      <row>
10313       <entry>
10314        <indexterm>
10315         <primary>cume_dist</primary>
10316        </indexterm>
10317        <function>cume_dist()</function>
10318       </entry>
10319       <entry>
10320        <type>double precision</type>
10321       </entry>
10322       <entry>relative rank of the current row: (number of rows preceding or peer with current row) / (total rows)</entry>
10323      </row>
10324
10325      <row>
10326       <entry>
10327        <indexterm>
10328         <primary>ntile</primary>
10329        </indexterm>
10330        <function>ntile(<replaceable class="parameter">num_buckets</replaceable> <type>integer</>)</function>
10331       </entry>
10332       <entry>
10333        <type>integer</type>
10334       </entry>
10335       <entry>integer ranging from 1 to the argument value, dividing the
10336        partition as equally as possible</entry>
10337      </row>
10338
10339      <row>
10340       <entry>
10341        <indexterm>
10342         <primary>lag</primary>
10343        </indexterm>
10344        <function>
10345          lag(<replaceable class="parameter">value</replaceable> <type>any</>
10346              [, <replaceable class="parameter">offset</replaceable> <type>integer</>
10347              [, <replaceable class="parameter">default</replaceable> <type>any</> ]])
10348        </function>
10349       </entry>
10350       <entry>
10351        <type>same type as <replaceable class="parameter">value</replaceable></type>
10352       </entry>
10353       <entry>
10354        returns <replaceable class="parameter">value</replaceable> evaluated at
10355        the row that is <replaceable class="parameter">offset</replaceable>
10356        rows before the current row within the partition; if there is no such
10357        row, instead return <replaceable class="parameter">default</replaceable>.
10358        Both <replaceable class="parameter">offset</replaceable> and
10359        <replaceable class="parameter">default</replaceable> are evaluated
10360        with respect to the current row.  If omitted,
10361        <replaceable class="parameter">offset</replaceable> defaults to 1 and
10362        <replaceable class="parameter">default</replaceable> to null
10363       </entry>
10364      </row>
10365
10366      <row>
10367       <entry>
10368        <indexterm>
10369         <primary>lead</primary>
10370        </indexterm>
10371        <function>
10372          lead(<replaceable class="parameter">value</replaceable> <type>any</>
10373               [, <replaceable class="parameter">offset</replaceable> <type>integer</>
10374               [, <replaceable class="parameter">default</replaceable> <type>any</> ]])
10375        </function>
10376       </entry>
10377       <entry>
10378        <type>same type as <replaceable class="parameter">value</replaceable></type>
10379       </entry>
10380       <entry>
10381        returns <replaceable class="parameter">value</replaceable> evaluated at
10382        the row that is <replaceable class="parameter">offset</replaceable>
10383        rows after the current row within the partition; if there is no such
10384        row, instead return <replaceable class="parameter">default</replaceable>.
10385        Both <replaceable class="parameter">offset</replaceable> and
10386        <replaceable class="parameter">default</replaceable> are evaluated
10387        with respect to the current row.  If omitted,
10388        <replaceable class="parameter">offset</replaceable> defaults to 1 and
10389        <replaceable class="parameter">default</replaceable> to null
10390       </entry>
10391      </row>
10392
10393      <row>
10394       <entry>
10395        <indexterm>
10396         <primary>first_value</primary>
10397        </indexterm>
10398        <function>first_value(<replaceable class="parameter">value</replaceable> <type>any</>)</function>
10399       </entry>
10400       <entry>
10401        <type>same type as <replaceable class="parameter">value</replaceable></type>
10402       </entry>
10403       <entry>
10404        returns <replaceable class="parameter">value</replaceable> evaluated
10405        at the row that is the first row of the window frame
10406       </entry>
10407      </row>
10408
10409      <row>
10410       <entry>
10411        <indexterm>
10412         <primary>last_value</primary>
10413        </indexterm>
10414        <function>last_value(<replaceable class="parameter">value</replaceable> <type>any</>)</function>
10415       </entry>
10416       <entry>
10417        <type>same type as <replaceable class="parameter">value</replaceable></type>
10418       </entry>
10419       <entry>
10420        returns <replaceable class="parameter">value</replaceable> evaluated
10421        at the row that is the last row of the window frame
10422       </entry>
10423      </row>
10424
10425      <row>
10426       <entry>
10427        <indexterm>
10428         <primary>nth_value</primary>
10429        </indexterm>
10430        <function>
10431          nth_value(<replaceable class="parameter">value</replaceable> <type>any</>, <replaceable class="parameter">nth</replaceable> <type>integer</>)
10432        </function>
10433       </entry>
10434       <entry>
10435        <type>same type as <replaceable class="parameter">value</replaceable></type>
10436       </entry>
10437       <entry>
10438        returns <replaceable class="parameter">value</replaceable> evaluated
10439        at the row that is the <replaceable class="parameter">nth</replaceable>
10440        row of the window frame (counting from 1); null if no such row
10441       </entry>
10442      </row>
10443     </tbody>
10444    </tgroup>
10445   </table>
10446
10447   <para>
10448    All of the functions listed in
10449    <xref linkend="functions-window-table"> depend on the sort ordering
10450    specified by the <literal>ORDER BY</> clause of the associated window
10451    definition.  Rows that are not distinct in the <literal>ORDER BY</>
10452    ordering are said to be <firstterm>peers</>; the four ranking functions
10453    are defined so that they give the same answer for any two peer rows.
10454   </para>
10455
10456   <para>
10457    Note that <function>first_value</>, <function>last_value</>, and
10458    <function>nth_value</> consider only the rows within the <quote>window
10459    frame</>, which by default contains the rows from the start of the
10460    partition through the last peer of the current row.  This is
10461    likely to give unhelpful results for <function>nth_value</> and
10462    particularly <function>last_value</>.  You can redefine the frame as
10463    being the whole partition by adding <literal>ROWS BETWEEN UNBOUNDED
10464    PRECEDING AND UNBOUNDED FOLLOWING</> to the <literal>OVER</> clause.
10465    See <xref linkend="syntax-window-functions"> for more information.
10466   </para>
10467
10468   <para>
10469    When an aggregate function is used as a window function, it aggregates
10470    over the rows within the current row's window frame.  To obtain
10471    aggregation over the whole partition, omit <literal>ORDER BY</> or use
10472    <literal>ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING</>.
10473    An aggregate used with <literal>ORDER BY</> and the default window frame
10474    definition produces a <quote>running sum</> type of behavior, which may or
10475    may not be what's wanted.
10476   </para>
10477
10478   <note>
10479    <para>
10480     The SQL standard defines a <literal>RESPECT NULLS</> or
10481     <literal>IGNORE NULLS</> option for <function>lead</>, <function>lag</>,
10482     <function>first_value</>, <function>last_value</>, and
10483     <function>nth_value</>.  This is not implemented in
10484     <productname>PostgreSQL</productname>: the behavior is always the
10485     same as the standard's default, namely <literal>RESPECT NULLS</>.
10486     Likewise, the standard's <literal>FROM FIRST</> or <literal>FROM LAST</>
10487     option for <function>nth_value</> is not implemented: only the
10488     default <literal>FROM FIRST</> behavior is supported.  (You can achieve
10489     the result of <literal>FROM LAST</> by reversing the <literal>ORDER BY</>
10490     ordering.)
10491    </para>
10492   </note>
10493
10494  </sect1>
10495
10496  <sect1 id="functions-subquery">
10497   <title>Subquery Expressions</title>
10498
10499   <indexterm>
10500    <primary>EXISTS</primary>
10501   </indexterm>
10502
10503   <indexterm>
10504    <primary>IN</primary>
10505   </indexterm>
10506
10507   <indexterm>
10508    <primary>NOT IN</primary>
10509   </indexterm>
10510
10511   <indexterm>
10512    <primary>ANY</primary>
10513   </indexterm>
10514
10515   <indexterm>
10516    <primary>ALL</primary>
10517   </indexterm>
10518
10519   <indexterm>
10520    <primary>SOME</primary>
10521   </indexterm>
10522
10523   <indexterm>
10524    <primary>subquery</primary>
10525   </indexterm>
10526
10527   <para>
10528    This section describes the <acronym>SQL</acronym>-compliant subquery
10529    expressions available in <productname>PostgreSQL</productname>.
10530    All of the expression forms documented in this section return
10531    Boolean (true/false) results.
10532   </para>
10533
10534   <sect2>
10535    <title><literal>EXISTS</literal></title>
10536
10537 <synopsis>
10538 EXISTS (<replaceable>subquery</replaceable>)
10539 </synopsis>
10540
10541   <para>
10542    The argument of <token>EXISTS</token> is an arbitrary <command>SELECT</> statement,
10543    or <firstterm>subquery</firstterm>.  The
10544    subquery is evaluated to determine whether it returns any rows.
10545    If it returns at least one row, the result of <token>EXISTS</token> is
10546    <quote>true</>; if the subquery returns no rows, the result of <token>EXISTS</token>
10547    is <quote>false</>.
10548   </para>
10549
10550   <para>
10551    The subquery can refer to variables from the surrounding query,
10552    which will act as constants during any one evaluation of the subquery.
10553   </para>
10554
10555   <para>
10556    The subquery will generally only be executed long enough to determine
10557    whether at least one row is returned, not all the way to completion.
10558    It is unwise to write a subquery that has side effects (such as
10559    calling sequence functions); whether the side effects occur
10560    might be unpredictable.
10561   </para>
10562
10563   <para>
10564    Since the result depends only on whether any rows are returned,
10565    and not on the contents of those rows, the output list of the
10566    subquery is normally unimportant.  A common coding convention is
10567    to write all <literal>EXISTS</> tests in the form
10568    <literal>EXISTS(SELECT 1 WHERE ...)</literal>.  There are exceptions to
10569    this rule however, such as subqueries that use <token>INTERSECT</token>.
10570   </para>
10571
10572   <para>
10573    This simple example is like an inner join on <literal>col2</>, but
10574    it produces at most one output row for each <literal>tab1</> row,
10575    even if there are several matching <literal>tab2</> rows:
10576 <screen>
10577 SELECT col1
10578 FROM tab1
10579 WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
10580 </screen>
10581   </para>
10582   </sect2>
10583
10584   <sect2>
10585    <title><literal>IN</literal></title>
10586
10587 <synopsis>
10588 <replaceable>expression</replaceable> IN (<replaceable>subquery</replaceable>)
10589 </synopsis>
10590
10591   <para>
10592    The right-hand side is a parenthesized
10593    subquery, which must return exactly one column.  The left-hand expression
10594    is evaluated and compared to each row of the subquery result.
10595    The result of <token>IN</token> is <quote>true</> if any equal subquery row is found.
10596    The result is <quote>false</> if no equal row is found (including the
10597    case where the subquery returns no rows).
10598   </para>
10599
10600   <para>
10601    Note that if the left-hand expression yields null, or if there are
10602    no equal right-hand values and at least one right-hand row yields
10603    null, the result of the <token>IN</token> construct will be null, not false.
10604    This is in accordance with SQL's normal rules for Boolean combinations
10605    of null values.
10606   </para>
10607
10608   <para>
10609    As with <token>EXISTS</token>, it's unwise to assume that the subquery will
10610    be evaluated completely.
10611   </para>
10612
10613 <synopsis>
10614 <replaceable>row_constructor</replaceable> IN (<replaceable>subquery</replaceable>)
10615 </synopsis>
10616
10617   <para>
10618    The left-hand side of this form of <token>IN</token> is a row constructor,
10619    as described in <xref linkend="sql-syntax-row-constructors">.
10620    The right-hand side is a parenthesized
10621    subquery, which must return exactly as many columns as there are
10622    expressions in the left-hand row.  The left-hand expressions are
10623    evaluated and compared row-wise to each row of the subquery result.
10624    The result of <token>IN</token> is <quote>true</> if any equal subquery row is found.
10625    The result is <quote>false</> if no equal row is found (including the
10626    case where the subquery returns no rows).
10627   </para>
10628
10629   <para>
10630    As usual, null values in the rows are combined per
10631    the normal rules of SQL Boolean expressions.  Two rows are considered
10632    equal if all their corresponding members are non-null and equal; the rows
10633    are unequal if any corresponding members are non-null and unequal;
10634    otherwise the result of that row comparison is unknown (null).
10635    If all the per-row results are either unequal or null, with at least one
10636    null, then the result of <token>IN</token> is null.
10637   </para>
10638   </sect2>
10639
10640   <sect2>
10641    <title><literal>NOT IN</literal></title>
10642
10643 <synopsis>
10644 <replaceable>expression</replaceable> NOT IN (<replaceable>subquery</replaceable>)
10645 </synopsis>
10646
10647   <para>
10648    The right-hand side is a parenthesized
10649    subquery, which must return exactly one column.  The left-hand expression
10650    is evaluated and compared to each row of the subquery result.
10651    The result of <token>NOT IN</token> is <quote>true</> if only unequal subquery rows
10652    are found (including the case where the subquery returns no rows).
10653    The result is <quote>false</> if any equal row is found.
10654   </para>
10655
10656   <para>
10657    Note that if the left-hand expression yields null, or if there are
10658    no equal right-hand values and at least one right-hand row yields
10659    null, the result of the <token>NOT IN</token> construct will be null, not true.
10660    This is in accordance with SQL's normal rules for Boolean combinations
10661    of null values.
10662   </para>
10663
10664   <para>
10665    As with <token>EXISTS</token>, it's unwise to assume that the subquery will
10666    be evaluated completely.
10667   </para>
10668
10669 <synopsis>
10670 <replaceable>row_constructor</replaceable> NOT IN (<replaceable>subquery</replaceable>)
10671 </synopsis>
10672
10673   <para>
10674    The left-hand side of this form of <token>NOT IN</token> is a row constructor,
10675    as described in <xref linkend="sql-syntax-row-constructors">.
10676    The right-hand side is a parenthesized
10677    subquery, which must return exactly as many columns as there are
10678    expressions in the left-hand row.  The left-hand expressions are
10679    evaluated and compared row-wise to each row of the subquery result.
10680    The result of <token>NOT IN</token> is <quote>true</> if only unequal subquery rows
10681    are found (including the case where the subquery returns no rows).
10682    The result is <quote>false</> if any equal row is found.
10683   </para>
10684
10685   <para>
10686    As usual, null values in the rows are combined per
10687    the normal rules of SQL Boolean expressions.  Two rows are considered
10688    equal if all their corresponding members are non-null and equal; the rows
10689    are unequal if any corresponding members are non-null and unequal;
10690    otherwise the result of that row comparison is unknown (null).
10691    If all the per-row results are either unequal or null, with at least one
10692    null, then the result of <token>NOT IN</token> is null.
10693   </para>
10694   </sect2>
10695
10696   <sect2>
10697    <title><literal>ANY</literal>/<literal>SOME</literal></title>
10698
10699 <synopsis>
10700 <replaceable>expression</replaceable> <replaceable>operator</replaceable> ANY (<replaceable>subquery</replaceable>)
10701 <replaceable>expression</replaceable> <replaceable>operator</replaceable> SOME (<replaceable>subquery</replaceable>)
10702 </synopsis>
10703
10704   <para>
10705    The right-hand side is a parenthesized
10706    subquery, which must return exactly one column.  The left-hand expression
10707    is evaluated and compared to each row of the subquery result using the
10708    given <replaceable>operator</replaceable>, which must yield a Boolean
10709    result.
10710    The result of <token>ANY</token> is <quote>true</> if any true result is obtained.
10711    The result is <quote>false</> if no true result is found (including the
10712    case where the subquery returns no rows).
10713   </para>
10714
10715   <para>
10716    <token>SOME</token> is a synonym for <token>ANY</token>.
10717    <token>IN</token> is equivalent to <literal>= ANY</literal>.
10718   </para>
10719
10720   <para>
10721    Note that if there are no successes and at least one right-hand row yields
10722    null for the operator's result, the result of the <token>ANY</token> construct
10723    will be null, not false.
10724    This is in accordance with SQL's normal rules for Boolean combinations
10725    of null values.
10726   </para>
10727
10728   <para>
10729    As with <token>EXISTS</token>, it's unwise to assume that the subquery will
10730    be evaluated completely.
10731   </para>
10732
10733 <synopsis>
10734 <replaceable>row_constructor</replaceable> <replaceable>operator</> ANY (<replaceable>subquery</replaceable>)
10735 <replaceable>row_constructor</replaceable> <replaceable>operator</> SOME (<replaceable>subquery</replaceable>)
10736 </synopsis>
10737
10738   <para>
10739    The left-hand side of this form of <token>ANY</token> is a row constructor,
10740    as described in <xref linkend="sql-syntax-row-constructors">.
10741    The right-hand side is a parenthesized
10742    subquery, which must return exactly as many columns as there are
10743    expressions in the left-hand row.  The left-hand expressions are
10744    evaluated and compared row-wise to each row of the subquery result,
10745    using the given <replaceable>operator</replaceable>.
10746    The result of <token>ANY</token> is <quote>true</> if the comparison
10747    returns true for any subquery row.
10748    The result is <quote>false</> if the comparison returns false for every
10749    subquery row (including the case where the subquery returns no
10750    rows).
10751    The result is NULL if the comparison does not return true for any row,
10752    and it returns NULL for at least one row.
10753   </para>
10754
10755   <para>
10756    See <xref linkend="row-wise-comparison"> for details about the meaning
10757    of a row-wise comparison.
10758   </para>
10759   </sect2>
10760
10761   <sect2>
10762    <title><literal>ALL</literal></title>
10763
10764 <synopsis>
10765 <replaceable>expression</replaceable> <replaceable>operator</replaceable> ALL (<replaceable>subquery</replaceable>)
10766 </synopsis>
10767
10768   <para>
10769    The right-hand side is a parenthesized
10770    subquery, which must return exactly one column.  The left-hand expression
10771    is evaluated and compared to each row of the subquery result using the
10772    given <replaceable>operator</replaceable>, which must yield a Boolean
10773    result.
10774    The result of <token>ALL</token> is <quote>true</> if all rows yield true
10775    (including the case where the subquery returns no rows).
10776    The result is <quote>false</> if any false result is found.
10777    The result is NULL if the comparison does not return false for any row,
10778    and it returns NULL for at least one row.
10779   </para>
10780
10781   <para>
10782    <token>NOT IN</token> is equivalent to <literal>&lt;&gt; ALL</literal>.
10783   </para>
10784
10785   <para>
10786    As with <token>EXISTS</token>, it's unwise to assume that the subquery will
10787    be evaluated completely.
10788   </para>
10789
10790 <synopsis>
10791 <replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> ALL (<replaceable>subquery</replaceable>)
10792 </synopsis>
10793
10794   <para>
10795    The left-hand side of this form of <token>ALL</token> is a row constructor,
10796    as described in <xref linkend="sql-syntax-row-constructors">.
10797    The right-hand side is a parenthesized
10798    subquery, which must return exactly as many columns as there are
10799    expressions in the left-hand row.  The left-hand expressions are
10800    evaluated and compared row-wise to each row of the subquery result,
10801    using the given <replaceable>operator</replaceable>.
10802    The result of <token>ALL</token> is <quote>true</> if the comparison
10803    returns true for all subquery rows (including the
10804    case where the subquery returns no rows).
10805    The result is <quote>false</> if the comparison returns false for any
10806    subquery row.
10807    The result is NULL if the comparison does not return false for any
10808    subquery row, and it returns NULL for at least one row.
10809   </para>
10810
10811   <para>
10812    See <xref linkend="row-wise-comparison"> for details about the meaning
10813    of a row-wise comparison.
10814   </para>
10815   </sect2>
10816
10817   <sect2>
10818    <title>Row-wise Comparison</title>
10819
10820    <indexterm zone="functions-subquery">
10821     <primary>comparison</primary>
10822     <secondary>subquery result row</secondary>
10823    </indexterm>
10824
10825 <synopsis>
10826 <replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> (<replaceable>subquery</replaceable>)
10827 </synopsis>
10828
10829   <para>
10830    The left-hand side is a row constructor,
10831    as described in <xref linkend="sql-syntax-row-constructors">.
10832    The right-hand side is a parenthesized subquery, which must return exactly
10833    as many columns as there are expressions in the left-hand row. Furthermore,
10834    the subquery cannot return more than one row.  (If it returns zero rows,
10835    the result is taken to be null.)  The left-hand side is evaluated and
10836    compared row-wise to the single subquery result row.
10837   </para>
10838
10839   <para>
10840    See <xref linkend="row-wise-comparison"> for details about the meaning
10841    of a row-wise comparison.
10842   </para>
10843   </sect2>
10844  </sect1>
10845
10846
10847  <sect1 id="functions-comparisons">
10848   <title>Row and Array Comparisons</title>
10849
10850   <indexterm>
10851    <primary>IN</primary>
10852   </indexterm>
10853
10854   <indexterm>
10855    <primary>NOT IN</primary>
10856   </indexterm>
10857
10858   <indexterm>
10859    <primary>ANY</primary>
10860   </indexterm>
10861
10862   <indexterm>
10863    <primary>ALL</primary>
10864   </indexterm>
10865
10866   <indexterm>
10867    <primary>SOME</primary>
10868   </indexterm>
10869
10870   <indexterm>
10871    <primary>row-wise comparison</primary>
10872   </indexterm>
10873
10874   <indexterm>
10875    <primary>comparison</primary>
10876    <secondary>row-wise</secondary>
10877   </indexterm>
10878
10879   <indexterm>
10880    <primary>IS DISTINCT FROM</primary>
10881   </indexterm>
10882
10883   <indexterm>
10884    <primary>IS NOT DISTINCT FROM</primary>
10885   </indexterm>
10886
10887   <para>
10888    This section describes several specialized constructs for making
10889    multiple comparisons between groups of values.  These forms are
10890    syntactically related to the subquery forms of the previous section,
10891    but do not involve subqueries.
10892    The forms involving array subexpressions are
10893    <productname>PostgreSQL</productname> extensions; the rest are
10894    <acronym>SQL</acronym>-compliant.
10895    All of the expression forms documented in this section return
10896    Boolean (true/false) results.
10897   </para>
10898
10899   <sect2>
10900    <title><literal>IN</literal></title>
10901
10902 <synopsis>
10903 <replaceable>expression</replaceable> IN (<replaceable>value</replaceable> <optional>, ...</optional>)
10904 </synopsis>
10905
10906   <para>
10907    The right-hand side is a parenthesized list
10908    of scalar expressions.  The result is <quote>true</> if the left-hand expression's
10909    result is equal to any of the right-hand expressions.  This is a shorthand
10910    notation for
10911
10912 <synopsis>
10913 <replaceable>expression</replaceable> = <replaceable>value1</replaceable>
10914 OR
10915 <replaceable>expression</replaceable> = <replaceable>value2</replaceable>
10916 OR
10917 ...
10918 </synopsis>
10919   </para>
10920
10921   <para>
10922    Note that if the left-hand expression yields null, or if there are
10923    no equal right-hand values and at least one right-hand expression yields
10924    null, the result of the <token>IN</token> construct will be null, not false.
10925    This is in accordance with SQL's normal rules for Boolean combinations
10926    of null values.
10927   </para>
10928   </sect2>
10929
10930   <sect2>
10931    <title><literal>NOT IN</literal></title>
10932
10933 <synopsis>
10934 <replaceable>expression</replaceable> NOT IN (<replaceable>value</replaceable> <optional>, ...</optional>)
10935 </synopsis>
10936
10937   <para>
10938    The right-hand side is a parenthesized list
10939    of scalar expressions.  The result is <quote>true</quote> if the left-hand expression's
10940    result is unequal to all of the right-hand expressions.  This is a shorthand
10941    notation for
10942
10943 <synopsis>
10944 <replaceable>expression</replaceable> &lt;&gt; <replaceable>value1</replaceable>
10945 AND
10946 <replaceable>expression</replaceable> &lt;&gt; <replaceable>value2</replaceable>
10947 AND
10948 ...
10949 </synopsis>
10950   </para>
10951
10952   <para>
10953    Note that if the left-hand expression yields null, or if there are
10954    no equal right-hand values and at least one right-hand expression yields
10955    null, the result of the <token>NOT IN</token> construct will be null, not true
10956    as one might naively expect.
10957    This is in accordance with SQL's normal rules for Boolean combinations
10958    of null values.
10959   </para>
10960
10961   <tip>
10962   <para>
10963    <literal>x NOT IN y</literal> is equivalent to <literal>NOT (x IN y)</literal> in all
10964    cases.  However, null values are much more likely to trip up the novice when
10965    working with <token>NOT IN</token> than when working with <token>IN</token>.
10966    It is best to express your condition positively if possible.
10967   </para>
10968   </tip>
10969   </sect2>
10970
10971   <sect2>
10972    <title><literal>ANY</literal>/<literal>SOME</literal> (array)</title>
10973
10974 <synopsis>
10975 <replaceable>expression</replaceable> <replaceable>operator</replaceable> ANY (<replaceable>array expression</replaceable>)
10976 <replaceable>expression</replaceable> <replaceable>operator</replaceable> SOME (<replaceable>array expression</replaceable>)
10977 </synopsis>
10978
10979   <para>
10980    The right-hand side is a parenthesized expression, which must yield an
10981    array value.
10982    The left-hand expression
10983    is evaluated and compared to each element of the array using the
10984    given <replaceable>operator</replaceable>, which must yield a Boolean
10985    result.
10986    The result of <token>ANY</token> is <quote>true</> if any true result is obtained.
10987    The result is <quote>false</> if no true result is found (including the
10988    case where the array has zero elements).
10989   </para>
10990
10991   <para>
10992    If the array expression yields a null array, the result of
10993    <token>ANY</token> will be null.  If the left-hand expression yields null,
10994    the result of <token>ANY</token> is ordinarily null (though a non-strict
10995    comparison operator could possibly yield a different result).
10996    Also, if the right-hand array contains any null elements and no true
10997    comparison result is obtained, the result of <token>ANY</token>
10998    will be null, not false (again, assuming a strict comparison operator).
10999    This is in accordance with SQL's normal rules for Boolean combinations
11000    of null values.
11001   </para>
11002
11003   <para>
11004    <token>SOME</token> is a synonym for <token>ANY</token>.
11005   </para>
11006   </sect2>
11007
11008   <sect2>
11009    <title><literal>ALL</literal> (array)</title>
11010
11011 <synopsis>
11012 <replaceable>expression</replaceable> <replaceable>operator</replaceable> ALL (<replaceable>array expression</replaceable>)
11013 </synopsis>
11014
11015   <para>
11016    The right-hand side is a parenthesized expression, which must yield an
11017    array value.
11018    The left-hand expression
11019    is evaluated and compared to each element of the array using the
11020    given <replaceable>operator</replaceable>, which must yield a Boolean
11021    result.
11022    The result of <token>ALL</token> is <quote>true</> if all comparisons yield true
11023    (including the case where the array has zero elements).
11024    The result is <quote>false</> if any false result is found.
11025   </para>
11026
11027   <para>
11028    If the array expression yields a null array, the result of
11029    <token>ALL</token> will be null.  If the left-hand expression yields null,
11030    the result of <token>ALL</token> is ordinarily null (though a non-strict
11031    comparison operator could possibly yield a different result).
11032    Also, if the right-hand array contains any null elements and no false
11033    comparison result is obtained, the result of <token>ALL</token>
11034    will be null, not true (again, assuming a strict comparison operator).
11035    This is in accordance with SQL's normal rules for Boolean combinations
11036    of null values.
11037   </para>
11038   </sect2>
11039
11040   <sect2 id="row-wise-comparison">
11041    <title>Row-wise Comparison</title>
11042
11043 <synopsis>
11044 <replaceable>row_constructor</replaceable> <replaceable>operator</replaceable> <replaceable>row_constructor</replaceable>
11045 </synopsis>
11046
11047   <para>
11048    Each side is a row constructor,
11049    as described in <xref linkend="sql-syntax-row-constructors">.
11050    The two row values must have the same number of fields.
11051    Each side is evaluated and they are compared row-wise.  Row comparisons
11052    are allowed when the <replaceable>operator</replaceable> is
11053    <literal>=</>,
11054    <literal>&lt;&gt;</>,
11055    <literal>&lt;</>,
11056    <literal>&lt;=</>,
11057    <literal>&gt;</> or
11058    <literal>&gt;=</>,
11059    or has semantics similar to one of these.  (To be specific, an operator
11060    can be a row comparison operator if it is a member of a B-Tree operator
11061    class, or is the negator of the <literal>=</> member of a B-Tree operator
11062    class.)
11063   </para>
11064
11065   <para>
11066    The <literal>=</> and <literal>&lt;&gt;</> cases work slightly differently
11067    from the others.  Two rows are considered
11068    equal if all their corresponding members are non-null and equal; the rows
11069    are unequal if any corresponding members are non-null and unequal;
11070    otherwise the result of the row comparison is unknown (null).
11071   </para>
11072
11073   <para>
11074    For the <literal>&lt;</>, <literal>&lt;=</>, <literal>&gt;</> and
11075    <literal>&gt;=</> cases, the row elements are compared left-to-right,
11076    stopping as soon as an unequal or null pair of elements is found.
11077    If either of this pair of elements is null, the result of the
11078    row comparison is unknown (null); otherwise comparison of this pair
11079    of elements determines the result.  For example,
11080    <literal>ROW(1,2,NULL) &lt; ROW(1,3,0)</>
11081    yields true, not null, because the third pair of elements are not
11082    considered.
11083   </para>
11084
11085   <note>
11086    <para>
11087     Prior to <productname>PostgreSQL</productname> 8.2, the
11088     <literal>&lt;</>, <literal>&lt;=</>, <literal>&gt;</> and <literal>&gt;=</>
11089     cases were not handled per SQL specification.  A comparison like
11090     <literal>ROW(a,b) &lt; ROW(c,d)</>
11091     was implemented as
11092     <literal>a &lt; c AND b &lt; d</>
11093     whereas the correct behavior is equivalent to
11094     <literal>a &lt; c OR (a = c AND b &lt; d)</>.
11095    </para>
11096   </note>
11097
11098 <synopsis>
11099 <replaceable>row_constructor</replaceable> IS DISTINCT FROM <replaceable>row_constructor</replaceable>
11100 </synopsis>
11101
11102   <para>
11103    This construct is similar to a <literal>&lt;&gt;</literal> row comparison,
11104    but it does not yield null for null inputs.  Instead, any null value is
11105    considered unequal to (distinct from) any non-null value, and any two
11106    nulls are considered equal (not distinct).  Thus the result will
11107    either be true or false, never null.
11108   </para>
11109
11110 <synopsis>
11111 <replaceable>row_constructor</replaceable> IS NOT DISTINCT FROM <replaceable>row_constructor</replaceable>
11112 </synopsis>
11113
11114   <para>
11115    This construct is similar to a <literal>=</literal> row comparison,
11116    but it does not yield null for null inputs.  Instead, any null value is
11117    considered unequal to (distinct from) any non-null value, and any two
11118    nulls are considered equal (not distinct).  Thus the result will always
11119    be either true or false, never null.
11120   </para>
11121
11122   <note>
11123    <para>
11124     The SQL specification requires row-wise comparison to return NULL if the
11125     result depends on comparing two NULL values or a NULL and a non-NULL.
11126     <productname>PostgreSQL</productname> does this only when comparing the
11127     results of two row constructors or comparing a row constructor to the
11128     output of a subquery (as in <xref linkend="functions-subquery">).
11129     In other contexts where two composite-type values are compared, two
11130     NULL field values are considered equal, and a NULL is considered larger
11131     than a non-NULL.  This is necessary in order to have consistent sorting
11132     and indexing behavior for composite types.
11133    </para>
11134   </note>
11135
11136   </sect2>
11137  </sect1>
11138
11139  <sect1 id="functions-srf">
11140   <title>Set Returning Functions</title>
11141
11142   <indexterm zone="functions-srf">
11143    <primary>set returning functions</primary>
11144    <secondary>functions</secondary>
11145   </indexterm>
11146
11147   <indexterm>
11148    <primary>generate_series</primary>
11149   </indexterm>
11150
11151   <para>
11152    This section describes functions that possibly return more than one row.
11153    Currently the only functions in this class are series generating functions,
11154    as detailed in <xref linkend="functions-srf-series"> and
11155    <xref linkend="functions-srf-subscripts">.
11156   </para>
11157
11158   <table id="functions-srf-series">
11159    <title>Series Generating Functions</title>
11160    <tgroup cols="4">
11161     <thead>
11162      <row>
11163       <entry>Function</entry>
11164       <entry>Argument Type</entry>
11165       <entry>Return Type</entry>
11166       <entry>Description</entry>
11167      </row>
11168     </thead>
11169
11170     <tbody>
11171      <row>
11172       <entry><literal><function>generate_series</function>(<parameter>start</parameter>, <parameter>stop</parameter>)</literal></entry>
11173       <entry><type>int</type> or <type>bigint</type></entry>
11174       <entry><type>setof int</type> or <type>setof bigint</type> (same as argument type)</entry>
11175       <entry>
11176        Generate a series of values, from <parameter>start</parameter> to <parameter>stop</parameter>
11177        with a step size of one
11178       </entry>
11179      </row>
11180
11181      <row>
11182       <entry><literal><function>generate_series</function>(<parameter>start</parameter>, <parameter>stop</parameter>, <parameter>step</parameter>)</literal></entry>
11183       <entry><type>int</type> or <type>bigint</type></entry>
11184       <entry><type>setof int</type> or <type>setof bigint</type> (same as argument type)</entry>
11185       <entry>
11186        Generate a series of values, from <parameter>start</parameter> to <parameter>stop</parameter>
11187        with a step size of <parameter>step</parameter>
11188       </entry>
11189      </row>
11190
11191      <row>
11192       <entry><literal><function>generate_series</function>(<parameter>start</parameter>, <parameter>stop</parameter>, <parameter>step</parameter> <type>interval</>)</literal></entry>
11193       <entry><type>timestamp</type> or <type>timestamp with time zone</type></entry>
11194       <entry><type>setof timestamp</type> or <type>setof timestamp with time zone</type> (same as argument type)</entry>
11195       <entry>
11196        Generate a series of values, from <parameter>start</parameter> to <parameter>stop</parameter>
11197        with a step size of <parameter>step</parameter>
11198       </entry>
11199      </row>
11200
11201     </tbody>
11202    </tgroup>
11203   </table>
11204
11205   <para>
11206    When <parameter>step</parameter> is positive, zero rows are returned if
11207    <parameter>start</parameter> is greater than <parameter>stop</parameter>.
11208    Conversely, when <parameter>step</parameter> is negative, zero rows are
11209    returned if <parameter>start</parameter> is less than <parameter>stop</parameter>.
11210    Zero rows are also returned for <literal>NULL</literal> inputs. It is an error
11211    for <parameter>step</parameter> to be zero. Some examples follow:
11212 <programlisting>
11213 SELECT * FROM generate_series(2,4);
11214  generate_series
11215 -----------------
11216                2
11217                3
11218                4
11219 (3 rows)
11220
11221 SELECT * FROM generate_series(5,1,-2);
11222  generate_series
11223 -----------------
11224                5
11225                3
11226                1
11227 (3 rows)
11228
11229 SELECT * FROM generate_series(4,3);
11230  generate_series
11231 -----------------
11232 (0 rows)
11233
11234 -- this example relies on the date-plus-integer operator
11235 SELECT current_date + s.a AS dates FROM generate_series(0,14,7) AS s(a);
11236    dates
11237 ------------
11238  2004-02-05
11239  2004-02-12
11240  2004-02-19
11241 (3 rows)
11242
11243 SELECT * FROM generate_series('2008-03-01 00:00'::timestamp,
11244                               '2008-03-04 12:00', '10 hours');
11245    generate_series
11246 ---------------------
11247  2008-03-01 00:00:00
11248  2008-03-01 10:00:00
11249  2008-03-01 20:00:00
11250  2008-03-02 06:00:00
11251  2008-03-02 16:00:00
11252  2008-03-03 02:00:00
11253  2008-03-03 12:00:00
11254  2008-03-03 22:00:00
11255  2008-03-04 08:00:00
11256 (9 rows)
11257 </programlisting>
11258   </para>
11259
11260   <table id="functions-srf-subscripts">
11261    <title>Subscript Generating Functions</title>
11262    <tgroup cols="3">
11263     <thead>
11264      <row>
11265       <entry>Function</entry>
11266       <entry>Return Type</entry>
11267       <entry>Description</entry>
11268      </row>
11269     </thead>
11270
11271     <tbody>
11272      <row>
11273       <entry><literal><function>generate_subscripts</function>(<parameter>array anyarray</parameter>, <parameter>dim int</parameter>)</literal></entry>
11274       <entry><type>setof int</type></entry>
11275       <entry>
11276        Generate a series comprising the given array's subscripts.
11277       </entry>
11278      </row>
11279
11280      <row>
11281       <entry><literal><function>generate_subscripts</function>(<parameter>array anyarray</parameter>, <parameter>dim int</parameter>, <parameter>reverse boolean</parameter>)</literal></entry>
11282       <entry><type>setof int</type></entry>
11283       <entry>
11284        Generate a series comprising the given array's subscripts. When
11285        <parameter>reverse</parameter> is true, the series is returned in
11286        reverse order.
11287       </entry>
11288      </row>
11289
11290     </tbody>
11291    </tgroup>
11292   </table>
11293
11294   <indexterm>
11295    <primary>generate_subscripts</primary>
11296   </indexterm>
11297
11298   <para>
11299    <function>generate_subscripts</> is a convenience function that generates
11300    the set of valid subscripts for the specified dimension of the given
11301    array.
11302    Zero rows are returned for arrays that do not have the requested dimension,
11303    or for NULL arrays (but valid subscripts are returned for NULL array
11304    elements).  Some examples follow:
11305 <programlisting>
11306 -- basic usage
11307 select generate_subscripts('{NULL,1,NULL,2}'::int[], 1) as s;
11308  s
11309 ---
11310  1
11311  2
11312  3
11313  4
11314 (4 rows)
11315
11316 -- presenting an array, the subscript and the subscripted
11317 -- value requires a subquery
11318 select * from arrays;
11319          a
11320 --------------------
11321  {-1,-2}
11322  {100,200}
11323 (2 rows)
11324
11325 select a as array, s as subscript, a[s] as value
11326 from (select generate_subscripts(a, 1) as s, a from arrays) foo;
11327    array   | subscript | value
11328 -----------+-----------+-------
11329  {-1,-2}   |         1 |    -1
11330  {-1,-2}   |         2 |    -2
11331  {100,200} |         1 |   100
11332  {100,200} |         2 |   200
11333 (4 rows)
11334
11335 -- unnest a 2D array
11336 create or replace function unnest2(anyarray)
11337 returns setof anyelement as $$
11338 select $1[i][j]
11339    from generate_subscripts($1,1) g1(i),
11340         generate_subscripts($1,2) g2(j);
11341 $$ language sql immutable;
11342 CREATE FUNCTION
11343 postgres=# select * from unnest2(array[[1,2],[3,4]]);
11344  unnest2
11345 ---------
11346        1
11347        2
11348        3
11349        4
11350 (4 rows)
11351 </programlisting>
11352   </para>
11353
11354  </sect1>
11355
11356  <sect1 id="functions-info">
11357   <title>System Information Functions</title>
11358
11359   <para>
11360    <xref linkend="functions-info-session-table"> shows several
11361    functions that extract session and system information.
11362   </para>
11363
11364   <para>
11365    In addition to the functions listed in this section, there are a number of
11366    functions related to the statistics system that also provide system
11367    information. See <xref linkend="monitoring-stats-views"> for more
11368    information.
11369   </para>
11370
11371    <table id="functions-info-session-table">
11372     <title>Session Information Functions</title>
11373     <tgroup cols="3">
11374      <thead>
11375       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
11376      </thead>
11377
11378      <tbody>
11379       <row>
11380        <entry><literal><function>current_catalog</function></literal></entry>
11381        <entry><type>name</type></entry>
11382        <entry>name of current database (called <quote>catalog</quote> in the SQL standard)</entry>
11383       </row>
11384
11385       <row>
11386        <entry><literal><function>current_database</function>()</literal></entry>
11387        <entry><type>name</type></entry>
11388        <entry>name of current database</entry>
11389       </row>
11390
11391       <row>
11392        <entry><literal><function>current_schema</function>[()]</literal></entry>
11393        <entry><type>name</type></entry>
11394        <entry>name of current schema</entry>
11395       </row>
11396
11397       <row>
11398        <entry><literal><function>current_schemas</function>(<type>boolean</type>)</literal></entry>
11399        <entry><type>name[]</type></entry>
11400        <entry>names of schemas in search path optionally including implicit schemas</entry>
11401       </row>
11402
11403       <row>
11404        <entry><literal><function>current_user</function></literal></entry>
11405        <entry><type>name</type></entry>
11406        <entry>user name of current execution context</entry>
11407       </row>
11408
11409       <row>
11410        <entry><literal><function>current_query</function></literal></entry>
11411        <entry><type>text</type></entry>
11412        <entry>text of the currently executing query, as submitted
11413        by the client (might contain more than one statement)</entry>
11414       </row>
11415
11416       <row>
11417        <!-- See also the entry for this in monitoring.sgml -->
11418        <entry><literal><function>pg_backend_pid</function>()</literal></entry>
11419        <entry><type>int</type></entry>
11420        <entry>
11421         Process ID of the server process attached to the current session
11422        </entry>
11423       </row>
11424
11425       <row>
11426        <entry><literal><function>inet_client_addr</function>()</literal></entry>
11427        <entry><type>inet</type></entry>
11428        <entry>address of the remote connection</entry>
11429       </row>
11430
11431       <row>
11432        <entry><literal><function>inet_client_port</function>()</literal></entry>
11433        <entry><type>int</type></entry>
11434        <entry>port of the remote connection</entry>
11435       </row>
11436
11437       <row>
11438        <entry><literal><function>inet_server_addr</function>()</literal></entry>
11439        <entry><type>inet</type></entry>
11440        <entry>address of the local connection</entry>
11441       </row>
11442
11443       <row>
11444        <entry><literal><function>inet_server_port</function>()</literal></entry>
11445        <entry><type>int</type></entry>
11446        <entry>port of the local connection</entry>
11447       </row>
11448
11449       <row>
11450        <entry><literal><function>pg_my_temp_schema</function>()</literal></entry>
11451        <entry><type>oid</type></entry>
11452        <entry>OID of session's temporary schema, or 0 if none</entry>
11453       </row>
11454
11455       <row>
11456        <entry><literal><function>pg_is_other_temp_schema</function>(<type>oid</type>)</literal></entry>
11457        <entry><type>boolean</type></entry>
11458        <entry>is schema another session's temporary schema?</entry>
11459       </row>
11460
11461       <row>
11462        <entry><literal><function>pg_postmaster_start_time</function>()</literal></entry>
11463        <entry><type>timestamp with time zone</type></entry>
11464        <entry>server start time</entry>
11465       </row>
11466
11467       <row>
11468        <entry><literal><function>pg_conf_load_time</function>()</literal></entry>
11469        <entry><type>timestamp with time zone</type></entry>
11470        <entry>configuration load time</entry>
11471       </row>
11472
11473       <row>
11474        <entry><literal><function>session_user</function></literal></entry>
11475        <entry><type>name</type></entry>
11476        <entry>session user name</entry>
11477       </row>
11478
11479       <row>
11480        <entry><literal><function>user</function></literal></entry>
11481        <entry><type>name</type></entry>
11482        <entry>equivalent to <function>current_user</function></entry>
11483       </row>
11484
11485       <row>
11486        <entry><literal><function>version</function>()</literal></entry>
11487        <entry><type>text</type></entry>
11488        <entry><productname>PostgreSQL</> version information</entry>
11489       </row>
11490      </tbody>
11491     </tgroup>
11492    </table>
11493
11494    <indexterm>
11495     <primary>user</primary>
11496     <secondary>current</secondary>
11497    </indexterm>
11498
11499    <indexterm>
11500     <primary>schema</primary>
11501     <secondary>current</secondary>
11502    </indexterm>
11503
11504    <indexterm>
11505     <primary>search path</primary>
11506     <secondary>current</secondary>
11507    </indexterm>
11508
11509    <indexterm>
11510     <primary>current_catalog</primary>
11511    </indexterm>
11512
11513    <indexterm>
11514     <primary>current_database</primary>
11515    </indexterm>
11516
11517    <indexterm>
11518     <primary>current_schema</primary>
11519    </indexterm>
11520
11521    <indexterm>
11522     <primary>current_user</primary>
11523    </indexterm>
11524
11525    <para>
11526     The <function>session_user</function> is normally the user who initiated
11527     the current database connection; but superusers can change this setting
11528     with <xref linkend="sql-set-session-authorization" endterm="sql-set-session-authorization-title">.
11529     The <function>current_user</function> is the user identifier
11530     that is applicable for permission checking. Normally it is equal
11531     to the session user, but it can be changed with
11532     <xref linkend="sql-set-role" endterm="sql-set-role-title">.
11533     It also changes during the execution of
11534     functions with the attribute <literal>SECURITY DEFINER</literal>.
11535     In Unix parlance, the session user is the <quote>real user</quote> and
11536     the current user is the <quote>effective user</quote>.
11537    </para>
11538
11539    <note>
11540     <para>
11541      <function>current_catalog</function>, <function>current_schema</function>,
11542      <function>current_user</function>, <function>session_user</function>,
11543      and <function>user</function> have special syntactic status
11544      in <acronym>SQL</acronym>: they must be called without trailing
11545      parentheses (optional in PostgreSQL in the case
11546      of <function>current_schema</function>).
11547     </para>
11548    </note>
11549
11550    <para>
11551     <function>current_schema</function> returns the name of the schema that is
11552     first in the search path (or a null value if the search path is
11553     empty).  This is the schema that will be used for any tables or
11554     other named objects that are created without specifying a target schema.
11555     <function>current_schemas(boolean)</function> returns an array of the names of all
11556     schemas presently in the search path.  The Boolean option determines whether or not
11557     implicitly included system schemas such as <literal>pg_catalog</> are included in the
11558     returned search path.
11559    </para>
11560
11561    <note>
11562     <para>
11563      The search path can be altered at run time.  The command is:
11564 <programlisting>
11565 SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ...</optional>
11566 </programlisting>
11567     </para>
11568    </note>
11569
11570    <indexterm>
11571     <primary>inet_client_addr</primary>
11572    </indexterm>
11573
11574    <indexterm>
11575     <primary>inet_client_port</primary>
11576    </indexterm>
11577
11578    <indexterm>
11579     <primary>inet_server_addr</primary>
11580    </indexterm>
11581
11582    <indexterm>
11583     <primary>inet_server_port</primary>
11584    </indexterm>
11585
11586    <para>
11587      <function>inet_client_addr</function> returns the IP address of the
11588      current client, and <function>inet_client_port</function> returns the
11589      port number.
11590      <function>inet_server_addr</function> returns the IP address on which
11591      the server accepted the current connection, and
11592      <function>inet_server_port</function> returns the port number.
11593      All these functions return NULL if the current connection is via a
11594      Unix-domain socket.
11595    </para>
11596
11597    <indexterm>
11598     <primary>pg_my_temp_schema</primary>
11599    </indexterm>
11600
11601    <indexterm>
11602     <primary>pg_is_other_temp_schema</primary>
11603    </indexterm>
11604
11605    <para>
11606     <function>pg_my_temp_schema</function> returns the OID of the current
11607     session's temporary schema, or zero if it has none (because it has not
11608     created any temporary tables).
11609     <function>pg_is_other_temp_schema</function> returns true if the
11610     given OID is the OID of another session's temporary schema.
11611     (This can be useful, for example, to exclude other sessions' temporary
11612     tables from a catalog display.)
11613    </para>
11614
11615    <indexterm>
11616     <primary>pg_postmaster_start_time</primary>
11617    </indexterm>
11618
11619    <para>
11620     <function>pg_postmaster_start_time</function> returns the
11621     <type>timestamp with time zone</type> when the
11622     server started.
11623    </para>
11624
11625    <indexterm>
11626     <primary>pg_conf_load_time</primary>
11627    </indexterm>
11628
11629    <para>
11630     <function>pg_conf_load_time</function> returns the
11631     <type>timestamp with time zone</type> when the
11632     server configuration files were last loaded.
11633     (If the current session was alive at the time, this will be the time
11634     when the session itself re-read the configuration files, so the
11635     reading will vary a little in different sessions.  Otherwise it is
11636     the time when the postmaster process re-read the configuration files.)
11637    </para>
11638
11639    <indexterm>
11640     <primary>version</primary>
11641    </indexterm>
11642
11643    <para>
11644     <function>version</function> returns a string describing the
11645     <productname>PostgreSQL</productname> server's version.
11646    </para>
11647
11648   <indexterm>
11649    <primary>privilege</primary>
11650    <secondary>querying</secondary>
11651   </indexterm>
11652
11653   <para>
11654    <xref linkend="functions-info-access-table"> lists functions that
11655    allow the user to query object access privileges programmatically.
11656    See <xref linkend="ddl-priv"> for more information about
11657    privileges.
11658   </para>
11659
11660    <table id="functions-info-access-table">
11661     <title>Access Privilege Inquiry Functions</title>
11662     <tgroup cols="3">
11663      <thead>
11664       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
11665      </thead>
11666
11667      <tbody>
11668       <row>
11669        <entry><literal><function>has_any_column_privilege</function>(<parameter>user</parameter>,
11670                                   <parameter>table</parameter>,
11671                                   <parameter>privilege</parameter>)</literal>
11672        </entry>
11673        <entry><type>boolean</type></entry>
11674        <entry>does user have privilege for any column of table</entry>
11675       </row>
11676       <row>
11677        <entry><literal><function>has_any_column_privilege</function>(<parameter>table</parameter>,
11678                                   <parameter>privilege</parameter>)</literal>
11679        </entry>
11680        <entry><type>boolean</type></entry>
11681        <entry>does current user have privilege for any column of table</entry>
11682       </row>
11683       <row>
11684        <entry><literal><function>has_column_privilege</function>(<parameter>user</parameter>,
11685                                   <parameter>table</parameter>,
11686                                   <parameter>column</parameter>,
11687                                   <parameter>privilege</parameter>)</literal>
11688        </entry>
11689        <entry><type>boolean</type></entry>
11690        <entry>does user have privilege for column</entry>
11691       </row>
11692       <row>
11693        <entry><literal><function>has_column_privilege</function>(<parameter>table</parameter>,
11694                                   <parameter>column</parameter>,
11695                                   <parameter>privilege</parameter>)</literal>
11696        </entry>
11697        <entry><type>boolean</type></entry>
11698        <entry>does current user have privilege for column</entry>
11699       </row>
11700       <row>
11701        <entry><literal><function>has_database_privilege</function>(<parameter>user</parameter>,
11702                                   <parameter>database</parameter>,
11703                                   <parameter>privilege</parameter>)</literal>
11704        </entry>
11705        <entry><type>boolean</type></entry>
11706        <entry>does user have privilege for database</entry>
11707       </row>
11708       <row>
11709        <entry><literal><function>has_database_privilege</function>(<parameter>database</parameter>,
11710                                   <parameter>privilege</parameter>)</literal>
11711        </entry>
11712        <entry><type>boolean</type></entry>
11713        <entry>does current user have privilege for database</entry>
11714       </row>
11715       <row>
11716        <entry><literal><function>has_foreign_data_wrapper_privilege</function>(<parameter>user</parameter>,
11717                                   <parameter>fdw</parameter>,
11718                                   <parameter>privilege</parameter>)</literal>
11719        </entry>
11720        <entry><type>boolean</type></entry>
11721        <entry>does user have privilege for foreign-data wrapper</entry>
11722       </row>
11723       <row>
11724        <entry><literal><function>has_foreign_data_wrapper_privilege</function>(<parameter>fdw</parameter>,
11725                                   <parameter>privilege</parameter>)</literal>
11726        </entry>
11727        <entry><type>boolean</type></entry>
11728        <entry>does current user have privilege for foreign-data wrapper</entry>
11729       </row>
11730       <row>
11731        <entry><literal><function>has_function_privilege</function>(<parameter>user</parameter>,
11732                                   <parameter>function</parameter>,
11733                                   <parameter>privilege</parameter>)</literal>
11734        </entry>
11735        <entry><type>boolean</type></entry>
11736        <entry>does user have privilege for function</entry>
11737       </row>
11738       <row>
11739        <entry><literal><function>has_function_privilege</function>(<parameter>function</parameter>,
11740                                   <parameter>privilege</parameter>)</literal>
11741        </entry>
11742        <entry><type>boolean</type></entry>
11743        <entry>does current user have privilege for function</entry>
11744       </row>
11745       <row>
11746        <entry><literal><function>has_language_privilege</function>(<parameter>user</parameter>,
11747                                   <parameter>language</parameter>,
11748                                   <parameter>privilege</parameter>)</literal>
11749        </entry>
11750        <entry><type>boolean</type></entry>
11751        <entry>does user have privilege for language</entry>
11752       </row>
11753       <row>
11754        <entry><literal><function>has_language_privilege</function>(<parameter>language</parameter>,
11755                                   <parameter>privilege</parameter>)</literal>
11756        </entry>
11757        <entry><type>boolean</type></entry>
11758        <entry>does current user have privilege for language</entry>
11759       </row>
11760       <row>
11761        <entry><literal><function>has_schema_privilege</function>(<parameter>user</parameter>,
11762                                   <parameter>schema</parameter>,
11763                                   <parameter>privilege</parameter>)</literal>
11764        </entry>
11765        <entry><type>boolean</type></entry>
11766        <entry>does user have privilege for schema</entry>
11767       </row>
11768       <row>
11769        <entry><literal><function>has_schema_privilege</function>(<parameter>schema</parameter>,
11770                                   <parameter>privilege</parameter>)</literal>
11771        </entry>
11772        <entry><type>boolean</type></entry>
11773        <entry>does current user have privilege for schema</entry>
11774       </row>
11775       <row>
11776        <entry><literal><function>has_server_privilege</function>(<parameter>user</parameter>,
11777                                   <parameter>server</parameter>,
11778                                   <parameter>privilege</parameter>)</literal>
11779        </entry>
11780        <entry><type>boolean</type></entry>
11781        <entry>does user have privilege for foreign server</entry>
11782       </row>
11783       <row>
11784        <entry><literal><function>has_server_privilege</function>(<parameter>server</parameter>,
11785                                   <parameter>privilege</parameter>)</literal>
11786        </entry>
11787        <entry><type>boolean</type></entry>
11788        <entry>does current user have privilege for foreign server</entry>
11789       </row>
11790       <row>
11791        <entry><literal><function>has_table_privilege</function>(<parameter>user</parameter>,
11792                                   <parameter>table</parameter>,
11793                                   <parameter>privilege</parameter>)</literal>
11794        </entry>
11795        <entry><type>boolean</type></entry>
11796        <entry>does user have privilege for table</entry>
11797       </row>
11798       <row>
11799        <entry><literal><function>has_table_privilege</function>(<parameter>table</parameter>,
11800                                   <parameter>privilege</parameter>)</literal>
11801        </entry>
11802        <entry><type>boolean</type></entry>
11803        <entry>does current user have privilege for table</entry>
11804       </row>
11805       <row>
11806        <entry><literal><function>has_tablespace_privilege</function>(<parameter>user</parameter>,
11807                                   <parameter>tablespace</parameter>,
11808                                   <parameter>privilege</parameter>)</literal>
11809        </entry>
11810        <entry><type>boolean</type></entry>
11811        <entry>does user have privilege for tablespace</entry>
11812       </row>
11813       <row>
11814        <entry><literal><function>has_tablespace_privilege</function>(<parameter>tablespace</parameter>,
11815                                   <parameter>privilege</parameter>)</literal>
11816        </entry>
11817        <entry><type>boolean</type></entry>
11818        <entry>does current user have privilege for tablespace</entry>
11819       </row>
11820       <row>
11821        <entry><literal><function>pg_has_role</function>(<parameter>user</parameter>,
11822                                   <parameter>role</parameter>,
11823                                   <parameter>privilege</parameter>)</literal>
11824        </entry>
11825        <entry><type>boolean</type></entry>
11826        <entry>does user have privilege for role</entry>
11827       </row>
11828       <row>
11829        <entry><literal><function>pg_has_role</function>(<parameter>role</parameter>,
11830                                   <parameter>privilege</parameter>)</literal>
11831        </entry>
11832        <entry><type>boolean</type></entry>
11833        <entry>does current user have privilege for role</entry>
11834       </row>
11835      </tbody>
11836     </tgroup>
11837    </table>
11838
11839    <indexterm>
11840     <primary>has_any_column_privilege</primary>
11841    </indexterm>
11842    <indexterm>
11843     <primary>has_column_privilege</primary>
11844    </indexterm>
11845    <indexterm>
11846     <primary>has_database_privilege</primary>
11847    </indexterm>
11848    <indexterm>
11849     <primary>has_function_privilege</primary>
11850    </indexterm>
11851    <indexterm>
11852     <primary>has_foreign_data_wrapper_privilege</primary>
11853    </indexterm>
11854    <indexterm>
11855     <primary>has_language_privilege</primary>
11856    </indexterm>
11857    <indexterm>
11858     <primary>has_schema_privilege</primary>
11859    </indexterm>
11860    <indexterm>
11861     <primary>has_server_privilege</primary>
11862    </indexterm>
11863    <indexterm>
11864     <primary>has_table_privilege</primary>
11865    </indexterm>
11866    <indexterm>
11867     <primary>has_tablespace_privilege</primary>
11868    </indexterm>
11869    <indexterm>
11870     <primary>pg_has_role</primary>
11871    </indexterm>
11872
11873    <para>
11874     <function>has_table_privilege</function> checks whether a user
11875     can access a table in a particular way.  The user can be
11876     specified by name or by OID
11877     (<literal>pg_authid.oid</literal>), or if the argument is
11878     omitted
11879     <function>current_user</function> is assumed.  The table can be specified
11880     by name or by OID.  (Thus, there are actually six variants of
11881     <function>has_table_privilege</function>, which can be distinguished by
11882     the number and types of their arguments.)  When specifying by name,
11883     the name can be schema-qualified if necessary.
11884     The desired access privilege type
11885     is specified by a text string, which must evaluate to one of the
11886     values <literal>SELECT</literal>, <literal>INSERT</literal>,
11887     <literal>UPDATE</literal>, <literal>DELETE</literal>, <literal>TRUNCATE</>,
11888     <literal>REFERENCES</literal>, or <literal>TRIGGER</literal>.  Optionally,
11889     <literal>WITH GRANT OPTION</> can be added to a privilege type to test
11890     whether the privilege is held with grant option.  Also, multiple privilege
11891     types can be listed separated by commas, in which case the result will
11892     be <literal>true</> if any of the listed privileges is held.
11893     (Case of the privilege string is not significant, and extra whitespace
11894     is allowed between but not within privilege names.)
11895     Some examples:
11896 <programlisting>
11897 SELECT has_table_privilege('myschema.mytable', 'select');
11898 SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION');
11899 </programlisting>
11900    </para>
11901
11902    <para>
11903     <function>has_any_column_privilege</function> checks whether a user can
11904     access any column of a table in a particular way.
11905     Its argument possibilities
11906     are analogous to <function>has_table_privilege</>,
11907     except that the desired access privilege type must evaluate to some
11908     combination of
11909     <literal>SELECT</literal>,
11910     <literal>INSERT</literal>,
11911     <literal>UPDATE</literal>, or
11912     <literal>REFERENCES</literal>.  Note that having any of these privileges
11913     at the table level implicitly grants it for each column of the table,
11914     so <function>has_any_column_privilege</function> will always return
11915     <literal>true</> if <function>has_table_privilege</> does for the same
11916     arguments.  But <function>has_any_column_privilege</> also succeeds if
11917     there is a column-level grant of the privilege for at least one column.
11918    </para>
11919
11920    <para>
11921     <function>has_column_privilege</function> checks whether a user
11922     can access a column in a particular way.
11923     Its argument possibilities
11924     are analogous to <function>has_table_privilege</function>,
11925     with the addition that the column can be specified either by name
11926     or attribute number.
11927     The desired access privilege type must evaluate to some combination of
11928     <literal>SELECT</literal>,
11929     <literal>INSERT</literal>,
11930     <literal>UPDATE</literal>, or
11931     <literal>REFERENCES</literal>.  Note that having any of these privileges
11932     at the table level implicitly grants it for each column of the table.
11933    </para>
11934
11935    <para>
11936     <function>has_database_privilege</function> checks whether a user
11937     can access a database in a particular way.
11938     Its argument possibilities
11939     are analogous to <function>has_table_privilege</function>.
11940     The desired access privilege type must evaluate to some combination of
11941     <literal>CREATE</literal>,
11942     <literal>CONNECT</literal>,
11943     <literal>TEMPORARY</literal>, or
11944     <literal>TEMP</literal> (which is equivalent to
11945     <literal>TEMPORARY</literal>).
11946    </para>
11947
11948    <para>
11949     <function>has_function_privilege</function> checks whether a user
11950     can access a function in a particular way.
11951     Its argument possibilities
11952     are analogous to <function>has_table_privilege</function>.
11953     When specifying a function by a text string rather than by OID,
11954     the allowed input is the same as for the <type>regprocedure</> data type
11955     (see <xref linkend="datatype-oid">).
11956     The desired access privilege type must evaluate to
11957     <literal>EXECUTE</literal>.
11958     An example is:
11959 <programlisting>
11960 SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
11961 </programlisting>
11962    </para>
11963
11964    <para>
11965     <function>has_foreign_data_wrapper_privilege</function> checks whether a user
11966     can access a foreign-data wrapper in a particular way.
11967     Its argument possibilities
11968     are analogous to <function>has_table_privilege</function>.
11969     The desired access privilege type must evaluate to
11970     <literal>USAGE</literal>.
11971    </para>
11972
11973    <para>
11974     <function>has_language_privilege</function> checks whether a user
11975     can access a procedural language in a particular way.
11976     Its argument possibilities
11977     are analogous to <function>has_table_privilege</function>.
11978     The desired access privilege type must evaluate to
11979     <literal>USAGE</literal>.
11980    </para>
11981
11982    <para>
11983     <function>has_schema_privilege</function> checks whether a user
11984     can access a schema in a particular way.
11985     Its argument possibilities
11986     are analogous to <function>has_table_privilege</function>.
11987     The desired access privilege type must evaluate to some combination of
11988     <literal>CREATE</literal> or
11989     <literal>USAGE</literal>.
11990    </para>
11991
11992    <para>
11993     <function>has_server_privilege</function> checks whether a user
11994     can access a foreign server in a particular way.
11995     Its argument possibilities
11996     are analogous to <function>has_table_privilege</function>.
11997     The desired access privilege type must evaluate to
11998     <literal>USAGE</literal>.
11999    </para>
12000
12001    <para>
12002     <function>has_tablespace_privilege</function> checks whether a user
12003     can access a tablespace in a particular way.
12004     Its argument possibilities
12005     are analogous to <function>has_table_privilege</function>.
12006     The desired access privilege type must evaluate to
12007     <literal>CREATE</literal>.
12008    </para>
12009
12010    <para>
12011     <function>pg_has_role</function> checks whether a user
12012     can access a role in a particular way.
12013     Its argument possibilities
12014     are analogous to <function>has_table_privilege</function>.
12015     The desired access privilege type must evaluate to some combination of
12016     <literal>MEMBER</literal> or
12017     <literal>USAGE</literal>.
12018     <literal>MEMBER</literal> denotes direct or indirect membership in
12019     the role (that is, the right to do <command>SET ROLE</>), while
12020     <literal>USAGE</literal> denotes whether the privileges of the role
12021     are immediately available without doing <command>SET ROLE</>.
12022    </para>
12023
12024   <para>
12025    <xref linkend="functions-info-schema-table"> shows functions that
12026    determine whether a certain object is <firstterm>visible</> in the
12027    current schema search path.
12028    For example, a table is said to be visible if its
12029    containing schema is in the search path and no table of the same
12030    name appears earlier in the search path.  This is equivalent to the
12031    statement that the table can be referenced by name without explicit
12032    schema qualification.  To list the names of all visible tables:
12033 <programlisting>
12034 SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
12035 </programlisting>
12036   </para>
12037
12038    <table id="functions-info-schema-table">
12039     <title>Schema Visibility Inquiry Functions</title>
12040     <tgroup cols="3">
12041      <thead>
12042       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
12043      </thead>
12044
12045      <tbody>
12046       <row>
12047        <entry><literal><function>pg_conversion_is_visible</function>(<parameter>conversion_oid</parameter>)</literal>
12048        </entry>
12049        <entry><type>boolean</type></entry>
12050        <entry>is conversion visible in search path</entry>
12051       </row>
12052       <row>
12053        <entry><literal><function>pg_function_is_visible</function>(<parameter>function_oid</parameter>)</literal>
12054        </entry>
12055        <entry><type>boolean</type></entry>
12056        <entry>is function visible in search path</entry>
12057       </row>
12058       <row>
12059        <entry><literal><function>pg_operator_is_visible</function>(<parameter>operator_oid</parameter>)</literal>
12060        </entry>
12061        <entry><type>boolean</type></entry>
12062        <entry>is operator visible in search path</entry>
12063       </row>
12064       <row>
12065        <entry><literal><function>pg_opclass_is_visible</function>(<parameter>opclass_oid</parameter>)</literal>
12066        </entry>
12067        <entry><type>boolean</type></entry>
12068        <entry>is operator class visible in search path</entry>
12069       </row>
12070       <row>
12071        <entry><literal><function>pg_table_is_visible</function>(<parameter>table_oid</parameter>)</literal>
12072        </entry>
12073        <entry><type>boolean</type></entry>
12074        <entry>is table visible in search path</entry>
12075       </row>
12076       <row>
12077        <entry><literal><function>pg_ts_config_is_visible</function>(<parameter>config_oid</parameter>)</literal>
12078        </entry>
12079        <entry><type>boolean</type></entry>
12080        <entry>is text search configuration visible in search path</entry>
12081       </row>
12082       <row>
12083        <entry><literal><function>pg_ts_dict_is_visible</function>(<parameter>dict_oid</parameter>)</literal>
12084        </entry>
12085        <entry><type>boolean</type></entry>
12086        <entry>is text search dictionary visible in search path</entry>
12087       </row>
12088       <row>
12089        <entry><literal><function>pg_ts_parser_is_visible</function>(<parameter>parser_oid</parameter>)</literal>
12090        </entry>
12091        <entry><type>boolean</type></entry>
12092        <entry>is text search parser visible in search path</entry>
12093       </row>
12094       <row>
12095        <entry><literal><function>pg_ts_template_is_visible</function>(<parameter>template_oid</parameter>)</literal>
12096        </entry>
12097        <entry><type>boolean</type></entry>
12098        <entry>is text search template visible in search path</entry>
12099       </row>
12100       <row>
12101        <entry><literal><function>pg_type_is_visible</function>(<parameter>type_oid</parameter>)</literal>
12102        </entry>
12103        <entry><type>boolean</type></entry>
12104        <entry>is type (or domain) visible in search path</entry>
12105       </row>
12106      </tbody>
12107     </tgroup>
12108    </table>
12109
12110    <indexterm>
12111     <primary>pg_conversion_is_visible</primary>
12112    </indexterm>
12113    <indexterm>
12114     <primary>pg_function_is_visible</primary>
12115    </indexterm>
12116    <indexterm>
12117     <primary>pg_operator_is_visible</primary>
12118    </indexterm>
12119    <indexterm>
12120     <primary>pg_opclass_is_visible</primary>
12121    </indexterm>
12122    <indexterm>
12123     <primary>pg_table_is_visible</primary>
12124    </indexterm>
12125    <indexterm>
12126     <primary>pg_ts_config_is_visible</primary>
12127    </indexterm>
12128    <indexterm>
12129     <primary>pg_ts_dict_is_visible</primary>
12130    </indexterm>
12131    <indexterm>
12132     <primary>pg_ts_parser_is_visible</primary>
12133    </indexterm>
12134    <indexterm>
12135     <primary>pg_ts_template_is_visible</primary>
12136    </indexterm>
12137    <indexterm>
12138     <primary>pg_type_is_visible</primary>
12139    </indexterm>
12140
12141    <para>
12142     Each function performs the visibility check for one type of database
12143     object.  Note that <function>pg_table_is_visible</function> can also be used
12144     with views, indexes and sequences; <function>pg_type_is_visible</function>
12145     can also be used with domains. For functions and operators, an object in
12146     the search path is visible if there is no object of the same name
12147     <emphasis>and argument data type(s)</> earlier in the path.  For operator
12148     classes, both name and associated index access method are considered.
12149    </para>
12150
12151    <para>
12152     All these functions require object OIDs to identify the object to be
12153     checked.  If you want to test an object by name, it is convenient to use
12154     the OID alias types (<type>regclass</>, <type>regtype</>,
12155     <type>regprocedure</>, <type>regoperator</>, <type>regconfig</>,
12156     or <type>regdictionary</>),
12157     for example:
12158 <programlisting>
12159 SELECT pg_type_is_visible('myschema.widget'::regtype);
12160 </programlisting>
12161     Note that it would not make much sense to test a non-schema-qualified
12162     type name in this way &mdash; if the name can be recognized at all, it must be visible.
12163    </para>
12164
12165    <indexterm>
12166     <primary>format_type</primary>
12167    </indexterm>
12168
12169    <indexterm>
12170     <primary>pg_get_keywords</primary>
12171    </indexterm>
12172
12173    <indexterm>
12174     <primary>pg_get_viewdef</primary>
12175    </indexterm>
12176
12177    <indexterm>
12178     <primary>pg_get_ruledef</primary>
12179    </indexterm>
12180
12181    <indexterm>
12182     <primary>pg_get_functiondef</primary>
12183    </indexterm>
12184
12185    <indexterm>
12186     <primary>pg_get_function_arguments</primary>
12187    </indexterm>
12188
12189    <indexterm>
12190     <primary>pg_get_function_identity_arguments</primary>
12191    </indexterm>
12192
12193    <indexterm>
12194     <primary>pg_get_function_result</primary>
12195    </indexterm>
12196
12197    <indexterm>
12198     <primary>pg_get_indexdef</primary>
12199    </indexterm>
12200
12201    <indexterm>
12202     <primary>pg_get_triggerdef</primary>
12203    </indexterm>
12204
12205    <indexterm>
12206     <primary>pg_get_constraintdef</primary>
12207    </indexterm>
12208
12209    <indexterm>
12210     <primary>pg_get_expr</primary>
12211    </indexterm>
12212
12213    <indexterm>
12214     <primary>pg_get_userbyid</primary>
12215    </indexterm>
12216
12217    <indexterm>
12218     <primary>pg_get_serial_sequence</primary>
12219    </indexterm>
12220
12221    <indexterm>
12222     <primary>pg_tablespace_databases</primary>
12223    </indexterm>
12224
12225    <indexterm>
12226     <primary>pg_typeof</primary>
12227    </indexterm>
12228
12229   <para>
12230    <xref linkend="functions-info-catalog-table"> lists functions that
12231    extract information from the system catalogs.
12232   </para>
12233
12234    <table id="functions-info-catalog-table">
12235     <title>System Catalog Information Functions</title>
12236     <tgroup cols="3">
12237      <thead>
12238       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
12239      </thead>
12240
12241      <tbody>
12242       <row>
12243        <entry><literal><function>format_type</function>(<parameter>type_oid</parameter>, <parameter>typemod</>)</literal></entry>
12244        <entry><type>text</type></entry>
12245        <entry>get SQL name of a data type</entry>
12246       </row>
12247       <row>
12248        <entry><literal><function>pg_get_keywords</function>()</literal></entry>
12249        <entry><type>setof record</type></entry>
12250        <entry>get list of SQL keywords and their categories</entry>
12251       </row>
12252       <row>
12253        <entry><literal><function>pg_get_constraintdef</function>(<parameter>constraint_oid</parameter>)</literal></entry>
12254        <entry><type>text</type></entry>
12255        <entry>get definition of a constraint</entry>
12256       </row>
12257       <row>
12258        <entry><literal><function>pg_get_constraintdef</function>(<parameter>constraint_oid</parameter>, <parameter>pretty_bool</>)</literal></entry>
12259        <entry><type>text</type></entry>
12260        <entry>get definition of a constraint</entry>
12261       </row>
12262       <row>
12263        <entry><literal><function>pg_get_expr</function>(<parameter>expr_text</parameter>, <parameter>relation_oid</>)</literal></entry>
12264        <entry><type>text</type></entry>
12265        <entry>decompile internal form of an expression, assuming that any Vars
12266        in it refer to the relation indicated by the second parameter</entry>
12267       </row>
12268       <row>
12269        <entry><literal><function>pg_get_expr</function>(<parameter>expr_text</parameter>, <parameter>relation_oid</>, <parameter>pretty_bool</>)</literal></entry>
12270        <entry><type>text</type></entry>
12271        <entry>decompile internal form of an expression, assuming that any Vars
12272        in it refer to the relation indicated by the second parameter</entry>
12273       </row>
12274       <row>
12275        <entry><literal><function>pg_get_functiondef</function>(<parameter>func_oid</parameter>)</literal></entry>
12276        <entry><type>text</type></entry>
12277        <entry>get definition of a function</entry>
12278       </row>
12279       <row>
12280        <entry><literal><function>pg_get_function_arguments</function>(<parameter>func_oid</parameter>)</literal></entry>
12281        <entry><type>text</type></entry>
12282        <entry>get argument list of function's definition (with default values)</entry>
12283       </row>
12284       <row>
12285        <entry><literal><function>pg_get_function_identity_arguments</function>(<parameter>func_oid</parameter>)</literal></entry>
12286        <entry><type>text</type></entry>
12287        <entry>get argument list to identify a function (without default values)</entry>
12288       </row>
12289       <row>
12290        <entry><literal><function>pg_get_function_result</function>(<parameter>func_oid</parameter>)</literal></entry>
12291        <entry><type>text</type></entry>
12292        <entry>get <literal>RETURNS</> clause for function</entry>
12293       </row>
12294       <row>
12295        <entry><literal><function>pg_get_indexdef</function>(<parameter>index_oid</parameter>)</literal></entry>
12296        <entry><type>text</type></entry>
12297        <entry>get <command>CREATE INDEX</> command for index</entry>
12298       </row>
12299       <row>
12300        <entry><literal><function>pg_get_indexdef</function>(<parameter>index_oid</parameter>, <parameter>column_no</>, <parameter>pretty_bool</>)</literal></entry>
12301        <entry><type>text</type></entry>
12302        <entry>get <command>CREATE INDEX</> command for index,
12303        or definition of just one index column when
12304        <parameter>column_no</> is not zero</entry>
12305       </row>
12306       <row>
12307        <entry><literal><function>pg_get_ruledef</function>(<parameter>rule_oid</parameter>)</literal></entry>
12308        <entry><type>text</type></entry>
12309        <entry>get <command>CREATE RULE</> command for rule</entry>
12310       </row>
12311       <row>
12312        <entry><literal><function>pg_get_ruledef</function>(<parameter>rule_oid</parameter>, <parameter>pretty_bool</>)</literal></entry>
12313        <entry><type>text</type></entry>
12314        <entry>get <command>CREATE RULE</> command for rule</entry>
12315       </row>
12316       <row>
12317        <entry><literal><function>pg_get_serial_sequence</function>(<parameter>table_name</parameter>, <parameter>column_name</parameter>)</literal></entry>
12318        <entry><type>text</type></entry>
12319        <entry>get name of the sequence that a <type>serial</type> or <type>bigserial</type> column
12320        uses</entry>
12321       </row>
12322       <row>
12323        <entry><function>pg_get_triggerdef</function>(<parameter>trigger_oid</parameter>)</entry>
12324        <entry><type>text</type></entry>
12325        <entry>get <command>CREATE [ CONSTRAINT ] TRIGGER</> command for trigger</entry>
12326       </row>
12327       <row>
12328        <entry><literal><function>pg_get_userbyid</function>(<parameter>role_oid</parameter>)</literal></entry>
12329        <entry><type>name</type></entry>
12330        <entry>get role name with given OID</entry>
12331       </row>
12332       <row>
12333        <entry><literal><function>pg_get_viewdef</function>(<parameter>view_name</parameter>)</literal></entry>
12334        <entry><type>text</type></entry>
12335        <entry>get underlying <command>SELECT</command> command for view (<emphasis>deprecated</emphasis>)</entry>
12336       </row>
12337       <row>
12338        <entry><literal><function>pg_get_viewdef</function>(<parameter>view_name</parameter>, <parameter>pretty_bool</>)</literal></entry>
12339        <entry><type>text</type></entry>
12340        <entry>get underlying <command>SELECT</command> command for view (<emphasis>deprecated</emphasis>)</entry>
12341       </row>
12342       <row>
12343        <entry><literal><function>pg_get_viewdef</function>(<parameter>view_oid</parameter>)</literal></entry>
12344        <entry><type>text</type></entry>
12345        <entry>get underlying <command>SELECT</command> command for view</entry>
12346       </row>
12347       <row>
12348        <entry><literal><function>pg_get_viewdef</function>(<parameter>view_oid</parameter>, <parameter>pretty_bool</>)</literal></entry>
12349        <entry><type>text</type></entry>
12350        <entry>get underlying <command>SELECT</command> command for view</entry>
12351       </row>
12352       <row>
12353        <entry><literal><function>pg_tablespace_databases</function>(<parameter>tablespace_oid</parameter>)</literal></entry>
12354        <entry><type>setof oid</type></entry>
12355        <entry>get the set of database OIDs that have objects in the tablespace</entry>
12356       </row>
12357       <row>
12358        <entry><literal><function>pg_typeof</function>(<parameter>any</parameter>)</literal></entry>
12359        <entry><type>regtype</type></entry>
12360        <entry>get the data type of any value</entry>
12361       </row>
12362      </tbody>
12363     </tgroup>
12364    </table>
12365
12366   <para>
12367    <function>format_type</function> returns the SQL name of a data type that
12368    is identified by its type OID and possibly a type modifier.  Pass NULL
12369    for the type modifier if no specific modifier is known.
12370   </para>
12371
12372   <para>
12373    <function>pg_get_keywords</function> returns a set of records describing
12374    the SQL keywords recognized by the server. The <structfield>word</> column
12375    contains the keyword.  The <structfield>catcode</> column contains a
12376    category code: <literal>U</> for unreserved, <literal>C</> for column name,
12377    <literal>T</> for type or function name, or <literal>R</> for reserved.
12378    The <structfield>catdesc</> column contains a possibly-localized string
12379    describing the category.
12380   </para>
12381
12382   <para>
12383    <function>pg_get_constraintdef</function>,
12384    <function>pg_get_indexdef</function>, <function>pg_get_ruledef</function>,
12385    and <function>pg_get_triggerdef</function>, respectively reconstruct the
12386    creating command for a constraint, index, rule, or trigger. (Note that this
12387    is a decompiled reconstruction, not the original text of the command.)
12388    <function>pg_get_expr</function> decompiles the internal form of an
12389    individual expression, such as the default value for a column.  It can be
12390    useful when examining the contents of system catalogs.  If the expression
12391    might contain Vars, specify the OID of the relation they refer to as the
12392    second parameter; if no Vars are expected, zero is sufficient.
12393    <function>pg_get_viewdef</function> reconstructs the <command>SELECT</>
12394    query that defines a view. Most of these functions come in two variants,
12395    one of which can optionally <quote>pretty-print</> the result.  The
12396    pretty-printed format is more readable, but the default format is more
12397    likely to be interpreted the same way by future versions of
12398    <productname>PostgreSQL</>; avoid using pretty-printed output for dump
12399    purposes.  Passing <literal>false</> for the pretty-print parameter yields
12400    the same result as the variant that does not have the parameter at all.
12401   </para>
12402
12403   <para>
12404    <function>pg_get_functiondef</> returns a complete
12405    <command>CREATE OR REPLACE FUNCTION</> statement for a function.
12406    <function>pg_get_function_arguments</function> returns the argument list
12407    of a function, in the form it would need to appear in within
12408    <command>CREATE FUNCTION</>.
12409    <function>pg_get_function_result</function> similarly returns the
12410    appropriate <literal>RETURNS</> clause for the function.
12411    <function>pg_get_function_identity_arguments</function> returns the
12412    argument list necessary to identify a function, in the form it
12413    would need to appear in within <command>ALTER FUNCTION</>, for
12414    instance.  This form omits default values.
12415   </para>
12416
12417   <para>
12418    <function>pg_get_serial_sequence</function> returns the name of the
12419    sequence associated with a column, or NULL if no sequence is associated
12420    with the column.  The first input parameter is a table name with
12421    optional schema, and the second parameter is a column name.  Because
12422    the first parameter is potentially a schema and table, it is not treated
12423    as a double-quoted identifier, meaning it is lowercased by default,
12424    while the second parameter, being just a column name, is treated as
12425    double-quoted and has its case preserved.  The function returns a value
12426    suitably formatted for passing to sequence functions (see <xref
12427    linkend="functions-sequence">).  This association can be modified or
12428    removed with <command>ALTER SEQUENCE OWNED BY</>.  (The function
12429    probably should have been called
12430    <function>pg_get_owned_sequence</function>; its current name reflects the fact
12431    that it's typically used with <type>serial</> or <type>bigserial</>
12432    columns.)
12433   </para>
12434
12435   <para>
12436    <function>pg_get_userbyid</function> extracts a role's name given
12437    its OID.
12438   </para>
12439
12440   <para>
12441    <function>pg_tablespace_databases</function> allows a tablespace to be
12442    examined. It returns the set of OIDs of databases that have objects stored
12443    in the tablespace. If this function returns any rows, the tablespace is not
12444    empty and cannot be dropped. To display the specific objects populating the
12445    tablespace, you will need to connect to the databases identified by
12446    <function>pg_tablespace_databases</function> and query their
12447    <structname>pg_class</> catalogs.
12448   </para>
12449
12450   <para>
12451    <function>pg_typeof</function> returns the OID of the data type of the
12452    value that is passed to it.  This can be helpful for troubleshooting or
12453    dynamically constructing SQL queries.  The function is declared as
12454    returning <type>regtype</>, which is an OID alias type (see
12455    <xref linkend="datatype-oid">); this means that it is the same as an
12456    OID for comparison purposes but displays as a type name.  For example:
12457 <programlisting>
12458 SELECT pg_typeof(33);
12459
12460  pg_typeof
12461 -----------
12462  integer
12463 (1 row)
12464
12465 SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
12466  typlen
12467 --------
12468       4
12469 (1 row)
12470 </programlisting>
12471   </para>
12472
12473    <indexterm>
12474     <primary>col_description</primary>
12475    </indexterm>
12476
12477    <indexterm>
12478     <primary>obj_description</primary>
12479    </indexterm>
12480
12481    <indexterm>
12482     <primary>shobj_description</primary>
12483    </indexterm>
12484
12485    <indexterm>
12486     <primary>comment</primary>
12487     <secondary sortas="database objects">about database objects</secondary>
12488    </indexterm>
12489
12490    <para>
12491     The functions shown in <xref linkend="functions-info-comment-table">
12492     extract comments previously stored with the <xref linkend="sql-comment"
12493     endterm="sql-comment-title"> command.  A null value is returned if no
12494     comment could be found for the specified parameters.
12495    </para>
12496
12497    <table id="functions-info-comment-table">
12498     <title>Comment Information Functions</title>
12499     <tgroup cols="3">
12500      <thead>
12501       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
12502      </thead>
12503
12504      <tbody>
12505       <row>
12506        <entry><literal><function>col_description</function>(<parameter>table_oid</parameter>, <parameter>column_number</parameter>)</literal></entry>
12507        <entry><type>text</type></entry>
12508        <entry>get comment for a table column</entry>
12509       </row>
12510       <row>
12511        <entry><literal><function>obj_description</function>(<parameter>object_oid</parameter>, <parameter>catalog_name</parameter>)</literal></entry>
12512        <entry><type>text</type></entry>
12513        <entry>get comment for a database object</entry>
12514       </row>
12515       <row>
12516        <entry><literal><function>obj_description</function>(<parameter>object_oid</parameter>)</literal></entry>
12517        <entry><type>text</type></entry>
12518        <entry>get comment for a database object (<emphasis>deprecated</emphasis>)</entry>
12519       </row>
12520       <row>
12521        <entry><literal><function>shobj_description</function>(<parameter>object_oid</parameter>, <parameter>catalog_name</parameter>)</literal></entry>
12522        <entry><type>text</type></entry>
12523        <entry>get comment for a shared database object</entry>
12524       </row>
12525      </tbody>
12526     </tgroup>
12527    </table>
12528
12529    <para>
12530     <function>col_description</function> returns the comment for a table column,
12531     which is specified by the OID of its table and its column number.
12532     <function>obj_description</function> cannot be used for table columns since
12533     columns do not have OIDs of their own.
12534    </para>
12535
12536    <para>
12537     The two-parameter form of <function>obj_description</function> returns the
12538     comment for a database object specified by its OID and the name of the
12539     containing system catalog.  For example,
12540     <literal>obj_description(123456,'pg_class')</literal>
12541     would retrieve the comment for the table with OID 123456.
12542     The one-parameter form of <function>obj_description</function> requires only
12543     the object OID.  It is deprecated since there is no guarantee that
12544     OIDs are unique across different system catalogs; therefore, the wrong
12545     comment might be returned.
12546    </para>
12547
12548    <para>
12549     <function>shobj_description</function> is used just like
12550     <function>obj_description</function> except it is used for retrieving
12551     comments on shared objects.  Some system catalogs are global to all
12552     databases within each cluster and their descriptions are stored globally
12553     as well.
12554    </para>
12555
12556    <indexterm>
12557     <primary>txid_current</primary>
12558    </indexterm>
12559
12560    <indexterm>
12561     <primary>txid_current_snapshot</primary>
12562    </indexterm>
12563
12564    <indexterm>
12565     <primary>txid_snapshot_xmin</primary>
12566    </indexterm>
12567
12568    <indexterm>
12569     <primary>txid_snapshot_xmax</primary>
12570    </indexterm>
12571
12572    <indexterm>
12573     <primary>txid_snapshot_xip</primary>
12574    </indexterm>
12575
12576    <indexterm>
12577     <primary>txid_visible_in_snapshot</primary>
12578    </indexterm>
12579
12580    <para>
12581     The functions shown in <xref linkend="functions-txid-snapshot">
12582     provide server transaction information in an exportable form.  The main
12583     use of these functions is to determine which transactions were committed
12584     between two snapshots.
12585    </para>
12586
12587    <table id="functions-txid-snapshot">
12588     <title>Transaction IDs and snapshots</title>
12589     <tgroup cols="3">
12590      <thead>
12591       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
12592      </thead>
12593
12594      <tbody>
12595       <row>
12596        <entry><literal><function>txid_current</function>()</literal></entry>
12597        <entry><type>bigint</type></entry>
12598        <entry>get current transaction ID</entry>
12599       </row>
12600       <row>
12601        <entry><literal><function>txid_current_snapshot</function>()</literal></entry>
12602        <entry><type>txid_snapshot</type></entry>
12603        <entry>get current snapshot</entry>
12604       </row>
12605       <row>
12606        <entry><literal><function>txid_snapshot_xmin</function>(<parameter>txid_snapshot</parameter>)</literal></entry>
12607        <entry><type>bigint</type></entry>
12608        <entry>get xmin of snapshot</entry>
12609       </row>
12610       <row>
12611        <entry><literal><function>txid_snapshot_xmax</function>(<parameter>txid_snapshot</parameter>)</literal></entry>
12612        <entry><type>bigint</type></entry>
12613        <entry>get xmax of snapshot</entry>
12614       </row>
12615       <row>
12616        <entry><literal><function>txid_snapshot_xip</function>(<parameter>txid_snapshot</parameter>)</literal></entry>
12617        <entry><type>setof bigint</type></entry>
12618        <entry>get in-progress transaction IDs in snapshot</entry>
12619       </row>
12620       <row>
12621        <entry><literal><function>txid_visible_in_snapshot</function>(<parameter>bigint</parameter>, <parameter>txid_snapshot</parameter>)</literal></entry>
12622        <entry><type>boolean</type></entry>
12623        <entry>is transaction ID visible in snapshot? (do not use with subtransaction ids)</entry>
12624       </row>
12625      </tbody>
12626     </tgroup>
12627    </table>
12628
12629    <para>
12630     The internal transaction ID type (<type>xid</>) is 32 bits wide and
12631     wraps around every 4 billion transactions.  However, these functions
12632     export a 64-bit format that is extended with an <quote>epoch</> counter
12633     so it will not wrap around during the life of an installation.
12634     The data type used by these functions, <type>txid_snapshot</type>,
12635     stores information about transaction ID
12636     visibility at a particular moment in time.  Its components are
12637     described in <xref linkend="functions-txid-snapshot-parts">.
12638    </para>
12639
12640    <table id="functions-txid-snapshot-parts">
12641     <title>Snapshot components</title>
12642     <tgroup cols="2">
12643      <thead>
12644       <row>
12645        <entry>Name</entry>
12646        <entry>Description</entry>
12647       </row>
12648      </thead>
12649
12650      <tbody>
12651
12652       <row>
12653        <entry><type>xmin</type></entry>
12654        <entry>
12655          Earliest transaction ID (txid) that is still active.  All earlier
12656          transactions will either be committed and visible, or rolled
12657          back and dead.
12658        </entry>
12659       </row>
12660
12661       <row>
12662        <entry><type>xmax</type></entry>
12663        <entry>
12664         First as-yet-unassigned txid.  All txids greater than or equal to this
12665         are not yet started as of the time of the snapshot, and thus invisible.
12666        </entry>
12667       </row>
12668
12669       <row>
12670        <entry><type>xip_list</type></entry>
12671        <entry>
12672         Active txids at the time of the snapshot.  The list
12673         includes only those active txids between <literal>xmin</>
12674         and <literal>xmax</>; there might be active txids higher
12675         than <literal>xmax</>.  A txid that is <literal>xmin &lt;= txid &lt;
12676         xmax</literal> and not in this list was already completed
12677         at the time of the snapshot, and thus either visible or
12678         dead according to its commit status.  The list does not
12679         include txids of subtransactions.
12680        </entry>
12681       </row>
12682
12683      </tbody>
12684     </tgroup>
12685    </table>
12686
12687    <para>
12688     <type>txid_snapshot</>'s textual representation is
12689     <literal><replaceable>xmin</>:<replaceable>xmax</>:<replaceable>xip_list</></literal>.
12690     For example <literal>10:20:10,14,15</literal> means
12691     <literal>xmin=10, xmax=20, xip_list=10, 14, 15</literal>.
12692    </para>
12693   </sect1>
12694
12695   <sect1 id="functions-admin">
12696    <title>System Administration Functions</title>
12697
12698    <para>
12699     <xref linkend="functions-admin-set-table"> shows the functions
12700     available to query and alter run-time configuration parameters.
12701    </para>
12702
12703    <table id="functions-admin-set-table">
12704     <title>Configuration Settings Functions</title>
12705     <tgroup cols="3">
12706      <thead>
12707       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
12708      </thead>
12709
12710      <tbody>
12711       <row>
12712        <entry>
12713         <literal><function>current_setting</function>(<parameter>setting_name</parameter>)</literal>
12714        </entry>
12715        <entry><type>text</type></entry>
12716        <entry>get current value of setting</entry>
12717       </row>
12718       <row>
12719        <entry>
12720         <literal><function>set_config(<parameter>setting_name</parameter>,
12721                              <parameter>new_value</parameter>,
12722                              <parameter>is_local</parameter>)</function></literal>
12723        </entry>
12724        <entry><type>text</type></entry>
12725        <entry>set parameter and return new value</entry>
12726       </row>
12727      </tbody>
12728     </tgroup>
12729    </table>
12730
12731    <indexterm>
12732     <primary>SET</primary>
12733    </indexterm>
12734
12735    <indexterm>
12736     <primary>SHOW</primary>
12737    </indexterm>
12738
12739    <indexterm>
12740     <primary>configuration</primary>
12741     <secondary sortas="server">of the server</secondary>
12742     <tertiary>functions</tertiary>
12743    </indexterm>
12744
12745    <para>
12746     The function <function>current_setting</function> yields the
12747     current value of the setting <parameter>setting_name</parameter>.
12748     It corresponds to the <acronym>SQL</acronym> command
12749     <command>SHOW</command>.  An example:
12750 <programlisting>
12751 SELECT current_setting('datestyle');
12752
12753  current_setting
12754 -----------------
12755  ISO, MDY
12756 (1 row)
12757 </programlisting>
12758    </para>
12759
12760    <para>
12761     <function>set_config</function> sets the parameter
12762     <parameter>setting_name</parameter> to
12763     <parameter>new_value</parameter>.  If
12764     <parameter>is_local</parameter> is <literal>true</literal>, the
12765     new value will only apply to the current transaction. If you want
12766     the new value to apply for the current session, use
12767     <literal>false</literal> instead. The function corresponds to the
12768     SQL command <command>SET</command>. An example:
12769 <programlisting>
12770 SELECT set_config('log_statement_stats', 'off', false);
12771
12772  set_config
12773 ------------
12774  off
12775 (1 row)
12776 </programlisting>
12777    </para>
12778
12779    <indexterm>
12780     <primary>pg_cancel_backend</primary>
12781    </indexterm>
12782    <indexterm>
12783     <primary>pg_terminate_backend</primary>
12784    </indexterm>
12785    <indexterm>
12786     <primary>pg_reload_conf</primary>
12787    </indexterm>
12788    <indexterm>
12789     <primary>pg_rotate_logfile</primary>
12790    </indexterm>
12791
12792    <indexterm>
12793     <primary>signal</primary>
12794     <secondary sortas="backend">backend processes</secondary>
12795    </indexterm>
12796
12797    <para>
12798     The functions shown in <xref
12799     linkend="functions-admin-signal-table"> send control signals to
12800     other server processes.  Use of these functions is restricted
12801     to superusers.
12802    </para>
12803
12804    <table id="functions-admin-signal-table">
12805     <title>Server Signalling Functions</title>
12806     <tgroup cols="3">
12807      <thead>
12808       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
12809       </row>
12810      </thead>
12811
12812      <tbody>
12813       <row>
12814        <entry>
12815         <literal><function>pg_cancel_backend</function>(<parameter>pid</parameter> <type>int</>)</literal>
12816         </entry>
12817        <entry><type>boolean</type></entry>
12818        <entry>Cancel a backend's current query</entry>
12819       </row>
12820       <row>
12821        <entry>
12822         <literal><function>pg_terminate_backend</function>(<parameter>pid</parameter> <type>int</>)</literal>
12823         </entry>
12824        <entry><type>boolean</type></entry>
12825        <entry>Terminate a backend</entry>
12826       </row>
12827       <row>
12828        <entry>
12829         <literal><function>pg_reload_conf</function>()</literal>
12830         </entry>
12831        <entry><type>boolean</type></entry>
12832        <entry>Cause server processes to reload their configuration files</entry>
12833       </row>
12834       <row>
12835        <entry>
12836         <literal><function>pg_rotate_logfile</function>()</literal>
12837         </entry>
12838        <entry><type>boolean</type></entry>
12839        <entry>Rotate server's log file</entry>
12840       </row>
12841      </tbody>
12842     </tgroup>
12843    </table>
12844
12845    <para>
12846     Each of these functions returns <literal>true</literal> if
12847     successful and <literal>false</literal> otherwise.
12848    </para>
12849
12850    <para>
12851     <function>pg_cancel_backend</> and <function>pg_terminate_backend</>
12852     send signals (<systemitem>SIGINT</> or <systemitem>SIGTERM</>
12853     respectively) to backend processes identified by process ID.
12854     The process ID of an active backend can be found from
12855     the <structfield>procpid</structfield> column of the
12856     <structname>pg_stat_activity</structname> view, or by listing the
12857     <command>postgres</command> processes on the server (using
12858     <application>ps</> on Unix or the <application>Task
12859     Manager</> on <productname>Windows</>).
12860    </para>
12861
12862    <para>
12863     <function>pg_reload_conf</> sends a <systemitem>SIGHUP</> signal
12864     to the server, causing configuration files
12865     to be reloaded by all server processes.
12866    </para>
12867
12868    <para>
12869     <function>pg_rotate_logfile</> signals the log-file manager to switch
12870     to a new output file immediately.  This works only when the built-in
12871     log collector is running, since otherwise there is no log-file manager
12872     subprocess.
12873    </para>
12874
12875    <indexterm>
12876     <primary>pg_start_backup</primary>
12877    </indexterm>
12878    <indexterm>
12879     <primary>pg_stop_backup</primary>
12880    </indexterm>
12881    <indexterm>
12882     <primary>pg_switch_xlog</primary>
12883    </indexterm>
12884    <indexterm>
12885     <primary>pg_current_xlog_location</primary>
12886    </indexterm>
12887    <indexterm>
12888     <primary>pg_current_xlog_insert_location</primary>
12889    </indexterm>
12890    <indexterm>
12891     <primary>pg_xlogfile_name_offset</primary>
12892    </indexterm>
12893    <indexterm>
12894     <primary>pg_xlogfile_name</primary>
12895    </indexterm>
12896    <indexterm>
12897     <primary>backup</primary>
12898    </indexterm>
12899
12900    <para>
12901     The functions shown in <xref
12902     linkend="functions-admin-backup-table"> assist in making on-line backups.
12903     Use of the first three functions is restricted to superusers.
12904    </para>
12905
12906    <table id="functions-admin-backup-table">
12907     <title>Backup Control Functions</title>
12908     <tgroup cols="3">
12909      <thead>
12910       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
12911       </row>
12912      </thead>
12913
12914      <tbody>
12915       <row>
12916        <entry>
12917         <literal><function>pg_start_backup</function>(<parameter>label</> <type>text</> <optional>, <parameter>fast</> <type>boolean</> </optional>)</literal>
12918         </entry>
12919        <entry><type>text</type></entry>
12920        <entry>Prepare for performing on-line backup</entry>
12921       </row>
12922       <row>
12923        <entry>
12924         <literal><function>pg_stop_backup</function>()</literal>
12925         </entry>
12926        <entry><type>text</type></entry>
12927        <entry>Finish performing on-line backup</entry>
12928       </row>
12929       <row>
12930        <entry>
12931         <literal><function>pg_switch_xlog</function>()</literal>
12932         </entry>
12933        <entry><type>text</type></entry>
12934        <entry>Force switch to a new transaction log file</entry>
12935       </row>
12936       <row>
12937        <entry>
12938         <literal><function>pg_current_xlog_location</function>()</literal>
12939         </entry>
12940        <entry><type>text</type></entry>
12941        <entry>Get current transaction log write location</entry>
12942       </row>
12943       <row>
12944        <entry>
12945         <literal><function>pg_current_xlog_insert_location</function>()</literal>
12946         </entry>
12947        <entry><type>text</type></entry>
12948        <entry>Get current transaction log insert location</entry>
12949       </row>
12950       <row>
12951        <entry>
12952         <literal><function>pg_xlogfile_name_offset</function>(<parameter>location</> <type>text</>)</literal>
12953         </entry>
12954        <entry><type>text</>, <type>integer</></entry>
12955        <entry>Convert transaction log location string to file name and decimal byte offset within file</entry>
12956       </row>
12957       <row>
12958        <entry>
12959         <literal><function>pg_xlogfile_name</function>(<parameter>location</> <type>text</>)</literal>
12960         </entry>
12961        <entry><type>text</type></entry>
12962        <entry>Convert transaction log location string to file name</entry>
12963       </row>
12964      </tbody>
12965     </tgroup>
12966    </table>
12967
12968    <para>
12969     <function>pg_start_backup</> accepts an
12970     arbitrary user-defined label for the backup.  (Typically this would be
12971     the name under which the backup dump file will be stored.)  The function
12972     writes a backup label file (<filename>backup_label</>) into the
12973     database cluster's data directory, performs a checkpoint,
12974     and then returns the backup's starting transaction log location as text.
12975     The user can ignore this result value, but it is
12976     provided in case it is useful.
12977 <programlisting>
12978 postgres=# select pg_start_backup('label_goes_here');
12979  pg_start_backup
12980 -----------------
12981  0/D4445B8
12982 (1 row)
12983 </programlisting>
12984     There is an optional boolean second parameter.  If <literal>true</>,
12985     it specifies executing <function>pg_start_backup</> as quickly as
12986     possible.  This forces an immediate checkpoint which will cause a
12987     spike in I/O operations, slowing any concurrently executing queries.
12988    </para>
12989
12990    <para>
12991     <function>pg_stop_backup</> removes the label file created by
12992     <function>pg_start_backup</>, and creates a backup history file in
12993     the transaction log archive area.  The history file includes the label given to
12994     <function>pg_start_backup</>, the starting and ending transaction log locations for
12995     the backup, and the starting and ending times of the backup.  The return
12996     value is the backup's ending transaction log location (which again
12997     can be ignored).  After recording the ending location, the current
12998     transaction log insertion
12999     point is automatically advanced to the next transaction log file, so that the
13000     ending transaction log file can be archived immediately to complete the backup.
13001    </para>
13002
13003    <para>
13004     <function>pg_switch_xlog</> moves to the next transaction log file, allowing the
13005     current file to be archived (assuming you are using continuous archiving).
13006     The return value is the ending transaction log location + 1 within the just-completed transaction log file.
13007     If there has been no transaction log activity since the last transaction log switch,
13008     <function>pg_switch_xlog</> does nothing and returns the start location
13009     of the transaction log file currently in use.
13010    </para>
13011
13012    <para>
13013     <function>pg_current_xlog_location</> displays the current transaction log write
13014     location in the same format used by the above functions.  Similarly,
13015     <function>pg_current_xlog_insert_location</> displays the current transaction log
13016     insertion point.  The insertion point is the <quote>logical</> end
13017     of the transaction log
13018     at any instant, while the write location is the end of what has actually
13019     been written out from the server's internal buffers.  The write location
13020     is the end of what can be examined from outside the server, and is usually
13021     what you want if you are interested in archiving partially-complete transaction log
13022     files.  The insertion point is made available primarily for server
13023     debugging purposes.  These are both read-only operations and do not
13024     require superuser permissions.
13025    </para>
13026
13027    <para>
13028     You can use <function>pg_xlogfile_name_offset</> to extract the
13029     corresponding transaction log file name and byte offset from the results of any of the
13030     above functions.  For example:
13031 <programlisting>
13032 postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
13033         file_name         | file_offset
13034 --------------------------+-------------
13035  00000001000000000000000D |     4039624
13036 (1 row)
13037 </programlisting>
13038     Similarly, <function>pg_xlogfile_name</> extracts just the transaction log file name.
13039     When the given transaction log location is exactly at a transaction log file boundary, both
13040     these functions return the name of the preceding transaction log file.
13041     This is usually the desired behavior for managing transaction log archiving
13042     behavior, since the preceding file is the last one that currently
13043     needs to be archived.
13044    </para>
13045
13046    <para>
13047     For details about proper usage of these functions, see
13048     <xref linkend="continuous-archiving">.
13049    </para>
13050
13051    <para>
13052     The functions shown in <xref linkend="functions-admin-dbsize"> calculate
13053     the disk space usage of database objects.
13054    </para>
13055
13056    <indexterm>
13057     <primary>pg_column_size</primary>
13058    </indexterm>
13059    <indexterm>
13060     <primary>pg_database_size</primary>
13061    </indexterm>
13062    <indexterm>
13063     <primary>pg_relation_size</primary>
13064    </indexterm>
13065    <indexterm>
13066     <primary>pg_size_pretty</primary>
13067    </indexterm>
13068    <indexterm>
13069     <primary>pg_tablespace_size</primary>
13070    </indexterm>
13071    <indexterm>
13072     <primary>pg_total_relation_size</primary>
13073    </indexterm>
13074
13075    <table id="functions-admin-dbsize">
13076     <title>Database Object Size Functions</title>
13077     <tgroup cols="3">
13078      <thead>
13079       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
13080       </row>
13081      </thead>
13082
13083      <tbody>
13084       <row>
13085        <entry><literal><function>pg_column_size</function>(<type>any</type>)</literal></entry>
13086        <entry><type>int</type></entry>
13087        <entry>Number of bytes used to store a particular value (possibly compressed)</entry>
13088       </row>
13089       <row>
13090        <entry>
13091         <literal><function>pg_database_size</function>(<type>oid</type>)</literal>
13092         </entry>
13093        <entry><type>bigint</type></entry>
13094        <entry>Disk space used by the database with the specified OID</entry>
13095       </row>
13096       <row>
13097        <entry>
13098         <literal><function>pg_database_size</function>(<type>name</type>)</literal>
13099         </entry>
13100        <entry><type>bigint</type></entry>
13101        <entry>Disk space used by the database with the specified name</entry>
13102       </row>
13103       <row>
13104        <entry>
13105         <literal><function>pg_relation_size</function>(<parameter>relation</parameter> <type>regclass</type>, <parameter>fork</parameter> <type>text</type>)</literal>
13106         </entry>
13107        <entry><type>bigint</type></entry>
13108        <entry>
13109         Disk space used by the specified fork (<literal>'main'</literal>,
13110         <literal>'fsm'</literal> or <literal>'vm'</>)
13111         of the table or index with the specified OID or name
13112        </entry>
13113       </row>
13114       <row>
13115        <entry>
13116         <literal><function>pg_relation_size</function>(<parameter>relation</parameter> <type>regclass</type>)</literal>
13117         </entry>
13118        <entry><type>bigint</type></entry>
13119        <entry>
13120         Shorthand for <literal>pg_relation_size(..., 'main')</literal>
13121        </entry>
13122       </row>
13123       <row>
13124        <entry>
13125         <literal><function>pg_size_pretty</function>(<type>bigint</type>)</literal>
13126         </entry>
13127        <entry><type>text</type></entry>
13128        <entry>Converts a size in bytes into a human-readable format with size units</entry>
13129       </row>
13130       <row>
13131        <entry>
13132         <literal><function>pg_tablespace_size</function>(<type>oid</type>)</literal>
13133         </entry>
13134        <entry><type>bigint</type></entry>
13135        <entry>Disk space used by the tablespace with the specified OID</entry>
13136       </row>
13137       <row>
13138        <entry>
13139         <literal><function>pg_tablespace_size</function>(<type>name</type>)</literal>
13140         </entry>
13141        <entry><type>bigint</type></entry>
13142        <entry>Disk space used by the tablespace with the specified name</entry>
13143       </row>
13144       <row>
13145        <entry>
13146         <literal><function>pg_total_relation_size</function>(<type>regclass</type>)</literal>
13147         </entry>
13148        <entry><type>bigint</type></entry>
13149        <entry>
13150         Total disk space used by the table with the specified OID or name,
13151         including indexes and <acronym>TOAST</> data
13152        </entry>
13153       </row>
13154      </tbody>
13155     </tgroup>
13156    </table>
13157
13158    <para>
13159     <function>pg_column_size</> shows the space used to store any individual
13160     data value.
13161    </para>
13162
13163    <para>
13164     <function>pg_database_size</function> and <function>pg_tablespace_size</>
13165     accept the OID or name of a database or tablespace, and return the total
13166     disk space used therein.
13167    </para>
13168
13169    <para>
13170     <function>pg_relation_size</> accepts the OID or name of a table, index or
13171     toast table, and returns the size in bytes. Specifying
13172     <literal>'main'</literal> or leaving out the second argument returns the
13173     size of the main data fork of the relation. Specifying
13174     <literal>'fsm'</literal> returns the size of the
13175     Free Space Map (see <xref linkend="storage-fsm">) associated with the
13176     relation. Specifying <literal>'vm'</literal> returns the size of the
13177     Visibility Map (see <xref linkend="storage-vm">) associated with the
13178     relation.
13179    </para>
13180
13181    <para>
13182     <function>pg_size_pretty</> can be used to format the result of one of
13183     the other functions in a human-readable way, using kB, MB, GB or TB as
13184     appropriate.
13185    </para>
13186
13187    <para>
13188     <function>pg_total_relation_size</> accepts the OID or name of a
13189     table or toast table, and returns the size in bytes of the data
13190     and all associated indexes and toast tables.
13191    </para>
13192
13193    <para>
13194     The functions shown in <xref
13195     linkend="functions-admin-genfile"> provide native access to
13196     files on the machine hosting the server. Only files within the
13197     database cluster directory and the <varname>log_directory</> can be
13198     accessed.  Use a relative path for files in the cluster directory,
13199     and a path matching the <varname>log_directory</> configuration setting
13200     for log files.  Use of these functions is restricted to superusers.
13201    </para>
13202
13203    <table id="functions-admin-genfile">
13204     <title>Generic File Access Functions</title>
13205     <tgroup cols="3">
13206      <thead>
13207       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
13208       </row>
13209      </thead>
13210
13211      <tbody>
13212       <row>
13213        <entry>
13214         <literal><function>pg_ls_dir</function>(<parameter>dirname</> <type>text</>)</literal>
13215        </entry>
13216        <entry><type>setof text</type></entry>
13217        <entry>List the contents of a directory</entry>
13218       </row>
13219       <row>
13220        <entry>
13221         <literal><function>pg_read_file</function>(<parameter>filename</> <type>text</>, <parameter>offset</> <type>bigint</>, <parameter>length</> <type>bigint</>)</literal>
13222        </entry>
13223        <entry><type>text</type></entry>
13224        <entry>Return the contents of a text file</entry>
13225       </row>
13226       <row>
13227        <entry>
13228         <literal><function>pg_stat_file</function>(<parameter>filename</> <type>text</>)</literal>
13229        </entry>
13230        <entry><type>record</type></entry>
13231        <entry>Return information about a file</entry>
13232       </row>
13233      </tbody>
13234     </tgroup>
13235    </table>
13236
13237    <indexterm>
13238     <primary>pg_ls_dir</primary>
13239    </indexterm>
13240    <para>
13241     <function>pg_ls_dir</> returns all the names in the specified
13242     directory, except the special entries <quote><literal>.</></> and
13243     <quote><literal>..</></>.
13244    </para>
13245
13246    <indexterm>
13247     <primary>pg_read_file</primary>
13248    </indexterm>
13249    <para>
13250     <function>pg_read_file</> returns part of a text file, starting
13251     at the given <parameter>offset</>, returning at most <parameter>length</>
13252     bytes (less if the end of file is reached first).  If <parameter>offset</>
13253     is negative, it is relative to the end of the file.
13254    </para>
13255
13256    <indexterm>
13257     <primary>pg_stat_file</primary>
13258    </indexterm>
13259    <para>
13260     <function>pg_stat_file</> returns a record containing the file
13261     size, last accessed time stamp, last modified time stamp,
13262     last file status change time stamp (Unix platforms only),
13263     file creation time stamp (Windows only), and a <type>boolean</type>
13264     indicating if it is a directory.  Typical usages include:
13265 <programlisting>
13266 SELECT * FROM pg_stat_file('filename');
13267 SELECT (pg_stat_file('filename')).modification;
13268 </programlisting>
13269    </para>
13270
13271    <para>
13272     The functions shown in <xref linkend="functions-advisory-locks"> manage
13273     advisory locks.  For details about proper use of these functions, see
13274     <xref linkend="advisory-locks">.
13275    </para>
13276
13277    <table id="functions-advisory-locks">
13278     <title>Advisory Lock Functions</title>
13279     <tgroup cols="3">
13280      <thead>
13281       <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
13282       </row>
13283      </thead>
13284
13285      <tbody>
13286       <row>
13287        <entry>
13288         <literal><function>pg_advisory_lock</function>(<parameter>key</> <type>bigint</>)</literal>
13289        </entry>
13290        <entry><type>void</type></entry>
13291        <entry>Obtain exclusive advisory lock</entry>
13292       </row>
13293       <row>
13294        <entry>
13295         <literal><function>pg_advisory_lock</function>(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</literal>
13296        </entry>
13297        <entry><type>void</type></entry>
13298        <entry>Obtain exclusive advisory lock</entry>
13299       </row>
13300
13301       <row>
13302        <entry>
13303         <literal><function>pg_advisory_lock_shared</function>(<parameter>key</> <type>bigint</>)</literal>
13304        </entry>
13305        <entry><type>void</type></entry>
13306        <entry>Obtain shared advisory lock</entry>
13307       </row>
13308       <row>
13309        <entry>
13310         <literal><function>pg_advisory_lock_shared</function>(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</literal>
13311        </entry>
13312        <entry><type>void</type></entry>
13313        <entry>Obtain shared advisory lock</entry>
13314       </row>
13315
13316       <row>
13317        <entry>
13318         <literal><function>pg_try_advisory_lock</function>(<parameter>key</> <type>bigint</>)</literal>
13319        </entry>
13320        <entry><type>boolean</type></entry>
13321        <entry>Obtain exclusive advisory lock if available</entry>
13322       </row>
13323       <row>
13324        <entry>
13325         <literal><function>pg_try_advisory_lock</function>(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</literal>
13326        </entry>
13327        <entry><type>boolean</type></entry>
13328        <entry>Obtain exclusive advisory lock if available</entry>
13329       </row>
13330
13331       <row>
13332        <entry>
13333         <literal><function>pg_try_advisory_lock_shared</function>(<parameter>key</> <type>bigint</>)</literal>
13334        </entry>
13335        <entry><type>boolean</type></entry>
13336        <entry>Obtain shared advisory lock if available</entry>
13337       </row>
13338       <row>
13339        <entry>
13340         <literal><function>pg_try_advisory_lock_shared</function>(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</literal>
13341        </entry>
13342        <entry><type>boolean</type></entry>
13343        <entry>Obtain shared advisory lock if available</entry>
13344       </row>
13345
13346       <row>
13347        <entry>
13348         <literal><function>pg_advisory_unlock</function>(<parameter>key</> <type>bigint</>)</literal>
13349        </entry>
13350        <entry><type>boolean</type></entry>
13351        <entry>Release an exclusive advisory lock</entry>
13352       </row>
13353       <row>
13354        <entry>
13355         <literal><function>pg_advisory_unlock</function>(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</literal>
13356        </entry>
13357        <entry><type>boolean</type></entry>
13358        <entry>Release an exclusive advisory lock</entry>
13359       </row>
13360
13361       <row>
13362        <entry>
13363         <literal><function>pg_advisory_unlock_shared</function>(<parameter>key</> <type>bigint</>)</literal>
13364        </entry>
13365        <entry><type>boolean</type></entry>
13366        <entry>Release a shared advisory lock</entry>
13367       </row>
13368       <row>
13369        <entry>
13370         <literal><function>pg_advisory_unlock_shared</function>(<parameter>key1</> <type>int</>, <parameter>key2</> <type>int</>)</literal>
13371        </entry>
13372        <entry><type>boolean</type></entry>
13373        <entry>Release a shared advisory lock</entry>
13374       </row>
13375
13376       <row>
13377        <entry>
13378         <literal><function>pg_advisory_unlock_all</function>()</literal>
13379        </entry>
13380        <entry><type>void</type></entry>
13381        <entry>Release all advisory locks held by the current session</entry>
13382       </row>
13383
13384      </tbody>
13385     </tgroup>
13386    </table>
13387
13388    <indexterm>
13389     <primary>pg_advisory_lock</primary>
13390    </indexterm>
13391    <para>
13392     <function>pg_advisory_lock</> locks an application-defined resource,
13393     which can be identified either by a single 64-bit key value or two
13394     32-bit key values (note that these two key spaces do not overlap).
13395     The key type is specified in <literal>pg_locks.objid</>.  If
13396     another session already holds a lock on the same resource, the
13397     function will wait until the resource becomes available.  The lock
13398     is exclusive.  Multiple lock requests stack, so that if the same resource
13399     is locked three times it must be also unlocked three times to be
13400     released for other sessions' use.
13401    </para>
13402
13403    <indexterm>
13404     <primary>pg_advisory_lock_shared</primary>
13405    </indexterm>
13406    <para>
13407     <function>pg_advisory_lock_shared</> works the same as
13408     <function>pg_advisory_lock</>,
13409     except the lock can be shared with other sessions requesting shared locks.
13410     Only would-be exclusive lockers are locked out.
13411    </para>
13412
13413    <indexterm>
13414     <primary>pg_try_advisory_lock</primary>
13415    </indexterm>
13416    <para>
13417     <function>pg_try_advisory_lock</> is similar to
13418     <function>pg_advisory_lock</>, except the function will not wait for the
13419     lock to become available.  It will either obtain the lock immediately and
13420     return <literal>true</>, or return <literal>false</> if the lock cannot be
13421     acquired immediately.
13422    </para>
13423
13424    <indexterm>
13425     <primary>pg_try_advisory_lock_shared</primary>
13426    </indexterm>
13427    <para>
13428     <function>pg_try_advisory_lock_shared</> works the same as
13429     <function>pg_try_advisory_lock</>, except it attempts to acquire
13430     a shared rather than an exclusive lock.
13431    </para>
13432
13433    <indexterm>
13434     <primary>pg_advisory_unlock</primary>
13435    </indexterm>
13436    <para>
13437     <function>pg_advisory_unlock</> will release a previously-acquired
13438     exclusive advisory lock.  It
13439     returns <literal>true</> if the lock is successfully released.
13440     If the lock was not held, it will return <literal>false</>,
13441     and in addition, an SQL warning will be raised by the server.
13442    </para>
13443
13444    <indexterm>
13445     <primary>pg_advisory_unlock_shared</primary>
13446    </indexterm>
13447    <para>
13448     <function>pg_advisory_unlock_shared</> works the same as
13449     <function>pg_advisory_unlock</>,
13450     except it releases a shared advisory lock.
13451    </para>
13452
13453    <indexterm>
13454     <primary>pg_advisory_unlock_all</primary>
13455    </indexterm>
13456    <para>
13457     <function>pg_advisory_unlock_all</> will release all advisory locks
13458     held by the current session.  (This function is implicitly invoked
13459     at session end, even if the client disconnects ungracefully.)
13460    </para>
13461
13462   </sect1>
13463
13464   <sect1 id="functions-trigger">
13465    <title>Trigger Functions</title>
13466
13467    <indexterm>
13468      <primary>suppress_redundant_updates_trigger</primary>
13469    </indexterm>
13470
13471    <para>
13472       Currently <productname>PostgreSQL</> provides one built in trigger
13473       function, <function>suppress_redundant_updates_trigger</>,
13474       which will prevent any update
13475       that does not actually change the data in the row from taking place, in
13476       contrast to the normal behaviour which always performs the update
13477       regardless of whether or not the data has changed. (This normal behaviour
13478       makes updates run faster, since no checking is required, and is also
13479       useful in certain cases.)
13480     </para>
13481
13482     <para>
13483       Ideally, you should normally avoid running updates that don't actually
13484       change the data in the record. Redundant updates can cost considerable
13485       unnecessary time, especially if there are lots of indexes to alter,
13486       and space in dead rows that will eventually have to be vacuumed.
13487       However, detecting such situations in client code is not
13488       always easy, or even possible, and writing expressions to detect
13489       them can be error-prone. An alternative is to use
13490       <function>suppress_redundant_updates_trigger</>, which will skip
13491       updates that don't change the data. You should use this with care,
13492       however. The trigger takes a small but non-trivial time for each record,
13493       so if most of the records affected by an update are actually changed,
13494       use of this trigger will actually make the update run slower.
13495     </para>
13496
13497     <para>
13498       The <function>suppress_redundant_updates_trigger</> function can be
13499       added to a table like this:
13500 <programlisting>
13501 CREATE TRIGGER z_min_update
13502 BEFORE UPDATE ON tablename
13503 FOR EACH ROW EXECUTE PROCEDURE suppress_redundant_updates_trigger();
13504 </programlisting>
13505       In most cases, you would want to fire this trigger last for each row.
13506       Bearing in mind that triggers fire in name order, you would then
13507       choose a trigger name that comes after the name of any other trigger
13508       you might have on the table.
13509     </para>
13510     <para>
13511        For more information about creating triggers, see
13512         <xref linkend="SQL-CREATETRIGGER">.
13513     </para>
13514   </sect1>
13515 </chapter>