|
1 | | -<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.438 2008/07/03 20:58:46 tgl Exp $ --> |
| 1 | +<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.439 2008/07/07 16:11:35 petere Exp $ --> |
2 | 2 |
|
3 | 3 | <chapter id="functions"> |
4 | 4 | <title>Functions and Operators</title> |
@@ -8339,6 +8339,60 @@ SELECT xmlroot(xmlparse(document '<?xml version="1.1"?><content>abc</content>'), |
8339 | 8339 | </para> |
8340 | 8340 | </sect3> |
8341 | 8341 |
|
| 8342 | + <sect3> |
| 8343 | + <title><literal>xmlagg</literal></title> |
| 8344 | + |
| 8345 | + <indexterm> |
| 8346 | + <primary>xmlagg</primary> |
| 8347 | + </indexterm> |
| 8348 | + |
| 8349 | +<synopsis> |
| 8350 | +<function>xmlagg</function>(<replaceable>xml</replaceable>) |
| 8351 | +</synopsis> |
| 8352 | + |
| 8353 | + <para> |
| 8354 | + The function <function>xmlagg</function> is, unlike the other |
| 8355 | + functions below, an aggregate function. It concatenates the |
| 8356 | + input values to the aggregate function call, |
| 8357 | + like <function>xmlconcat</function> does. |
| 8358 | + See <xref linkend="functions-aggregate"> for general information |
| 8359 | + about aggregate functions. |
| 8360 | + </para> |
| 8361 | + |
| 8362 | + <para> |
| 8363 | + Example: |
| 8364 | +<screen><![CDATA[ |
| 8365 | +CREATE TABLE test (y int, x xml); |
| 8366 | +INSERT INTO test VALUES (1, '<foo>abc</foo>'); |
| 8367 | +INSERT INTO test VALUES (2, '<bar/>'); |
| 8368 | +SELECT xmlagg(x) FROM test; |
| 8369 | + xmlagg |
| 8370 | +---------------------- |
| 8371 | + <foo>abc</foo><bar/> |
| 8372 | +]]></screen> |
| 8373 | + </para> |
| 8374 | + |
| 8375 | + <para> |
| 8376 | + Note that in the current implementation, the order of the |
| 8377 | + concatenation is in principle undefined. Making the input values |
| 8378 | + to be sorted in some other way will usually work, however. For |
| 8379 | + instance, in the above example, one could influence the order |
| 8380 | + like so: |
| 8381 | +<screen><![CDATA[ |
| 8382 | +SELECT xmlagg(x) FROM (SELECT * FROM test ORDER BY y DESC) AS tab; |
| 8383 | + xmlagg |
| 8384 | +---------------------- |
| 8385 | + <bar/><foo>abc</foo> |
| 8386 | +]]></screen> |
| 8387 | + |
| 8388 | + But this approach is not guaranteed to work in all situations and |
| 8389 | + in all versions of PostgreSQL. A future version of PostgreSQL |
| 8390 | + will probably provide an additional feature to control the order |
| 8391 | + in a proper way (<literal>xmlagg(expr ORDER BY expr, expr, |
| 8392 | + ...</literal>). |
| 8393 | + </para> |
| 8394 | + </sect3> |
| 8395 | + |
8342 | 8396 | <sect3> |
8343 | 8397 | <title>XML Predicates</title> |
8344 | 8398 |
|
|