<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="sourcedocs" page="projection" subpage=""/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Document Projection</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: Document Projection"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Document Projection</h1>
<p>Document Projection is a mechanism that analyzes a query to determine what parts of a document it
can potentially access, and then while building a tree to represent the document, leaves out those parts
of the tree that cannot make any difference to the result of the query.</p>
<p><i>Document projection is available only in Saxon-EE</i></p>
<p>Document projection can be enabled as an option on the XQuery command line interface: set
<code>-projection:on</code>. It is only used if requested. The command line option affects both the primary
source document supplied on the command line, and any calls on the <code>doc()</code> function within the body of the
query that use a literal string argument for the document URI.</p>
<p>For feedback on the impact of document projection in terms of reducing the size of the source document in memory,
use the <code>-t</code> option on the command line, which shows for each document loaded how many nodes from the input
document were retained and how many discarded.</p>
<p>From the s9api API, document projection can be invoked as an option on the <code>DocumentBuilder</code>. The call
<code>setDocumentProjectionQuery()</code> supplies as its argument a compiled query (an <code>XQueryExecutable</code>),
and the document built by the document builder is then projected to retain only the parts of the document that are
accessed by this query, when it operates on this document as the initial context item. For example, if the supplied
query is <code>count(//ITEM)</code>, then only the <code>ITEM</code> elements will be retained.</p>
<p>It is also possible to request that a query should perform document projection on documents that it reads using the
<code>doc()</code> function, provided this has a string-literal argument. This can be requested using the option
<code>setAllowDocumentProjection(true)</code> on the <code>XQueryExpression</code> object. This is not available
directly in the s9api interface, but the <code>XQueryExpression</code> is reachable from the <code>XQueryExecutable</code>
using the accessor method <code>getUnderlyingCompiledQuery()</code>.</p>
<div class="boxed"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">It is best to avoid
supplying a query that actually returns nodes from the document supplied as the context item, since the analysis cannot
know what the invoker of the query will want to do with these nodes. For example, the query <code><out>{//ITEM}</out></code>
works better than <code>//ITEM</code>, since it is clear that all descendants of the <code>ITEM</code> elements must be retained, but
not their ancestors. If the supplied query selects nodes from the input document, then Saxon assumes that the application will
need access to the entire subtree rooted at these nodes, but that it will not attempt to navigate upwards or outwards from these
nodes. On the other hand, nodes that are atomized (for example in a filter) will be retained without their
descendants, except as needed to compute the filter.</div>
<p>The more complex the query, the less likely it is that Saxon will be able to analyze it to determine the subset of
the document required. If precise analysis is not possible, document projection has no effect. Currently Saxon makes
no attempt to analyze accesses made within user-defined functions. Also, of course, Saxon cannot analyze the expectations
of external (Java) functions called from the query.</p>
<p>Currently document projection is supported only for XQuery, and it works only when a document is parsed and loaded
for the purpose of executing a single query. It is possible, however, to use the mechanism to create
a manual filter for source documents if the required subset of the document is known. To achieve this, create
a query that selects the required parts of the document supplied as the context item,
and compile it to a s9api <code>XQueryExecutable</code>. The query
does not have to do anything useful: the only requirement is that the result of the query on the subset document must be the
same as the result on the original document. Then supply this <code>XQueryExecutable</code> to the s9api <code>DocumentBuilder</code>
used to build the document.</p>
<p>Of course, when document projection is used manually like this then it entirely a user responsibility
to ensure that the selected part of the document contains all the nodes required.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="w3c-dtds.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
