SAXON10.SAXONQ(1)

📦 version 10.9, in opensuse-leap 16.0

💖 SAXON10.SAXONQ(1) 💖

okay bestie, so this is the manual page for saxon10q — that's the Saxon XQuery 3.0 processor, living in the User Commands section of the manual, and it's literally about to be your new fave. grab a snack, we're going in 🍓

✨ NAME ✨

saxon10q — the Saxon XQuery 3.0 processor, no cap 👑

🦋 SYNOPSIS 🦋

saxon10q [options] [params]

like, that's it. options, then params, in that order. slay 💅

🌸 DESCRIPTION 🌸

It's a command to run a query contained in a file. simple as that, and yet so powerful 🫶

Saxon 9.8 and later releases implement the XQuery 3.1 Recommendation dated 18 April 2017. and because XQuery 3.1 is backwards compatible with XQuery 1.0 and XQuery 3.0, Saxon will also execute queries written according to the 1.0 or 3.0 versions of the specification. iconic behavior honestly. but — and this is the part where you go "wait what" — Saxon no longer has a mode to execute as an XQuery 1.0 or 3.0 processor (that is, to reject constructs that were not present in earlier versions of the language). so she's not gonna gatekeep old syntax at you. for information about the conformance of Saxon to the XQuery 3.1 specification, and about the handling of implementation-defined features of the specification, see Conformance <https://www.saxonica.com/documentation10/index.html#!conformance>. ✨

Saxon uses the same run-time engine to support both XQuery and XSLT, reflecting the fact that the two languages have very similar semantics. most of the compile-time code (in particular, the type checking logic and the optimizer) is also common. the XQuery support in Saxon consists essentially of an XQuery parser (which is itself an extension of the XPath parser); the parser generates the same internal interpretable code as the XSLT processor. there are also some constructs in the internal expression tree that will only be generated from XQuery source rather than XSLT source — the examples being the XQuery order by and group by clauses, which have no direct XSLT equivalent. main character energy, honestly 💜

The XQuery processor may be invoked either from the operating system command line, or via an API from a user-written application. There is no graphical user interface provided. ngl, terminal girlies stay winning 😭

Saxon is an in-memory processor. unless you can take advantage of streaming, Saxon is designed to process source documents that fit in memory. she's been used successfully to process source documents of 100Mbytes or more without streaming, but if you attempt anything this large, you need to be aware (a) that you will need to allocate sufficient memory to the Java VM (at least 5 times the size of the source document), and (b) that complex FLWOR expressions may be very time-consuming to execute. (in this scenario, Saxon-EE is recommended, because it has a more powerful optimizer for complex joins.) so like… feed her memory or she WILL stress 💀

