<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.524 2010/08/05 18:21:17 tgl Exp $ -->

<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.525 2010/08/08 19:15:27 tgl Exp $ -->

<chapter id="functions">

<title>Functions and Operators</title>

linkend="datatype-xml"> for information about the <type>xml</type>

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 ofmany of these

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

functions requires the installation to have been built

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

</para>

<synopsis>

<function>xmlconcat</function>(<replaceable>xml</replaceable><optional>, ...</optional>)

</synopsis>

<para>

The function <function>xmlconcat</function> concatenates a list

of individual XML values to create a single value containing an

]]></screen>

</para>

</sect3>

<sect3>

<title><literal>xmlelement</literal></title>

<indexterm>

<primary>xmlelement</primary>

</indexterm>

<synopsis>

<function>xmlelement</function>(name <replaceable>name</replaceable> <optional>, xmlattributes(<replaceable>value</replaceable> <optional>AS <replaceable>attname</replaceable></optional> <optional>, ... </optional>)</optional> <optional><replaceable>, content, ...</replaceable></optional>)

</synopsis>

<para>

The <function>xmlelement</function> expression produces an XML

element with the given name, attributes, and content.

at which point a more precise description will appear.

</para>

</sect3>

<sect3>

<title><literal>xmlforest</literal></title>

<indexterm>

<primary>xmlforest</primary>

</indexterm>

<synopsis>

<function>xmlforest</function>(<replaceable>content</replaceable> <optional>AS <replaceable>name</replaceable></optional> <optional>, ...</optional>)

</synopsis>

<para>

The <function>xmlforest</function> expression produces an XML

forest (sequence) of elements using the given names and content.

<function>xmlelement</function>.

</para>

</sect3>

<sect3>

<title><literal>xmlpi</literal></title>

<indexterm>

<primary>xmlpi</primary>

</indexterm>

<synopsis>

<function>xmlpi</function>(name <replaceable>target</replaceable> <optional>, <replaceable>content</replaceable></optional>)

</synopsis>

<para>

The <function>xmlpi</function> expression creates an XML

processing instruction. The content, if present, must not

]]></screen>

</para>

</sect3>

<sect3>

<title><literal>xmlroot</literal></title>

<indexterm>

<primary>xmlroot</primary>

</indexterm>

<synopsis>

<function>xmlroot</function>(<replaceable>xml</replaceable>, version <replaceable>text</replaceable> | no value <optional>, standalone yes|no|no value</optional>)

</synopsis>

<para>

The <function>xmlroot</function> expression alters the properties

of the root node of an XML value. If a version is specified,

<para>

