| SAXONICA |
The rules that determine whether a path expression can be streamed are:
The expression to be streamed starts
with a call on the document() or doc() function.
The path expression introduced by the call on doc() or document must conform
to a subset of XPath defined as follows:
any XPath expression is acceptable if it conforms to the rules for path expressions appearing in identity constraints in XML Schema. These rules allow no predicates; the first step (but only the first) can be introduced with "//"; the last step can optionally use the attribute axis; all other steps must be simple Axis Steps using the child axis.
In addition, Saxon allows the expression to contain a union, for example doc()/(*/ABC | */XYZ).
Unions can also be expressed in abbreviated form, for example
the above can be written as doc()/*/(ABC|XYZ).
The expression must either select elements only, or attributes only, or a mixture of elements and attributes.
Simple filters (one or more) are also supported. Each filter may apply to the last step or to the expression as a whole, and it must only use downward selection from the context node (the self, child, attribute, descendant, descendant-or-self, or namespace axes). It must not be positional (that is, it must not reference position() or last(), and must not be numeric: in fact, it must be such that Saxon can determine at compile time that it will not be numeric). Filters cannot be applied to unions or to branches of unions. Any violation of these conditions causes the expression to be evaluated without the streaming optimization.
These rules apply after other optimization rewrites have been applied to the expression. For example, some FLWOR expressions may be rewritten to a path expression that satisfies these rules.
The optimization is enabled only if explicitly requested, either by using the saxon:stream()
extension function, or the saxon:read-once attribute on anXSLT xsl:copy-of instruction,
or the XQuery pragma saxon:stream. It is available only if the stylesheet or query is processed
using Saxon-SA.
If the path expression cannot be evaluated in streaming mode, execution does not fail; rather it is evaluated with an unoptimized copy-of instruction. This will give the same results provided enough memory is available for this mode of evaluation.
The facility should not be used if the source document is read more than once in the course
of the query/transformation. There are two reasons for this: firstly, performance will be better in this case if the
document is read into memory; and secondly, when this optimization is used, there is no guarantee that the
doc() function will be stable, that is, that it will return the same results when called
repeatedly with the same URI.
