<!-- doc/src/sgml/xml2.sgml -->

<sect1 id="xml2" xreflabel="xml2">
 <title>xml2 &mdash; XPath querying and XSLT functionality</title>

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

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

 <sect2 id="xml2-deprecation">
  <title>Deprecation Notice</title>

  <para>
   From <productname>PostgreSQL</productname> 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 a future version of PostgreSQL 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 <email>pgsql-hackers@lists.postgresql.org</email> so that the deficiency
   can be addressed.
  </para>
 </sect2>

 <sect2 id="xml2-functions">
  <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.
  </para>

  <table id="xml2-functions-table">
   <title><filename>xml2</filename> Functions</title>
    <tgroup cols="1">
     <thead>
      <row>
       <entry role="func_table_entry"><para role="func_signature">
        Function
       </para>
       <para>
        Description
       </para></entry>
      </row>
     </thead>

     <tbody>
      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>xml_valid</function> ( <parameter>document</parameter> <type>text</type> )
        <returnvalue>boolean</returnvalue>
       </para>
       <para>
        Parses the given document and returns true if the
        document is well-formed XML.  (Note: this is an alias for the standard
        PostgreSQL function <function>xml_is_well_formed()</function>.  The
        name <function>xml_valid()</function> is technically incorrect since validity
        and well-formedness have different meanings in XML.)
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>xpath_string</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type> )
        <returnvalue>text</returnvalue>
       </para>
       <para>
        Evaluates the XPath query on the supplied document, and
        casts the result to <type>text</type>.
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>xpath_number</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type> )
        <returnvalue>real</returnvalue>
       </para>
       <para>
        Evaluates the XPath query on the supplied document, and
        casts the result to <type>real</type>.
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>xpath_bool</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type> )
        <returnvalue>boolean</returnvalue>
       </para>
       <para>
        Evaluates the XPath query on the supplied document, and
        casts the result to <type>boolean</type>.
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>xpath_nodeset</function> ( <parameter>document</parameter> <type>text</type>, <parameter>query</parameter> <type>text</type>, <parameter>toptag</parameter> <type>text</type>, <parameter>itemtag</parameter> <type>text</type>