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.