head	1.12;
access;
symbols
	REL9_0_0:1.7.14.5
	REL9_1_ALPHA1:1.11
	REL9_0_RC1:1.7.14.4
	REL9_0_BETA4:1.7.14.2
	REL9_0_STABLE:1.7.0.14
	REL9_0_BETA3:1.7
	REL9_0_BETA2:1.7
	REL8_3_11:1.4.2.1
	REL8_4_4:1.7
	REL9_0_BETA1:1.7
	REL9_0_ALPHA5_BRANCH:1.7.0.12
	REL9_0_ALPHA5:1.7
	REL8_3_10:1.4.2.1
	REL8_4_3:1.7
	REL9_0_ALPHA4:1.7
	REL9_0_ALPHA4_BRANCH:1.7.0.10
	REL8_5_ALPHA3:1.7
	REL8_5_ALPHA3_BRANCH:1.7.0.8
	REL8_3_9:1.4.2.1
	REL8_4_2:1.7
	REL8_5_ALPHA2:1.7
	REL8_5_ALPHA2_BRANCH:1.7.0.6
	REL8_3_8:1.4.2.1
	REL8_4_1:1.7
	REL8_5_ALPHA1:1.7
	REL8_5_ALPHA1_BRANCH:1.7.0.4
	REL8_4_STABLE:1.7.0.2
	REL8_4_0:1.7
	REL8_4_RC2:1.7
	REL8_4_RC1:1.7
	REL8_4_BETA2:1.6
	REL8_4_BETA1:1.5
	REL8_3_7:1.4.2.1
	REL8_3_6:1.4.2.1
	REL8_3_5:1.4.2.1
	REL8_3_4:1.4.2.1
	REL8_3_3:1.4.2.1
	REL8_3_2:1.4.2.1
	REL8_3_1:1.4
	REL8_3_STABLE:1.4.0.2
	REL8_3_0:1.4
	REL8_3_RC2:1.4
	REL8_3_RC1:1.4
	REL8_3_BETA4:1.2
	REL8_3_BETA3:1.2;
locks; strict;
comment	@# @;


1.12
date	2010.09.09.00.48.22;	author momjian;	state Exp;
branches;
next	1.11;

1.11
date	2010.08.17.04.37.21;	author petere;	state Exp;
branches;
next	1.10;

1.10
date	2010.08.10.20.42.01;	author petere;	state Exp;
branches;
next	1.9;

1.9
date	2010.07.29.19.34.40;	author petere;	state Exp;
branches;
next	1.8;

1.8
date	2010.07.27.19.01.16;	author petere;	state Exp;
branches;
next	1.7;

1.7
date	2009.05.18.11.08.24;	author petere;	state Exp;
branches
	1.7.2.1
	1.7.14.1;
next	1.6;

1.6
date	2009.04.27.16.27.36;	author momjian;	state Exp;
branches;
next	1.5;

1.5
date	2008.05.08.16.49.37;	author tgl;	state Exp;
branches;
next	1.4;

1.4
date	2007.12.06.04.12.10;	author tgl;	state Exp;
branches
	1.4.2.1;
next	1.3;

1.3
date	2007.12.03.23.49.51;	author tgl;	state Exp;
branches;
next	1.2;

1.2
date	2007.11.11.14.23.18;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	2007.11.10.23.30.46;	author momjian;	state Exp;
branches;
next	;

1.4.2.1
date	2008.05.08.16.49.48;	author tgl;	state Exp;
branches;
next	1.4.2.2;

1.4.2.2
date	2010.07.27.18.55.44;	author petere;	state Exp;
branches;
next	;

1.7.2.1
date	2010.07.27.18.56.22;	author petere;	state Exp;
branches;
next	;

1.7.14.1
date	2010.07.27.19.01.04;	author petere;	state Exp;
branches;
next	1.7.14.2;

1.7.14.2
date	2010.07.29.19.34.37;	author petere;	state Exp;
branches;
next	1.7.14.3;

1.7.14.3
date	2010.08.10.20.42.02;	author petere;	state Exp;
branches;
next	1.7.14.4;

1.7.14.4
date	2010.08.17.04.37.19;	author petere;	state Exp;
branches;
next	1.7.14.5;

1.7.14.5
date	2010.09.09.00.48.29;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.12
log
@Doc fixes:

- remove excessive table cells
- moving function parameters into function tags rather than having
  them being considered separate
- add return type column on XML2 contrib module functions list and
  removing return types from function
- add table header to XML2 contrib parameter table

Thom Brown

Backpatch to 9.0.X.
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.11 2010/08/17 04:37:21 petere Exp $ -->

