<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.200 2007/05/08 17:02:59 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.201 2007/05/21 17:10:28 petere Exp $ -->

<chapter id="datatype">

<title id="datatype-title">Data Types</title>

<sect1 id="datatype-uuid">

<title><acronym>UUID</acronym> Type</title>

<indexterm zone="datatype-xml">

<indexterm zone="datatype-uuid">

<primary>UUID</primary>

</indexterm>

value is a full document or only a content fragment.

</para>

<sect2>

<title>Creating XML Values</title>

<para>

To produce a value of type <type>xml</type> from character data,

use the function

Examples:

<programlisting><![CDATA[

XMLPARSE (DOCUMENT '<?xml version="1.0"?><book><title>Manual</title><chapter>...</chapter><book>')

XMLPARSE (CONTENT 'abc<foo>bar</bar><bar>foo</foo>')

XMLPARSE (CONTENT 'abc<foo>bar</foo><bar>foo</bar>')

]]></programlisting>

While this is the only way to convert character strings into XML

values according to the SQL standard, the PostgreSQL-specific

The default is <literal>CONTENT</literal>, so all forms of XML

data are allowed.

</para>

</sect2>

<sect2>

<title>Encoding Handling</title>

<para>

Care must be taken when dealing with multiple character encodings

on the client, server, and in the XML data passed through them.

processed in UTF-8, computations will be most efficient if the

server encoding is also UTF-8.

</para>

</sect2>

<sect2>

<title>Accessing XML Values</title>

<para>

The <type>xml</type> data type is unusual in that it does not

provide any comparison operators. This is because there is no

well-defined and universally useful comparison algorithm for XML

data. One consequence of this is that you cannot retrieve rows by

comparing an <type>xml</type> column against a search value. XML

values should therefore typically be accompanied by a separate key

field such as an ID. An alternative solution for comparing XML

values is to convert them to character strings first, but note

that character string comparison has little to do with a useful

XML comparison method.

</para>

<para>

Since there are no comparison operators for the <type>xml</type>

data type, it is not possible to create an index directly on a

column of this type. If speedy searches in XML data are desired,

possible workarounds would be casting the expression to a

character string type and indexing that, or indexing an XPath

expression. The actual query would of course have to be adjusted

to search by the indexed expression.

</para>

<para>

The full-text search module Tsearch2 could also be used to speed

up full-document searches in XML data. The necessary

preprocessing support is, however, not available in the PostgreSQL

distribution in this release.

</para>

</sect2>

</sect1>

&array;

<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.379 2007/05/07 07:53:26 petere Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.380 2007/05/21 17:10:28 petere Exp $ -->

<chapter id="functions">

<title>Functions and Operators</title>

type. The function-like expressions <function>xmlparse</function>

and <function>xmlserialize</function> for converting to and from

type <type>xml</type> are not repeated here. Use of many of these

<type>xml</type>functions requires the installation to have been built

functions requires the installation to have been built

with <command>configure --with-libxml</>.

</para>

</sect3>

</sect2>

<sect2 id="functions-xml-processing">

<title>Processing XML</title>

<indexterm>

<primary>XPath</primary>

</indexterm>

<para>

To process values of data type <type>xml</type>, PostgreSQL offers

the function <function>xpath</function>, which evaluates XPath 1.0

expressions.

</para>

<synopsis>

<function>xpath</function>(<replaceable>xpath</replaceable>, <replaceable>xml</replaceable><optional>, <replaceable>nsarray</replaceable></optional>)

</synopsis>

<para>

The function <function>xpath</function> evaluates the XPath

expression <replaceable>xpath</replaceable> against the XML value

<replaceable>xml</replaceable>. It returns an array of XML values

corresponding to the node set produced by the XPath expression.

</para>

<para>

The third argument of the function is an array of namespace

mappings. This array should be a two-dimensional array with the

length of the second axis being equal to 2 (i.e., it should be an

array of arrays, each of which consists of exactly 2 elements).

The first element of each array entry is the namespace name, the

second the namespace URI.

</para>

<para>

Example:

<screen><![CDATA[

SELECT xpath('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>', ARRAY[ARRAY['my', 'http://example.com']]);

xpath

--------

{test}

(1 row)

]]></screen>

</para>

</sect2>

<sect2 id="functions-xml-mapping">

<title>Mapping Tables to XML</title>

]]></programlisting>

</figure>

</sect2>

<sect2>

<title>Processing XML</title>

<para>

<acronym>XML</> support is not just the existence of an

<type>xml</type> data type, but a variety of features supported by

a database system. These capabilities include import/export,

indexing, searching, transforming, and <acronym>XML</> to

<acronym>SQL</> mapping. <productname>PostgreSQL</> supports some

but not all of these <acronym>XML</> capabilities. For an

overview of <acronym>XML</> use in databases, see <ulink

url="http://www.rpbourret.com/xml/XMLAndDatabases.htm"></>.

</para>

<variablelist>

<varlistentry>

<term>Indexing</term>

<listitem>

<para>

<filename>contrib/xml2/</> functions can be used in expression

indexes to index specific <acronym>XML</> fields. To index the

full contents of <acronym>XML</> documents, the full-text

indexing tool <filename>contrib/tsearch2/</> can be used. Of

course, Tsearch2 indexes have no <acronym>XML</> awareness so

additional <filename>contrib/xml2/</> checks should be added to

queries.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Searching</term>

<listitem>

<para>

XPath searches are implemented using <filename>contrib/xml2/</>.

It processes <acronym>XML</> text documents and returns results

based on the requested query.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Transforming</term>

<listitem>

<para>

<filename>contrib/xml2/</> supports <acronym>XSLT</> (Extensible

Stylesheet Language Transformation).

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>XML to SQL Mapping</term>

<listitem>

<para>

This involves converting <acronym>XML</> data to and from

relational structures. <productname>PostgreSQL</> has no

internal support for such mapping, and relies on external tools

to do such conversions.

</para>

</listitem>

</varlistentry>

</variablelist>

</sect2>

</sect1>