Name
filter — Composes trees of shallow copies of given XML entities.
Synopsis
node-set filter ( |
selection sequence
); |
Description
The function takes a single parameter which can be any expression. The function evaluates its argument and returns a shallow copy of the nodes that are selected by the argument, preserving any relationships that exist among these nodes. Duplicate nodes are removed before the processing.
The structure of the resulting node-set may be explained in the
following way. First of all, all input entities are grouped by
their documents, so we have a set of distinct documents and for
every document we have a list of entities that refers to various
nodes of the document. After that, every such document is processed
separately, and the result of processing is a node-set; the union
of these node-sets will be returned as the result of the call of
filter() function. A copy of the document is made, and a "color" is
assigned to every node of the copy: it's "black if the original
node is listed in the selection sequence, otherwise it's
"white". Then "white" nodes are removed from the copy, node after
node: if a "white" node may be found, it is replaced with list of
its children. Finally, we have a list of one or more "black" nodes
whose descendants are all "black", too, and this list is added into
the resulting node-set.
(The actual algorithm is much faster and much more complicated than the described one, but the result is identical.)
Note that this function is defined in XQuery standard, not in XPath, but in Virtuoso it may be used freely in expression of any kind.
Parameters
selection
The sequence of nodes that should be included into the result
Return Types
Node-set
Errors
Table24.142.Errors signalled by filter()
| SQLState | Error Code | Error Text | Description |
|---|---|---|---|
| XP001 | XPFB0 | The argument of XQUERY function filter() must be a sequence of XML entities | According to the XQuery standard, the function should signal an error if input contains values other than XML entity. |
Examples
Example24.586.Composing table of contents
The following example is from the XQuery standard and it illustrates how filter() might be used to compute a table of contents for a document that contains many levels of nested sections. The query filters the document, retaining only section elements, title elements nested directly inside section elements, and the text of those title elements. Other elements, such as paragraphs and figure titles, are eliminated, leaving only the "skeleton" of the document. The example generates a table of contents for a document named "cookbook.xml".
<toc>
{
filter(document("cookbook.xml") //
(section | section/title | section/title/text()))
}
</toc>