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
Example 24.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.