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 parameters. If the last option before the parameters
has no leading hyphen and option letter then it is recognized as the -q
option.
Command line options
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 Using 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 Initializer; this
initializer will be called during the initialization process, and may be used to
set any options required on the |
-l[:(on|off)] |
If |
-mr:classname |
Use the specified |
-now:yyyy-mm-ddThh:mm:ss+hh:mm |
Sets the value of |
-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:[-]flags |
Allows individual optimizations to be enabled or disabled selectively. There is a set of single-letter flags identifying particular optimizations (c: generate bytecode; f: inline functions; g: extract global variables; j: just-in-time compilation (currently XSLT-only); k: create keys; l: loop lifting; m: miscellaneous; r: template rule-sets (not relevant to XQuery); s: extract common subexpressions; v: inline variables; w: create switch statements; x: index predicates). A value such as opt:gs runs with only the selected optimizations; opt:-gs runs with the selected optimizations disabled and all others enabled. The value opt:0 suppresses all optimizations. 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 PTreeURIResolver. This option is available in Saxon-EE only. It cannot be
used in conjunction with the |
-pipe:(push|pull) |
Ignored; will be dropped in a future release. |
-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. |
-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). The base
URI of the query is taken from the current working directory. So, for
example, |
-quit:(on|off) |
With the default setting, |
-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. |
-scmin:filename |
Loads a precompiled schema component model from the given file. The file should be
generated in a previous run using the
This option is retained for compatibility. From Saxon 9.7, SCM files can also be
supplied in the |
-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. |
-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 TraceListener. If the classname is omitted, a system-supplied trace
listener is used. This traces execution of function calls to the standard error
output. For performance profiling, set
classname to |
-TB:filename |
Monitors generation of hot-spot bytecode and produces an XML report on the given filename giving, for each expression that was a candidate for bytecode generation and that was actually executed, data about the number of times and speed of execution in the interpreter, the number of times and speed of execution in compiled form, and the cost of compilation. Note that if an expression A contains an expression B and both are candidates for bytecode generation, then the statistics for B relate only to the time before A was compiled in its own right. |
-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 query, or why it chooses one method over another when several are available. |
-TP:filename |
This is equivalent to setting
|
-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 |
-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 the specified SAX parser for the source file and any files loaded using the
|
-xi:(on|off) |
Apply XInclude processing to all source XML documents (but not to schema 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 |
Command line parameters
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.