p:xquery (3.0) 

Specifying the query

What appears on the query port determines the query the step invokes. XQuery queries are usually text documents (not XML), but there is a way to specify a query using XML-only called XQueryX. There are several ways to specify the query:

• If the document on the query port is a text document, this is the query.

• If the document on the query port is an XML document with root element <c:query> (the c namespace prefix must be bound to the namespace http://www.w3.org/ns/xproc-step), the text value of this root element is the query.

  Usually this means that the <c:query> root element consists of text contents only (a single text node). However, if there are child elements, all text nodes in the document will be concatenated.

• If the document on the query port is an XML document with its root element in the XQueryX namespace (http://www.w3.org/2005/XQueryX), the document is treated as an XQueryX query.

  Whether XQueryX is supported is implementation defined and therefore depends on the XProc processor used.

• In all other cases, the document on the query port is first serialized (as if written to disk), using the (optional) serialization document-property settings. The resulting text is used as the query.

Basic usage

Assume we have input documents containing <thing> elements and we want to output a list of these elements, ordered by the value of their id attribute. The following XQuery query, called sort-things.xql, does the trick:

xquery version "3.0" encoding "UTF-8";

<things-sorted count="{count(collection()//thing)}">
  {
    for $thing in collection()//thing
      order by @id
    return
      $thing
  }
</things-sorted>

The following pipeline releases this query on some input documents containing <thing> elements:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" sequence="true">

    <things>
      <!-- Input document 1 -->
      <thing id="123"/>
      <nested-things>
        <thing id="456"/>
      </nested-things>
    </things>

    <things>
      <!-- Input document 2 -->
      <thing id="789"/>
    </things>

  </p:input>
  <p:output port="result" sequence="true"/>

  <p:xquery>
    <p:with-input port="query" href="sort-things.xql"/>
  </p:xquery>

</p:declare-step>

Result document:

<things-sorted count="3">
   <thing id="123"/>
   <thing id="456"/>
   <thing id="789"/>
</things-sorted>

Passing parameters to a query

Let’s make the Basic usage example also usable for other elements than <thing>. The name of the element to count is passed as an external variable. The query, called sort.xql, is as follows:

xquery version "3.0" encoding "UTF-8";

declare variable $elm-name as xs:string external;

<things-sorted count="{count(collection()//*[local-name() eq $elm-name])}">
  {
    for $elm in collection()//*[local-name() eq $elm-name]
      order by @id
    return
      $elm
  }
</things-sorted>

The following pipeline releases this query on the same input documents as the Basic usage example. It again selects <thing> elements, but the (local) name of this element is now passed as an external variable:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source" sequence="true">

    <things>
      <!-- Input document 1 -->
      <thing id="123"/>
      <nested-things>
        <thing id="456"/>
      </nested-things>
    </things>

    <things>
      <!-- Input document 2 -->
      <thing id="789"/>
    </things>

  </p:input>
  <p:output port="result" sequence="true"/>

  <p:xquery parameters="map{'elm-name': 'thing'}">
    <p:with-input port="query" href="sort.xql"/>
  </p:xquery>

</p:declare-step>

Result document:

<things-sorted count="3">
   <thing id="123"/>
   <thing id="456"/>
   <thing id="789"/>
</things-sorted>