<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="Function: xpath_eval - Virtuoso Functions Guide" />
<meta name="dc.subject" content="Function: xpath_eval - Virtuoso Functions Guide" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="functions.html" title="Chapter Contents" />
<link rel="prev" href="appendixa.html" title="Appendix" />
<link rel="next" href="functions.html#.html" title="" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>Function: xpath_eval - Virtuoso Functions Guide</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="fn_xpath_eval" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>22. Virtuoso Functions Guide - xpath_eval</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="functions.html">Chapter Contents</a> | <a class="link" href="fn_XMLUpdate.html" title="XMLUpdate">Prev</a> | <a class="link" href="fn_xper_cut.html" title="xper_cut">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div>
<a class="selected" href="functions.html">Virtuoso Functions Guide</a>
</div>
<br />
<div>
<a href="functions.html#admin">Administration</a>
</div>
<div>
<a href="functions.html#aggr">Aggregate Functions</a>
</div>
<div>
<a href="functions.html#array">Array Manipulation</a>
</div>
<div>
<a href="functions.html#bpel">BPEL APIs</a>
</div>
<div>
<a href="functions.html#backup">Backup</a>
</div>
<div>
<a href="functions.html#compression">Compression</a>
</div>
<div>
<a href="functions.html#cursors">Cursor</a>
</div>
<div>
<a href="functions.html#time">Date & Time Manipulation</a>
</div>
<div>
<a href="functions.html#debug">Debug</a>
</div>
<div>
<a href="functions.html#dict">Dictionary Manipulation</a>
</div>
<div>
<a href="functions.html#encoding">Encoding & Decoding</a>
</div>
<div>
<a href="functions.html#file">File Manipulation</a>
</div>
<div>
<a href="functions.html#ft">Free Text</a>
</div>
<div>
<a href="functions.html#hash">Hashing / Cryptographic</a>
</div>
<div>
<a href="functions.html#ldap">LDAP</a>
</div>
<div>
<a href="functions.html#localization">Locale</a>
</div>
<div>
<a href="functions.html#mail">Mail</a>
</div>
<div>
<a href="functions.html#misc">Miscellaneous</a>
</div>
<div>
<a href="functions.html#number">Number</a>
</div>
<div>
<a href="functions.html#phrz">Phrases</a>
</div>
<div>
<a href="functions.html#rdf">RDF data</a>
</div>
<div>
<a href="functions.html#rmt">Remote SQL Data Source</a>
</div>
<div>
<a href="functions.html#repl">Replication</a>
</div>
<div>
<a href="functions.html#soap">SOAP</a>
</div>
<div>
<a href="functions.html#sql">SQL</a>
</div>
<div>
<a href="functions.html#string">String</a>
</div>
<div>
<a href="functions.html#txn">Transaction</a>
</div>
<div>
<a href="functions.html#type">Type Mapping</a>
</div>
<div>
<a href="functions.html#uddi">UDDI</a>
</div>
<div>
<a href="functions.html#udt">User Defined Types & The CLR</a>
</div>
<div>
<a href="functions.html#vad">VAD</a>
</div>
<div>
<a href="functions.html#jvmpl">Virtuoso Java PL API</a>
</div>
<div>
<a href="functions.html#bif">Virtuoso Server Extension Interface (VSEI)</a>
</div>
<div>
<a href="functions.html#ws">Web & Internet</a>
</div>
<div>
<a class="selected" href="functions.html#xml">XML</a>
</div>
<div class="selected">
<div>
<a href="fn_XMLAGG.html">xmlagg</a>
</div>
<div>
<a href="fn_XMLATTRIBUTES.html">xmlattributes</a>
</div>
<div>
<a href="fn_XMLAddAttribute.html">xmladdattribute</a>
</div>
<div>
<a href="fn_XMLAppendChildren.html">xmlappendchildren</a>
</div>
<div>
<a href="fn_XMLCONCAT.html">xmlconcat</a>
</div>
<div>
<a href="fn_XMLELEMENT.html">xmlelement</a>
</div>
<div>
<a href="fn_XMLFOREST.html">xmlforest</a>
</div>
<div>
<a href="fn_XMLInsertAfter.html">xmlinsertafter</a>
</div>
<div>
<a href="fn_XMLInsertBefore.html">xmlinsertbefore</a>
</div>
<div>
<a href="fn_XMLReplace.html">xmlreplace</a>
</div>
<div>
<a href="fn_XMLType.XMLType.html">xmltype.xmltype</a>
</div>
<div>
<a href="fn_XMLType.createNonSchemaBasedXML.html">xmltype.createnonsch...</a>
</div>
<div>
<a href="fn_XMLType.createSchemaBasedXML.html">xmltype.createschema...</a>
</div>
<div>
<a href="fn_XMLType.createXML.html">xmltype.createxml</a>
</div>
<div>
<a href="fn_XMLType.existsNode.html">xmltype.existsnode</a>
</div>
<div>
<a href="fn_XMLType.extract.html">xmltype.extract</a>
</div>
<div>
<a href="fn_XMLType.getClobVal.html">xmltype.getclobval</a>
</div>
<div>
<a href="fn_XMLType.getNamespace.html">xmltype.getnamespace</a>
</div>
<div>
<a href="fn_XMLType.getNumVal.html">xmltype.getnumval</a>
</div>
<div>
<a href="fn_XMLType.getRootElement.html">xmltype.getrooteleme...</a>
</div>
<div>
<a href="fn_XMLType.getSchemaURL.html">xmltype.getschemaurl</a>
</div>
<div>
<a href="fn_XMLType.getStringVal.html">xmltype.getstringval</a>
</div>
<div>
<a href="fn_XMLType.isFragment.html">xmltype.isfragment</a>
</div>
<div>
<a href="fn_XMLType.isSchemaBased.html">xmltype.isschemabase...</a>
</div>
<div>
<a href="fn_XMLType.isSchemaValid.html">xmltype.isschemavali...</a>
</div>
<div>
<a href="fn_XMLType.isSchemaValidated.html">xmltype.isschemavali...</a>
</div>
<div>
<a href="fn_XMLType.schemaValidate.html">xmltype.schemavalida...</a>
</div>
<div>
<a href="fn_XMLType.setSchemaValidated.html">xmltype.setschemaval...</a>
</div>
<div>
<a href="fn_XMLType.toObject.html">xmltype.toobject</a>
</div>
<div>
<a href="fn_XMLType.transform.html">xmltype.transform</a>
</div>
<div>
<a href="fn_XMLUpdate.html">xmlupdate</a>
</div>
<div>
<a href="fn_xper_right_sibling.html">xper navigation</a>
</div>
<div>
<a href="fn_createXML.html">createxml</a>
</div>
<div>
<a href="fn_isentity.html">isentity</a>
</div>
<div>
<a href="fn_serialize_to_UTF8_xml.html">serialize_to_utf8_xm...</a>
</div>
<div>
<a href="fn_tidy_html.html">tidy_html</a>
</div>
<div>
<a href="fn_tidy_list_errors.html">tidy_list_errors</a>
</div>
<div>
<a href="fn_updateXML.html">updatexml</a>
</div>
<div>
<a href="fn_xml_add_system_path.html">xml_add_system_path</a>
</div>
<div>
<a href="fn_xml_auto.html">xml_auto</a>
</div>
<div>
<a href="fn_xml_auto_dtd.html">xml_auto_dtd</a>
</div>
<div>
<a href="fn_xml_auto_schema.html">xml_auto_schema</a>
</div>
<div>
<a href="fn_xml_create_tables_from_mapping_schema_decl.html">xml_create_tables_fr...</a>
</div>
<div>
<a href="fn_xml_cut.html">xml_cut</a>
</div>
<div>
<a href="fn_xml_doc_output_option.html">xml_doc_output_optio...</a>
</div>
<div>
<a href="fn_xml_get_system_paths.html">xml_get_system_paths</a>
</div>
<div>
<a href="fn_xml_load_mapping_schema_decl.html">xml_load_mapping_sch...</a>
</div>
<div>
<a href="fn_xml_load_schema_decl.html">xml_load_schema_decl</a>
</div>
<div>
<a href="fn_xml_namespace_scope.html">xml_namespace_scope</a>
</div>
<div>
<a href="fn_xml_persistent.html">xml_persistent</a>
</div>
<div>
<a href="fn_xml_set_ns_decl.html">xml_set_ns_decl</a>
</div>
<div>
<a href="fn_xml_template.html">xml_template</a>
</div>
<div>
<a href="fn_xml_tree.html">xml_tree</a>
</div>
<div>
<a href="fn_xml_tree_doc.html">xml_tree_doc</a>
</div>
<div>
<a href="fn_xml_tree_doc_media_type.html">xml_tree_doc_media_t...</a>
</div>
<div>
<a href="fn_xml_uri_get.html">xml_uri_get</a>
</div>
<div>
<a href="fn_xml_validate_dtd.html">xml_validate_dtd</a>
</div>
<div>
<a href="fn_xml_validate_schema.html">xml_validate_schema</a>
</div>
<div>
<a href="fn_xml_view_dtd.html">xml_view_dtd</a>
</div>
<div>
<a href="fn_xml_view_schema.html">xml_view_schema</a>
</div>
<div>
<a href="fn_xmlsql_update.html">xmlsql_update</a>
</div>
<div>
<a class="selected" href="fn_xpath_eval.html">xpath_eval</a>
</div>
<div>
<a href="fn_xper_cut.html">xper_cut</a>
</div>
<div>
<a href="fn_xper_doc.html">xper_doc</a>
</div>
<div>
<a href="fn_xper_locate_words.html">xper_locate_words</a>
</div>
<div>
<a href="fn_xpf_extension.html">xpf_extension</a>
</div>
<div>
<a href="fn_xpf_extension_remove.html">xpf_extension_remove</a>
</div>
<div>
<a href="fn_xquery_eval.html">xquery_eval</a>
</div>
<div>
<a href="fn_xslt.html">xslt</a>
</div>
<div>
<a href="fn_xslt_format_number.html">xslt_format_number</a>
</div>
<div>
<a href="fn_xslt_sheet.html">xslt_sheet</a>
</div>
<div>
<a href="fn_xslt_stale.html">xslt_stale</a>
</div>
<div>
<a href="fn_xte_head.html">xte_head</a>
</div>
<div>
<a href="fn_xte_node.html">xte_node</a>
</div>
<div>
<a href="fn_xte_node_from_nodebld.html">xte_node_from_nodebl...</a>
</div>
<div>
<a href="fn_xte_nodebld_acc.html">xte_nodebld_acc</a>
</div>
<div>
<a href="fn_xte_nodebld_final.html">xte_nodebld_final</a>
</div>
<div>
<a href="fn_xte_nodebld_init.html">xte_nodebld_init</a>
</div>
<div>
<a href="fn_xtree_doc.html">xtree_doc</a>
</div>
</div>
<div>
<a href="functions.html#XPATH">XPATH & XQUERY</a>
</div>
<br />
<div>
<a href="functionidx.html">Functions Index</a>
</div>
<br />
</div>
<div id="text">
<h2>xpath_eval</h2>
<div class="refpurpose">Applies an XPATH expression to a context node and returns result(s).</div>
<div class="funcsynopsis">
<span class="funcdef">
<span class="function">xpath_eval</span>
</span>
(<span class="paramdef">in <span class="parameter">xpath_expression </span>varchar</span>,
<span class="paramdef">in <span class="parameter">xml_tree </span>XML Entity</span>,
<span class="paramdefoptional">[in <span class="optional">index </span>integer]</span>,
<span class="paramdefoptional">[in <span class="optional">named_params</span> vector]</span>);
</div>
<div class="refsect1">
<div class="refsect1title">Description</div>
<p>
This function returns the result of applying the XPath
expression to the context node. By default only the first result is
returned, but supplying a third argument allows you to specify an
index for the value; the default assumes a value of 1 here. A value
of 0 returns an array of 0 or more elements, one for each value
selected by the XPath expression.
</p>
<p>
When this function returns an entity in a result set, the client will
see an nvarchar value containing the serialization of the entity,
complete with markup. When the entity is passed as an SQL value it
remains an entity referencing the node of a parsed XML tree,
permitting navigation inside the tree.
</p>
<p>
The expression can be passed parameters by specifying a fourth argument
to <span class="computeroutput">xpath_eval()</span>. This will be a vector of name/value
pairs. The values can be referenced from inside XPath expression by using
their names with '$' prefix. You may use any Virtuoso data type.
The names in the parameter vector should appear without the '$' sign.
If any of the parameter values is NULL the parameter will be ignored because NULL
has no XPath counterpart.
If the same name appears more than once in the vector, the last name/value pair is
used and all preceding pairs with this name are silently ignored.
Obviously, names should be strings that are valid XPath variable names.
</p>
</div>
<div class="refsect1">
<div class="refsect1title">Parameters</div>
<div class="refsect2">
<span class="refsect2title">xpath_expression – </span>
A valid XPATH expression. In almost all application this is a string.
There is a tricky extension that is used by BPEL-like applications: <span class="computeroutput">xpath_expression</span> can be an XML entity
whost string-value is a valid XPATH expression. An example of such an entity is "select" or "test"
attribute in XSLT stylesheet. This trick lets XPATH processor to resolve namespace prefixes by looking at namespace declarations
at the header of the stylesheet.
</div>
<div class="refsect2">
<span class="refsect2title">xml_tree – </span>
An XML entity such as that returned from the <span class="computeroutput">xtree_doc()</span> function.
</div>
<div class="refsect2">
<span class="refsect2title">index – </span>
Result index. This parameter is optional. If omitted a
value of 1 is assumed, meaning only the first result is returned. If
a value of 0 is supplied then an array of 0 or more elements is
returned containing one element per result.
</div>
<div class="refsect2">
<span class="refsect2title">named_params – </span>
A vector of keyword/value parameters to be passed to the
XPath processor.
</div>
</div>
<div class="refsect1">
<div class="refsect1title">Return Types</div>
<p>This function will return the first or
<span class="computeroutput">index</span> selected result of applying the XPath
expression to the <span class="computeroutput">xml_tree</span> input. If an <span class="computeroutput">index</span>
value of 0 is supplied then the output is an array.</p>
</div>
<div class="refsect1title">Errors</div>
<table class="data">
<tr>
<th class="data">SQL State</th>
<th class="data">Error Code</th>
<th class="data">Error Text</th>
<th class="data">Description</th>
</tr>
<tr>
<td class="data">
<a name="errXP370" />
<span class="errorcode">XP370</span>
</td>
<td class="data">
<a name="errXI009" />
<span class="errorcode">XI009</span>
</td>
<td class="data">
<span class="errorname">Argument 2 of xpath_eval must be an entity, not a value of type [type name] ([type code])</span>
</td>
<td class="data">The xml_tree parameter should always be an entity.
In some cases the XPath expression does not use context entity, but it should be provided anyway
(e.g. some fake document).</td>
</tr>
</table>
<br />
<p />
<div class="refsect1">
<div class="refsect1title">Examples</div>
<a name="ex_xpath_eval" />
<div class="example">
<div class="exampletitle">Finding the Authors of Document Titles</div>
<div>
<pre class="programlisting">
select xt_file, xpath_eval ('//author', t) from xml_text
where xpath_contains (xt_text, '//chapter/title[. = 'Introduction']', t);
</pre>
</div>
<p>
This will select all titles that are descendants of chapter and have a
string value of 'Introduction'. This will next evaluate
<span class="computeroutput">//author</span> in the context of each, retrieving the
author entities in the document of the title.
</p>
</div>
<a name="ex_xpath_eval2" />
<div class="example">
<div class="exampletitle">xpath_eval and Repeating Nodes.</div>
<p>This example shows how the xpath_eval can be used to retrieve
multiple node answers to queries. First to set the scene consider the following
statements that create a table with XML inside.</p>
<div>
<pre class="programlisting">
CREATE TABLE t_articles (
article_id int NOT NULL,
article_title varchar(255) NOT NULL,
article_xml long varchar
);
insert into t_articles (article_id, article_title) values (1, 'a');
insert into t_articles (article_id, article_title) values (2, 'b');
UPDATE t_articles SET article_xml = '
<beatles id = "b1">
<beatle instrument = "guitar" alive = "no">john lennon</beatle>
<beatle instrument = "guitar" alive = "no">george harrison</beatle>
</beatles>'
WHERE article_id = 1;
UPDATE t_articles SET article_xml = '
<beatles id = "b2">
<beatle instrument = "bass" alive = "yes">paul mccartney</beatle>
<beatle instrument = "drums" alive = "yes">ringo starr</beatle>
</beatles>'
WHERE article_id = 2;
</pre>
</div>
<p>Now we make a query that will return a vector of results, each
vector element corresponding to a node-set of the result.</p>
<div>
<pre class="programlisting">
SELECT xpath_eval('//beatle/@instrument', xml_tree_doc (article_xml), 0)
AS beatle_instrument FROM t_articles WHERE article_id = 2;
</pre>
</div>
<p>The repeating nodes are returned as part of a vector, the third argument
to xpath_eval is set to 0, which means that it is to return all nodes.</p>
<p>Otherwise, we can select the first node-set by supplying 1 as the third
parameter to xpath_eval: </p>
<div>
<pre class="programlisting">
SELECT xpath_eval('//beatle/@instrument', xml_tree_doc (article_xml), 1)
AS beatle_instrument FROM t_articles WHERE article_id = 2;
</pre>
</div>
</div>
<a name="ex_xpath_eval3" />
<div class="example">
<div class="exampletitle">Passing a named parameter to the XPath</div>
<div>
<pre class="programlisting">
SQL> select xpath_eval(
'//phone[../name like $$n]',
xtree_doc ('<phonebook>
<dept><name>Installation Service</name><phone>555-1111</phone></dept>
<dept><name>Tech Support</name><phone>555-1112</phone></dept>
</phonebook>'),
1,
vector('n', 'Tech%') );
callret
VARCHAR
_______________________________________________________________________________
<phone>555-1112</phone>
</pre>
</div>
<p>
Like in SQL queries, XPath parameters are used to avoid printing literal values into
the text of the query. The listing above demonstrates how to find the phone of
the first department whose name is like the specified pattern.
</p>
<p>
Note that if the text of the XPath expression is entered as a string in ISQL,
dollar signs in front of parameter names should be doubled, as in this sample.
ISQL uses the same syntax ($name) for macro expansion, and double dollar sign
is replaced by ISQL with single dollar sign character.
</p>
</div>
</div>
<div class="refsect1">
<div class="refsect1title">See Also</div>
<p>
<a href="fn_xquery_eval.html">xquery_eval()</a>
</p>
<p>
<a href="queryingxmldata.html#xpathcontainsSQLPred">xpath_contains SQL predicate</a>
</p>
<p>
<a href="queryingxmldata.html#xcontainspredicate">xcontains SQL Predicate</a>
</p>
</div>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
744
