Name
xquery_eval — Applies an XQUERY expression to a context node and returns result(s).
Synopsis
xquery_eval ( |
in xquery_expression varchar , |
in xml_tree XML Entity , | |
in index integer , | |
in named_params vector
) ; |
Description
The xquery_eval function returns the result of applying the xquery 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 calculated by the xquery expression.
When an entity is returned in a result set to a client the client will see an nvarchar value containing the serialization of the entity, complete with markup. When the entity is passed as a SQL value it remains an entity referencing the node of a parsed XML tree, permitting navigation inside the tree.
The expression can be passed parameters by specifying a fourth
argument to xquery_eval()
. 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 XQuery variable names.
Parameters
xquery_expression
A valid XQuery expression. In almost all applications this is a
string. There is a tricky extension that is used by BPEL-like
applications: xpath_expression
can be an XML entity
whost string-value is a valid XQuery expression. An example of such
an entity is "select" or "test" attribute in XSLT stylesheet. This
trick lets XQuery processor to resolve namespace prefixes by
looking at namespace declarations at the header of the
stylesheet.
xml_tree
An XML entity such as that returned from the xtree_doc()
function.
index
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 results is returned containing one element per result. (Note that results can be in turn sequences of atomic values).
named_params
A vector of keyword/value parameters to be passed to the XQuery processor.
Return Types
This function will return the first or index selected result of
applying the xpath expression to the xml_tree
input. If an index value of
0 is supplied then the output is an array.
Examples
Example24.532.Finding the Authors of Document Titles
select xt_file, xquery_eval ('<authors>//author</authors>', t) from xml_text where xpath_contains (xt_text, '//chapter/title[. = 'Introduction']', t);
This will select all titles that are descendants of chapter and have a string value of 'Introduction'. This will next evaluate //author in the context of each, retrieving the author entities in the document of the title and construct an element whose name is "authors" and list of children contains all retrieved entities.