<sect1 id="xml2">
 <title>xml2</title>

 <indexterm zone="xml2">
  <primary>xml2</primary>
 </indexterm>

 <para>
  The <filename>xml2</> module provides XPath querying and
  XSLT functionality.
 </para>

 <sect2>
  <title>Deprecation notice</title>

  <para>
   From <productname>PostgreSQL</> 8.3 on, there is XML-related
   functionality based on the SQL/XML standard in the core server.
   That functionality covers XML syntax checking and XPath queries,
   which is what this module does, and more, but the API is
   not at all compatible.  It is planned that this module will be
   removed in PostgreSQL 8.4 in favor of the newer standard API, so
   you are encouraged to try converting your applications.  If you
   find that some of the functionality of this module is not
   available in an adequate form with the newer API, please explain
   your issue to pgsql-hackers@@postgresql.org so that the deficiency
   can be addressed.
  </para>
 </sect2>

 <sect2>
  <title>Description of functions</title>

  <para>
   <xref linkend="xml2-functions-table"> shows the functions provided by this module.
   These functions provide straightforward XML parsing and XPath queries.
   All arguments are of type <type>text</>, so for brevity that is not shown.
  </para>

  <table id="xml2-functions-table">
   <title>Functions</title>
   <tgroup cols="3">
   <thead>
     <row>
      <entry>Function</entry>
      <entry>Returns</entry>
      <entry>Description</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>
       <function>
        xml_is_well_formed(document)
       </function>
      </entry>
      <entry>
       <type>bool</type>
      </entry>
      <entry>
       <para>
        This parses the document text in its parameter and returns true if the
        document is well-formed XML.  (Note: before PostgreSQL 8.2, this
        function was called <function>xml_valid()</>.  That is the wrong name
        since validity and well-formedness have different meanings in XML.
        The old name is still available, but is deprecated.)
       </para>
      </entry>
     </row>
     <row>
      <entry>
        <function>
         xpath_string(document, query)
        </function>
      </entry>
      <entry>
       <type>text</type>
      </entry>
      <entry morerows="2">
       <para>
        These functions evaluate the XPath query on the supplied document, and
        cast the result to the specified type.
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <function>
        xpath_number(document, query)
       </function>
      </entry>
      <entry>
       <type>float4</type>
      </entry>
     </row>
     <row>
      <entry>
       <function>
        xpath_bool(document, query)
       </function>
      </entry>
      <entry>
       <type>bool</type>
      </entry>
     </row>
     <row>
      <entry>
        <function>
         xpath_nodeset(document, query, toptag, itemtag)
        </function>
      </entry>
      <entry>
       <type>text</type>
      </entry>
      <entry>
       <para>
       This evaluates query on document and wraps the result in XML tags. If
       the result is multivalued, the output will look like:
<synopsis>
&lt;toptag&gt;
&lt;itemtag&gt;Value 1 which could be an XML fragment&lt;/itemtag&gt;
&lt;itemtag&gt;Value 2....&lt;/itemtag&gt;
&lt;/toptag&gt;
</synopsis>
        If either <literal>toptag</> or <literal>itemtag</> is an empty string, the relevant tag is omitted.
       </para>
      </entry>
     </row>
     <row>
      <entry>
        <function>
         xpath_nodeset(document, query)
        </function>
      </entry>
      <entry>
       <type>text</type>
      </entry>
      <entry>
       <para>
        Like <function>xpath_nodeset(document, query, toptag, itemtag)</> but result omits both tags.
       </para>
      </entry>
     </row>
     <row>
      <entry>
        <function>
         xpath_nodeset(document, query, itemtag)
        </function>
      </entry>
      <entry>
       <type>text</type>
      </entry>
      <entry>
       <para>
        Like <function>xpath_nodeset(document, query, toptag, itemtag)</> but result omits toptag.
       </para>
      </entry>
     </row>
     <row>
      <entry>
        <function>
         xpath_list(document, query, separator)
        </function>
      </entry>
      <entry>
       <type>text</type>
      </entry>
      <entry>
       <para>
        This function returns multiple values separated by the specified
        separator, for example <literal>Value 1,Value 2,Value 3</> if
        separator is <literal>,</>.
       </para>
      </entry>
     </row>
     <row>
      <entry>
        <function>
         xpath_list(document, query)
        </function>
      </entry>
      <entry>
       <type>text</type>
      </entry>
      <entry>
       This is a wrapper for the above function that uses <literal>,</>
       as the separator.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>
 </sect2>

 <sect2>
  <title><literal>xpath_table</literal></title>

<synopsis>
xpath_table(text key, text document, text relation, text xpaths, text criteria) returns setof record
</synopsis>

  <para>
   <function>xpath_table</> is a table function that evaluates a set of XPath
   queries on each of a set of documents and returns the results as a
   table. The primary key field from the original document table is returned
   as the first column of the result so that the result set
   can readily be used in joins.  The parameters are described in
   <xref linkend="xml2-xpath-table-parameters">.
  </para>

  <table id="xml2-xpath-table-parameters">
   <title><function>xpath_table</function> Parameters</title>
   <tgroup cols="2">
     <thead>
     <row>
      <entry>Parameter</entry>
      <entry>Description</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><parameter>key</parameter></entry>
      <entry>
       <para>
        the name of the <quote>key</> field &mdash; this is just a field to be used as
        the first column of the output table, i.e., it identifies the record from
        which each output row came (see note below about multiple values)
       </para>
      </entry>
     </row>
     <row>
      <entry><parameter>document</parameter></entry>
      <entry>
       <para>
        the name of the field containing the XML document
       </para>
      </entry>
     </row>
     <row>
      <entry><parameter>relation</parameter></entry>
      <entry>
       <para>
        the name of the table or view containing the documents
       </para>
      </entry>
     </row>
     <row>
      <entry><parameter>xpaths</parameter></entry>
      <entry>
       <para>
        one or more XPath expressions, separated by <literal>|</literal>
       </para>
      </entry>
     </row>
     <row>
      <entry><parameter>criteria</parameter></entry>
      <entry>
       <para>
        the contents of the WHERE clause. This cannot be omitted, so use
        <literal>true</literal> or <literal>1=1</literal> if you want to
        process all the rows in the relation
       </para>
      </entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  <para>
   These parameters (except the XPath strings) are just substituted
   into a plain SQL SELECT statement, so you have some flexibility &mdash; the
   statement is
  </para>

  <para>
   <literal>
    SELECT &lt;key&gt;, &lt;document&gt; FROM &lt;relation&gt; WHERE &lt;criteria&gt;
   </literal>
  </para>

  <para>
   so those parameters can be <emphasis>anything</> valid in those particular
   locations. The result from this SELECT needs to return exactly two
   columns (which it will unless you try to list multiple fields for key
   or document). Beware that this simplistic approach requires that you
   validate any user-supplied values to avoid SQL injection attacks.
  </para>

  <para>
   The function has to be used in a <literal>FROM</> expression, with an
   <literal>AS</> clause to specify the output columns; for example
