Home > Online Product Documentation > Table of Contents > Accessing Other Documents During Query Execution

Accessing Other Documents During Query Execution

During execution of a query, you might want to access data in another document. To do this, call the document() function.

This section discusses the following topics:

Format of the document() Function

To query multiple documents with a single query, call the document() function in a query. During execution of a query on a particular document, this function allows you to access another XML document.

The format for the document() function is

node-set document(object, node-set?)
               

            

The XPath processor examines the first argument. If it is a single value (that is, it is not a node set) the XPath processor converts it to a string, if it is not already a string. Separate directory names and the file name with a forward slash (/). See the following format:

This string must be an absolute path. The XPath processor retrieves the specified document. The new context node is the root node of this document. Suppose you invoke the document() function and the requested document does not exist. If the invocation is in a stylesheet, the XPath processor returns an empty node set. If the invocation is anywhere else, the XPath processor returns an error message.

When the First Argument is a Node Set

It is possible for the first argument of the document() function to be a node set. In this case, the result is as if you had called the document() function on each node in this node set. That is, the first argument of the document() function is each node in the node set in turn. The second argument, if there is one, is the same for each iteration of the document() function. This allows you to obtain the contents of multiple documents.

Specification of Second Argument

If you specify a second argument, it must be a node set. The XPath processor examines the first node (in the context of document order) in the node set to determine the document that this node belongs to. The XPath processor retrieves the name of the directory that contains this document and appends the relative path from the first argument to the name of the directory. This creates an absolute path, and the XPath processor retrieves the specified document.

If there is no second argument, the query must be an expression in an XSLT stylesheet. The XPath processor appends the relative path to the name of the directory that contains the XSLT stylesheet. This allows the query to examine the stylesheet itself.

Example of Calling the document() Function

Suppose you have the following XML document:

<?xml version="1.0" encoding="UTF-8"?> 
               
<books> 
               

              

                
<bookstore>bookstore1:bookstore1.xml</bookstore> 
                   
<bookstore>bookstore2:bookstore2.xml</bookstore> 
                   
<bookstore>bookstore3:bookstore3.xml</bookstore>
                   

                
              
</books> 
               

            

The following query returns the bookstore elements:

/books/bookstore
               

            

Now suppose you pass this query to the document() function as follows:

document(/books/bookstore)
               

            

This query returns the root nodes of bookstore1.xml, bookstore2.xml, and bookstore3.xml.