🎀 OPTIONS 🎀

  • -backup:(on|off) — Only relevant when -update:on is specified. Default is on. 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. 🙈 so maybe keep it on unless you're feeling chaotic
  • -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 <https://www.saxonica.com/documentation10/index.html#!sourcedocs/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. command line stays on top, periodt 👑
  • -dtd:(on|off|recover) — Setting -dtd:on requests DTD-based validation of the source file and of any files read using the doc() function. Requires an XML parser that supports validation. The setting -dtd:off (which is the default) suppresses DTD validation. The setting -dtd:recover performs DTD validation but treats the error as non-fatal if it fails. Note that any external DTD is likely to be read even if not used for validation, because DTDs can contain definitions of entities. lowkey sneaky of them but okay 💅
  • -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] — 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. it's giving behind the scenes and we love that 🔥
  • -ext:(on|off) — If -ext:off is specified, suppress calls on dynamically-loaded external Java functions. This does not affect calls on integrated extension functions, including Saxon and EXSLT extension functions. This option is useful when loading an untrusted query, perhaps from a remote site using an http:// URL; it ensures that the query cannot call arbitrary Java methods and thereby gain privileged access to resources on your machine. 🚨 okay so this one is genuinely a safety girlie — use it, fr fr
  • -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 Configuration programmatically. 🫶
  • -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() and saxon: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. detective mode: activated 🔍
  • -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 the import module declaration in the query prolog, and (if -u is also specified, or if the file name begins with http:, https:, file: or classpath:) to process the URI of the query source file provided on the command line. 💜
  • -now:yyyy-mm-ddThh:mm:ss+hh:mm — Sets the value of current-dateTime() (and implicit-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. time travel but make it QA ✨
  • -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). ⚠️ even if the query fails, bestie — she is not asking permission, so double-check that filename
  • -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
    • 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
    • n: constant folding
    • 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.) so yeah, turning optimization off doesn't fully turn off the chaos 😭

  • -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. gentle parenting your errors, love that for you 🌸
  • -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 val. This may take the values strict, lax, or strip. For example, source.xml?val=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. she literally leaves out what doesn't matter — we stan an efficient queen 💅
  • -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. inline queries are such a flex 🔥
  • -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. pick your exit strategy bestie 🎀
  • -r:classname — ok so this one lets you plug in your own URIResolver, no cap. It's a user-defined class that implements the URIResolver interface from JAXP — its whole job is: take a URI handed to it as a string, hand back a SAX InputSource. Saxon calls it for URIs used in the doc() function, and (if you also passed -u) for the URI of the source file you gave on the command line. 🎀
  • -repeat:integer — runs the transformation N times, where N is the integer you typed. Honestly iconic for performance measurement, because the timings for the first few runs of the query are usually dominated by Java warm-up time. 💅
  • -s:filename-or-URI — this is your input, bestie. Takes 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. The file must contain an XML document, and the document node of that document is what your query gets as the context item. Bonus: you can pass the filename as - to read the source document from standard input — in that case the base URI is that of the current directory. 🦋
  • -sa — invokes a schema-aware query. Requires Saxon-EE to be installed, so like… check you actually have it before you come for me. 👑
  • -scmin:filename — loads a precompiled schema component model from the given file. That file should have been generated in a previous run using the -export option. When you use this option, the -xsd option should not be present. Schemas loaded from an SCM file are assumed to be valid — without checking. 🙈

Heads up though: this option is retained for compatibility. From Saxon 9.7, SCM files can also be supplied in the -xsd option. So it's giving legacy, iykyk.

If the query can't be streamed, execution will fail with diagnostic errors. Also it requires Saxon-EE. No soft-launch, just failure. 💀
  • -strip:(all|none|ignorable) — specifies what whitespace is to be stripped from source documents (and yes, it applies both to the principal source document and to any documents loaded, for example using the doc() function). The default is none: no whitespace stripping. ✨
  • -t — display version and timing information to the standard error output. It also traces the files that are read and written, and extension modules that are loaded. Lowkey the most useful little flag ever. 🔥
  • -T[:classname] — notify query tracing information. Also switches line numbering on for the source document. If a classname is specified, it's 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. That creates an output file giving timings for each instruction executed, and that output file can subsequently be analyzed to give an execution time profile for the query. See Performance Analysis https://www.saxonica.com/documentation10/index.html#!using-xquery/performanceanalysis.

  • -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. Nested stats, she's complicated. 😭
  • -TJ — switches on tracing of the binding of calls to external Java methods. 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. Detective mode fr fr. 🔍
  • -Tlevel:(none|low|normal|high) — controls the level of detail of the tracing produced by the -T option. The values are:
    • none — effectively switches tracing off.
    • low — traces function calls.
    • normal — traces execution of significant expressions such as element constructors.
    • high — traces execution of finer-grained expressions such as the clauses of a FLWOR expression.
  • -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 https://www.saxonica.com/documentation10/index.html#!using-xquery/performanceanalysis. ✨
  • -traceout:filename — indicates that the output of the Ctrace() function should be directed to a specified file. Alternatively, specify #out to direct the output to System.out, #err to send it to System.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. So pick a lane, bestie.
  • -tree:(linked|tiny|tinyc) — selects the implementation of the internal tree model. tiny selects the "tiny tree" model (the default), linked selects the linked tree model, and tinyc selects the "condensed tiny tree" model. See Choosing a tree model https://www.saxonica.com/documentation10/index.html#!sourcedocs/choosingmodel. 🌸
  • -u — indicates that the name of the source document is a URI; otherwise it's taken as a filename, unless it starts with http:, https:, file: or classpath:, in which case it's taken as a URL. Slay, flexible. 💅
  • -update:(on|off|discard) — indicates whether XQuery Update syntax is accepted. Requires Saxon-EE. Let's break it down:
    • on enables XQuery update; any eligible files updated by the query are written back to filestore. A file is eligible for updating if it was read using the doc() or collection() functions using a URI that represents an updateable location. The context document supplied using the -s option is not eligible for updating.
    • off (the default) disables update — any use of XQuery update syntax is an error.
    • discard allows XQuery Update syntax, but modifications made to files are not saved in filestore. If the document supplied in the -s option is updated, the updated document is serialized as the result of the query (writing it to the -o destination); updates to any other documents are simply discarded.
