Name

cx:exist-db — Evaluate XQuery expressions with eXist-db.

Synopsis

This step sends an XQuery expression to an external eXist-db database.

Input portPrimarySequenceContent typesDefault binding
source✔ ✔ any p:empty
query  text xml 
Output portPrimarySequenceContent typesDefault binding
result✔ ✔ any 
Option nameTypeDefault value
database-urixs:anyURI?()
parametersmap(xs:QName,item()*)?()
passwordxs:string?()
query-parametersmap(xs:QName, item()*)?()
query-propertiesmap(xs:QName, item()*)?()
usernamexs:string?()
versionxs:string?()
This is an extension step; to use it, your pipeline must include its declaration. For example, by including the extension library with an import at the top of your pipeline:
<p:import href="https://exproc.org/library/exist-db.xpl"/>
Declaration
 1 |<p:declare-step xmlns:cx="http://xmlcalabash.com/ns/extensions"
   |                xmlns:p="http://www.w3.org/ns/xproc"
   |                type="cx:exist-db">
   |   <p:input port="source"
 5 |            content-types="any"
   |            sequence="true"
   |            primary="true">
   |      <p:empty/>
   |   </p:input>
10 |   <p:input port="query" content-types="text xml"/>
   |   <p:output port="result" sequence="true" content-types="any"/>
   |   <p:option name="parameters" as="map(xs:QName,item()*)?"/>
   |   <p:option name="version" as="xs:string?"/>
   |   <p:option name="database-uri" as="xs:anyURI?"/>
15 |   <p:option name="username" as="xs:string?"/>
   |   <p:option name="password" as="xs:string?"/>
   |   <p:option name="query-parameters" as="map(xs:QName, item()*)?"/>
   |   <p:option name="query-properties" as="map(xs:QName, item()*)?"/>
   |</p:declare-step>

In order to use the eXist-db with XML Calabash, you must also download the XML Calabash extension step for eXist-db, existdb-3.0.27.zip and add its resources to your classpath. If you are using Maven, include the eXist-db step in your dependencies: com.xmlcalabash:existdb:3.0.27.

Description

This step is modeled on the p:xquery step, but specifically uses the eXist-db implementation. If values are given for database-uri, username, and password, they override any values given in the configuration file. Any query parameters or properties defined in the configuration file are merged with the query-parameters and query-properties option maps. The cx:exist-db step can also be nominated as the default processor for p:xquery by setting the default XQuery processor. It can also be specified for a single instance of p:xquery by setting the cx:processor attribute to https://exist-db.org/.

When eXist-db is used as the query processor (with either the cx:exist-db step or when it is used as the default XQuery processor), it always queries an eXist-db database. You cannot pass documents to the step.

Queries that bind external variables to atomic values and return XML documents seem to work fine. Passing non-atomic values, returning non-XML results, or returning a sequence of results often don’t work. It’s not clear if this is due to bugs in the REST API or misunderstandings about how the API works. Suggestions for improvements most welcome.

Options

The cx:exist-db step has several additional options beyond the standard p:xquery options:

database-uri

This is the URI of the HTTP API endpoint for the database that you wish to query, for example, http://existdb:8080/exist/rest/db/.

query-parameters

A map of name/value pairs used to construct the query wrapper. These are very casually described by example in the REST API documentation. You may also find the JavaDoc comments in the source informative, but beware that they may be inconsistent with the implementation.

query-properties

A map of name/value pairs used to construct the query properties. These are also casually described by example in the REST API documentation and in more detail in the JavaDoc comments in the source.

username

The username for the request.

password

The password for the request.

The following parameters (in the standard parameters option) also apply. (When eXist-db is used as the default p:xquery processor, this is the only way to set them.)

Parameter nameParameter value
cx:database-uriThe database URI
cx:queryA map of query parameters
cx:propertiesA map of query properties
cx:usernameThe username
cx:passwordThe password

Where the cx prefix is bound to the XML Calabash extension namespace, http://xmlcalabash.com/ns/extensions.

If the XML Calabash debug option is enabled, the query that is sent to the eXist-db database will be output on the console.

Configuration

The cc:xquery-processor element in the configuration file provides default values for some eXist-db properties.

The following attributes are recognized:

Attribute nameAttribute value
namehttps://exist-db.org/
database-uriThe REST API endpoint
usernameThe username
passwordThe password
existdb:*Query parameters
ser:*Query properties

Where existdb is bound to http://exist.sourceforge.net/NS/exist and ser is bound to http://exist-db.org/xquery/types/serialized.

For example:

1 |<cc:xquery-processor xmlns:exist="http://exist.sourceforge.net/NS/exist"
  |                     xmlns:ser="http://exist-db.org/xquery/types/serialized"
  |                     name="https://exist-db.org/"
  |                     database-uri="http://localhost:8080/exist/rest/db/"
5 |                     username="admin" password="secret"
  |                     exist:max="10" ser:omit-xml-declaration="yes"/>