begriffs open source - ai-pg/blob - full-docs/html/functions-xml.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.15. XML Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-uuid.html" title="9.14. UUID Functions" /><link rel="next" href="functions-json.html" title="9.16. JSON Functions and Operators" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.15. XML Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-uuid.html" title="9.14. UUID Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-json.html" title="9.16. JSON Functions and Operators">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-XML"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.15. XML Functions <a href="#FUNCTIONS-XML" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-PRODUCING-XML">9.15.1. Producing XML Content</a></span></dt><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-XML-PREDICATES">9.15.2. XML Predicates</a></span></dt><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-XML-PROCESSING">9.15.3. Processing XML</a></span></dt><dt><span class="sect2"><a href="functions-xml.html#FUNCTIONS-XML-MAPPING">9.15.4. Mapping Tables to XML</a></span></dt></dl></div><a id="id-1.5.8.21.2" class="indexterm"></a><p>
   3    The functions and function-like expressions described in this
   4    section operate on values of type <code class="type">xml</code>.  See <a class="xref" href="datatype-xml.html" title="8.13. XML Type">Section 8.13</a> for information about the <code class="type">xml</code>
   5    type.  The function-like expressions <code class="function">xmlparse</code>
   6    and <code class="function">xmlserialize</code> for converting to and from
   7    type <code class="type">xml</code> are documented there, not in this section.
   8   </p><p>
   9    Use of most of these functions
  10    requires <span class="productname">PostgreSQL</span> to have been built
  11    with <code class="command">configure --with-libxml</code>.
  12   </p><div class="sect2" id="FUNCTIONS-PRODUCING-XML"><div class="titlepage"><div><div><h3 class="title">9.15.1. Producing XML Content <a href="#FUNCTIONS-PRODUCING-XML" class="id_link">#</a></h3></div></div></div><p>
  13     A set of functions and function-like expressions is available for
  14     producing XML content from SQL data.  As such, they are
  15     particularly suitable for formatting query results into XML
  16     documents for processing in client applications.
  17    </p><div class="sect3" id="FUNCTIONS-PRODUCING-XML-XMLTEXT"><div class="titlepage"><div><div><h4 class="title">9.15.1.1. <code class="literal">xmltext</code> <a href="#FUNCTIONS-PRODUCING-XML-XMLTEXT" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.5.3.2" class="indexterm"></a><pre class="synopsis">
  18 <code class="function">xmltext</code> ( <code class="type">text</code> ) → <code class="returnvalue">xml</code>
  19 </pre><p>
  20      The function <code class="function">xmltext</code> returns an XML value with a single
  21      text node containing the input argument as its content. Predefined entities
  22      like ampersand (<code class="literal">&amp;</code>), left and right angle brackets
  23      (<code class="literal">&lt; &gt;</code>), and quotation marks (<code class="literal">""</code>)
  24      are escaped.
  25     </p><p>
  26      Example:
  27 </p><pre class="screen">
  28 SELECT xmltext('&lt; foo &amp; bar &gt;');
  29          xmltext
  30 -------------------------
  31  &amp;lt; foo &amp;amp; bar &amp;gt;
  32 </pre><p>
  33     </p></div><div class="sect3" id="FUNCTIONS-PRODUCING-XML-XMLCOMMENT"><div class="titlepage"><div><div><h4 class="title">9.15.1.2. <code class="literal">xmlcomment</code> <a href="#FUNCTIONS-PRODUCING-XML-XMLCOMMENT" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.5.4.2" class="indexterm"></a><pre class="synopsis">
  34 <code class="function">xmlcomment</code> ( <code class="type">text</code> ) → <code class="returnvalue">xml</code>
  35 </pre><p>
  36      The function <code class="function">xmlcomment</code> creates an XML value
  37      containing an XML comment with the specified text as content.
  38      The text cannot contain <span class="quote">“<span class="quote"><code class="literal">--</code></span>”</span> or end with a
  39      <span class="quote">“<span class="quote"><code class="literal">-</code></span>”</span>, otherwise the resulting construct
  40      would not be a valid XML comment.
  41      If the argument is null, the result is null.
  42     </p><p>
  43      Example:
  44 </p><pre class="screen">
  45 SELECT xmlcomment('hello');
  46
  47   xmlcomment
  48 --------------
  49  &lt;!--hello--&gt;
  50 </pre><p>
  51     </p></div><div class="sect3" id="FUNCTIONS-PRODUCING-XML-XMLCONCAT"><div class="titlepage"><div><div><h4 class="title">9.15.1.3. <code class="literal">xmlconcat</code> <a href="#FUNCTIONS-PRODUCING-XML-XMLCONCAT" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.5.5.2" class="indexterm"></a><pre class="synopsis">
  52 <code class="function">xmlconcat</code> ( <code class="type">xml</code> [<span class="optional">, ...</span>] ) → <code class="returnvalue">xml</code>
  53 </pre><p>
  54      The function <code class="function">xmlconcat</code> concatenates a list
  55      of individual XML values to create a single value containing an
  56      XML content fragment.  Null values are omitted; the result is
  57      only null if there are no nonnull arguments.
  58     </p><p>
  59      Example:
  60 </p><pre class="screen">
  61 SELECT xmlconcat('&lt;abc/&gt;', '&lt;bar&gt;foo&lt;/bar&gt;');
  62
  63       xmlconcat
  64 ----------------------
  65  &lt;abc/&gt;&lt;bar&gt;foo&lt;/bar&gt;
  66 </pre><p>
  67     </p><p>
  68      XML declarations, if present, are combined as follows.  If all
  69      argument values have the same XML version declaration, that
  70      version is used in the result, else no version is used.  If all
  71      argument values have the standalone declaration value
  72      <span class="quote">“<span class="quote">yes</span>”</span>, then that value is used in the result.  If
  73      all argument values have a standalone declaration value and at
  74      least one is <span class="quote">“<span class="quote">no</span>”</span>, then that is used in the result.
  75      Else the result will have no standalone declaration.  If the
  76      result is determined to require a standalone declaration but no
  77      version declaration, a version declaration with version 1.0 will
  78      be used because XML requires an XML declaration to contain a
  79      version declaration.  Encoding declarations are ignored and
  80      removed in all cases.
  81     </p><p>
  82      Example:
  83 </p><pre class="screen">
  84 SELECT xmlconcat('&lt;?xml version="1.1"?&gt;&lt;foo/&gt;', '&lt;?xml version="1.1" standalone="no"?&gt;&lt;bar/&gt;');
  85
  86              xmlconcat
  87 -----------------------------------
  88  &lt;?xml version="1.1"?&gt;&lt;foo/&gt;&lt;bar/&gt;
  89 </pre><p>
  90     </p></div><div class="sect3" id="FUNCTIONS-PRODUCING-XML-XMLELEMENT"><div class="titlepage"><div><div><h4 class="title">9.15.1.4. <code class="literal">xmlelement</code> <a href="#FUNCTIONS-PRODUCING-XML-XMLELEMENT" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.5.6.2" class="indexterm"></a><pre class="synopsis">
  91 <code class="function">xmlelement</code> ( <code class="literal">NAME</code> <em class="replaceable"><code>name</code></em> [<span class="optional">, <code class="literal">XMLATTRIBUTES</code> ( <em class="replaceable"><code>attvalue</code></em> [<span class="optional"> <code class="literal">AS</code> <em class="replaceable"><code>attname</code></em> </span>] [<span class="optional">, ...</span>] ) </span>] [<span class="optional">, <em class="replaceable"><code>content</code></em> [<span class="optional">, ...</span>]</span>] ) → <code class="returnvalue">xml</code>
  92 </pre><p>
  93      The <code class="function">xmlelement</code> expression produces an XML
  94      element with the given name, attributes, and content.
  95      The <em class="replaceable"><code>name</code></em>
  96      and <em class="replaceable"><code>attname</code></em> items shown in the syntax are
  97      simple identifiers, not values.  The <em class="replaceable"><code>attvalue</code></em>
  98      and <em class="replaceable"><code>content</code></em> items are expressions, which can
  99      yield any <span class="productname">PostgreSQL</span> data type.  The
 100      argument(s) within <code class="literal">XMLATTRIBUTES</code> generate attributes
 101      of the XML element; the <em class="replaceable"><code>content</code></em> value(s) are
 102      concatenated to form its content.
 103     </p><p>
 104      Examples:
 105 </p><pre class="screen">
 106 SELECT xmlelement(name foo);
 107
 108  xmlelement
 109 ------------
 110  &lt;foo/&gt;
 111
 112 SELECT xmlelement(name foo, xmlattributes('xyz' as bar));
 113
 114     xmlelement
 115 ------------------
 116  &lt;foo bar="xyz"/&gt;
 117
 118 SELECT xmlelement(name foo, xmlattributes(current_date as bar), 'cont', 'ent');
 119
 120              xmlelement
 121 -------------------------------------
 122  &lt;foo bar="2007-01-26"&gt;content&lt;/foo&gt;
 123 </pre><p>
 124     </p><p>
 125      Element and attribute names that are not valid XML names are
 126      escaped by replacing the offending characters by the sequence
 127      <code class="literal">_x<em class="replaceable"><code>HHHH</code></em>_</code>, where
 128      <em class="replaceable"><code>HHHH</code></em> is the character's Unicode
 129      codepoint in hexadecimal notation.  For example:
 130 </p><pre class="screen">
 131 SELECT xmlelement(name "foo$bar", xmlattributes('xyz' as "a&amp;b"));
 132
 133             xmlelement
 134 ----------------------------------
 135  &lt;foo_x0024_bar a_x0026_b="xyz"/&gt;
 136 </pre><p>
 137     </p><p>
 138      An explicit attribute name need not be specified if the attribute
 139      value is a column reference, in which case the column's name will
 140      be used as the attribute name by default.  In other cases, the
 141      attribute must be given an explicit name.  So this example is
 142      valid:
 143 </p><pre class="screen">
 144 CREATE TABLE test (a xml, b xml);
 145 SELECT xmlelement(name test, xmlattributes(a, b)) FROM test;
 146 </pre><p>
 147      But these are not:
 148 </p><pre class="screen">
 149 SELECT xmlelement(name test, xmlattributes('constant'), a, b) FROM test;
 150 SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;
 151 </pre><p>
 152     </p><p>
 153      Element content, if specified, will be formatted according to
 154      its data type.  If the content is itself of type <code class="type">xml</code>,
 155      complex XML documents can be constructed.  For example:
 156 </p><pre class="screen">
 157 SELECT xmlelement(name foo, xmlattributes('xyz' as bar),
 158                             xmlelement(name abc),
 159                             xmlcomment('test'),
 160                             xmlelement(name xyz));
 161
 162                   xmlelement
 163 ----------------------------------------------
 164  &lt;foo bar="xyz"&gt;&lt;abc/&gt;&lt;!--test--&gt;&lt;xyz/&gt;&lt;/foo&gt;
 165 </pre><p>
 166
 167      Content of other types will be formatted into valid XML character
 168      data.  This means in particular that the characters &lt;, &gt;,
 169      and &amp; will be converted to entities.  Binary data (data type
 170      <code class="type">bytea</code>) will be represented in base64 or hex
 171      encoding, depending on the setting of the configuration parameter
 172      <a class="xref" href="runtime-config-client.html#GUC-XMLBINARY">xmlbinary</a>.  The particular behavior for
 173      individual data types is expected to evolve in order to align the
 174      PostgreSQL mappings with those specified in SQL:2006 and later,
 175      as discussed in <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-CASTS" title="D.3.1.3. Mappings between SQL and XML Data Types and Values">Section D.3.1.3</a>.
 176     </p></div><div class="sect3" id="FUNCTIONS-PRODUCING-XML-XMLFOREST"><div class="titlepage"><div><div><h4 class="title">9.15.1.5. <code class="literal">xmlforest</code> <a href="#FUNCTIONS-PRODUCING-XML-XMLFOREST" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.5.7.2" class="indexterm"></a><pre class="synopsis">
 177 <code class="function">xmlforest</code> ( <em class="replaceable"><code>content</code></em> [<span class="optional"> <code class="literal">AS</code> <em class="replaceable"><code>name</code></em> </span>] [<span class="optional">, ...</span>] ) → <code class="returnvalue">xml</code>
 178 </pre><p>
 179      The <code class="function">xmlforest</code> expression produces an XML
 180      forest (sequence) of elements using the given names and content.
 181      As for <code class="function">xmlelement</code>,
 182      each <em class="replaceable"><code>name</code></em> must be a simple identifier, while
 183      the <em class="replaceable"><code>content</code></em> expressions can have any data
 184      type.
 185     </p><p>
 186      Examples:
 187 </p><pre class="screen">
 188 SELECT xmlforest('abc' AS foo, 123 AS bar);
 189
 190           xmlforest
 191 ------------------------------
 192  &lt;foo&gt;abc&lt;/foo&gt;&lt;bar&gt;123&lt;/bar&gt;
 193
 194
 195 SELECT xmlforest(table_name, column_name)
 196 FROM information_schema.columns
 197 WHERE table_schema = 'pg_catalog';
 198
 199                                 xmlforest
 200 -----------------------------------------------------------------------
 201  &lt;table_name&gt;pg_authid&lt;/table_name&gt;&lt;column_name&gt;rolname&lt;/column_name&gt;
 202  &lt;table_name&gt;pg_authid&lt;/table_name&gt;&lt;column_name&gt;rolsuper&lt;/column_name&gt;
 203  ...
 204 </pre><p>
 205
 206      As seen in the second example, the element name can be omitted if
 207      the content value is a column reference, in which case the column
 208      name is used by default.  Otherwise, a name must be specified.
 209     </p><p>
 210      Element names that are not valid XML names are escaped as shown
 211      for <code class="function">xmlelement</code> above.  Similarly, content
 212      data is escaped to make valid XML content, unless it is already
 213      of type <code class="type">xml</code>.
 214     </p><p>
 215      Note that XML forests are not valid XML documents if they consist
 216      of more than one element, so it might be useful to wrap
 217      <code class="function">xmlforest</code> expressions in
 218      <code class="function">xmlelement</code>.
 219     </p></div><div class="sect3" id="FUNCTIONS-PRODUCING-XML-XMLPI"><div class="titlepage"><div><div><h4 class="title">9.15.1.6. <code class="literal">xmlpi</code> <a href="#FUNCTIONS-PRODUCING-XML-XMLPI" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.5.8.2" class="indexterm"></a><pre class="synopsis">
 220 <code class="function">xmlpi</code> ( <code class="literal">NAME</code> <em class="replaceable"><code>name</code></em> [<span class="optional">, <em class="replaceable"><code>content</code></em> </span>] ) → <code class="returnvalue">xml</code>
 221 </pre><p>
 222      The <code class="function">xmlpi</code> expression creates an XML
 223      processing instruction.
 224      As for <code class="function">xmlelement</code>,
 225      the <em class="replaceable"><code>name</code></em> must be a simple identifier, while
 226      the <em class="replaceable"><code>content</code></em> expression can have any data type.
 227      The <em class="replaceable"><code>content</code></em>, if present, must not contain the
 228      character sequence <code class="literal">?&gt;</code>.
 229     </p><p>
 230      Example:
 231 </p><pre class="screen">
 232 SELECT xmlpi(name php, 'echo "hello world";');
 233
 234             xmlpi
 235 -----------------------------
 236  &lt;?php echo "hello world";?&gt;
 237 </pre><p>
 238     </p></div><div class="sect3" id="FUNCTIONS-PRODUCING-XML-XMLROOT"><div class="titlepage"><div><div><h4 class="title">9.15.1.7. <code class="literal">xmlroot</code> <a href="#FUNCTIONS-PRODUCING-XML-XMLROOT" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.5.9.2" class="indexterm"></a><pre class="synopsis">
 239 <code class="function">xmlroot</code> ( <code class="type">xml</code>, <code class="literal">VERSION</code> {<code class="type">text</code>|<code class="literal">NO VALUE</code>} [<span class="optional">, <code class="literal">STANDALONE</code> {<code class="literal">YES</code>|<code class="literal">NO</code>|<code class="literal">NO VALUE</code>} </span>] ) → <code class="returnvalue">xml</code>
 240 </pre><p>
 241      The <code class="function">xmlroot</code> expression alters the properties
 242      of the root node of an XML value.  If a version is specified,
 243      it replaces the value in the root node's version declaration; if a
 244      standalone setting is specified, it replaces the value in the
 245      root node's standalone declaration.
 246     </p><p>
 247 </p><pre class="screen">
 248 SELECT xmlroot(xmlparse(document '&lt;?xml version="1.1"?&gt;&lt;content&gt;abc&lt;/content&gt;'),
 249                version '1.0', standalone yes);
 250
 251                 xmlroot
 252 ----------------------------------------
 253  &lt;?xml version="1.0" standalone="yes"?&gt;
 254  &lt;content&gt;abc&lt;/content&gt;
 255 </pre><p>
 256     </p></div><div class="sect3" id="FUNCTIONS-XML-XMLAGG"><div class="titlepage"><div><div><h4 class="title">9.15.1.8. <code class="literal">xmlagg</code> <a href="#FUNCTIONS-XML-XMLAGG" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.5.10.2" class="indexterm"></a><pre class="synopsis">
 257 <code class="function">xmlagg</code> ( <code class="type">xml</code> ) → <code class="returnvalue">xml</code>
 258 </pre><p>
 259      The function <code class="function">xmlagg</code> is, unlike the other
 260      functions described here, an aggregate function.  It concatenates the
 261      input values to the aggregate function call,
 262      much like <code class="function">xmlconcat</code> does, except that concatenation
 263      occurs across rows rather than across expressions in a single row.
 264      See <a class="xref" href="functions-aggregate.html" title="9.21. Aggregate Functions">Section 9.21</a> for additional information
 265      about aggregate functions.
 266     </p><p>
 267      Example:
 268 </p><pre class="screen">
 269 CREATE TABLE test (y int, x xml);
 270 INSERT INTO test VALUES (1, '&lt;foo&gt;abc&lt;/foo&gt;');
 271 INSERT INTO test VALUES (2, '&lt;bar/&gt;');
 272 SELECT xmlagg(x) FROM test;
 273         xmlagg
 274 ----------------------
 275  &lt;foo&gt;abc&lt;/foo&gt;&lt;bar/&gt;
 276 </pre><p>
 277     </p><p>
 278      To determine the order of the concatenation, an <code class="literal">ORDER BY</code>
 279      clause may be added to the aggregate call as described in
 280      <a class="xref" href="sql-expressions.html#SYNTAX-AGGREGATES" title="4.2.7. Aggregate Expressions">Section 4.2.7</a>. For example:
 281
 282 </p><pre class="screen">
 283 SELECT xmlagg(x ORDER BY y DESC) FROM test;
 284         xmlagg
 285 ----------------------
 286  &lt;bar/&gt;&lt;foo&gt;abc&lt;/foo&gt;
 287 </pre><p>
 288     </p><p>
 289      The following non-standard approach used to be recommended
 290      in previous versions, and may still be useful in specific
 291      cases:
 292
 293 </p><pre class="screen">
 294 SELECT xmlagg(x) FROM (SELECT * FROM test ORDER BY y DESC) AS tab;
 295         xmlagg
 296 ----------------------
 297  &lt;bar/&gt;&lt;foo&gt;abc&lt;/foo&gt;
 298 </pre><p>
 299     </p></div></div><div class="sect2" id="FUNCTIONS-XML-PREDICATES"><div class="titlepage"><div><div><h3 class="title">9.15.2. XML Predicates <a href="#FUNCTIONS-XML-PREDICATES" class="id_link">#</a></h3></div></div></div><p>
 300      The expressions described in this section check properties
 301      of <code class="type">xml</code> values.
 302     </p><div class="sect3" id="FUNCTIONS-PRODUCING-XML-IS-DOCUMENT"><div class="titlepage"><div><div><h4 class="title">9.15.2.1. <code class="literal">IS DOCUMENT</code> <a href="#FUNCTIONS-PRODUCING-XML-IS-DOCUMENT" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.6.3.2" class="indexterm"></a><pre class="synopsis">
 303 <code class="type">xml</code> <code class="literal">IS DOCUMENT</code> → <code class="returnvalue">boolean</code>
 304 </pre><p>
 305      The expression <code class="literal">IS DOCUMENT</code> returns true if the
 306      argument XML value is a proper XML document, false if it is not
 307      (that is, it is a content fragment), or null if the argument is
 308      null.  See <a class="xref" href="datatype-xml.html" title="8.13. XML Type">Section 8.13</a> about the difference
 309      between documents and content fragments.
 310     </p></div><div class="sect3" id="FUNCTIONS-PRODUCING-XML-IS-NOT-DOCUMENT"><div class="titlepage"><div><div><h4 class="title">9.15.2.2. <code class="literal">IS NOT DOCUMENT</code> <a href="#FUNCTIONS-PRODUCING-XML-IS-NOT-DOCUMENT" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.6.4.2" class="indexterm"></a><pre class="synopsis">
 311 <code class="type">xml</code> <code class="literal">IS NOT DOCUMENT</code> → <code class="returnvalue">boolean</code>
 312 </pre><p>
 313      The expression <code class="literal">IS NOT DOCUMENT</code> returns false if the
 314      argument XML value is a proper XML document, true if it is not (that is,
 315      it is a content fragment), or null if the argument is null.
 316     </p></div><div class="sect3" id="XML-EXISTS"><div class="titlepage"><div><div><h4 class="title">9.15.2.3. <code class="literal">XMLEXISTS</code> <a href="#XML-EXISTS" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.6.5.2" class="indexterm"></a><pre class="synopsis">
 317 <code class="function">XMLEXISTS</code> ( <code class="type">text</code> <code class="literal">PASSING</code> [<span class="optional"><code class="literal">BY</code> {<code class="literal">REF</code>|<code class="literal">VALUE</code>}</span>] <code class="type">xml</code> [<span class="optional"><code class="literal">BY</code> {<code class="literal">REF</code>|<code class="literal">VALUE</code>}</span>] ) → <code class="returnvalue">boolean</code>
 318 </pre><p>
 319      The function <code class="function">xmlexists</code> evaluates an XPath 1.0
 320      expression (the first argument), with the passed XML value as its context
 321      item.  The function returns false if the result of that evaluation
 322      yields an empty node-set, true if it yields any other value.  The
 323      function returns null if any argument is null.  A nonnull value
 324      passed as the context item must be an XML document, not a content
 325      fragment or any non-XML value.
 326     </p><p>
 327      Example:
 328      </p><pre class="screen">
 329 SELECT xmlexists('//town[text() = ''Toronto'']' PASSING BY VALUE '&lt;towns&gt;&lt;town&gt;Toronto&lt;/town&gt;&lt;town&gt;Ottawa&lt;/town&gt;&lt;/towns&gt;');
 330
 331  xmlexists
 332 ------------
 333  t
 334 (1 row)
 335 </pre><p>
 336     </p><p>
 337      The <code class="literal">BY REF</code> and <code class="literal">BY VALUE</code> clauses
 338      are accepted in <span class="productname">PostgreSQL</span>, but are ignored,
 339      as discussed in <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-POSTGRESQL" title="D.3.2. Incidental Limits of the Implementation">Section D.3.2</a>.
 340     </p><p>
 341      In the SQL standard, the <code class="function">xmlexists</code> function
 342      evaluates an expression in the XML Query language,
 343      but <span class="productname">PostgreSQL</span> allows only an XPath 1.0
 344      expression, as discussed in
 345      <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-XPATH1" title="D.3.1. Queries Are Restricted to XPath 1.0">Section D.3.1</a>.
 346     </p></div><div class="sect3" id="XML-IS-WELL-FORMED"><div class="titlepage"><div><div><h4 class="title">9.15.2.4. <code class="literal">xml_is_well_formed</code> <a href="#XML-IS-WELL-FORMED" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.6.6.2" class="indexterm"></a><a id="id-1.5.8.21.6.6.3" class="indexterm"></a><a id="id-1.5.8.21.6.6.4" class="indexterm"></a><pre class="synopsis">
 347 <code class="function">xml_is_well_formed</code> ( <code class="type">text</code> ) → <code class="returnvalue">boolean</code>
 348 <code class="function">xml_is_well_formed_document</code> ( <code class="type">text</code> ) → <code class="returnvalue">boolean</code>
 349 <code class="function">xml_is_well_formed_content</code> ( <code class="type">text</code> ) → <code class="returnvalue">boolean</code>
 350 </pre><p>
 351      These functions check whether a <code class="type">text</code> string represents
 352      well-formed XML, returning a Boolean result.
 353      <code class="function">xml_is_well_formed_document</code> checks for a well-formed
 354      document, while <code class="function">xml_is_well_formed_content</code> checks
 355      for well-formed content.  <code class="function">xml_is_well_formed</code> does
 356      the former if the <a class="xref" href="runtime-config-client.html#GUC-XMLOPTION">xmloption</a> configuration
 357      parameter is set to <code class="literal">DOCUMENT</code>, or the latter if it is set to
 358      <code class="literal">CONTENT</code>.  This means that
 359      <code class="function">xml_is_well_formed</code> is useful for seeing whether
 360      a simple cast to type <code class="type">xml</code> will succeed, whereas the other two
 361      functions are useful for seeing whether the corresponding variants of
 362      <code class="function">XMLPARSE</code> will succeed.
 363     </p><p>
 364      Examples:
 365
 366 </p><pre class="screen">
 367 SET xmloption TO DOCUMENT;
 368 SELECT xml_is_well_formed('&lt;&gt;');
 369  xml_is_well_formed
 370 --------------------
 371  f
 372 (1 row)
 373
 374 SELECT xml_is_well_formed('&lt;abc/&gt;');
 375  xml_is_well_formed
 376 --------------------
 377  t
 378 (1 row)
 379
 380 SET xmloption TO CONTENT;
 381 SELECT xml_is_well_formed('abc');
 382  xml_is_well_formed
 383 --------------------
 384  t
 385 (1 row)
 386
 387 SELECT xml_is_well_formed_document('&lt;pg:foo xmlns:pg="http://postgresql.org/stuff"&gt;bar&lt;/pg:foo&gt;');
 388  xml_is_well_formed_document
 389 -----------------------------
 390  t
 391 (1 row)
 392
 393 SELECT xml_is_well_formed_document('&lt;pg:foo xmlns:pg="http://postgresql.org/stuff"&gt;bar&lt;/my:foo&gt;');
 394  xml_is_well_formed_document
 395 -----------------------------
 396  f
 397 (1 row)
 398 </pre><p>
 399
 400      The last example shows that the checks include whether
 401      namespaces are correctly matched.
 402     </p></div></div><div class="sect2" id="FUNCTIONS-XML-PROCESSING"><div class="titlepage"><div><div><h3 class="title">9.15.3. Processing XML <a href="#FUNCTIONS-XML-PROCESSING" class="id_link">#</a></h3></div></div></div><p>
 403     To process values of data type <code class="type">xml</code>, PostgreSQL offers
 404     the functions <code class="function">xpath</code> and
 405     <code class="function">xpath_exists</code>, which evaluate XPath 1.0
 406     expressions, and the <code class="function">XMLTABLE</code>
 407     table function.
 408    </p><div class="sect3" id="FUNCTIONS-XML-PROCESSING-XPATH"><div class="titlepage"><div><div><h4 class="title">9.15.3.1. <code class="literal">xpath</code> <a href="#FUNCTIONS-XML-PROCESSING-XPATH" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.7.3.2" class="indexterm"></a><pre class="synopsis">
 409 <code class="function">xpath</code> ( <em class="parameter"><code>xpath</code></em> <code class="type">text</code>, <em class="parameter"><code>xml</code></em> <code class="type">xml</code> [<span class="optional">, <em class="parameter"><code>nsarray</code></em> <code class="type">text[]</code> </span>] ) → <code class="returnvalue">xml[]</code>
 410 </pre><p>
 411      The function <code class="function">xpath</code> evaluates the XPath 1.0
 412      expression <em class="parameter"><code>xpath</code></em> (given as text)
 413      against the XML value
 414      <em class="parameter"><code>xml</code></em>.  It returns an array of XML values
 415      corresponding to the node-set produced by the XPath expression.
 416      If the XPath expression returns a scalar value rather than a node-set,
 417      a single-element array is returned.
 418     </p><p>
 419      The second argument must be a well formed XML document. In particular,
 420      it must have a single root node element.
 421     </p><p>
 422      The optional third argument of the function is an array of namespace
 423      mappings.  This array should be a two-dimensional <code class="type">text</code> array with
 424      the length of the second axis being equal to 2 (i.e., it should be an
 425      array of arrays, each of which consists of exactly 2 elements).
 426      The first element of each array entry is the namespace name (alias), the
 427      second the namespace URI. It is not required that aliases provided in
 428      this array be the same as those being used in the XML document itself (in
 429      other words, both in the XML document and in the <code class="function">xpath</code>
 430      function context, aliases are <span class="emphasis"><em>local</em></span>).
 431     </p><p>
 432      Example:
 433 </p><pre class="screen">
 434 SELECT xpath('/my:a/text()', '&lt;my:a xmlns:my="http://example.com"&gt;test&lt;/my:a&gt;',
 435              ARRAY[ARRAY['my', 'http://example.com']]);
 436
 437  xpath
 438 --------
 439  {test}
 440 (1 row)
 441 </pre><p>
 442     </p><p>
 443      To deal with default (anonymous) namespaces, do something like this:
 444 </p><pre class="screen">
 445 SELECT xpath('//mydefns:b/text()', '&lt;a xmlns="http://example.com"&gt;&lt;b&gt;test&lt;/b&gt;&lt;/a&gt;',
 446              ARRAY[ARRAY['mydefns', 'http://example.com']]);
 447
 448  xpath
 449 --------
 450  {test}
 451 (1 row)
 452 </pre><p>
 453     </p></div><div class="sect3" id="FUNCTIONS-XML-PROCESSING-XPATH-EXISTS"><div class="titlepage"><div><div><h4 class="title">9.15.3.2. <code class="literal">xpath_exists</code> <a href="#FUNCTIONS-XML-PROCESSING-XPATH-EXISTS" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.7.4.2" class="indexterm"></a><pre class="synopsis">
 454 <code class="function">xpath_exists</code> ( <em class="parameter"><code>xpath</code></em> <code class="type">text</code>, <em class="parameter"><code>xml</code></em> <code class="type">xml</code> [<span class="optional">, <em class="parameter"><code>nsarray</code></em> <code class="type">text[]</code> </span>] ) → <code class="returnvalue">boolean</code>
 455 </pre><p>
 456      The function <code class="function">xpath_exists</code> is a specialized form
 457      of the <code class="function">xpath</code> function.  Instead of returning the
 458      individual XML values that satisfy the XPath 1.0 expression, this function
 459      returns a Boolean indicating whether the query was satisfied or not
 460      (specifically, whether it produced any value other than an empty node-set).
 461      This function is equivalent to the <code class="literal">XMLEXISTS</code> predicate,
 462      except that it also offers support for a namespace mapping argument.
 463     </p><p>
 464      Example:
 465 </p><pre class="screen">
 466 SELECT xpath_exists('/my:a/text()', '&lt;my:a xmlns:my="http://example.com"&gt;test&lt;/my:a&gt;',
 467                      ARRAY[ARRAY['my', 'http://example.com']]);
 468
 469  xpath_exists
 470 --------------
 471  t
 472 (1 row)
 473 </pre><p>
 474     </p></div><div class="sect3" id="FUNCTIONS-XML-PROCESSING-XMLTABLE"><div class="titlepage"><div><div><h4 class="title">9.15.3.3. <code class="literal">xmltable</code> <a href="#FUNCTIONS-XML-PROCESSING-XMLTABLE" class="id_link">#</a></h4></div></div></div><a id="id-1.5.8.21.7.5.2" class="indexterm"></a><a id="id-1.5.8.21.7.5.3" class="indexterm"></a><pre class="synopsis">
 475 <code class="function">XMLTABLE</code> (
 476     [<span class="optional"> <code class="literal">XMLNAMESPACES</code> ( <em class="replaceable"><code>namespace_uri</code></em> <code class="literal">AS</code> <em class="replaceable"><code>namespace_name</code></em> [<span class="optional">, ...</span>] ), </span>]
 477     <em class="replaceable"><code>row_expression</code></em> <code class="literal">PASSING</code> [<span class="optional"><code class="literal">BY</code> {<code class="literal">REF</code>|<code class="literal">VALUE</code>}</span>] <em class="replaceable"><code>document_expression</code></em> [<span class="optional"><code class="literal">BY</code> {<code class="literal">REF</code>|<code class="literal">VALUE</code>}</span>]
 478     <code class="literal">COLUMNS</code> <em class="replaceable"><code>name</code></em> { <em class="replaceable"><code>type</code></em> [<span class="optional"><code class="literal">PATH</code> <em class="replaceable"><code>column_expression</code></em></span>] [<span class="optional"><code class="literal">DEFAULT</code> <em class="replaceable"><code>default_expression</code></em></span>] [<span class="optional"><code class="literal">NOT NULL</code> | <code class="literal">NULL</code></span>]
 479                   | <code class="literal">FOR ORDINALITY</code> }
 480             [<span class="optional">, ...</span>]
 481 ) → <code class="returnvalue">setof record</code>
 482 </pre><p>
 483      The <code class="function">xmltable</code> expression produces a table based
 484      on an XML value, an XPath filter to extract rows, and a
 485      set of column definitions.
 486      Although it syntactically resembles a function, it can only appear
 487      as a table in a query's <code class="literal">FROM</code> clause.
 488     </p><p>
 489      The optional <code class="literal">XMLNAMESPACES</code> clause gives a
 490      comma-separated list of namespace definitions, where
 491      each <em class="replaceable"><code>namespace_uri</code></em> is a <code class="type">text</code>
 492      expression and each <em class="replaceable"><code>namespace_name</code></em> is a simple
 493      identifier.  It specifies the XML namespaces used in the document and
 494      their aliases. A default namespace specification is not currently
 495      supported.
 496     </p><p>
 497      The required <em class="replaceable"><code>row_expression</code></em> argument is an
 498      XPath 1.0 expression (given as <code class="type">text</code>) that is evaluated,
 499      passing the XML value <em class="replaceable"><code>document_expression</code></em> as
 500      its context item, to obtain a set of XML nodes. These nodes are what
 501      <code class="function">xmltable</code> transforms into output rows. No rows
 502      will be produced if the <em class="replaceable"><code>document_expression</code></em>
 503      is null, nor if the <em class="replaceable"><code>row_expression</code></em> produces
 504      an empty node-set or any value other than a node-set.
 505     </p><p>
 506      <em class="replaceable"><code>document_expression</code></em> provides the context
 507      item for the <em class="replaceable"><code>row_expression</code></em>. It must be a
 508      well-formed XML document; fragments/forests are not accepted.
 509      The <code class="literal">BY REF</code> and <code class="literal">BY VALUE</code> clauses
 510      are accepted but ignored, as discussed in
 511      <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-POSTGRESQL" title="D.3.2. Incidental Limits of the Implementation">Section D.3.2</a>.
 512     </p><p>
 513      In the SQL standard, the <code class="function">xmltable</code> function
 514      evaluates expressions in the XML Query language,
 515      but <span class="productname">PostgreSQL</span> allows only XPath 1.0
 516      expressions, as discussed in
 517      <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-XPATH1" title="D.3.1. Queries Are Restricted to XPath 1.0">Section D.3.1</a>.
 518     </p><p>
 519      The required <code class="literal">COLUMNS</code> clause specifies the
 520      column(s) that will be produced in the output table.
 521      See the syntax summary above for the format.
 522      A name is required for each column, as is a data type
 523      (unless <code class="literal">FOR ORDINALITY</code> is specified, in which case
 524      type <code class="type">integer</code> is implicit).  The path, default and
 525      nullability clauses are optional.
 526     </p><p>
 527      A column marked <code class="literal">FOR ORDINALITY</code> will be populated
 528      with row numbers, starting with 1, in the order of nodes retrieved from
 529      the <em class="replaceable"><code>row_expression</code></em>'s result node-set.
 530      At most one column may be marked <code class="literal">FOR ORDINALITY</code>.
 531     </p><div class="note"><h3 class="title">Note</h3><p>
 532       XPath 1.0 does not specify an order for nodes in a node-set, so code
 533       that relies on a particular order of the results will be
 534       implementation-dependent.  Details can be found in
 535       <a class="xref" href="xml-limits-conformance.html#XML-XPATH-1-SPECIFICS" title="D.3.1.2. Restriction of XPath to 1.0">Section D.3.1.2</a>.
 536      </p></div><p>
 537      The <em class="replaceable"><code>column_expression</code></em> for a column is an
 538      XPath 1.0 expression that is evaluated for each row, with the current
 539      node from the <em class="replaceable"><code>row_expression</code></em> result as its
 540      context item, to find the value of the column.  If
 541      no <em class="replaceable"><code>column_expression</code></em> is given, then the
 542      column name is used as an implicit path.
 543     </p><p>
 544      If a column's XPath expression returns a non-XML value (which is limited
 545      to string, boolean, or double in XPath 1.0) and the column has a
 546      PostgreSQL type other than <code class="type">xml</code>, the column will be set
 547      as if by assigning the value's string representation to the PostgreSQL
 548      type.  (If the value is a boolean, its string representation is taken
 549      to be <code class="literal">1</code> or <code class="literal">0</code> if the output
 550      column's type category is numeric, otherwise <code class="literal">true</code> or
 551      <code class="literal">false</code>.)
 552     </p><p>
 553      If a column's XPath expression returns a non-empty set of XML nodes
 554      and the column's PostgreSQL type is <code class="type">xml</code>, the column will
 555      be assigned the expression result exactly, if it is of document or
 556      content form.
 557      <a href="#ftn.id-1.5.8.21.7.5.15.2" class="footnote"><sup class="footnote" id="id-1.5.8.21.7.5.15.2">[8]</sup></a>
 558     </p><p>
 559      A non-XML result assigned to an <code class="type">xml</code> output column produces
 560      content, a single text node with the string value of the result.
 561      An XML result assigned to a column of any other type may not have more than
 562      one node, or an error is raised. If there is exactly one node, the column
 563      will be set as if by assigning the node's string
 564      value (as defined for the XPath 1.0 <code class="function">string</code> function)
 565      to the PostgreSQL type.
 566     </p><p>
 567      The string value of an XML element is the concatenation, in document order,
 568      of all text nodes contained in that element and its descendants. The string
 569      value of an element with no descendant text nodes is an
 570      empty string (not <code class="literal">NULL</code>).
 571      Any <code class="literal">xsi:nil</code> attributes are ignored.
 572      Note that the whitespace-only <code class="literal">text()</code> node between two non-text
 573      elements is preserved, and that leading whitespace on a <code class="literal">text()</code>
 574      node is not flattened.
 575      The XPath 1.0 <code class="function">string</code> function may be consulted for the
 576      rules defining the string value of other XML node types and non-XML values.
 577     </p><p>
 578      The conversion rules presented here are not exactly those of the SQL
 579      standard, as discussed in <a class="xref" href="xml-limits-conformance.html#FUNCTIONS-XML-LIMITS-CASTS" title="D.3.1.3. Mappings between SQL and XML Data Types and Values">Section D.3.1.3</a>.
 580     </p><p>
 581      If the path expression returns an empty node-set
 582      (typically, when it does not match)
 583      for a given row, the column will be set to <code class="literal">NULL</code>, unless
 584      a <em class="replaceable"><code>default_expression</code></em> is specified; then the
 585      value resulting from evaluating that expression is used.
 586     </p><p>
 587      A <em class="replaceable"><code>default_expression</code></em>, rather than being
 588      evaluated immediately when <code class="function">xmltable</code> is called,
 589      is evaluated each time a default is needed for the column.
 590      If the expression qualifies as stable or immutable, the repeat
 591      evaluation may be skipped.
 592      This means that you can usefully use volatile functions like
 593      <code class="function">nextval</code> in
 594      <em class="replaceable"><code>default_expression</code></em>.
 595     </p><p>
 596      Columns may be marked <code class="literal">NOT NULL</code>. If the
 597      <em class="replaceable"><code>column_expression</code></em> for a <code class="literal">NOT
 598      NULL</code> column does not match anything and there is
 599      no <code class="literal">DEFAULT</code> or
 600      the <em class="replaceable"><code>default_expression</code></em> also evaluates to null,
 601      an error is reported.
 602     </p><p>
 603      Examples:
 604   </p><pre class="screen">
 605 CREATE TABLE xmldata AS SELECT
 606 xml $$
 607 &lt;ROWS&gt;
 608   &lt;ROW id="1"&gt;
 609     &lt;COUNTRY_ID&gt;AU&lt;/COUNTRY_ID&gt;
 610     &lt;COUNTRY_NAME&gt;Australia&lt;/COUNTRY_NAME&gt;
 611   &lt;/ROW&gt;
 612   &lt;ROW id="5"&gt;
 613     &lt;COUNTRY_ID&gt;JP&lt;/COUNTRY_ID&gt;
 614     &lt;COUNTRY_NAME&gt;Japan&lt;/COUNTRY_NAME&gt;
 615     &lt;PREMIER_NAME&gt;Shinzo Abe&lt;/PREMIER_NAME&gt;
 616     &lt;SIZE unit="sq_mi"&gt;145935&lt;/SIZE&gt;
 617   &lt;/ROW&gt;
 618   &lt;ROW id="6"&gt;
 619     &lt;COUNTRY_ID&gt;SG&lt;/COUNTRY_ID&gt;
 620     &lt;COUNTRY_NAME&gt;Singapore&lt;/COUNTRY_NAME&gt;
 621     &lt;SIZE unit="sq_km"&gt;697&lt;/SIZE&gt;
 622   &lt;/ROW&gt;
 623 &lt;/ROWS&gt;
 624 $$ AS data;
 625
 626 SELECT xmltable.*
 627   FROM xmldata,
 628        XMLTABLE('//ROWS/ROW'
 629                 PASSING data
 630                 COLUMNS id int PATH '@id',
 631                         ordinality FOR ORDINALITY,
 632                         "COUNTRY_NAME" text,
 633                         country_id text PATH 'COUNTRY_ID',
 634                         size_sq_km float PATH 'SIZE[@unit = "sq_km"]',
 635                         size_other text PATH
 636                              'concat(SIZE[@unit!="sq_km"], " ", SIZE[@unit!="sq_km"]/@unit)',
 637                         premier_name text PATH 'PREMIER_NAME' DEFAULT 'not specified');
 638
 639  id | ordinality | COUNTRY_NAME | country_id | size_sq_km |  size_other  | premier_name
 640 ----+------------+--------------+------------+------------+--------------+---------------
 641   1 |          1 | Australia    | AU         |            |              | not specified
 642   5 |          2 | Japan        | JP         |            | 145935 sq_mi | Shinzo Abe
 643   6 |          3 | Singapore    | SG         |        697 |              | not specified
 644 </pre><p>
 645
 646      The following example shows concatenation of multiple text() nodes,
 647      usage of the column name as XPath filter, and the treatment of whitespace,
 648      XML comments and processing instructions:
 649
 650   </p><pre class="screen">
 651 CREATE TABLE xmlelements AS SELECT
 652 xml $$
 653   &lt;root&gt;
 654    &lt;element&gt;  Hello&lt;!-- xyxxz --&gt;2a2&lt;?aaaaa?&gt; &lt;!--x--&gt;  bbb&lt;x&gt;xxx&lt;/x&gt;CC  &lt;/element&gt;
 655   &lt;/root&gt;
 656 $$ AS data;
 657
 658 SELECT xmltable.*
 659   FROM xmlelements, XMLTABLE('/root' PASSING data COLUMNS element text);
 660          element
 661 -------------------------
 662    Hello2a2   bbbxxxCC
 663 </pre><p>
 664     </p><p>
 665      The following example illustrates how
 666      the <code class="literal">XMLNAMESPACES</code> clause can be used to specify
 667      a list of namespaces
 668      used in the XML document as well as in the XPath expressions:
 669
 670   </p><pre class="screen">
 671 WITH xmldata(data) AS (VALUES ('
 672 &lt;example xmlns="http://example.com/myns" xmlns:B="http://example.com/b"&gt;
 673  &lt;item foo="1" B:bar="2"/&gt;
 674  &lt;item foo="3" B:bar="4"/&gt;
 675  &lt;item foo="4" B:bar="5"/&gt;
 676 &lt;/example&gt;'::xml)
 677 )
 678 SELECT xmltable.*
 679   FROM XMLTABLE(XMLNAMESPACES('http://example.com/myns' AS x,
 680                               'http://example.com/b' AS "B"),
 681              '/x:example/x:item'
 682                 PASSING (SELECT data FROM xmldata)
 683                 COLUMNS foo int PATH '@foo',
 684                   bar int PATH '@B:bar');
 685  foo | bar
 686 -----+-----
 687    1 |   2
 688    3 |   4
 689    4 |   5
 690 (3 rows)
 691 </pre><p>
 692     </p></div></div><div class="sect2" id="FUNCTIONS-XML-MAPPING"><div class="titlepage"><div><div><h3 class="title">9.15.4. Mapping Tables to XML <a href="#FUNCTIONS-XML-MAPPING" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.21.8.2" class="indexterm"></a><p>
 693     The following functions map the contents of relational tables to
 694     XML values.  They can be thought of as XML export functionality:
 695 </p><pre class="synopsis">
 696 <code class="function">table_to_xml</code> ( <em class="parameter"><code>table</code></em> <code class="type">regclass</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 697                <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 698 <code class="function">query_to_xml</code> ( <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 699                <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 700 <code class="function">cursor_to_xml</code> ( <em class="parameter"><code>cursor</code></em> <code class="type">refcursor</code>, <em class="parameter"><code>count</code></em> <code class="type">integer</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 701                 <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 702 </pre><p>
 703    </p><p>
 704     <code class="function">table_to_xml</code> maps the content of the named
 705     table, passed as parameter <em class="parameter"><code>table</code></em>.  The
 706     <code class="type">regclass</code> type accepts strings identifying tables using the
 707     usual notation, including optional schema qualification and
 708     double quotes (see <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a> for details).
 709     <code class="function">query_to_xml</code> executes the
 710     query whose text is passed as parameter
 711     <em class="parameter"><code>query</code></em> and maps the result set.
 712     <code class="function">cursor_to_xml</code> fetches the indicated number of
 713     rows from the cursor specified by the parameter
 714     <em class="parameter"><code>cursor</code></em>.  This variant is recommended if
 715     large tables have to be mapped, because the result value is built
 716     up in memory by each function.
 717    </p><p>
 718     If <em class="parameter"><code>tableforest</code></em> is false, then the resulting
 719     XML document looks like this:
 720 </p><pre class="screen">
 721 &lt;tablename&gt;
 722   &lt;row&gt;
 723     &lt;columnname1&gt;data&lt;/columnname1&gt;
 724     &lt;columnname2&gt;data&lt;/columnname2&gt;
 725   &lt;/row&gt;
 726
 727   &lt;row&gt;
 728     ...
 729   &lt;/row&gt;
 730
 731   ...
 732 &lt;/tablename&gt;
 733 </pre><p>
 734
 735     If <em class="parameter"><code>tableforest</code></em> is true, the result is an
 736     XML content fragment that looks like this:
 737 </p><pre class="screen">
 738 &lt;tablename&gt;
 739   &lt;columnname1&gt;data&lt;/columnname1&gt;
 740   &lt;columnname2&gt;data&lt;/columnname2&gt;
 741 &lt;/tablename&gt;
 742
 743 &lt;tablename&gt;
 744   ...
 745 &lt;/tablename&gt;
 746
 747 ...
 748 </pre><p>
 749
 750     If no table name is available, that is, when mapping a query or a
 751     cursor, the string <code class="literal">table</code> is used in the first
 752     format, <code class="literal">row</code> in the second format.
 753    </p><p>
 754     The choice between these formats is up to the user.  The first
 755     format is a proper XML document, which will be important in many
 756     applications.  The second format tends to be more useful in the
 757     <code class="function">cursor_to_xml</code> function if the result values are to be
 758     reassembled into one document later on.  The functions for
 759     producing XML content discussed above, in particular
 760     <code class="function">xmlelement</code>, can be used to alter the results
 761     to taste.
 762    </p><p>
 763     The data values are mapped in the same way as described for the
 764     function <code class="function">xmlelement</code> above.
 765    </p><p>
 766     The parameter <em class="parameter"><code>nulls</code></em> determines whether null
 767     values should be included in the output.  If true, null values in
 768     columns are represented as:
 769 </p><pre class="screen">
 770 &lt;columnname xsi:nil="true"/&gt;
 771 </pre><p>
 772     where <code class="literal">xsi</code> is the XML namespace prefix for XML
 773     Schema Instance.  An appropriate namespace declaration will be
 774     added to the result value.  If false, columns containing null
 775     values are simply omitted from the output.
 776    </p><p>
 777     The parameter <em class="parameter"><code>targetns</code></em> specifies the
 778     desired XML namespace of the result.  If no particular namespace
 779     is wanted, an empty string should be passed.
 780    </p><p>
 781     The following functions return XML Schema documents describing the
 782     mappings performed by the corresponding functions above:
 783 </p><pre class="synopsis">
 784 <code class="function">table_to_xmlschema</code> ( <em class="parameter"><code>table</code></em> <code class="type">regclass</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 785                      <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 786 <code class="function">query_to_xmlschema</code> ( <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 787                      <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 788 <code class="function">cursor_to_xmlschema</code> ( <em class="parameter"><code>cursor</code></em> <code class="type">refcursor</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 789                       <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 790 </pre><p>
 791     It is essential that the same parameters are passed in order to
 792     obtain matching XML data mappings and XML Schema documents.
 793    </p><p>
 794     The following functions produce XML data mappings and the
 795     corresponding XML Schema in one document (or forest), linked
 796     together.  They can be useful where self-contained and
 797     self-describing results are wanted:
 798 </p><pre class="synopsis">
 799 <code class="function">table_to_xml_and_xmlschema</code> ( <em class="parameter"><code>table</code></em> <code class="type">regclass</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 800                              <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 801 <code class="function">query_to_xml_and_xmlschema</code> ( <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 802                              <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 803 </pre><p>
 804    </p><p>
 805     In addition, the following functions are available to produce
 806     analogous mappings of entire schemas or the entire current
 807     database:
 808 </p><pre class="synopsis">
 809 <code class="function">schema_to_xml</code> ( <em class="parameter"><code>schema</code></em> <code class="type">name</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 810                 <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 811 <code class="function">schema_to_xmlschema</code> ( <em class="parameter"><code>schema</code></em> <code class="type">name</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 812                       <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 813 <code class="function">schema_to_xml_and_xmlschema</code> ( <em class="parameter"><code>schema</code></em> <code class="type">name</code>, <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 814                               <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 815
 816 <code class="function">database_to_xml</code> ( <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 817                   <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 818 <code class="function">database_to_xmlschema</code> ( <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 819                         <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 820 <code class="function">database_to_xml_and_xmlschema</code> ( <em class="parameter"><code>nulls</code></em> <code class="type">boolean</code>,
 821                                 <em class="parameter"><code>tableforest</code></em> <code class="type">boolean</code>, <em class="parameter"><code>targetns</code></em> <code class="type">text</code> ) → <code class="returnvalue">xml</code>
 822 </pre><p>
 823
 824     These functions ignore tables that are not readable by the current user.
 825     The database-wide functions additionally ignore schemas that the current
 826     user does not have <code class="literal">USAGE</code> (lookup) privilege for.
 827    </p><p>
 828     Note that these potentially produce a lot of data, which needs to
 829     be built up in memory.  When requesting content mappings of large
 830     schemas or databases, it might be worthwhile to consider mapping the
 831     tables separately instead, possibly even through a cursor.
 832    </p><p>
 833     The result of a schema content mapping looks like this:
 834
 835 </p><pre class="screen">
 836 &lt;schemaname&gt;
 837
 838 table1-mapping
 839
 840 table2-mapping
 841
 842 ...
 843
 844 &lt;/schemaname&gt;</pre><p>
 845
 846     where the format of a table mapping depends on the
 847     <em class="parameter"><code>tableforest</code></em> parameter as explained above.
 848    </p><p>
 849     The result of a database content mapping looks like this:
 850
 851 </p><pre class="screen">
 852 &lt;dbname&gt;
 853
 854 &lt;schema1name&gt;
 855   ...
 856 &lt;/schema1name&gt;
 857
 858 &lt;schema2name&gt;
 859   ...
 860 &lt;/schema2name&gt;
 861
 862 ...
 863
 864 &lt;/dbname&gt;</pre><p>
 865
 866     where the schema mapping is as above.
 867    </p><p>
 868     As an example of using the output produced by these functions,
 869     <a class="xref" href="functions-xml.html#XSLT-XML-HTML" title="Example 9.1. XSLT Stylesheet for Converting SQL/XML Output to HTML">Example 9.1</a> shows an XSLT stylesheet that
 870     converts the output of
 871     <code class="function">table_to_xml_and_xmlschema</code> to an HTML
 872     document containing a tabular rendition of the table data.  In a
 873     similar manner, the results from these functions can be
 874     converted into other XML-based formats.
 875    </p><div class="example" id="XSLT-XML-HTML"><p class="title"><strong>Example 9.1. XSLT Stylesheet for Converting SQL/XML Output to HTML</strong></p><div class="example-contents"><pre class="programlisting">
 876 &lt;?xml version="1.0"?&gt;
 877 &lt;xsl:stylesheet version="1.0"
 878     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 879     xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 880     xmlns="http://www.w3.org/1999/xhtml"
 881 &gt;
 882
 883   &lt;xsl:output method="xml"
 884       doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
 885       doctype-public="-//W3C/DTD XHTML 1.0 Strict//EN"
 886       indent="yes"/&gt;
 887
 888   &lt;xsl:template match="/*"&gt;
 889     &lt;xsl:variable name="schema" select="//xsd:schema"/&gt;
 890     &lt;xsl:variable name="tabletypename"
 891                   select="$schema/xsd:element[@name=name(current())]/@type"/&gt;
 892     &lt;xsl:variable name="rowtypename"
 893                   select="$schema/xsd:complexType[@name=$tabletypename]/xsd:sequence/xsd:element[@name='row']/@type"/&gt;
 894
 895     &lt;html&gt;
 896       &lt;head&gt;
 897         &lt;title&gt;&lt;xsl:value-of select="name(current())"/&gt;&lt;/title&gt;
 898       &lt;/head&gt;
 899       &lt;body&gt;
 900         &lt;table&gt;
 901           &lt;tr&gt;
 902             &lt;xsl:for-each select="$schema/xsd:complexType[@name=$rowtypename]/xsd:sequence/xsd:element/@name"&gt;
 903               &lt;th&gt;&lt;xsl:value-of select="."/&gt;&lt;/th&gt;
 904             &lt;/xsl:for-each&gt;
 905           &lt;/tr&gt;
 906
 907           &lt;xsl:for-each select="row"&gt;
 908             &lt;tr&gt;
 909               &lt;xsl:for-each select="*"&gt;
 910                 &lt;td&gt;&lt;xsl:value-of select="."/&gt;&lt;/td&gt;
 911               &lt;/xsl:for-each&gt;
 912             &lt;/tr&gt;
 913           &lt;/xsl:for-each&gt;
 914         &lt;/table&gt;
 915       &lt;/body&gt;
 916     &lt;/html&gt;
 917   &lt;/xsl:template&gt;
 918
 919 &lt;/xsl:stylesheet&gt;
 920 </pre></div></div><br class="example-break" /></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.id-1.5.8.21.7.5.15.2" class="footnote"><p><a href="#id-1.5.8.21.7.5.15.2" class="para"><sup class="para">[8] </sup></a>
 921        A result containing more than one element node at the top level, or
 922        non-whitespace text outside of an element, is an example of content form.
 923        An XPath result can be of neither form, for example if it returns an
 924        attribute node selected from the element that contains it. Such a result
 925        will be put into content form with each such disallowed node replaced by
 926        its string value, as defined for the XPath 1.0
 927        <code class="function">string</code> function.
 928       </p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-uuid.html" title="9.14. UUID Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-json.html" title="9.16. JSON Functions and Operators">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.14. UUID Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.16. JSON Functions and Operators</td></tr></table></div></body></html>