begriffs open source - ai-pg/blob - full-docs/src/sgml/html/datatype-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>8.13. XML Type</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="datatype-uuid.html" title="8.12. UUID Type" /><link rel="next" href="datatype-json.html" title="8.14. JSON Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.13. <acronym class="acronym">XML</acronym> Type</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-uuid.html" title="8.12. UUID Type">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</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="datatype-json.html" title="8.14. JSON Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-XML"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.13. <acronym class="acronym">XML</acronym> Type <a href="#DATATYPE-XML" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="datatype-xml.html#DATATYPE-XML-CREATING">8.13.1. Creating XML Values</a></span></dt><dt><span class="sect2"><a href="datatype-xml.html#DATATYPE-XML-ENCODING-HANDLING">8.13.2. Encoding Handling</a></span></dt><dt><span class="sect2"><a href="datatype-xml.html#DATATYPE-XML-ACCESSING-XML-VALUES">8.13.3. Accessing XML Values</a></span></dt></dl></div><a id="id-1.5.7.21.2" class="indexterm"></a><p>
   3     The <code class="type">xml</code> data type can be used to store XML data.  Its
   4     advantage over storing XML data in a <code class="type">text</code> field is that it
   5     checks the input values for well-formedness, and there are support
   6     functions to perform type-safe operations on it; see <a class="xref" href="functions-xml.html" title="9.15. XML Functions">Section 9.15</a>.  Use of this data type requires the
   7     installation to have been built with <code class="command">configure
   8     --with-libxml</code>.
   9    </p><p>
  10     The <code class="type">xml</code> type can store well-formed
  11     <span class="quote">“<span class="quote">documents</span>”</span>, as defined by the XML standard, as well
  12     as <span class="quote">“<span class="quote">content</span>”</span> fragments, which are defined by reference
  13     to the more permissive
  14     <a class="ulink" href="https://www.w3.org/TR/2010/REC-xpath-datamodel-20101214/#DocumentNode" target="_top"><span class="quote">“<span class="quote">document node</span>”</span></a>
  15     of the XQuery and XPath data model.
  16     Roughly, this means that content fragments can have
  17     more than one top-level element or character node.  The expression
  18     <code class="literal"><em class="replaceable"><code>xmlvalue</code></em> IS DOCUMENT</code>
  19     can be used to evaluate whether a particular <code class="type">xml</code>
  20     value is a full document or only a content fragment.
  21    </p><p>
  22     Limits and compatibility notes for the <code class="type">xml</code> data type
  23     can be found in <a class="xref" href="xml-limits-conformance.html" title="D.3. XML Limits and Conformance to SQL/XML">Section D.3</a>.
  24    </p><div class="sect2" id="DATATYPE-XML-CREATING"><div class="titlepage"><div><div><h3 class="title">8.13.1. Creating XML Values <a href="#DATATYPE-XML-CREATING" class="id_link">#</a></h3></div></div></div><p>
  25     To produce a value of type <code class="type">xml</code> from character data,
  26     use the function
  27     <code class="function">xmlparse</code>:<a id="id-1.5.7.21.6.2.3" class="indexterm"></a>
  28 </p><pre class="synopsis">
  29 XMLPARSE ( { DOCUMENT | CONTENT } <em class="replaceable"><code>value</code></em>)
  30 </pre><p>
  31     Examples:
  32 </p><pre class="programlisting">
  33 XMLPARSE (DOCUMENT '&lt;?xml version="1.0"?&gt;&lt;book&gt;&lt;title&gt;Manual&lt;/title&gt;&lt;chapter&gt;...&lt;/chapter&gt;&lt;/book&gt;')
  34 XMLPARSE (CONTENT 'abc&lt;foo&gt;bar&lt;/foo&gt;&lt;bar&gt;foo&lt;/bar&gt;')
  35 </pre><p>
  36     While this is the only way to convert character strings into XML
  37     values according to the SQL standard, the PostgreSQL-specific
  38     syntaxes:
  39 </p><pre class="programlisting">
  40 xml '&lt;foo&gt;bar&lt;/foo&gt;'
  41 '&lt;foo&gt;bar&lt;/foo&gt;'::xml
  42 </pre><p>
  43     can also be used.
  44    </p><p>
  45     The <code class="type">xml</code> type does not validate input values
  46     against a document type declaration
  47     (DTD),<a id="id-1.5.7.21.6.3.2" class="indexterm"></a>
  48     even when the input value specifies a DTD.
  49     There is also currently no built-in support for validating against
  50     other XML schema languages such as XML Schema.
  51    </p><p>
  52     The inverse operation, producing a character string value from
  53     <code class="type">xml</code>, uses the function
  54     <code class="function">xmlserialize</code>:<a id="id-1.5.7.21.6.4.3" class="indexterm"></a>
  55 </p><pre class="synopsis">
  56 XMLSERIALIZE ( { DOCUMENT | CONTENT } <em class="replaceable"><code>value</code></em> AS <em class="replaceable"><code>type</code></em> [ [ NO ] INDENT ] )
  57 </pre><p>
  58     <em class="replaceable"><code>type</code></em> can be
  59     <code class="type">character</code>, <code class="type">character varying</code>, or
  60     <code class="type">text</code> (or an alias for one of those).  Again, according
  61     to the SQL standard, this is the only way to convert between type
  62     <code class="type">xml</code> and character types, but PostgreSQL also allows
  63     you to simply cast the value.
  64    </p><p>
  65     The <code class="literal">INDENT</code> option causes the result to be
  66     pretty-printed, while <code class="literal">NO INDENT</code> (which is the
  67     default) just emits the original input string.  Casting to a character
  68     type likewise produces the original string.
  69    </p><p>
  70     When a character string value is cast to or from type
  71     <code class="type">xml</code> without going through <code class="type">XMLPARSE</code> or
  72     <code class="type">XMLSERIALIZE</code>, respectively, the choice of
  73     <code class="literal">DOCUMENT</code> versus <code class="literal">CONTENT</code> is
  74     determined by the <span class="quote">“<span class="quote">XML option</span>”</span>
  75     <a id="id-1.5.7.21.6.6.7" class="indexterm"></a>
  76     session configuration parameter, which can be set using the
  77     standard command:
  78 </p><pre class="synopsis">
  79 SET XML OPTION { DOCUMENT | CONTENT };
  80 </pre><p>
  81     or the more PostgreSQL-like syntax
  82 </p><pre class="synopsis">
  83 SET xmloption TO { DOCUMENT | CONTENT };
  84 </pre><p>
  85     The default is <code class="literal">CONTENT</code>, so all forms of XML
  86     data are allowed.
  87    </p></div><div class="sect2" id="DATATYPE-XML-ENCODING-HANDLING"><div class="titlepage"><div><div><h3 class="title">8.13.2. Encoding Handling <a href="#DATATYPE-XML-ENCODING-HANDLING" class="id_link">#</a></h3></div></div></div><p>
  88     Care must be taken when dealing with multiple character encodings
  89     on the client, server, and in the XML data passed through them.
  90     When using the text mode to pass queries to the server and query
  91     results to the client (which is the normal mode), PostgreSQL
  92     converts all character data passed between the client and the
  93     server and vice versa to the character encoding of the respective
  94     end; see <a class="xref" href="multibyte.html" title="23.3. Character Set Support">Section 23.3</a>.  This includes string
  95     representations of XML values, such as in the above examples.
  96     This would ordinarily mean that encoding declarations contained in
  97     XML data can become invalid as the character data is converted
  98     to other encodings while traveling between client and server,
  99     because the embedded encoding declaration is not changed.  To cope
 100     with this behavior, encoding declarations contained in
 101     character strings presented for input to the <code class="type">xml</code> type
 102     are <span class="emphasis"><em>ignored</em></span>, and content is assumed
 103     to be in the current server encoding.  Consequently, for correct
 104     processing, character strings of XML data must be sent
 105     from the client in the current client encoding.  It is the
 106     responsibility of the client to either convert documents to the
 107     current client encoding before sending them to the server, or to
 108     adjust the client encoding appropriately.  On output, values of
 109     type <code class="type">xml</code> will not have an encoding declaration, and
 110     clients should assume all data is in the current client
 111     encoding.
 112    </p><p>
 113     When using binary mode to pass query parameters to the server
 114     and query results back to the client, no encoding conversion
 115     is performed, so the situation is different.  In this case, an
 116     encoding declaration in the XML data will be observed, and if it
 117     is absent, the data will be assumed to be in UTF-8 (as required by
 118     the XML standard; note that PostgreSQL does not support UTF-16).
 119     On output, data will have an encoding declaration
 120     specifying the client encoding, unless the client encoding is
 121     UTF-8, in which case it will be omitted.
 122    </p><p>
 123     Needless to say, processing XML data with PostgreSQL will be less
 124     error-prone and more efficient if the XML data encoding, client encoding,
 125     and server encoding are the same.  Since XML data is internally
 126     processed in UTF-8, computations will be most efficient if the
 127     server encoding is also UTF-8.
 128    </p><div class="caution"><h3 class="title">Caution</h3><p>
 129      Some XML-related functions may not work at all on non-ASCII data
 130      when the server encoding is not UTF-8.  This is known to be an
 131      issue for <code class="function">xmltable()</code> and <code class="function">xpath()</code> in particular.
 132     </p></div></div><div class="sect2" id="DATATYPE-XML-ACCESSING-XML-VALUES"><div class="titlepage"><div><div><h3 class="title">8.13.3. Accessing XML Values <a href="#DATATYPE-XML-ACCESSING-XML-VALUES" class="id_link">#</a></h3></div></div></div><p>
 133     The <code class="type">xml</code> data type is unusual in that it does not
 134     provide any comparison operators.  This is because there is no
 135     well-defined and universally useful comparison algorithm for XML
 136     data.  One consequence of this is that you cannot retrieve rows by
 137     comparing an <code class="type">xml</code> column against a search value.  XML
 138     values should therefore typically be accompanied by a separate key
 139     field such as an ID.  An alternative solution for comparing XML
 140     values is to convert them to character strings first, but note
 141     that character string comparison has little to do with a useful
 142     XML comparison method.
 143    </p><p>
 144     Since there are no comparison operators for the <code class="type">xml</code>
 145     data type, it is not possible to create an index directly on a
 146     column of this type.  If speedy searches in XML data are desired,
 147     possible workarounds include casting the expression to a
 148     character string type and indexing that, or indexing an XPath
 149     expression.  Of course, the actual query would have to be adjusted
 150     to search by the indexed expression.
 151    </p><p>
 152     The text-search functionality in PostgreSQL can also be used to speed
 153     up full-document searches of XML data.  The necessary
 154     preprocessing support is, however, not yet available in the PostgreSQL
 155     distribution.
 156    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-uuid.html" title="8.12. UUID Type">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-json.html" title="8.14. JSON Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.12. <acronym class="acronym">UUID</acronym> Type </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"> 8.14. <acronym class="acronym">JSON</acronym> Types</td></tr></table></div></body></html>