Saxon documentation (original) (raw)
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] [ _params..._]
For SaxonCS, there are two ways of running queries from the command line. If you download SaxonCS as an executable application from theSaxonica download page, then you can run a query with the command:
SaxonCS query [options] [ _params..._]
But if you install SaxonCS as a nuget package then you need to prefix the command with dotnet, like this:
dotnet SaxonCS query [options] [ _params..._]
For SaxonC, the query executable file must first be built. To do this, compile the Query.c C command line program by running the batch script./build64-linux.sh on Linux,./build64-mac.sh on MacOS, orbuild-windows.bat on Windows.
Then the command takes the form:
./query [options] [ _params..._]
The options will generally include either -q:queryFile which takes the query from a file, or -qs:query in which the query appears directly in the command line (usually in quotes).
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 -update:on is specified. Default ison. When backup is enabled, any file that is updated by the query will be preserved in its original state by renaming it, adding ".bak" to the original filename. If backup is disabled, updated files will be silently overwritten. |
|---|---|
| -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. |
| -dtd:(on|off | recover) |
| -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-expand:off suppresses this. (In the case of DTD-defined defaults, this might not work with all XML parsers. It does work with the Xerces parser (default for Java) and the Microsoft parser (default for .NET).) |
| -explain[:filename] | Traces expression rewrites made by the optimizer, followed by a representation of the final expression tree after optimization. If no file name is specified the output is sent to the standard error stream. The output is in XML format. Equivalent to setting the configuration option TRACE_OPTIMIZER_DECISIONS and then calling the explain() method of the XQueryExecutable. |
| -ext:(on|off) | If ext:off is specified, suppress access to certain external resources. Specifically it sets the configuration option ALLOW_EXTERNAL_FUNCTIONS, whose effect is rather wider than the name suggests. This option is useful when loading an untrusted query, perhaps from a remote site using anhttp:// URL; it ensures that the query cannot call arbitrary Java methods and thereby gain privileged access to resources on your machine. |
| -init:initializer | The value identifies user-supplied code that is called during the initialization process, and may be used to set any options required on the Saxon configuration. For SaxonJ, the value is the name of a user-supplied class that implements the interface Initializer. The class must be on the classpath. For SaxonCS, the value is the filename of a user-written assembly that contains an implementation of the interface Saxon.Api.IProcessorInitializer. For details see Callbacks. |
| -json:file-name | Selects a JSON file to act as the primary input of the query. The file is parsed (typically producing a map or array) following the rules of the json-doc function, and the resulting item becomes the initial context item for the query. This option cannot be combined with -s. |
| -l[:(on|off)] | If -l or -l:on is specified, causes line and column numbers to be maintained for source documents. These are accessible using the extension functions saxon:line-number() andsaxon:column-number(). Line numbers are useful when the purpose of the query is to find errors or anomalies in the source XML file. Without this option, line numbers are available while source documents are being parsed and validated, but they are not retained in the tree representation of the document. |
| -mr:classname | Use the specified ModuleURIResolver to process all query module URIs. The ModuleURIResolver is a user-defined class that implements the ModuleURIResolver interface. It is invoked to process URIs used in theimport module declaration in the query prolog, and (if-u is also specified, or if the file name begins withhttp:, https:, file: orclasspath:) to process the URI of the query source file provided on the command line. |
| -ns:(uri|##any | ##html5) |
| -now:yyyy-mm-ddThh:mm:ss+hh:mm | Sets the value of current-dateTime() (andimplicit-timezone()) for the query. This is designed for testing, to enable repeatable results to be obtained for comparison with reference results, or to test that queries can handle significant dates and times such as end-of-year processing. |
| -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 -wrap option is present. The file is created if it does not already exist; any necessary directories will also be created. If the file does exist, it is overwritten (even if the query fails). |
| -opt:[-]flags | Allows individual optimizations to be enabled or disabled selectively. There is a set of single-letter flags identifying particular optimizations: c: (no longer used) d: detect void path expressions e: cache regular expressions f: inline functions g: extract global variables j: just-in-time compilation of template rules (currently XSLT-only) k: create keys l: loop lifting m: miscellaneous (see below) n: constant folding p: predicate reordering r: template rule-sets (not relevant to XQuery) s: extract common subexpressions t: tail call optimization 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.) The -m (miscellaneous) flag is a prerequisite for some of the more specific optimizations. |
| -outval:(recover|fatal) | Normally, if validation of result documents is requested, a validation error is fatal. Setting the option -outval:recover causes such validation failures to be treated as warnings. The validation message is written both to the standard error stream, and (where possible) as a comment in the result document itself. |
| -p[:(on|off)] | Enable recognition of query parameters (such as xinclude=yes) in the StandardURIResolver. This option is available in Saxon-PE and Saxon-EE only. It cannot be used in conjunction with the -r option, and it automatically switches on the -u and -sa options. The effect is that Saxon-specific query parameters are recognized in a URI. One query parameter that is recognized is validation. This may take the valuesstrict, lax, or strip. For example,source.xml?validation=strict loads a document with strict schema validation. |
| -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. If this is the last option then the-q: prefix may be omitted. The file can be specified as "-" to read the query from standard input: in this case the base URI is that of the current directory. |
| -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 static base URI of the query is taken from the current working directory. So, for example, java net.sf.saxon.Query -qs:doc('a.xml')//p[1] selects elements within the file a.xml in the current directory. |
| -quit:(on|off) | With the default setting, on, the command will quit the Java VM and return an exit code if a failure occurs. This is useful when running from an operating system shell. With the setting quit:off the command instead throws a RunTimeException, which is more useful when the command is invoked from another Java application such as Ant. |
| -qversion:(3.1|4.0) | Defines the XQuery specification version to be used, in the absence of a version declaration in the query itself. The default is 3.1, and this is the only permitted value for Saxon-HE. The value 4.0 enables features defined in the draft XQuery 4.0 family of specifications, which should be regarded as experimental and subject to change. |
| -r:classname | Use the specified URIResolver to process all URIs. TheURIResolver is a user-defined class, that implements theURIResolver interface defined in JAXP, whose function is to take a URI supplied as a string, and return a SAX InputSource. It is invoked to process URIs used in the doc() function, and (if -u is also specified) to process the URI of the source file provided on the command line. |
| -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 -u option is specified, or if the name begins with "file:" or "http:", then the name is assumed to be a URI rather than a filename. This file must contain an XML document. The document node of the document is made available to the query as the context item. The filename can be specified as "-" to read the source document from standard input: in this case the base URI is that of the current directory. |
| -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 -export option. When this option is used, the -xsd option should not be present. Schemas loaded from an SCM file are assumed to be valid, without checking. This option is retained for compatibility. From Saxon 9.7, SCM files can also be supplied in the -xsd option. |
| -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) |
| -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 net.sf.saxon.trace.TimingTraceListener. This creates an output file giving timings for each instruction executed. This output file can subsequently be analyzed to give an execution time profile for the query. SeePerformance analysis. |
| -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. |
| -Tlevel:none|low | normal |
| -Tout:filename | Directs the output of tracing to a specified file (assuming that -T is enabled). |
| -TP:filename | This is equivalent to setting-T:net.sf.saxon.trace.TimedTraceListener and-traceout:filename; that is, it causes trace profile information to be set to the specified file. This output file can subsequently be analyzed to give an execution time profile for the query. See Performance analysis. |
| -TPxsl:filename | Supplies a stylesheet for formatting the performance data generated by the-TP option, allowing it to be output in XML or JSON format rather than HTML. See Performance analysis. |
| -traceout:filename | Indicates that the output of the trace() function should be directed to a specified file. Alternatively, specify #out to direct the output to System.out, #err to send it toSystem.err (the default), or #null to have it discarded. This option is ignored when a trace listener is in use: in that case,trace() output goes to the registered trace listener. |
| -tree:(linked|tiny | tinyc) |
| -u | Indicates that the name of the source document is a URI; otherwise it is taken as a filename, unless it starts with http:, https:,file: or classpath:, in which case it is taken as a URL. |
| -update:(on|off | discard) |
| -val[:(strict|lax)] | Requests schema-based validation of the source file and of any files read using the doc() function. This option is available only with Saxon-EE, and it automatically switches on the -sa option. Specify-val or -val:strict to request strict validation, or-val:lax for lax validation. |
| -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 adocument{} constructor around the supplied query, so that the result is a single XML document, which is then serialized. This will fail if the query result includes constructs that cannot be added to a document node in this way, notably free-standing attribute nodes. |
| -x:classname | Use the specified SAX parser for the source file and any files loaded using thedoc() function. The parser must be the fully-qualified class name of a Java class that implements the org.xml.sax.XMLReader orjavax.xml.parsers.SAXParserFactory interface, and it must be instantiable using a zero-argument public constructor. |
| -xi:(on|off) | Apply XInclude processing to all XML documents. This relies on XInclude support in the XML parser. The option affects documents read using functions such as doc(), document(), and collection() as well as the primary input document. It also affects schema documents. |
| -xmlversion:(1.0|1.1) | If -xmlversion:1.1 is specified, allows XML 1.1 and XML Namespaces 1.1 constructs. This option must be set if source documents using XML 1.1 are to be read, or if result documents are to be serialized as XML 1.1. This option also enables use of XML 1.1 constructs within the query itself. |
| -xsd:file1;file2;file3... | Loads additional schema documents. The declarations in these schema documents are available when validating source documents (or for use by thevalidate{} expression). This option may also be used to supply the locations of schema documents that are imported into the query, in the case where the import schema declaration gives the target namespace of the schema but not its location. |
| -xsdversion:(1.0|1.1) | If -xsdversion:1.1 is specified (the default), allows schema documents using XML Schema 1.1 to be read, and permits XML Schema 1.1 constructs such as assertions. |
| -xsiloc:(on|off) | If set to on (the default) the schema processor attempts to load any schema documents referenced in xsi:schemaLocation andxsi:noNamespaceSchemaLocation attributes in the instance document, unless a schema for the specified namespace (or non-namespace) is already available. If set to off, these attributes are ignored. |
| --feature:value | Set a feature defined in the Configuration interface. The names of features are defined in the Javadoc for class Feature (alternatively see Configuration features): the value used here is the part of the name after the last "/", for example --allow-external-functions:off. Only features accepting a string or boolean may be set; for booleans the values true/false, on/off, yes/no, and 1/0 are recognized. |
| -? | Display command syntax. Note: under some shell languages, this needs to be escaped as -\?. |
| --? | Display a list of features that are available using the --feature:value syntax. Note: under some shell languages, this needs to be escaped as --\?. |
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 thedoc() 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 variablelookup 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.