I386LINUX/util/I386LINUX/doc/postgresql/html/sql-createaggregate.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >CREATE AGGREGATE</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="SQL Commands"
  16 HREF="sql-commands.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="COPY"
  19 HREF="sql-copy.html"><LINK
  20 REL="NEXT"
  21 TITLE="CREATE CAST"
  22 HREF="sql-createcast.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="REFENTRY"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="sql-copy.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="sql-copy.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 ></TD
  68 ><TD
  69 WIDTH="10%"
  70 ALIGN="right"
  71 VALIGN="top"
  72 ><A
  73 HREF="sql-createcast.html"
  74 >Fast Forward</A
  75 ></TD
  76 ><TD
  77 WIDTH="10%"
  78 ALIGN="right"
  79 VALIGN="top"
  80 ><A
  81 HREF="sql-createcast.html"
  82 ACCESSKEY="N"
  83 >Next</A
  84 ></TD
  85 ></TR
  86 ></TABLE
  87 ><HR
  88 ALIGN="LEFT"
  89 WIDTH="100%"></DIV
  90 ><H1
  91 ><A
  92 NAME="SQL-CREATEAGGREGATE"
  93 ></A
  94 >CREATE AGGREGATE</H1
  95 ><DIV
  96 CLASS="REFNAMEDIV"
  97 ><A
  98 NAME="AEN36388"
  99 ></A
 100 ><H2
 101 >Name</H2
 102 >CREATE AGGREGATE&nbsp;--&nbsp;define a new aggregate function</DIV
 103 ><A
 104 NAME="AEN36391"
 105 ></A
 106 ><DIV
 107 CLASS="REFSYNOPSISDIV"
 108 ><A
 109 NAME="AEN36393"
 110 ></A
 111 ><H2
 112 >Synopsis</H2
 113 ><PRE
 114 CLASS="SYNOPSIS"
 115 >CREATE AGGREGATE <VAR
 116 CLASS="REPLACEABLE"
 117 >name</VAR
 118 > (
 119     BASETYPE = <VAR
 120 CLASS="REPLACEABLE"
 121 >input_data_type</VAR
 122 >,
 123     SFUNC = <VAR
 124 CLASS="REPLACEABLE"
 125 >sfunc</VAR
 126 >,
 127     STYPE = <VAR
 128 CLASS="REPLACEABLE"
 129 >state_data_type</VAR
 130 >
 131     [ , FINALFUNC = <VAR
 132 CLASS="REPLACEABLE"
 133 >ffunc</VAR
 134 > ]
 135     [ , INITCOND = <VAR
 136 CLASS="REPLACEABLE"
 137 >initial_condition</VAR
 138 > ]
 139 )</PRE
 140 ></DIV
 141 ><DIV
 142 CLASS="REFSECT1"
 143 ><A
 144 NAME="AEN36401"
 145 ></A
 146 ><H2
 147 >Description</H2
 148 ><P
 149 >   <TT
 150 CLASS="COMMAND"
 151 >CREATE AGGREGATE</TT
 152 > defines a new aggregate function. Some aggregate functions
 153    for base types such as <CODE
 154 CLASS="FUNCTION"
 155 >min(integer)</CODE
 156 >
 157    and <CODE
 158 CLASS="FUNCTION"
 159 >avg(double precision)</CODE
 160 > are already provided in the standard
 161    distribution. If one defines new types or needs an aggregate function not
 162    already provided, then <TT
 163 CLASS="COMMAND"
 164 >CREATE AGGREGATE</TT
 165 >
 166    can be used to provide the desired features.
 167   </P
 168 ><P
 169 >   If a schema name is given (for example, <TT
 170 CLASS="LITERAL"
 171 >CREATE AGGREGATE
 172    myschema.myagg ...</TT
 173 >) then the aggregate function is created in the
 174    specified schema.  Otherwise it is created in the current schema.
 175   </P
 176 ><P
 177 >   An  aggregate  function is identified by its name and input data type.
 178    Two aggregates in the same schema can have the same name if they operate on
 179    different input types.  The
 180    name and input data type of an aggregate must also be distinct from
 181    the name and input data type(s) of every ordinary function in the same
 182    schema.
 183   </P
 184 ><P
 185 >   An  aggregate function is made from one or two ordinary
 186    functions:
 187    a state transition function
 188    <VAR
 189 CLASS="REPLACEABLE"
 190 >sfunc</VAR
 191 >,
 192    and an optional final calculation function
 193    <VAR
 194 CLASS="REPLACEABLE"
 195 >ffunc</VAR
 196 >.
 197    These are used as follows:
 198 </P><PRE
 199 CLASS="PROGRAMLISTING"
 200 ><VAR
 201 CLASS="REPLACEABLE"
 202 >sfunc</VAR
 203 >( internal-state, next-data-item ) ---&#62; next-internal-state
 204 <VAR
 205 CLASS="REPLACEABLE"
 206 >ffunc</VAR
 207 >( internal-state ) ---&#62; aggregate-value</PRE
 208 ><P>
 209   </P
 210 ><P
 211 >   <SPAN
 212 CLASS="PRODUCTNAME"
 213 >PostgreSQL</SPAN
 214 > creates a temporary variable
 215    of data type <VAR
 216 CLASS="REPLACEABLE"
 217 >stype</VAR
 218 >
 219    to hold the current internal state of the aggregate.  At each input
 220    data item,
 221    the state transition function is invoked to calculate a new
 222    internal state value.  After all the data has been processed,
 223    the final function is invoked once to calculate the aggregate's return
 224    value.  If there is no final function then the ending state value
 225    is returned as-is.
 226   </P
 227 ><P
 228 >   An aggregate function may provide an initial condition,
 229    that is, an initial value for the internal state value.
 230    This is specified and stored in the database as a column of type
 231    <TT
 232 CLASS="TYPE"
 233 >text</TT
 234 >, but it must be a valid external representation
 235    of a constant of the state value data type.  If it is not supplied
 236    then the state value starts out null.
 237   </P
 238 ><P
 239 >   If the state transition function is declared <SPAN
 240 CLASS="QUOTE"
 241 >"strict"</SPAN
 242 >,
 243    then it cannot be called with null inputs.  With such a transition
 244    function, aggregate execution behaves as follows.  Null input values
 245    are ignored (the function is not called and the previous state value
 246    is retained).  If the initial state value is null, then the first
 247    nonnull input value replaces the state value, and the transition
 248    function is invoked beginning with the second nonnull input value.
 249    This is handy for implementing aggregates like <CODE
 250 CLASS="FUNCTION"
 251 >max</CODE
 252 >.
 253    Note that this behavior is only available when
 254    <VAR
 255 CLASS="REPLACEABLE"
 256 >state_data_type</VAR
 257 >
 258    is the same as
 259    <VAR
 260 CLASS="REPLACEABLE"
 261 >input_data_type</VAR
 262 >.
 263    When these types are different, you must supply a nonnull initial
 264    condition or use a nonstrict transition function.
 265   </P
 266 ><P
 267 >   If the state transition function is not strict, then it will be called
 268    unconditionally at each input value, and must deal with null inputs
 269    and null transition values for itself.  This allows the aggregate
 270    author to have full control over the aggregate's handling of null values.
 271   </P
 272 ><P
 273 >   If the final function is declared <SPAN
 274 CLASS="QUOTE"
 275 >"strict"</SPAN
 276 >, then it will not
 277    be called when the ending state value is null; instead a null result
 278    will be returned automatically.  (Of course this is just the normal
 279    behavior of strict functions.)  In any case the final function has
 280    the option of returning a null value.  For example, the final function for
 281    <CODE
 282 CLASS="FUNCTION"
 283 >avg</CODE
 284 > returns null when it sees there were zero
 285    input rows.
 286   </P
 287 ></DIV
 288 ><DIV
 289 CLASS="REFSECT1"
 290 ><A
 291 NAME="AEN36431"
 292 ></A
 293 ><H2
 294 >Parameters</H2
 295 ><P
 296 ></P
 297 ><DIV
 298 CLASS="VARIABLELIST"
 299 ><DL
 300 ><DT
 301 ><VAR
 302 CLASS="REPLACEABLE"
 303 >name</VAR
 304 ></DT
 305 ><DD
 306 ><P
 307 >      The name (optionally schema-qualified) of the aggregate function
 308       to create.
 309      </P
 310 ></DD
 311 ><DT
 312 ><VAR
 313 CLASS="REPLACEABLE"
 314 >input_data_type</VAR
 315 ></DT
 316 ><DD
 317 ><P
 318 >      The input data type on which this aggregate function operates.
 319       This can be specified as <TT
 320 CLASS="LITERAL"
 321 >"ANY"</TT
 322 > for an aggregate that
 323       does not examine its input values (an example is
 324       <CODE
 325 CLASS="FUNCTION"
 326 >count(*)</CODE
 327 >).
 328      </P
 329 ></DD
 330 ><DT
 331 ><VAR
 332 CLASS="REPLACEABLE"
 333 >sfunc</VAR
 334 ></DT
 335 ><DD
 336 ><P
 337 >      The name of the state transition function to be called for each
 338       input data value.  This is normally a function of two arguments,
 339       the first being of type <VAR
 340 CLASS="REPLACEABLE"
 341 >state_data_type</VAR
 342 > and the second
 343       of type <VAR
 344 CLASS="REPLACEABLE"
 345 >input_data_type</VAR
 346 >.  Alternatively,
 347       for an aggregate that does not examine its input values, the
 348       function takes just one argument of type <VAR
 349 CLASS="REPLACEABLE"
 350 >state_data_type</VAR
 351 >.  In either case
 352       the function must return a value of type <VAR
 353 CLASS="REPLACEABLE"
 354 >state_data_type</VAR
 355 >.  This function
 356       takes the current state value and the current input data item,
 357       and returns the next state value.
 358      </P
 359 ></DD
 360 ><DT
 361 ><VAR
 362 CLASS="REPLACEABLE"
 363 >state_data_type</VAR
 364 ></DT
 365 ><DD
 366 ><P
 367 >      The data type for the aggregate's state value.
 368      </P
 369 ></DD
 370 ><DT
 371 ><VAR
 372 CLASS="REPLACEABLE"
 373 >ffunc</VAR
 374 ></DT
 375 ><DD
 376 ><P
 377 >      The name of the final function called to compute the aggregate's
 378       result after all input data has been traversed.  The function
 379       must take a single argument of type <VAR
 380 CLASS="REPLACEABLE"
 381 >state_data_type</VAR
 382 >.  The return
 383       data type of the aggregate is defined as the return type of this
 384       function.  If <VAR
 385 CLASS="REPLACEABLE"
 386 >ffunc</VAR
 387 >
 388       is not specified, then the ending state value is used as the
 389       aggregate's result, and the return type is <VAR
 390 CLASS="REPLACEABLE"
 391 >state_data_type</VAR
 392 >.
 393      </P
 394 ></DD
 395 ><DT
 396 ><VAR
 397 CLASS="REPLACEABLE"
 398 >initial_condition</VAR
 399 ></DT
 400 ><DD
 401 ><P
 402 >      The initial setting for the state value.  This must be a string
 403       constant in the form accepted for the data type <VAR
 404 CLASS="REPLACEABLE"
 405 >state_data_type</VAR
 406 >.  If not
 407       specified, the state value starts out null.
 408      </P
 409 ></DD
 410 ></DL
 411 ></DIV
 412 ><P
 413 >   The parameters of <TT
 414 CLASS="COMMAND"
 415 >CREATE AGGREGATE</TT
 416 > can be
 417    written in any order, not just the order illustrated above.
 418   </P
 419 ></DIV
 420 ><DIV
 421 CLASS="REFSECT1"
 422 ><A
 423 NAME="AEN36476"
 424 ></A
 425 ><H2
 426 >Examples</H2
 427 ><P
 428 >   See <A
 429 HREF="xaggr.html"
 430 >Section 33.9</A
 431 >.
 432   </P
 433 ></DIV
 434 ><DIV
 435 CLASS="REFSECT1"
 436 ><A
 437 NAME="AEN36480"
 438 ></A
 439 ><H2
 440 >Compatibility</H2
 441 ><P
 442 >   <TT
 443 CLASS="COMMAND"
 444 >CREATE AGGREGATE</TT
 445 > is a
 446    <SPAN
 447 CLASS="PRODUCTNAME"
 448 >PostgreSQL</SPAN
 449 > language extension.  The SQL
 450    standard does not provide for user-defined aggregate function.
 451   </P
 452 ></DIV
 453 ><DIV
 454 CLASS="REFSECT1"
 455 ><A
 456 NAME="AEN36485"
 457 ></A
 458 ><H2
 459 >See Also</H2
 460 ><A
 461 HREF="sql-alteraggregate.html"
 462 ><I
 463 >ALTER AGGREGATE</I
 464 ></A
 465 >, <A
 466 HREF="sql-dropaggregate.html"
 467 ><I
 468 >DROP AGGREGATE</I
 469 ></A
 470 ></DIV
 471 ><DIV
 472 CLASS="NAVFOOTER"
 473 ><HR
 474 ALIGN="LEFT"
 475 WIDTH="100%"><TABLE
 476 SUMMARY="Footer navigation table"
 477 WIDTH="100%"
 478 BORDER="0"
 479 CELLPADDING="0"
 480 CELLSPACING="0"
 481 ><TR
 482 ><TD
 483 WIDTH="33%"
 484 ALIGN="left"
 485 VALIGN="top"
 486 ><A
 487 HREF="sql-copy.html"
 488 ACCESSKEY="P"
 489 >Prev</A
 490 ></TD
 491 ><TD
 492 WIDTH="34%"
 493 ALIGN="center"
 494 VALIGN="top"
 495 ><A
 496 HREF="index.html"
 497 ACCESSKEY="H"
 498 >Home</A
 499 ></TD
 500 ><TD
 501 WIDTH="33%"
 502 ALIGN="right"
 503 VALIGN="top"
 504 ><A
 505 HREF="sql-createcast.html"
 506 ACCESSKEY="N"
 507 >Next</A
 508 ></TD
 509 ></TR
 510 ><TR
 511 ><TD
 512 WIDTH="33%"
 513 ALIGN="left"
 514 VALIGN="top"
 515 >COPY</TD
 516 ><TD
 517 WIDTH="34%"
 518 ALIGN="center"
 519 VALIGN="top"
 520 ><A
 521 HREF="sql-commands.html"
 522 ACCESSKEY="U"
 523 >Up</A
 524 ></TD
 525 ><TD
 526 WIDTH="33%"
 527 ALIGN="right"
 528 VALIGN="top"
 529 >CREATE CAST</TD
 530 ></TR
 531 ></TABLE
 532 ></DIV
 533 ></BODY
 534 ></HTML
 535 >