PhoenixmlDb.XQuery

XQueryFacade

A simple string-in / string-out API for XQuery evaluation.

#XQueryFacade

Namespace: PhoenixmlDb.XQuery

A simple string-in / string-out API for XQuery evaluation.

XQueryFacade is the easiest way to evaluate XQuery expressions against XML input. It handles document parsing, engine setup, execution, and result serialization internally, providing a clean "pit of success" experience.

The user's XQuery is passed through unmodified — prolog declarations (namespaces, options, variable declarations) work exactly as in any conformant XQuery processor. When input XML is provided, it is available as:

• The context item (.) — the standard XQuery mechanism

• $input — declare as declare variable $input external; in the prolog

• doc('urn:xqueryfacade:input') — explicit URI access

Each method creates a fresh XdmDocumentStore and QueryEngine per call, making the facade safe for concurrent use. For high-throughput scenarios where you want to reuse a store across multiple queries, use QueryEngine directly with a shared XdmDocumentStore.

#Example

var xquery = new XQueryFacade();

// Context item — the standard XQuery way. Input XML is available as "." (the context item).
string result = await xquery.EvaluateAsync("//book/title/text()", inputXml);

// Works with full XQuery prolog
string result2 = await xquery.EvaluateAsync("""
    declare namespace bk = "http://example.com/books";
    declare variable $input external;
    $input//bk:book/bk:title/text()
    """, inputXml);

// Also available via doc()
string result3 = await xquery.EvaluateAsync(
    "doc('urn:xqueryfacade:input')//book/title/text()", inputXml);

// All results as strings
IReadOnlyList<string> results = await xquery.EvaluateAllAsync("//book/title/text()", inputXml);

// Scalar
string? title = await xquery.EvaluateScalarAsync("//book[1]/title/text()", inputXml);

// No input XML needed
string sum = await xquery.EvaluateAsync("1 + 1");

// With base URI for relative document resolution
var xml = File.ReadAllText("data/catalog.xml");
var baseUri = new Uri(Path.GetFullPath("data/catalog.xml"));
string result4 = await xquery.EvaluateAsync(
    "//item/doc(resolve-uri(@href, base-uri(.)))", xml, baseUri);
                                  

#Properties

#Methods

#DetectSerializationOptions(String)

Reads the serialization options a query's prolog declares —

declare option output:method "adaptive"

and friends — without executing it.

Public because a caller that runs the plan ITSELF (rather than through

EvaluateAsync

) still needs the declared options to serialize the result the way the query asked. The QT3 runner is exactly that caller: it must supply an environment — context item, external variables, resources — so it cannot go through the facade, but

<serialization-matches>

matches its regex against output serialized under the declared method. The alternative was re-implementing prolog option parsing in the test harness, and a second implementation of an engine behaviour is precisely the shape of bug that has cost the most time here.

#EvaluateAllAsync(String,String,Uri,Uri,Threading.CancellationToken)

Evaluates an XQuery expression and returns each result item as a separate string.

Parameters:

• xquery — The XQuery expression to evaluate. May include a full prolog.

• inputXml — Optional XML input. When provided, the parsed document is set as the XQuery context item (available as .), bound as the external variable $input, and accessible via doc('urn:xqueryfacade:input'). The query is passed through unmodified.

• baseUri — Optional base URI for the input document, enabling relative URI resolution.

• queryBaseUri — Optional base URI for the XQuery source, for module resolution and fn:static-base-uri().

• cancellationToken — Token to cancel the evaluation.

Returns: A list of serialized result strings, one per result item.

#EvaluateAsync(String,String,Uri,Uri,Threading.CancellationToken)

Evaluates an XQuery expression and returns all results concatenated as a single string.

Parameters:

• xquery — The XQuery expression to evaluate. May include a full prolog.

• inputXml — Optional XML input. When provided, the parsed document is set as the XQuery context item (available as .), bound as the external variable $input, and accessible via doc('urn:xqueryfacade:input'). The query is passed through unmodified.

• baseUri — Optional base URI for the input document. Used as the document-uri and base-uri for the input XML, enabling resolve-uri() and doc() to resolve relative references. Pass the file URI when loading XML from disk (e.g., new Uri(Path.GetFullPath("data.xml"))). Also used as the query base URI if queryBaseUri is not set.

• queryBaseUri — Optional base URI for the XQuery source. Used for fn:static-base-uri() and for resolving relative at location hints in import module declarations. When the query is loaded from a file, pass its URI (e.g., new Uri(Path.GetFullPath("query.xq"))).

• cancellationToken — Token to cancel the evaluation.

Returns: All result items serialized and concatenated. Returns an empty string if the result is the empty sequence.

#EvaluateScalarAsync(String,String,Uri,Uri,Threading.CancellationToken)

Evaluates an XQuery expression and returns the first result as a string, or

null

if empty.

Parameters:

• xquery — The XQuery expression to evaluate. May include a full prolog.

• inputXml — Optional XML input. When provided, the parsed document is set as the XQuery context item (available as .), bound as the external variable $input, and accessible via doc('urn:xqueryfacade:input'). The query is passed through unmodified.

• baseUri — Optional base URI for the input document, enabling relative URI resolution.

• queryBaseUri — Optional base URI for the XQuery source, for module resolution and fn:static-base-uri().

• cancellationToken — Token to cancel the evaluation.

Returns: The first result item serialized as a string, or null if the result is the empty sequence.