Use of the -t option is recommended: it gives feedback on which files have been updated by the query. Genuinely, don't fly blind on this one. 🫶
  • -val[:(strict|lax)] — requests schema-based validation of the source file and of any files read using the doc() function. 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. 🎀
Without this option, the command effectively wraps a document{} constructor around the supplied query, so the result is a single XML document, which is then serialized. That will fail if the query result includes constructs that cannot be added to a document node in this way — notably free-standing attribute nodes. So like… know your output. 💀
  • -x:classname — use the specified SAX parser for the source file and any files loaded using the doc() function. The parser must be the fully-qualified class name of a Java class that implements the org.xml.sax.XMLReader or javax.xml.parsers.SAXParserFactory interface, and it must be instantiable using a zero-argument public constructor. No weird constructors, ok? 😭
  • -xi:(on|off) — apply XInclude processing to all source XML documents (but not to schema documents). Currently this 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 -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. It 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 the validate{} 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 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 and xsi: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 https://www.saxonica.com/documentation10/index.html#!configuration/config-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. Pick your fave. 💅
  • -? — display command syntax. Simple. Iconic. ✨
  • --? — display a list of features that are available using the --feature:value syntax. The cheat sheet you didn't know you needed. 👑

💬 COMMAND LINE PARAMETERS 💬

okay so a param is literally just name=value — name is the parameter’s name, and value is the parameter’s value. Inside your query these pop up as external variables using the $name syntax, but only if you declared them in the query prolog. No declaration? Then the supplied parameter value is silently ignored — no error, no drama. 🙈

  • leading ? — bestie, this is an XPath expression. So ?time=current-dateTime() sets the external variable $time to the current date and time as an xs:dateTime instance, while ?debug=false() sets $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 that type according to the standard rules for converting function arguments — it does not 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 doc()) is the current directory. The dynamic context contains no context item, no position, no size, and no variables. 🫶
  • leading + — this one is 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. Example: +lookup=lookup.xml sets the external variable lookup to the document node at the root of the tree representing the parsed contents of the file lookup.xml. ✨
  • leading ! — this 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. If you are using the bash shell, you will need to escape ! as \!. 💅
bash bestie alert: that ! escape is real, don’t skip it 🫠

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: https://www.saxonica.com/documentation10/index.html#!extensions/output-extras. 👑

👀 SEE ALSO 👀

💖 AUTHOR 💖

Michael H. Kay <mike@saxonica.com>

xoxo, this was SAXON10.SAXONQ(1) from saxon10 10.9, dated 2023-09-27 — go pass those params, bestie 💅✨

📦 where this page comes from