Tools
xquery CLI
Command-line XQuery processor — query XML documents from the terminal
#xquery CLI
The xquery command-line tool executes XQuery expressions against XML files, directories, or URLs. Think of it as jq for XML — but with the full power of XQuery 4.0.
#Installation
dotnet tool install -g xquery4
After installation, the xquery command is available globally.
#Usage
xquery [options] <expression> [sources...]
xquery [options] -f <query-file> [sources...]
command | xquery [options] <expression>
#Arguments
|
Argument |
Description |
|---|---|
|
|
Inline XQuery expression to execute |
|
|
XML files, directories, or URLs to query |
#Options
|
Option |
Short |
Description |
|---|---|---|
|
|
|
Read XQuery from a file instead of inline |
|
|
|
Output method: |
|
|
Read XML input from stdin (waits indefinitely) |
|
|
|
Stdin auto-detection timeout in ms (default: 200) |
|
|
|
Show parse/compile/execute timing breakdown |
|
|
|
Show the execution plan before running |
|
|
|
Parse and compile only — validate without executing |
|
|
|
|
Show detailed error information |
|
|
|
Show help message |
|
|
Show version information |
#Exit Codes
|
Code |
Meaning |
|---|---|
|
0 |
Success |
|
1 |
Usage error, or a source that cannot be loaded |
|
2 |
Parse error |
|
3 |
Runtime error |
A source that cannot be loaded writes one line, Error: Cannot load source '<s>': <reason>, and
exits with code 1. --verbose adds the stack trace.
#Source Documents
The xquery tool supports these types of source input:
|
Source |
Description |
|---|---|
|
XML file |
Loaded as a document, a |
|
JSON file ( |
Loaded as its map or array, as |
|
Directory |
All |
|
URL |
HTTP/HTTPS URL — XML fetched from the network |
|
stdin |
Read as JSON when it starts with |
The first source is the context item (.), so you can write a path directly:
xquery '//title' books.xml
xquery '?items?*?name' data/a.json
All sources are available via doc($uri) by their path or URL. collection() returns the
loaded documents, then the JSON items.
#Examples
#Quick Queries
The most common use — XPath expressions against a file:
# Select all titles
xquery '//title' catalog.xml
# Count elements
xquery 'count(//product)' catalog.xml
# Filter by attribute
xquery '//product[@category="electronics"]/name' catalog.xml
# Get attribute values
xquery '//product/@id' catalog.xml
C# developer note: This is like running LINQ queries from the command line — no project setup, no compilation, just query and get results.
#FLWOR Queries
Use single quotes to wrap multi-line expressions:
xquery '
for $book in //book
where $book/price > 30
order by $book/price descending
return concat($book/title, " — $", $book/price)
' catalog.xml
#Query Files
For complex queries, write them in a .xq file:
xquery -f report.xq catalog.xml
report.xq:
for $cat in distinct-values(//product/@category)
let $products := //product[@category = $cat]
order by $cat
return <category name="{ $cat }">
<count>{ count($products) }</count>
<avg-price>{ format-number(avg($products/price), '#.00') }</avg-price>
</category>
#Multiple Source Files
Query across multiple documents:
# Multiple files
xquery 'count(collection()//product)' products.xml orders.xml
# An entire directory
xquery 'collection()//error' ./logs/
# Join data across files
xquery '
for $order in doc("orders.xml")//order
let $customer := doc("customers.xml")//customer[@id = $order/@customer-id]
return concat($order/@id, ": ", $customer/name)
' orders.xml customers.xml
#Reading from stdin
Pipe XML from another command:
curl https://api.example.com/data.xml | xquery '//item/name'
cat data.xml | xquery 'count(//error)'
#JSON Output
Use --output json (or -o json) to serialize maps and arrays as JSON instead of the default adaptive output:
xquery -o json 'map { "name": "test", "count": 42 }'
xquery -f query-with-json-option.xq data.xml
The second form works because --output json is also auto-detected from a declare option output:method "json" declaration in the query file. When that option is present, the CLI picks up the serialization method without requiring an explicit flag.
An unrecognised method is an error, on the command line or in the prolog: -o htm exits with
code 1, and declare option output:method "htm" raises SEPM0016. Before 2.4.0, both silently
fell back to adaptive output and exited 0, so a typo produced wrong output that looked like
success. Scripts that relied on that fallback now fail visibly.
For more complex results:
xquery '
array {
for $p in //product
return map {
"name": string($p/name),
"price": number($p/price)
}
}
' catalog.xml
#Working with JSON Input
Query JSON files using json-doc(). A JSON object is a map and a JSON array is an array, so
? selects from them. A relative path is resolved against the current directory.
xquery '
let $data := json-doc("config.json")
return $data?settings?theme
'
Given orders.json:
{"orders":[{"id":1,"total":12.5},{"id":2,"total":30}]}
# Sum a field over all array members
xquery 'sum(json-doc("orders.json")?orders?*?total)'
# 4.25e1 (JSON numbers are xs:double)
# JSON and XML in one query
xquery 'count(json-doc("orders.json")?orders?*) || " orders, " || count(doc("catalog.xml")//product) || " products"'
Several JSON files, with data/a.json = {"items":[{"name":"pen","price":2.5},{"name":"ink","price":7}]}
and data/b.json = {"items":[{"name":"pad","price":4}]}:
# One name per line, from every file
xquery 'for $f in ("data/a.json", "data/b.json") return json-doc($f)?items?*?name'
# pen
# ink
# pad
# Filter across files
xquery 'for $f in ("data/a.json", "data/b.json"), $i in json-doc($f)?items?*
where $i?price > 3
return $i?name || " " || $i?price'
# ink 7
# pad 4
# Merge the items of every file into one JSON array
xquery -o json 'array { for $f in ("data/a.json", "data/b.json") return json-doc($f)?items?* }'
# [{"name":"pen","price":2.5},{"name":"ink","price":7},{"name":"pad","price":4}]
Every JSON file in a folder, with a.json in data/ and b.json in data/sub/: give the folder as
a source, or read it from the query with uri-collection and the directory parameters of Saxon
(select, match, recurse, on-error, content-type):
# The folder as a source: collection() gives its documents, then its JSON items
xquery 'for $j in collection()[. instance of map(*)] return $j?items?*?name' data
# pen
# ink
# pad
# From the query, with a glob and subfolders
xquery 'for $u in uri-collection("data/?select=*.json;recurse=yes") return json-doc($u)?items?*?name'
# pen
# ink
# pad
#Execution Plan
See how the query engine plans to execute your query:
xquery --plan 'for $x in //product order by $x/price return $x/name' catalog.xml
This shows the query plan before execution — useful for understanding performance characteristics of complex queries.
#Performance Profiling
xquery --timing '//product[price > 50]' large-catalog.xml
Output (to stderr; the load line appears when the query has source documents):
load: 276.6 ms (1 document(s))
compile: 1142.0 ms
execute: 355.5 ms
total: 2512.0 ms
memory: peak=61.61 MiB allocated=3.58 MiB
--timing works with every source, for example JSON:
xquery --timing 'sum(json-doc("orders.json")?orders?*?total)'
#Validation Only
Check that a query compiles without running it:
xquery --dry-run -f complex-query.xq
#Real-World Workflows
#Data Extraction
# Extract all email addresses from an XML dataset
xquery '//contact/email' contacts.xml
# Get unique categories
xquery 'distinct-values(//product/@category)' catalog.xml
# Find duplicates
xquery '
for $name in //product/name
group by $n := string($name)
where count($name) > 1
return concat($n, " (", count($name), " occurrences)")
' catalog.xml
#Data Validation
# Find products with missing prices
xquery '//product[not(price)]/@id' catalog.xml
# Find orders with negative amounts
xquery '//order[total < 0]' orders.xml
# Validate email format
xquery '//email[not(matches(., "^[^@]+@[^@]+\.[^@]+$"))]' contacts.xml
#Format Conversion
# XML to CSV
xquery '
string-join((
"id,name,price",
for $p in //product
return string-join(($p/@id, $p/name, $p/price), ",")
), " ")
' -o text catalog.xml > products.csv
# XML to Markdown
xquery '
string-join((
"# Products",
"",
for $p in //product
return concat("- **", $p/name, "** — $", $p/price)
), " ")
' -o text catalog.xml > products.md
#Aggregation and Reporting
# Summary statistics
xquery '
let $products := //product
return map {
"count": count($products),
"total": sum($products/price),
"average": round(avg($products/price), 2),
"min": min($products/price),
"max": max($products/price)
}
' catalog.xml
#Shell Pipeline Integration
# Combine with other tools
xquery '//product/name' catalog.xml | sort | uniq -c | sort -rn
# Feed into jq for further JSON processing
xquery 'array { //product ! map { "name": string(name), "price": number(price) } }' catalog.xml \
| jq '.[] | select(.price > 50)'
# Watch for changes
watch -n 5 'xquery "count(//error)" /var/log/app/*.xml'
#Output Encoding
Output is written as UTF-8, with no byte-order mark, on every platform, whether it goes to the terminal or is redirected to a file.
Before 2.4.0, Windows consoles used their legacy code page (typically 1252 or 437). Characters
outside that page were replaced, both in the terminal and in redirected output, so
xquery -f q.xq > out.xml could write a file whose bytes didn't match its UTF-8 declaration. If
you have files produced that way, regenerate them.
#Comparison with Other Tools
|
Task |
xquery |
jq |
xmlstarlet |
grep |
|---|---|---|---|---|
|
Query XML |
Native |
No XML support |
Basic XPath 1.0 |
Text only |
|
Query JSON |
|
Native |
No JSON support |
Text only |
|
FLWOR queries |
Full XQuery |
Limited |
No |
No |
|
Cross-file joins |
|
Requires scripting |
Single file |
No |
|
Format conversion |
XML/JSON/CSV/text |
JSON only |
XML only |
No |
|
Type-aware |
xs:date, xs:decimal, etc. |
Limited |
No |
No |
#Using from .NET Code
The same engine is available as a library. See XQuery Extensibility for programmatic usage including setting variables, registering extension functions, and reading results.