Running XQuery from the Command Line
A command is available to run a query contained in a file. The form of command on the Java platform is:
java net.sf.saxon.Query [options] -q:queryfile [ params...]On the .NET platform, the command is simply:
Query [options] -q:queryfile [ params...]The options must come first, then the params. If the last option before the params has no
leading hyphen and option letter then it is recognized as the -q
option.
The options are as follows (in any order). Square brackets indicate an optional value.
-backup:(on|off) |
Only relevant when |
-catalog:filenames |
Filenames is either a file name or a list of file names separated by semicolons; the files are OASIS XML catalogs used to define how public identifiers and system identifiers (URIs) used in a source document, query, or schema are to be redirected, typically to resources available locally. For more details see XML catalogs. |
-config:filename |
Indicates that configuration information should be taken from the supplied configuration file. Any options supplied on the command line override options specified in the configuration file. |
-cr:classname |
Use the specified |
-dtd:(on|off|recover) |
Setting |
-expand:(on|off) |
Normally, if validation using a DTD or schema is requested, any fixed or default
values defined in the DTD or schema will be expanded. Specifying
|
-explain[:filename] |
Display a query execution plan. This is a representation of the expression tree after rewriting by the optimizer. If no file name is specified the output is sent to the standard error stream. The output is a tree in XML format. |
-ext:(on|off) |
If |
-init:initializer |
The value is the name of a user-supplied class that implements the interface |
-l[:(on|off)] |
If |
-mr:classname |
Use the specified |
-o:filename |
Send output to named file. In the absence of this option, the results go to
standard output. The output format depends on whether the |
-opt:0...10 |
Set optimization level. The value is an integer in the range 0 (no optimization) to 10 (full optimization); currently all values other than 0 result in full optimization but this is likely to change in future. The default is full optimization; this feature allows optimization to be suppressed in cases where reducing compile time is important, or where optimization gets in the way of debugging, or causes extension functions with side-effects to behave unpredictably. (Note however, that even with no optimization, lazy evaluation may still cause the evaluation order to be not as expected.) |
-outval:(recover|fatal) |
Normally, if validation of result documents is requested, a validation error is
fatal. Setting the option |
-p[:(on|off)] |
Use the |
-pipe:(push|pull) |
Execute query internally in push or pull mode. Default is push. This may give performance advantages for certain kinds of query, especially queries that construct intermediate trees in memory. In practice when the output is serialized there is usually little difference, and the option is there mainly for testing. |
-projection:(on|off) |
Use (or don't use) document projection. 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. Requires Saxon-EE. |
-stream:(on|off) |
Use (or don't use) streaming. Streaming allows simple queries to be executed while the source document is being read, avoiding the need to build a tree representation of the document in memory. For information about the kind of queries that can be streamed, see Streaming XQuery. If the query cannot be streamed, execution will fail with diagnostic errors. Requires Saxon-EE. |
-q:queryfile |
Identifies the file containing the query. The file can be specified as "-" to read
the query from standard input. If this is the last option then the
|
-qs:querystring |
Allows the query to be specified inline (if it contains spaces, you will need
quotes around the expression to keep the command line processor happy). For
example |
-quit:(on|off) |
With the default setting, |
-qversion:(1.0|3.0) |
Specifies the XQuery language version supported. Default is "1.0". The value "3.0" is currently only available with Saxon-EE. It supports a fairly small subset of the features from the draft XQuery 3.0 specification (originally published as XQuery 1.1 but due to be renamed). |
-r:classname |
Use the specified |
-repeat:integer |
Performs the transformation N times, where N is the specified integer. This option is useful for performance measurement, since timings for the first few runs of the query are often dominated by Java warm-up time. |
-s:filename-or-URI |
Take input from the specified file. If the |
-sa |
Invoke a schema-aware query. Requires Saxon-EE to be installed. |
-strip:(all|none|ignorable) |
Specifies what whitespace is to be stripped from source documents (applies both to
the principal source document and to any documents loaded for example using the
|
-t |
Display version and timing information to the standard error output. The output also traces the files that are read and written, and extension modules that are loaded. |
-T[:classname] |
Notify query tracing information. Also switches line numbering on for the source
document. If a classname is specified, it is a user-defined class, which must
implement |
-TJ |
Switches on tracing of the binding of calls to external Java methods. This is useful when analyzing why Saxon fails to find a Java method to match an extension function call in the stylesheet, or why it chooses one method over another when several are available. |
-traceout:filename |
Indicates that the output of the |
-tree:(linked|tiny|tinyc) |
Selects the implementation of the internal tree model. |
-u |
Indicates that the name of the source document is a URI; otherwise it is taken as a filename, unless it starts with "http:" or "file:", in which case they it is taken as a URL. |
-update:(on|off|discard) |
Indicates whether XQuery Update syntax is accepted. This option requires Saxon-EE.
The value |
-val[:(strict|lax)] |
Requests schema-based validation of the source file and of any files read using
the |
-wrap |
Wraps the result sequence in an XML element structure that indicates the type of
each node or atomic value in the query result. This format can handle any type of
query result. In the absence of this option, the command effectively wraps a
|
-x:classname |
Use specified SAX parser for source file and any files loaded using the
|
-xi:(on|off) |
Apply XInclude processing to all input XML documents (including schema documents as well as source documents). This currently only works when documents are parsed using the Xerces parser, which is the default in JDK 1.5 and later. |
-xmlversion:(1.0|1.1) |
If |
-xsd:file1;file2;file3... |
Loads additional schema documents. The declarations in these schema documents are
available when validating source documents (or for use by the
|
-xsdversion:(1.0|1.1) |
If |
-xsiloc:(on|off) |
If set to |
--feature:value |
Set a feature defined in the |
-? |
Display command syntax |
A param takes the form name=value
, name being the name of the
parameter, and value the value of the parameter. These parameters are accessible
within the query as external variables, using the $name
syntax, provided they
are declared in the query prolog. If there is no such declaration, the supplied parameter
value is silently ignored.
A param preceded by a leading question mark (?
) is interpreted as an
XPath expression. For example, ?time=current-dateTime()
sets the value of the
external variable $time
to the value of the current date and time, as an
instance of xs:dateTime
, while ?debug=false()
sets the value of
the variable $debug
to the boolean value false
. If the parameter
has a required type (for example declare variable $p as xs:date external;
),
then the supplied value must be compatible with this type according to the standard rules
for converting function arguments (it doesn't need to satisfy the stricter rules that apply
to variable initialization). The static context for the XPath expression includes only the
standard namespaces conventionally bound to the prefixes xs
, fn
,
xsi
, and saxon
. The static base URI (used when calling the
doc()
function) is the current directory. The dynamic context contains no
context item, position, or size, and no variables.
A param preceded by a leading plus sign (+
) is interpreted as a
filename or directory. The content of the file is parsed as XML, and the resulting document
node is passed to the stylesheet as the value of the parameter. If the parameter value is a
directory, then all the immediately contained files are parsed as XML, and the resulting
sequence of document nodes is passed as the value of the parameter. For example,
+lookup=lookup.xml
sets the value of the external variable
lookup
to the document node at the root of the tree representing the parsed
contents of the file lookup.xml
.
A param preceded by a leading exclamation mark (!
) is interpreted as a
serialization parameter. For example, !indent=yes
requests indented output,
and !encoding=iso-8859-1
requests that the serialized output be in ISO 8859/1
encoding. This is equivalent to specifying the option declaration declare option
saxon:output "indent=yes";
or declare option saxon:output
"encoding=iso-8859-1";
in the query prolog.
Under Windows, and some other operating systems, it is possible to supply a value
containing spaces by enclosing it in double quotes, for example name="John
Smith"
. This is a feature of the operating system shell, not something Saxon
does, so it may not work the same way under every operating system.
If the parameter name is in a non-null namespace, the parameter can be given a value using
the syntax {uri}localname=value
. Here uri
is the namespace URI of
the parameter's name, and localname
is the local part of the name.
This applies also to output parameters. For example, you can set the indentation level to 4
by using the parameter !{http://saxon.sf.net/}indent-spaces=4
. In this case,
however, lexical QNames using the prefix saxon
are also recognized, for
example !saxon:indent-spaces=4
. For the extended set of output parameters
supported by Saxon, see Additional
serialization parameters.