<programlisting>
SELECT * FROM
xpath_table('article_id',
            'article_xml',
            'articles',
            '/article/author|/article/pages|/article/title',
            'date_entered > ''2003-01-01'' ')
AS t(article_id integer, author text, page_count integer, title text);
</programlisting>
   The <literal>AS</> clause defines the names and types of the columns in the
   output table.  The first is the <quote>key</> field and the rest correspond
   to the XPath queries.
   If there are more XPath queries than result columns,
   the extra queries will be ignored. If there are more result columns
   than XPath queries, the extra columns will be NULL.
  </para>

  <para>
   Notice that this example defines the <structname>page_count</> result
   column as an integer.  The function deals internally with string
   representations, so when you say you want an integer in the output, it will
   take the string representation of the XPath result and use PostgreSQL input
   functions to transform it into an integer (or whatever type the <type>AS</>
   clause requests). An error will result if it can't do this &mdash; for
   example if the result is empty &mdash; so you may wish to just stick to
   <type>text</> as the column type if you think your data has any problems.
  </para>

  <para>
   The calling <command>SELECT</> statement doesn't necessarily have be
   be just <literal>SELECT *</> &mdash; it can reference the output
   columns by name or join them to other tables. The function produces a
   virtual table with which you can perform any operation you wish (e.g.
   aggregation, joining, sorting etc). So we could also have:
<programlisting>
SELECT t.title, p.fullname, p.email
FROM xpath_table('article_id', 'article_xml', 'articles',
                 '/article/title|/article/author/@@id',
                 'xpath_string(article_xml,''/article/@@date'') > ''2003-03-20'' ')
       AS t(article_id integer, title text, author_id integer),
     tblPeopleInfo AS p
WHERE t.author_id = p.person_id;
</programlisting>
   as a more complicated example. Of course, you could wrap all
   of this in a view for convenience.
  </para>

  <sect3>
   <title>Multivalued results</title>

   <para>
    The <function>xpath_table</> function assumes that the results of each XPath query
    might be multi-valued, so the number of rows returned by the function
    may not be the same as the number of input documents. The first row
    returned contains the first result from each query, the second row the
    second result from each query. If one of the queries has fewer values
    than the others, null values will be returned instead.
   </para>

   <para>
    In some cases, a user will know that a given XPath query will return
    only a single result (perhaps a unique document identifier) &mdash; if used
    alongside an XPath query returning multiple results, the single-valued
    result will appear only on the first row of the result. The solution
    to this is to use the key field as part of a join against a simpler
    XPath query. As an example:

<programlisting>
CREATE TABLE test (
    id int PRIMARY KEY,
    xml text
);

