xquery4 2.4.0

There is a newer version of this package available.
See the version list below for details.
dotnet tool install --global xquery4 --version 2.4.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 2.4.0
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=xquery4&version=2.4.0
                    
nuke :add-package xquery4 --version 2.4.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

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
2.6.0 42 10/6/2026
2.5.1 81 10/1/2026
2.4.1 82 9/28/2026
2.4.0 63 9/28/2026
2.2.0 284 9/25/2026
2.1.0 74 9/17/2026
2.0.0 75 9/15/2026
1.8.0 85 9/14/2026
1.7.0 79 9/11/2026
1.6.15 78 9/9/2026
1.6.14 95 9/7/2026
1.6.13 82 9/4/2026
1.6.12 81 9/1/2026
1.6.11 87 8/29/2026
1.6.10 87 8/29/2026
1.6.9 81 8/27/2026
1.6.8 79 8/26/2026
1.6.7 89 8/24/2026
1.6.6 85 8/23/2026
1.6.5 90 8/21/2026
Loading failed

Takes **PhoenixmlDb.Core 2.0.0** (unchanged).

### Fixed: typed results the conformance harness used to hide (#83, #85)

Before #49 the QT3 harness counted any `assert-type` it didn't recognise as a pass. Once it
checked for real, six engine defects showed up that had passed by default:

| | was | now |
|---|---|---|
| `fn:namespace-uri` | `xs:string` | `xs:anyURI` |
| `fn:prefix-from-QName` | `xs:string` | `xs:NCName` |
| `fn:default-language` | `xs:string` | `xs:language` |
| `map:put` with an equal key of another type | kept the old key | replaces key and value, same position |
| `xs:short(256) cast as xs:numeric` | lost `xs:short` | keeps it |
| `schema-element(unbound:x)` | `XPST0008` | `XPST0081` |

The new types reach code that had only seen plain strings, so these were fixed at the root: one
rule for `xs:string` arguments means `string-to-codepoints`, `codepoint-equal` and
`encode-for-uri` accept `xs:anyURI` and string subtypes, and string constructors accept a
string-subtype source.

### Behaviour changes — read before upgrading

- **`fn:namespace-uri` returns `xs:anyURI`.** Code that tests its result `instance of xs:string`
 gets a different answer.
- **`fn:distinct-values` treats an `xs:anyURI` and an equal `xs:string` as one value**, matching
 this engine's own `eq` and XPath 4.0. This reverses an earlier choice whose spec citation
 didn't hold up.
- **Default output renders `xs:anyURI`, `xs:untypedAtomic` and string subtypes bare**, the same
 way a plain `xs:string` already rendered. Without this, every `namespace-uri()` result
 printed through the facade would have gained quotes. A query that declares
 `output:method "adaptive"` still gets the quoted W3C form.

### Conformance

**W3C QT3: 29,895 / 31,379 (95.27%)**, measured on the release commit. The denominator is
unchanged. #85's per-case diff shows 14 cases newly passing and none newly failing: that fully
recovers the nine the harness correction exposed, plus five more.

The ratchet in `scripts/conformance-baseline.tsv` is raised to this measurement. It hadn't been
raised since before 2.2.0, so part of the raise (+91 across 19 sets) is earlier work that was
never recorded, for example 2.2.0's `xs:IDREFS` cast targets. It is not all this release.

### `xquery` CLI (ships on `cli-v2.4.0`)

- **Output methods: `html` and `xhtml` are supported, and an unrecognised method is now an error**
 (#87). Before this, `-o html`, `declare option output:method "html"` and any typo all silently
 fell back to adaptive output with exit code 0. Now `-o` accepts `adaptive`, `xml`, `html`,
 `xhtml`, `text` and `json`; any other value exits with code 1, and an unknown method in the
 prolog raises `SEPM0016`. **Scripts that relied on the silent fallback will now fail visibly.**
- **Output is UTF-8 on every platform** (#80; no earlier CLI release carried it). On
 Windows it used to follow the console's legacy code page, which corrupted non-ASCII characters
 in redirected output.
- Runs on PhoenixmlDb.Xslt 2.4.0 for `fn:transform`, so `source-location` and raw delivery of
 constructed nodes both work from a query.

### Upgrading

`PhoenixmlDb.Xslt` 2.4.0 needs its own fix for this change (xslt#188, promoting `xs:anyURI` to
`xs:string` for stylesheet-function parameters). Without it, a stylesheet function receiving
`namespace-uri()` fails. Take the two packages together; the lockstep pins enforce that.

**2.3.0 carried no library change** (it was byte-identical to 2.2.0, a lockstep bump that was
published and then superseded). Moving from 2.2.0 or earlier straight to 2.4.0 is the intended
path.