# 22. Virtuoso Functions Guide - filter

Chapter Contents | Prev | Next
Keyword Search:
www.openlinksw.com
docs.openlinksw.com
Book Home
Contents
Preface
Virtuoso Functions Guide
Administration
Aggregate Functions
Array Manipulation
BPEL APIs
Backup
Compression
Cursor
Date & Time Manipulation
Debug
Dictionary Manipulation
Encoding & Decoding
File Manipulation
Free Text
Hashing / Cryptographic
LDAP
Locale
Mail
Miscellaneous
Number
Remote SQL Data Source
Replication
SOAP
SQL
String
Transaction
Type Mapping
UDDI
User Defined Types & The CLR
Virtuoso Java PL API
Virtuoso Server Extension Interface (VSEI)
Web Server & Internet
XML
XPATH & XQUERY
and
append
assign
avg
boolean
ceiling
concat
contains
count
create-attribute
create-comment
create-element
create-pi
current
distinct
doc
document
document-literal
empty
ends-with
every
except
false
filter
floor
fn:collection
for
format-number
function-available
generate-id
id
if
intersect
is_after()
is_before()
key
lang
last
let
list()
local-name
max
min
name
namespace-uri
normalize-space
not
number
or
position
processxquery
processxslt
processxsql
progn()
replace()
round
serialize
shallow
some
starts-with
string
string-length
substring
substring-after
substring-before
sum
system-property
text_contains()
translate
true
tuple()
union
unordered
unparsed-entity-uri
urlify
xmlview
Functions Index

## filter

Composes trees of shallow copies of given XML entities.
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

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
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>

See Also

shallow()