begriffs open source - ai-pg/blob - full-docs/html/xml2.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>F.50. xml2 — XPath querying and XSLT functionality</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="uuid-ossp.html" title="F.49. uuid-ossp — a UUID generator" /><link rel="next" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">F.50. xml2 — XPath querying and XSLT functionality</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="uuid-ossp.html" title="F.49. uuid-ossp — a UUID generator">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><th width="60%" align="center">Appendix F. Additional Supplied Modules and Extensions</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="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Next</a></td></tr></table><hr /></div><div class="sect1" id="XML2"><div class="titlepage"><div><div><h2 class="title" style="clear: both">F.50. xml2 — XPath querying and XSLT functionality <a href="#XML2" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="xml2.html#XML2-DEPRECATION">F.50.1. Deprecation Notice</a></span></dt><dt><span class="sect2"><a href="xml2.html#XML2-FUNCTIONS">F.50.2. Description of Functions</a></span></dt><dt><span class="sect2"><a href="xml2.html#XML2-XPATH-TABLE">F.50.3. <code class="literal">xpath_table</code></a></span></dt><dt><span class="sect2"><a href="xml2.html#XML2-XSLT">F.50.4. XSLT Functions</a></span></dt><dt><span class="sect2"><a href="xml2.html#XML2-AUTHOR">F.50.5. Author</a></span></dt></dl></div><a id="id-1.11.7.60.2" class="indexterm"></a><p>
   3   The <code class="filename">xml2</code> module provides XPath querying and
   4   XSLT functionality.
   5  </p><div class="sect2" id="XML2-DEPRECATION"><div class="titlepage"><div><div><h3 class="title">F.50.1. Deprecation Notice <a href="#XML2-DEPRECATION" class="id_link">#</a></h3></div></div></div><p>
   6    From <span class="productname">PostgreSQL</span> 8.3 on, there is XML-related
   7    functionality based on the SQL/XML standard in the core server.
   8    That functionality covers XML syntax checking and XPath queries,
   9    which is what this module does, and more, but the API is
  10    not at all compatible.  It is planned that this module will be
  11    removed in a future version of PostgreSQL in favor of the newer standard API, so
  12    you are encouraged to try converting your applications.  If you
  13    find that some of the functionality of this module is not
  14    available in an adequate form with the newer API, please explain
  15    your issue to <code class="email">&lt;<a class="email" href="mailto:pgsql-hackers@lists.postgresql.org">pgsql-hackers@lists.postgresql.org</a>&gt;</code> so that the deficiency
  16    can be addressed.
  17   </p></div><div class="sect2" id="XML2-FUNCTIONS"><div class="titlepage"><div><div><h3 class="title">F.50.2. Description of Functions <a href="#XML2-FUNCTIONS" class="id_link">#</a></h3></div></div></div><p>
  18    <a class="xref" href="xml2.html#XML2-FUNCTIONS-TABLE" title="Table F.37. xml2 Functions">Table F.37</a> shows the functions provided by this module.
  19    These functions provide straightforward XML parsing and XPath queries.
  20   </p><div class="table" id="XML2-FUNCTIONS-TABLE"><p class="title"><strong>Table F.37. <code class="filename">xml2</code> Functions</strong></p><div class="table-contents"><table class="table" summary="xml2 Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
  21         Function
  22        </p>
  23        <p>
  24         Description
  25        </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
  26         <code class="function">xml_valid</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code> )
  27         → <code class="returnvalue">boolean</code>
  28        </p>
  29        <p>
  30         Parses the given document and returns true if the
  31         document is well-formed XML.  (Note: this is an alias for the standard
  32         PostgreSQL function <code class="function">xml_is_well_formed()</code>.  The
  33         name <code class="function">xml_valid()</code> is technically incorrect since validity
  34         and well-formedness have different meanings in XML.)
  35        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  36         <code class="function">xpath_string</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code> )
  37         → <code class="returnvalue">text</code>
  38        </p>
  39        <p>
  40         Evaluates the XPath query on the supplied document, and
  41         casts the result to <code class="type">text</code>.
  42        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  43         <code class="function">xpath_number</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code> )
  44         → <code class="returnvalue">real</code>
  45        </p>
  46        <p>
  47         Evaluates the XPath query on the supplied document, and
  48         casts the result to <code class="type">real</code>.
  49        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  50         <code class="function">xpath_bool</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code> )
  51         → <code class="returnvalue">boolean</code>
  52        </p>
  53        <p>
  54         Evaluates the XPath query on the supplied document, and
  55         casts the result to <code class="type">boolean</code>.
  56        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  57         <code class="function">xpath_nodeset</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>toptag</code></em> <code class="type">text</code>, <em class="parameter"><code>itemtag</code></em> <code class="type">text</code> )
  58         → <code class="returnvalue">text</code>
  59        </p>
  60        <p>
  61         Evaluates the query on the document and wraps the result in XML
  62         tags. If the result is multivalued, the output will look like:
  63 </p><pre class="synopsis">
  64 &lt;toptag&gt;
  65 &lt;itemtag&gt;Value 1 which could be an XML fragment&lt;/itemtag&gt;
  66 &lt;itemtag&gt;Value 2....&lt;/itemtag&gt;
  67 &lt;/toptag&gt;
  68 </pre><p>
  69         If either <em class="parameter"><code>toptag</code></em>
  70         or <em class="parameter"><code>itemtag</code></em> is an empty string, the relevant tag
  71         is omitted.
  72        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  73         <code class="function">xpath_nodeset</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>itemtag</code></em> <code class="type">text</code> )
  74         → <code class="returnvalue">text</code>
  75        </p>
  76        <p>
  77         Like <code class="function">xpath_nodeset(document, query, toptag, itemtag)</code> but result omits <em class="parameter"><code>toptag</code></em>.
  78        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  79         <code class="function">xpath_nodeset</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code> )
  80         → <code class="returnvalue">text</code>
  81        </p>
  82        <p>
  83         Like <code class="function">xpath_nodeset(document, query, toptag, itemtag)</code> but result omits both tags.
  84        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  85         <code class="function">xpath_list</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code>, <em class="parameter"><code>separator</code></em> <code class="type">text</code> )
  86         → <code class="returnvalue">text</code>
  87        </p>
  88        <p>
  89         Evaluates the query on the document and returns multiple values
  90         separated by the specified separator, for example <code class="literal">Value
  91         1,Value 2,Value 3</code> if <em class="parameter"><code>separator</code></em>
  92         is <code class="literal">,</code>.
  93        </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
  94         <code class="function">xpath_list</code> ( <em class="parameter"><code>document</code></em> <code class="type">text</code>, <em class="parameter"><code>query</code></em> <code class="type">text</code> )
  95         → <code class="returnvalue">text</code>
  96        </p>
  97        <p>
  98         This is a wrapper for the above function that uses <code class="literal">,</code>
  99         as the separator.
 100        </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="XML2-XPATH-TABLE"><div class="titlepage"><div><div><h3 class="title">F.50.3. <code class="literal">xpath_table</code> <a href="#XML2-XPATH-TABLE" class="id_link">#</a></h3></div></div></div><a id="id-1.11.7.60.6.2" class="indexterm"></a><pre class="synopsis">
 101 xpath_table(text key, text document, text relation, text xpaths, text criteria) returns setof record
 102 </pre><p>
 103    <code class="function">xpath_table</code> is a table function that evaluates a set of XPath
 104    queries on each of a set of documents and returns the results as a
 105    table. The primary key field from the original document table is returned
 106    as the first column of the result so that the result set
 107    can readily be used in joins.  The parameters are described in
 108    <a class="xref" href="xml2.html#XML2-XPATH-TABLE-PARAMETERS" title="Table F.38. xpath_table Parameters">Table F.38</a>.
 109   </p><div class="table" id="XML2-XPATH-TABLE-PARAMETERS"><p class="title"><strong>Table F.38. <code class="function">xpath_table</code> Parameters</strong></p><div class="table-contents"><table class="table" summary="xpath_table Parameters" border="1"><colgroup><col class="col1" /><col class="col2" /></colgroup><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><em class="parameter"><code>key</code></em></td><td>
 110        <p>
 111         the name of the <span class="quote">“<span class="quote">key</span>”</span> field — this is just a field to be used as
 112         the first column of the output table, i.e., it identifies the record from
 113         which each output row came (see note below about multiple values)
 114        </p>
 115       </td></tr><tr><td><em class="parameter"><code>document</code></em></td><td>
 116        <p>
 117         the name of the field containing the XML document
 118        </p>
 119       </td></tr><tr><td><em class="parameter"><code>relation</code></em></td><td>
 120        <p>
 121         the name of the table or view containing the documents
 122        </p>
 123       </td></tr><tr><td><em class="parameter"><code>xpaths</code></em></td><td>
 124        <p>
 125         one or more XPath expressions, separated by <code class="literal">|</code>
 126        </p>
 127       </td></tr><tr><td><em class="parameter"><code>criteria</code></em></td><td>
 128        <p>
 129         the contents of the WHERE clause. This cannot be omitted, so use
 130         <code class="literal">true</code> or <code class="literal">1=1</code> if you want to
 131         process all the rows in the relation
 132        </p>
 133       </td></tr></tbody></table></div></div><br class="table-break" /><p>
 134    These parameters (except the XPath strings) are just substituted
 135    into a plain SQL SELECT statement, so you have some flexibility — the
 136    statement is
 137   </p><p>
 138    <code class="literal">
 139     SELECT &lt;key&gt;, &lt;document&gt; FROM &lt;relation&gt; WHERE &lt;criteria&gt;
 140    </code>
 141   </p><p>
 142    so those parameters can be <span class="emphasis"><em>anything</em></span> valid in those particular
 143    locations. The result from this SELECT needs to return exactly two
 144    columns (which it will unless you try to list multiple fields for key
 145    or document). Beware that this simplistic approach requires that you
 146    validate any user-supplied values to avoid SQL injection attacks.
 147   </p><p>
 148    The function has to be used in a <code class="literal">FROM</code> expression, with an
 149    <code class="literal">AS</code> clause to specify the output columns; for example
 150 </p><pre class="programlisting">
 151 SELECT * FROM
 152 xpath_table('article_id',
 153             'article_xml',
 154             'articles',
 155             '/article/author|/article/pages|/article/title',
 156             'date_entered &gt; ''2003-01-01'' ')
 157 AS t(article_id integer, author text, page_count integer, title text);
 158 </pre><p>
 159    The <code class="literal">AS</code> clause defines the names and types of the columns in the
 160    output table.  The first is the <span class="quote">“<span class="quote">key</span>”</span> field and the rest correspond
 161    to the XPath queries.
 162    If there are more XPath queries than result columns,
 163    the extra queries will be ignored. If there are more result columns
 164    than XPath queries, the extra columns will be NULL.
 165   </p><p>
 166    Notice that this example defines the <code class="structname">page_count</code> result
 167    column as an integer.  The function deals internally with string
 168    representations, so when you say you want an integer in the output, it will
 169    take the string representation of the XPath result and use PostgreSQL input
 170    functions to transform it into an integer (or whatever type the <code class="type">AS</code>
 171    clause requests). An error will result if it can't do this — for
 172    example if the result is empty — so you may wish to just stick to
 173    <code class="type">text</code> as the column type if you think your data has any problems.
 174   </p><p>
 175    The calling <code class="command">SELECT</code> statement doesn't necessarily have to be
 176    just <code class="literal">SELECT *</code> — it can reference the output
 177    columns by name or join them to other tables. The function produces a
 178    virtual table with which you can perform any operation you wish (e.g.,
 179    aggregation, joining, sorting etc.). So we could also have:
 180 </p><pre class="programlisting">
 181 SELECT t.title, p.fullname, p.email
 182 FROM xpath_table('article_id', 'article_xml', 'articles',
 183                  '/article/title|/article/author/@id',
 184                  'xpath_string(article_xml,''/article/@date'') &gt; ''2003-03-20'' ')
 185        AS t(article_id integer, title text, author_id integer),
 186      tblPeopleInfo AS p
 187 WHERE t.author_id = p.person_id;
 188 </pre><p>
 189    as a more complicated example. Of course, you could wrap all
 190    of this in a view for convenience.
 191   </p><div class="sect3" id="XML2-XPATH-TABLE-MULTIVALUED-RESULTS"><div class="titlepage"><div><div><h4 class="title">F.50.3.1. Multivalued Results <a href="#XML2-XPATH-TABLE-MULTIVALUED-RESULTS" class="id_link">#</a></h4></div></div></div><p>
 192     The <code class="function">xpath_table</code> function assumes that the results of each XPath query
 193     might be multivalued, so the number of rows returned by the function
 194     may not be the same as the number of input documents. The first row
 195     returned contains the first result from each query, the second row the
 196     second result from each query. If one of the queries has fewer values
 197     than the others, null values will be returned instead.
 198    </p><p>
 199     In some cases, a user will know that a given XPath query will return
 200     only a single result (perhaps a unique document identifier) — if used
 201     alongside an XPath query returning multiple results, the single-valued
 202     result will appear only on the first row of the result. The solution
 203     to this is to use the key field as part of a join against a simpler
 204     XPath query. As an example:
 205
 206 </p><pre class="programlisting">
 207 CREATE TABLE test (
 208     id int PRIMARY KEY,
 209     xml text
 210 );
 211
 212 INSERT INTO test VALUES (1, '&lt;doc num="C1"&gt;
 213 &lt;line num="L1"&gt;&lt;a&gt;1&lt;/a&gt;&lt;b&gt;2&lt;/b&gt;&lt;c&gt;3&lt;/c&gt;&lt;/line&gt;
 214 &lt;line num="L2"&gt;&lt;a&gt;11&lt;/a&gt;&lt;b&gt;22&lt;/b&gt;&lt;c&gt;33&lt;/c&gt;&lt;/line&gt;
 215 &lt;/doc&gt;');
 216
 217 INSERT INTO test VALUES (2, '&lt;doc num="C2"&gt;
 218 &lt;line num="L1"&gt;&lt;a&gt;111&lt;/a&gt;&lt;b&gt;222&lt;/b&gt;&lt;c&gt;333&lt;/c&gt;&lt;/line&gt;
 219 &lt;line num="L2"&gt;&lt;a&gt;111&lt;/a&gt;&lt;b&gt;222&lt;/b&gt;&lt;c&gt;333&lt;/c&gt;&lt;/line&gt;
 220 &lt;/doc&gt;');
 221
 222 SELECT * FROM
 223   xpath_table('id','xml','test',
 224               '/doc/@num|/doc/line/@num|/doc/line/a|/doc/line/b|/doc/line/c',
 225               'true')
 226   AS t(id int, doc_num varchar(10), line_num varchar(10), val1 int, val2 int, val3 int)
 227 WHERE id = 1 ORDER BY doc_num, line_num
 228
 229  id | doc_num | line_num | val1 | val2 | val3
 230 ----+---------+----------+------+------+------
 231   1 | C1      | L1       |    1 |    2 |    3
 232   1 |         | L2       |   11 |   22 |   33
 233 </pre><p>
 234    </p><p>
 235     To get <code class="literal">doc_num</code> on every line, the solution is to use two invocations
 236     of <code class="function">xpath_table</code> and join the results:
 237
 238 </p><pre class="programlisting">
 239 SELECT t.*,i.doc_num FROM
 240   xpath_table('id', 'xml', 'test',
 241               '/doc/line/@num|/doc/line/a|/doc/line/b|/doc/line/c',
 242               'true')
 243     AS t(id int, line_num varchar(10), val1 int, val2 int, val3 int),
 244   xpath_table('id', 'xml', 'test', '/doc/@num', 'true')
 245     AS i(id int, doc_num varchar(10))
 246 WHERE i.id=t.id AND i.id=1
 247 ORDER BY doc_num, line_num;
 248
 249  id | line_num | val1 | val2 | val3 | doc_num
 250 ----+----------+------+------+------+---------
 251   1 | L1       |    1 |    2 |    3 | C1
 252   1 | L2       |   11 |   22 |   33 | C1
 253 (2 rows)
 254 </pre><p>
 255    </p></div></div><div class="sect2" id="XML2-XSLT"><div class="titlepage"><div><div><h3 class="title">F.50.4. XSLT Functions <a href="#XML2-XSLT" class="id_link">#</a></h3></div></div></div><p>
 256    The following functions are available if libxslt is installed:
 257   </p><div class="sect3" id="XML2-XSLT-XSLT-PROCESS"><div class="titlepage"><div><div><h4 class="title">F.50.4.1. <code class="literal">xslt_process</code> <a href="#XML2-XSLT-XSLT-PROCESS" class="id_link">#</a></h4></div></div></div><a id="id-1.11.7.60.7.3.2" class="indexterm"></a><pre class="synopsis">
 258 xslt_process(text document, text stylesheet, text paramlist) returns text
 259 </pre><p>
 260     This function applies the XSL stylesheet to the document and returns
 261     the transformed result. The <code class="literal">paramlist</code> is a list of parameter
 262     assignments to be used in the transformation, specified in the form
 263     <code class="literal">a=1,b=2</code>. Note that the
 264     parameter parsing is very simple-minded: parameter values cannot
 265     contain commas!
 266    </p><p>
 267     There is also a two-parameter version of <code class="function">xslt_process</code> which
 268     does not pass any parameters to the transformation.
 269    </p></div></div><div class="sect2" id="XML2-AUTHOR"><div class="titlepage"><div><div><h3 class="title">F.50.5. Author <a href="#XML2-AUTHOR" class="id_link">#</a></h3></div></div></div><p>
 270    John Gray <code class="email">&lt;<a class="email" href="mailto:jgray@azuli.co.uk">jgray@azuli.co.uk</a>&gt;</code>
 271   </p><p>
 272    Development of this module was sponsored by Torchbox Ltd. (www.torchbox.com).
 273    It has the same BSD license as PostgreSQL.
 274   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="uuid-ossp.html" title="F.49. uuid-ossp — a UUID generator">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="contrib.html" title="Appendix F. Additional Supplied Modules and Extensions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contrib-prog.html" title="Appendix G. Additional Supplied Programs">Next</a></td></tr><tr><td width="40%" align="left" valign="top">F.49. uuid-ossp — a UUID generator </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"> Appendix G. Additional Supplied Programs</td></tr></table></div></body></html>