xquery4 3.1.0

There is a newer version of this package available.
See the version list below for details.
dotnet tool install --global xquery4 --version 3.1.0
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local xquery4 --version 3.1.0
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=xquery4&version=3.1.0
                    
nuke :add-package xquery4 --version 3.1.0
                    

xquery

Command-line XQuery 3.1/4.0 processor for .NET. Query XML documents from the terminal using the PhoenixmlDb XQuery engine.

Installation

dotnet tool install -g xquery4

Usage

# Query an XML file
xquery '//book/title' library.xml

# Count elements
xquery 'count(//item)' catalog.xml

# Read from a query file
xquery -f transform.xq input.xml

# Query a directory of XML files
xquery 'collection()//product[price > 50]' ./data/

# JSON output
xquery -o json 'map { "count": count(//item) }' data.xml

# Read from stdin
cat data.xml | xquery '//item/@name'

# Show execution plan
xquery --plan 'for $x in 1 to 10 return $x * $x'

# Show timing breakdown
xquery --timing '//item' large-catalog.xml

# Validate the input against the schemas the query imports (typed nodes)
xquery --validation strict -f query.xq data.xml

Features

  • XQuery 3.1/4.0 — FLWOR, maps/arrays, higher-order functions, string constructors
  • Multiple output methods — adaptive, XML, text, JSON
  • Context item — input XML is available as . (standard XQuery)
  • Multiple sources — files, directories, URLs, stdin
  • Full prolog support — namespaces, variable/function declarations, serialization options
  • Execution plans — inspect how queries are compiled and optimized
  • Timing — built-in performance profiling

Documentation

Full documentation at phoenixml.dev

License

Apache-2.0

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
3.2.0 75 11/19/2026
3.1.0 121 11/17/2026
3.0.0 137 11/4/2026
2.9.0 251 10/15/2026
2.8.0 124 10/9/2026
2.7.0 119 10/7/2026
2.6.0 144 10/6/2026
2.5.1 137 10/1/2026
2.4.1 137 9/28/2026
2.4.0 117 9/28/2026
2.2.0 786 9/25/2026
2.1.0 127 9/17/2026
2.0.0 137 9/15/2026
1.8.0 150 9/14/2026 1.8.0 is deprecated because it has critical bugs.
1.7.0 149 9/11/2026 1.7.0 is deprecated because it has critical bugs.
1.6.15 151 9/9/2026 1.6.15 is deprecated because it has critical bugs.
1.6.14 154 9/7/2026 1.6.14 is deprecated because it has critical bugs.
1.6.13 139 9/4/2026 1.6.13 is deprecated because it has critical bugs.
1.6.12 147 9/1/2026 1.6.12 is deprecated because it has critical bugs.
1.6.11 153 8/29/2026 1.6.11 is deprecated because it has critical bugs.
Loading failed

A security update for hosts that compile or run untrusted queries, and a new opt-in execution limit.
Requires PhoenixmlDb.Core 2.6.0.

### New: a limit on the length of a built string

`QueryExecutionLimits.MaxStringLength` (`int?`, default `null`: no limit) sets the longest string,
in UTF-16 code units, that one operation may build. An operation that goes past it fails with
`FOER0000`, the code of the other execution limits; a query can catch it with `try`/`catch`.

- It applies to `fn:concat`, `fn:string-join`, the `||` operator, string constructors,
 `fn:codepoints-to-string`, `fn:replace`, `fn:serialize`, `fn:xml-to-json`, `fn:upper-case`,
 `fn:lower-case`, `fn:encode-for-uri`, `fn:escape-html-uri`, `fn:iri-to-uri`,
 `fn:normalize-unicode`, and the text that node constructors join.
- `fn:string-join`, `fn:replace`, string constructors and node constructors stop before the
 string passes the limit, so they do not allocate the full string.
- The limit is per string, not per query. `MaxResultItems` limits materialized sequences.
- `QueryExecutionContext.CheckStringLength(long)` applies the same limit in host code and
 extension functions.

A time limit alone cannot stop an expression that builds a very large string from no input. A
host that runs untrusted queries sets both.

### Security: import location hints with no base URI (GHSA-52r3-6pq9-42m5)

Only hosts that compile queries from untrusted parties are affected.

- **A relative import location hint with no base URI is not resolved against the working
 directory.** In a query compiled with no base URI:
 - `import schema ... at 'x.xsd'` gives XQST0059, with and without a `ResourcePolicy`. Under a
   policy whose file roots hold the working directory, 3.0.0 resolves the hint against the
   working directory and reads the file there.
 - `import module ... at 'm.xqm'` gives XQST0059, with and without a `ResourcePolicy`. 3.0.0 reads
   `m.xqm` from the working directory: with no policy, and under a policy whose file roots hold
   the working directory.

 With a base URI, a relative hint resolves against it. A host that compiles a query with no
 base URI and imports a module or schema from the working directory by a relative hint gives the
 working directory as the base URI (`CompilationOptions.BaseUri`). The `xquery` CLI does this.
 A location that the host maps (`ExternalModuleLocations`, `ExternalModules`) or supplies through
 its resource resolver does not change.

### Also in this release

- **A prefixed name parses in linear time** (#363): a query with 10,000 calls such as `fn:abs(1)`
 compiles in 0.19 s.
- **A sequence of long paths compiles** (#360): the sum of the cardinality estimates is clamped,
 so the cost model does not overflow.
- **The library builds with .NET SDK 10.0.401 and later** under warnings as errors: three
 `default(T)` expressions that IDE0034 reports are simplified. No compiled code changes.

### `xquery` CLI (ships on `cli-v3.1.0`)

- Runs on **PhoenixmlDb.XQuery 3.1.0** and **PhoenixmlDb.Xslt 3.1.0**, so it includes the
 fixes above and `fn:transform` from a query gets the 3.1.0 engine.
- Includes the fix for GHSA-52r3-6pq9-42m5 (see above).