<screen><![CDATA[

SELECT xmlroot(xmlparse(document '<?xml version="1.1"?><content>abc</content>'),

SELECT xmlroot(xmlparse(document '<?xml version="1.1"?><content>abc</content>'),

version '1.0', standalone yes);

xmlroot

<para>

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

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

the functions <function>xpath</function> and

<function>xpath_exists</function>, which evaluate XPath 1.0

expressions.

</para>

<synopsis>

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

<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

expression <replaceable>xpath</replaceable> (a <type>text</> value)

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>

<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

Theoptionalthird argument of the function is an array of namespace

mappings. This array should be a two-dimensional<type>text</>array with

thelength 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 (alias), the

second the namespace URI. It is not required that aliases provided in

this arrayare the samethat those being used in the XML document itself (in

this arraybe the sameas those being used in the XML document itself (in

other words, both in the XML document and in the <function>xpath</function>

function context, aliases are <emphasis>local</>).

</para>

<para>

Example:

<screen><![CDATA[

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

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

ARRAY[ARRAY['my', 'http://example.com']]);

xpath

</para>

<para>

How todeal with default (anonymous) namespaces:

Todeal with default (anonymous) namespaces, do something like this:

<screen><![CDATA[

SELECT xpath('//mydefns:b/text()', '<a xmlns="http://example.com"><b>test</b></a>',

ARRAY[ARRAY['mydefns', 'http://example.com']]);

--------

{test}

(1 row)

]]></screen>

</para>

<indexterm>

<primary>xpath_exists</primary>

</indexterm>

<synopsis>

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

</synopsis>

<para>

The function <function>xpath_exists</function> is a specialized form

of the <function>xpath</function> function. Instead of returning the

individual XML values that satisfy the XPath, this function returns a

boolean indicating whether the query was satisfied or not. This

function is equivalent to the standard <literal>XMLEXISTS</> predicate,

except that it also offers support for a namespace mapping argument.

</para>

<para>

Example:

<screen><![CDATA[

SELECT xpath_exists('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>',

ARRAY[ARRAY['my', 'http://example.com']]);

xpath_exists

--------------

t

(1 row)

]]></screen>

</para>

</sect2>

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

<title>Mapping Tables to XML</title>

<indexterm zone="functions-xml-mapping">

<indexterm zone="functions-xml-mapping">

<primary>XML export</primary>

</indexterm>

return0;

}

xpath_exists(PG_FUNCTION_ARGS)

{

text*xpath_expr_text=PG_GETARG_TEXT_P(0);

xmltype*data=PG_GETARG_XML_P(1);

ArrayType*namespaces=PG_GETARG_ARRAYTYPE_P(2);

intres_nitems;

xpath_internal(xpath_expr_text,data,namespaces,

&res_nitems,NULL);

PG_RETURN_BOOL(res_nitems>0);

NO_XML_SUPPORT();

return0;

}

DATA(insertOID=2614 (xmlexistsPGNSPPGUID12100ffftfi2016"25 142"_null__null__null__null_xmlexists_null__null__null_ ));

DESCR("test XML value against XPath expression");

DATA(insertOID=3049 (xpath_existsPGNSPPGUID12100ffftfi3016"25 142 1009"_null__null__null__null_xpath_exists_null__null__null_ ));

DESCR("test XML value against XPath expression, with namespace support");

DATA(insertOID=3050 (xpath_existsPGNSPPGUID14100ffftfi2016"25 142"_null__null__null__null_"select pg_catalog.xpath_exists($1, $2, ''{}''::pg_catalog.text[])"_null__null__null_ ));

DESCR("test XML value against XPath expression");

DATA(insertOID=2952 (uuid_inPGNSPPGUID12100ffftfi102950"2275"_null__null__null__null_uuid_in_null__null__null_ ));

DESCR("I/O");

externDatumxmltotext(PG_FUNCTION_ARGS);

externDatumxmlvalidate(PG_FUNCTION_ARGS);

externDatumxpath(PG_FUNCTION_ARGS);

externDatumxpath_exists(PG_FUNCTION_ARGS);

externDatumxmlexists(PG_FUNCTION_ARGS);

externDatumtable_to_xml(PG_FUNCTION_ARGS);

{<b>two</b>,<b>etc</b>}

(1 row)

-- Test xmlexistsevaluation

-- Test xmlexistsand xpath_exists

SELECT xmlexists('//town[text() = ''Toronto'']' PASSING BY REF '<towns><town>Bidford-on-Avon</town><town>Cwmbran</town><town>Bristol</town></towns>');

xmlexists

-----------

t

(1 row)

SELECT xpath_exists('//town[text() = ''Toronto'']','<towns><town>Bidford-on-Avon</town><town>Cwmbran</town><town>Bristol</town></towns>'::xml);

xpath_exists

--------------

f

(1 row)

SELECT xpath_exists('//town[text() = ''Cwmbran'']','<towns><town>Bidford-on-Avon</town><town>Cwmbran</town><town>Bristol</town></towns>'::xml);

xpath_exists

--------------

t

(1 row)

INSERT INTO xmltest VALUES (4, '<menu><beers><name>Budvar</name><cost>free</cost><name>Carling</name><cost>lots</cost></beers></menu>'::xml);

INSERT INTO xmltest VALUES (5, '<menu><beers><name>Molson</name><cost>free</cost><name>Carling</name><cost>lots</cost></beers></menu>'::xml);

INSERT INTO xmltest VALUES (6, '<myns:menu xmlns:myns="http://myns.com"><myns:beers><myns:name>Budvar</myns:name><myns:cost>free</myns:cost><myns:name>Carling</myns:name><myns:cost>lots</myns:cost></myns:beers></myns:menu>'::xml);

1

(1 row)

SELECT COUNT(id) FROM xmltest WHERE xpath_exists('/menu/beer',data);

count

-------

0

(1 row)

SELECT COUNT(id) FROM xmltest WHERE xpath_exists('/menu/beers',data);

count

-------

2

(1 row)

SELECT COUNT(id) FROM xmltest WHERE xpath_exists('/menu/beers/name[text() = ''Molson'']',data);

count

-------

1

(1 row)

SELECT COUNT(id) FROM xmltest WHERE xpath_exists('/myns:menu/myns:beer',data,ARRAY[ARRAY['myns','http://myns.com']]);

count

-------

0

(1 row)

SELECT COUNT(id) FROM xmltest WHERE xpath_exists('/myns:menu/myns:beers',data,ARRAY[ARRAY['myns','http://myns.com']]);

count

-------

2

(1 row)

SELECT COUNT(id) FROM xmltest WHERE xpath_exists('/myns:menu/myns:beers/myns:name[text() = ''Molson'']',data,ARRAY[ARRAY['myns','http://myns.com']]);

count

-------

1

(1 row)

CREATE TABLE query ( expr TEXT );

INSERT INTO query VALUES ('/menu/beers/cost[text() = ''lots'']');

SELECT COUNT(id) FROM xmltest, query WHERE xmlexists(expr PASSING BY REF data);