INSERT INTO test VALUES (1, '&lt;doc num="C1"&gt;
&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;
&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;
&lt;/doc&gt;');

INSERT INTO test VALUES (2, '&lt;doc num="C2"&gt;
&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;
&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;
&lt;/doc&gt;');

SELECT * FROM
  xpath_table('id','xml','test',
              '/doc/@@num|/doc/line/@@num|/doc/line/a|/doc/line/b|/doc/line/c',
              'true')
  AS t(id int, doc_num varchar(10), line_num varchar(10), val1 int, val2 int, val3 int)
WHERE id = 1 ORDER BY doc_num, line_num

 id | doc_num | line_num | val1 | val2 | val3
----+---------+----------+------+------+------
  1 | C1      | L1       |    1 |    2 |    3
  1 |         | L2       |   11 |   22 |   33
</programlisting>
   </para>

   <para>
    To get <literal>doc_num</> on every line, the solution is to use two invocations
    of <function>xpath_table</> and join the results:

<programlisting>
SELECT t.*,i.doc_num FROM
  xpath_table('id', 'xml', 'test',
              '/doc/line/@@num|/doc/line/a|/doc/line/b|/doc/line/c',
              'true')
    AS t(id int, line_num varchar(10), val1 int, val2 int, val3 int),
  xpath_table('id', 'xml', 'test', '/doc/@@num', 'true')
    AS i(id int, doc_num varchar(10))
WHERE i.id=t.id AND i.id=1
ORDER BY doc_num, line_num;

 id | line_num | val1 | val2 | val3 | doc_num
----+----------+------+------+------+---------
  1 | L1       |    1 |    2 |    3 | C1
  1 | L2       |   11 |   22 |   33 | C1
(2 rows)
</programlisting>
   </para>
  </sect3>
 </sect2>

 <sect2>
  <title>XSLT functions</title>

  <para>
   The following functions are available if libxslt is installed:
  </para>

  <sect3>
   <title><literal>xslt_process</literal></title>

<synopsis>
xslt_process(text document, text stylesheet, text paramlist) returns text
</synopsis>

   <para>
    This function applies the XSL stylesheet to the document and returns
    the transformed result. The <literal>paramlist</> is a list of parameter
    assignments to be used in the transformation, specified in the form
    <literal>a=1,b=2</>. Note that the
    parameter parsing is very simple-minded: parameter values cannot
    contain commas!
   </para>

   <para>
    Also note that if either the document or stylesheet values do not
    begin with a &lt; then they will be treated as URLs and libxslt will
    fetch them. It follows that you can use <function>xslt_process</> as a
    means to fetch the contents of URLs &mdash; you should be aware of the
    security implications of this.
   </para>

   <para>
    There is also a two-parameter version of <function>xslt_process</> which
    does not pass any parameters to the transformation.
   </para>
  </sect3>
 </sect2>

 <sect2>
  <title>Author</title>

  <para>
   John Gray <email>jgray@@azuli.co.uk</email>
  </para>

  <para>
   Development of this module was sponsored by Torchbox Ltd. (www.torchbox.com).
   It has the same BSD licence as PostgreSQL.
  </para>
 </sect2>

</sect1>
@


1.11
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.10 2010/08/10 20:42:01 petere Exp $ -->
d44 8
a51 1
   <tgroup cols="2">
d55 6
a60 3
<synopsis>
xml_is_well_formed(document) returns bool
</synopsis>
d74 3
a76 5
<synopsis>
xpath_string(document, query) returns text
xpath_number(document, query) returns float4
xpath_bool(document, query) returns bool
</synopsis>
d79 3
d90 26
a115 3
<synopsis>
xpath_nodeset(document, query, toptag, itemtag) returns text
</synopsis>
d133 6
a138 3
<synopsis>
xpath_nodeset(document, query) returns text
</synopsis>
d148 6
a153 3
<synopsis>
xpath_nodeset(document, query, itemtag) returns text
</synopsis>
d163 6
a168 3
<synopsis>
xpath_list(document, query, separator) returns text
</synopsis>
d180 6
a185 3
<synopsis>
xpath_list(document, query) returns text
</synopsis>
d216 6
@


1.10
log
@Add some links to tables
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.9 2010/07/29 19:34:40 petere Exp $ -->
d93 1
a93 1
        If either toptag or itemtag is an empty string, the relevant tag is omitted.
d105 1
a105 1
        Like xpath_nodeset(document,query,toptag,itemtag) but result omits both tags.
d117 1
a117 1
        Like xpath_nodeset(document,query,toptag,itemtag) but result omits toptag.
d298 1
a298 1
    than the others, NULLs will be returned instead.
d340 2
a341 2
    To get doc_num on every line, the solution is to use two invocations
    of xpath_table and join the results:
d380 1
a380 1
    the transformed result. The paramlist is a list of parameter
@


1.9
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.8 2010/07/27 19:01:16 petere Exp $ -->
d163 2
a164 1
   can readily be used in joins.
d167 2
a168 2
  <table>
   <title>Parameters</title>
@


1.8
log
@Spelling fixes
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.7 2009/05/18 11:08:24 petere Exp $ -->
d48 3
a50 3
       <synopsis>
        xml_is_well_formed(document) returns bool
       </synopsis>
d64 5
a68 5
       <synopsis>
        xpath_string(document,query) returns text
        xpath_number(document,query) returns float4
        xpath_bool(document,query) returns bool
       </synopsis>
d79 3
a81 3
       <synopsis>
        xpath_nodeset(document,query,toptag,itemtag) returns text
       </synopsis>
d87 6
a92 8
       </para>
       <literal>
        &lt;toptag&gt;
        &lt;itemtag&gt;Value 1 which could be an XML fragment&lt;/itemtag&gt;
        &lt;itemtag&gt;Value 2....&lt;/itemtag&gt;
        &lt;/toptag&gt;
       </literal>
       <para>
d99 3
a101 3
       <synopsis>
        xpath_nodeset(document,query) returns text
       </synopsis>
d111 3
a113 3
       <synopsis>
        xpath_nodeset(document,query,itemtag) returns text
       </synopsis>
d123 3
a125 3
       <synopsis>
        xpath_list(document,query,separator) returns text
       </synopsis>
d137 3
a139 3
       <synopsis>
        xpath_list(document,query) returns text
       </synopsis>
d154 3
a156 3
  <synopsis>
   xpath_table(text key, text document, text relation, text xpaths, text criteria) returns setof record
  </synopsis>
d241 1
a241 3
  </para>

  <programlisting>
d249 1
a249 3
  </programlisting>

  <para>
d275 1
a275 3
  </para>

  <programlisting>
d283 1
a283 3
  </programlisting>

  <para>
d307 29
a337 30
   <programlisting>
    CREATE TABLE test (
        id int4 NOT NULL,
        xml text,
        CONSTRAINT pk PRIMARY KEY (id)
    );

    INSERT INTO test VALUES (1, '&lt;doc num="C1"&gt;
    &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;
    &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;
    &lt;/doc&gt;');

    INSERT INTO test VALUES (2, '&lt;doc num="C2"&gt;
    &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;
    &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;
    &lt;/doc&gt;');

    SELECT * FROM
      xpath_table('id','xml','test',
                  '/doc/@@num|/doc/line/@@num|/doc/line/a|/doc/line/b|/doc/line/c',
                  'true')
      AS t(id int4, doc_num varchar(10), line_num varchar(10), val1 int4, val2 int4, val3 int4)
    WHERE id = 1 ORDER BY doc_num, line_num

     id | doc_num | line_num | val1 | val2 | val3
    ----+---------+----------+------+------+------
      1 | C1      | L1       |    1 |    2 |    3
      1 |         | L2       |   11 |   22 |   33
   </programlisting>

d341 18
a359 18

   <programlisting>
   SELECT t.*,i.doc_num FROM
     xpath_table('id', 'xml', 'test',
                 '/doc/line/@@num|/doc/line/a|/doc/line/b|/doc/line/c',
                 'true')
       AS t(id int4, line_num varchar(10), val1 int4, val2 int4, val3 int4),
     xpath_table('id', 'xml', 'test', '/doc/@@num', 'true')
       AS i(id int4, doc_num varchar(10))
   WHERE i.id=t.id AND i.id=1
   ORDER BY doc_num, line_num;

    id | line_num | val1 | val2 | val3 | doc_num
   ----+----------+------+------+------+---------
     1 | L1       |    1 |    2 |    3 | C1
     1 | L2       |   11 |   22 |   33 | C1
   (2 rows)
   </programlisting>
d373 3
a375 3
   <synopsis>
    xslt_process(text document, text stylesheet, text paramlist) returns text
   </synopsis>
@


1.7
log
@Refer to tables by id, not by "the following table", because tables are in
theory floating elements.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.6 2009/04/27 16:27:36 momjian Exp $ -->
d389 1
a389 1
    This function appplies the XSL stylesheet to the document and returns
@


1.7.14.1
log
@Spelling fixes
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.7 2009/05/18 11:08:24 petere Exp $ -->
d389 1
a389 1
    This function applies the XSL stylesheet to the document and returns
@


1.7.14.2
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.7.14.1 2010/07/27 19:01:04 petere Exp $ -->
d48 3
a50 3
<synopsis>
xml_is_well_formed(document) returns bool
</synopsis>
d64 5
a68 5
<synopsis>
xpath_string(document, query) returns text
xpath_number(document, query) returns float4
xpath_bool(document, query) returns bool
</synopsis>
d79 3
a81 3
<synopsis>
xpath_nodeset(document, query, toptag, itemtag) returns text
</synopsis>
d87 8
a94 6
<synopsis>
&lt;toptag&gt;
&lt;itemtag&gt;Value 1 which could be an XML fragment&lt;/itemtag&gt;
&lt;itemtag&gt;Value 2....&lt;/itemtag&gt;
&lt;/toptag&gt;
</synopsis>
d101 3
a103 3
<synopsis>
xpath_nodeset(document, query) returns text
</synopsis>
d113 3
a115 3
<synopsis>
xpath_nodeset(document, query, itemtag) returns text
</synopsis>
d125 3
a127 3
<synopsis>
xpath_list(document, query, separator) returns text
</synopsis>
d139 3
a141 3
<synopsis>
xpath_list(document, query) returns text
</synopsis>
d156 3
a158 3
<synopsis>
xpath_table(text key, text document, text relation, text xpaths, text criteria) returns setof record
</synopsis>
d243 3
a245 1
<programlisting>
d253 3
a255 1
</programlisting>
d281 3
a283 1
<programlisting>
d291 3
a293 1
</programlisting>
d317 1
d319 29
a347 29
<programlisting>
CREATE TABLE test (
    id int PRIMARY KEY,
    xml text
);

INSERT INTO test VALUES (1, '&lt;doc num="C1"&gt;
&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;
&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;
&lt;/doc&gt;');

INSERT INTO test VALUES (2, '&lt;doc num="C2"&gt;
&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;
&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;
&lt;/doc&gt;');

SELECT * FROM
  xpath_table('id','xml','test',
              '/doc/@@num|/doc/line/@@num|/doc/line/a|/doc/line/b|/doc/line/c',
              'true')
  AS t(id int, doc_num varchar(10), line_num varchar(10), val1 int, val2 int, val3 int)
WHERE id = 1 ORDER BY doc_num, line_num

 id | doc_num | line_num | val1 | val2 | val3
----+---------+----------+------+------+------
  1 | C1      | L1       |    1 |    2 |    3
  1 |         | L2       |   11 |   22 |   33
</programlisting>
   </para>
d352 1
d354 17
a370 18
<programlisting>
SELECT t.*,i.doc_num FROM
  xpath_table('id', 'xml', 'test',
              '/doc/line/@@num|/doc/line/a|/doc/line/b|/doc/line/c',
              'true')
    AS t(id int, line_num varchar(10), val1 int, val2 int, val3 int),
  xpath_table('id', 'xml', 'test', '/doc/@@num', 'true')
    AS i(id int, doc_num varchar(10))
WHERE i.id=t.id AND i.id=1
ORDER BY doc_num, line_num;

 id | line_num | val1 | val2 | val3 | doc_num
----+----------+------+------+------+---------
  1 | L1       |    1 |    2 |    3 | C1
  1 | L2       |   11 |   22 |   33 | C1
(2 rows)
</programlisting>
   </para>
d384 3
a386 3
<synopsis>
xslt_process(text document, text stylesheet, text paramlist) returns text
</synopsis>
@


1.7.14.3
log
@Add some links to tables
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.7.14.2 2010/07/29 19:34:37 petere Exp $ -->
d163 1
a163 2
   can readily be used in joins.  The parameters are described in
   <xref linkend="xml2-xpath-table-parameters">.
d166 2
a167 2
  <table id="xml2-xpath-table-parameters">
   <title><function>xpath_table</function> Parameters</title>
@


1.7.14.4
log
@Spell and markup checking
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.7.14.3 2010/08/10 20:42:02 petere Exp $ -->
d93 1
a93 1
        If either <literal>toptag</> or <literal>itemtag</> is an empty string, the relevant tag is omitted.
d105 1
a105 1
        Like <function>xpath_nodeset(document, query, toptag, itemtag)</> but result omits both tags.
d117 1
a117 1
        Like <function>xpath_nodeset(document, query, toptag, itemtag)</> but result omits toptag.
d298 1
a298 1
    than the others, null values will be returned instead.
d340 2
a341 2
    To get <literal>doc_num</> on every line, the solution is to use two invocations
    of <function>xpath_table</> and join the results:
d380 1
a380 1
    the transformed result. The <literal>paramlist</> is a list of parameter
@


1.7.14.5
log
@Doc fixes:

- remove excessive table cells
- moving function parameters into function tags rather than having
  them being considered separate
- add return type column on XML2 contrib module functions list and
  removing return types from function
- add table header to XML2 contrib parameter table

Thom Brown

Backpatch to 9.0.X.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.7.14.4 2010/08/17 04:37:19 petere Exp $ -->
d44 1
a44 8
   <tgroup cols="3">
   <thead>
     <row>
      <entry>Function</entry>
      <entry>Returns</entry>
      <entry>Description</entry>
     </row>
    </thead>
d48 3
a50 6
       <function>
        xml_is_well_formed(document)
       </function>
      </entry>
      <entry>
       <type>bool</type>
d64 5
a68 3
        <function>
         xpath_string(document, query)
        </function>
a70 3
       <type>text</type>
      </entry>
      <entry morerows="2">
d79 3
a81 26
       <function>
        xpath_number(document, query)
       </function>
      </entry>
      <entry>
       <type>float4</type>
      </entry>
     </row>
     <row>
      <entry>
       <function>
        xpath_bool(document, query)
       </function>
      </entry>
      <entry>
       <type>bool</type>
      </entry>
     </row>
     <row>
      <entry>
        <function>
         xpath_nodeset(document, query, toptag, itemtag)
        </function>
      </entry>
      <entry>
       <type>text</type>
d99 3
a101 6
        <function>
         xpath_nodeset(document, query)
        </function>
      </entry>
      <entry>
       <type>text</type>
d111 3
a113 6
        <function>
         xpath_nodeset(document, query, itemtag)
        </function>
      </entry>
      <entry>
       <type>text</type>
d123 3
a125 6
        <function>
         xpath_list(document, query, separator)
        </function>
      </entry>
      <entry>
       <type>text</type>
d137 3
a139 6
        <function>
         xpath_list(document, query)
        </function>
      </entry>
      <entry>
       <type>text</type>
a169 6
     <thead>
     <row>
      <entry>Parameter</entry>
      <entry>Description</entry>
     </row>
    </thead>
@


1.7.2.1
log
@Spelling fixes
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.7 2009/05/18 11:08:24 petere Exp $ -->
d389 1
a389 1
    This function applies the XSL stylesheet to the document and returns
@


1.6
log
@Proofreading adjustments for first two parts of documentation (Tutorial
and SQL).
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.5 2008/05/08 16:49:37 tgl Exp $ -->
d37 1
d42 1
a42 1
  <table>
@


1.5
log
@Fix contrib/xml2 makefile to not override CFLAGS, and in passing make it
auto-configure properly for libxslt present or not.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.4 2007/12/06 04:12:10 tgl Exp $ -->
d176 1
a176 1
        the first column of the output table, i.e. it identifies the record from
@


1.4
log
@Make an editorial pass over the newly SGML-ified contrib documentation.
Fix lots of bad markup, bad English, bad explanations.

This commit covers only about half the contrib modules, but I grow weary...
@
text
@d1 1
a1 1
<!-- $PostgreSQL$ -->
d377 1
a377 3
   The following functions are available if libxslt is installed (this is
   not currently detected automatically, so you will have to amend the
   Makefile):
@


1.4.2.1
log
@Fix contrib/xml2 makefile to not override CFLAGS, and in passing make it
auto-configure properly for libxslt present or not.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.4 2007/12/06 04:12:10 tgl Exp $ -->
d377 3
a379 1
   The following functions are available if libxslt is installed:
@


1.4.2.2
log
@Spelling fix
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/xml2.sgml,v 1.4.2.1 2008/05/08 16:49:48 tgl Exp $ -->
d388 1
a388 1
    This function applies the XSL stylesheet to the document and returns
@


1.3
log
@Entity-ify a passel of & < > characters.  Per gripe from Devrim.
@
text
@d1 2
d4 2
a5 2
 <title>xml2: XML-handling functions</title>
 
d10 5
d17 1
d19 11
a29 11
    From PostgreSQL 8.3 on, there is XML-related
    functionality based on the SQL/XML standard in the core server.
    That functionality covers XML syntax checking and XPath queries,
    which is what this module does as well, and more, but the API is
    not at all compatible.  It is planned that this module will be
    removed in PostgreSQL 8.4 in favor of the newer standard API, so
    you are encouraged to try converting your applications.  If you
    find that some of the functionality of this module is not
    available in an adequate form with the newer API, please explain
    your issue to pgsql-hackers@@postgresql.org so that the deficiency
    can be addressed.
d32 1
a32 1
  
d35 1
d37 2
a38 1
   The first set of functions are straightforward XML parsing and XPath queries:
d47 3
a49 3
       <programlisting>
        xml_is_well_formed(document) RETURNS bool
       </programlisting>
d54 4
a57 4
        document is well-formed XML.  (Note: before PostgreSQL 8.2, this function
        was called xml_valid().  That is the wrong name since validity and
        well-formedness have different meanings in XML.  The old name is still
        available, but is deprecated and will be removed in 8.3.)
d63 5
a67 5
       <programlisting>
        xpath_string(document,query) RETURNS text
        xpath_number(document,query) RETURNS float4
        xpath_bool(document,query) RETURNS bool
       </programlisting>
d78 3
a80 3
       <programlisting>
        xpath_nodeset(document,query,toptag,itemtag) RETURNS text
       </programlisting>
d88 4
a91 4
        &lt;toptag>
        &lt;itemtag>Value 1 which could be an XML fragment&lt;/itemtag>
        &lt;itemtag>Value 2....&lt;/itemtag>
        &lt;/toptag>
d100 3
a102 3
       <programlisting>
        xpath_nodeset(document,query) RETURNS
       </programlisting>
d106 1
a106 1
        Like xpath_nodeset(document,query,toptag,itemtag) but text omits both tags.
d112 3
a114 3
       <programlisting>
        xpath_nodeset(document,query,itemtag) RETURNS
       </programlisting>
d118 1
a118 1
        Like xpath_nodeset(document,query,toptag,itemtag) but text omits toptag.
d124 3
a126 3
       <programlisting>
        xpath_list(document,query,seperator) RETURNS text
       </programlisting>
d130 3
a132 2
        This function returns multiple values seperated by the specified
        seperator, e.g. Value 1,Value 2,Value 3 if seperator=','.
d138 3
a140 3
       <programlisting>
        xpath_list(document,query) RETURNS text
       </programlisting>
d143 2
a144 1
       This is a wrapper for the above function that uses ',' as the seperator.
a151 1

d154 5
d160 5
a164 5
   This is a table function which evaluates a set of XPath queries on
   each of a set of documents and returns the results as a table. The
   primary key field from the original document table is returned as the
   first column of the result so that the resultset from xpath_table can
   be readily used in joins.
d166 1
a166 6
  <para>
   The function itself takes 5 arguments, all text.
  </para>
  <programlisting>
   xpath_table(key,document,relation,xpaths,criteria)
  </programlisting>
d172 1
a172 1
      <entry><literal>key</literal></entry>
d175 3
a177 3
        the name of the "key" field - this is just a field to be used as
        the first column of the output table i.e. it identifies the record from
        which each output row came (see note below about multiple values).
d182 1
a182 1
      <entry><literal>document</literal></entry>
d190 1
a190 1
      <entry><literal>relation</literal></entry>
d198 1
a198 1
      <entry><literal>xpaths</literal></entry>
d201 1
a201 1
        multiple xpath expressions separated by <literal>|</literal>
d206 1
a206 1
      <entry><literal>criteria</literal></entry>
d209 3
a211 3
        The contents of the where clause. This needs to be specified,
        so use "true" or "1=1" here if you want to process all the rows in the
        relation.
d220 2
a221 2
   NB These parameters (except the XPath strings) are just substituted
   into a plain SQL SELECT statement, so you have some flexibility - the
d227 1
a227 1
   SELECT &lt;key>,&lt;document> FROM &lt;relation> WHERE &lt;criteria>
d232 1
a232 1
   so those parameters can be *anything* valid in those particular
d238 1
a238 1
 
d240 2
a241 1
   Using the function
d243 1
a243 6
 
  <para>
   The function has to be used in a FROM expression. This gives the following
   form:
  </para>
 
d246 5
a250 5
xpath_table('article_id', 
        'article_xml',
        'articles', 
        '/article/author|/article/pages|/article/title',
        'date_entered > ''2003-01-01'' ') 
d255 4
a258 2
   The AS clause defines the names and types of the columns in the
   virtual table. If there are more XPath queries than result columns,
d264 8
a271 8
   Note that I've said in this example that pages is an integer.  The
   function deals internally with string representations, so when you say
   you want an integer in the output, it will take the string
   representation of the XPath result and use PostgreSQL input functions
   to transform it into an integer (or whatever type the AS clause
   requests). An error will result if it can't do this - for example if
   the result is empty - so you may wish to just stick to 'text' as the
   column type if you think your data has any problems.
d273 1
d275 2
a276 1
   The select statement doesn't need to use * alone - it can reference the
d283 6
a288 6
SELECT t.title, p.fullname, p.email 
FROM xpath_table('article_id','article_xml','articles',
            '/article/title|/article/author/@@id',
            'xpath_string(article_xml,''/article/@@date'') > ''2003-03-20'' ')
            AS t(article_id integer, title text, author_id integer), 
     tblPeopleInfo AS p 
d296 1
d299 1
d301 1
a301 1
    The xpath_table function assumes that the results of each XPath query
d308 1
d311 1
a311 1
    only a single result (perhaps a unique document identifier) - if used
d317 1
a317 27
   
   <para>
    <literal>
    CREATE TABLE test
    (
      id int4 NOT NULL,
      xml text,
      CONSTRAINT pk PRIMARY KEY (id)
    ) 
    WITHOUT OIDS;
    
    INSERT INTO test VALUES (1, '&lt;doc num="C1">
    &lt;line num="L1">&lt;a>1&lt;/a>&lt;b>2&lt;/b>&lt;c>3&lt;/c>&lt;/line>
    &lt;line num="L2">&lt;a>11&lt;/a>&lt;b>22&lt;/b>&lt;c>33&lt;/c>&lt;/line>
    &lt;/doc>');
    
    INSERT INTO test VALUES (2, '&lt;doc num="C2">
    &lt;line num="L1">&lt;a>111&lt;/a>&lt;b>222&lt;/b>&lt;c>333&lt;/c>&lt;/line>
    &lt;line num="L2">&lt;a>111&lt;/a>&lt;b>222&lt;/b>&lt;c>333&lt;/c>&lt;/line>
    &lt;/doc>');
    </literal>
   </para>
  </sect3>
   
  <sect3>
   <title>The query</title>
   
d319 27
a345 5
   SELECT * FROM  xpath_table('id','xml','test', 
   '/doc/@@num|/doc/line/@@num|/doc/line/a|/doc/line/b|/doc/line/c','1=1') 
   AS t(id int4, doc_num varchar(10), line_num varchar(10), val1 int4, 
   val2 int4, val3 int4)
   WHERE id = 1 ORDER BY doc_num, line_num
d347 1
a347 1
   
d349 2
a350 1
   Gives the result:
d352 1
a352 1
   
d354 7
a360 18
    id | doc_num | line_num | val1 | val2 | val3
   ----+---------+----------+------+------+------
     1 | C1      | L1       |    1 |    2 |    3
     1 |         | L2       |   11 |   22 |   33
   </programlisting>
   
   <para>
   To get doc_num on every line, the solution is to use two invocations
   of xpath_table and join the results:
   </para>
   
   <programlisting>
   SELECT t.*,i.doc_num FROM 
     xpath_table('id','xml','test',
      '/doc/line/@@num|/doc/line/a|/doc/line/b|/doc/line/c','1=1') 
           AS t(id int4, line_num varchar(10), val1 int4, val2 int4, val3 int4),
     xpath_table('id','xml','test','/doc/@@num','1=1') 
           AS i(id int4, doc_num varchar(10))
d363 1
a363 7
   </programlisting>
   
   <para>
   which gives the desired result:
   </para>
   
   <programlisting>
a371 1
   
d375 1
d379 1
a379 1
   Makefile)
d384 4
a387 3
   <programlisting>
    xslt_process(document,stylesheet,paramlist) RETURNS text
   </programlisting>
d393 3
a395 3
    'a=1,b=2'. Note that this is also proof-of-concept code and the
    parameter parsing is very simple-minded (e.g. parameter values cannot
    contain commas!)
d397 1
d401 5
a405 4
    fetch them. It thus follows that you can use xslt_process as a means
    to fetch the contents of URLs - you should be aware of the security
    implications of this.
   </para> 
d407 2
a408 2
    There is also a two-parameter version of xslt_process which does not
    pass any parameters to the transformation.
d414 2
a415 1
  <title>Credits</title>
d417 1
a417 2
   Development of this module was sponsored by Torchbox Ltd. (www.torchbox.com)
   It has the same BSD licence as PostgreSQL.
d419 1
d421 2
a422 10
   This version of the XML functions provides both XPath querying and
   XSLT functionality. There is also a new table function which allows
   the straightforward return of multiple XML results. Note that the current code
   doesn't take any particular care over character sets - this is
   something that should be fixed at some point!
  </para>
  <para>
   If you have any comments or suggestions, please do contact me at
   <email>jgray@@azuli.co.uk.</email> Unfortunately, this isn't my main job, so 
   I can't guarantee a rapid response to your query!
d425 1
a426 1

@


1.2
log
@Remove tabs from SGML files.
@
text
@d404 1
a404 1
    begin with a < then they will be treated as URLs and libxslt will
@


1.1
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@d240 4
a243 4
	'article_xml',
	'articles', 
	'/article/author|/article/pages|/article/title',
	'date_entered > ''2003-01-01'' ') 
@

