Name
cx:elemental — Evaluate XQuery expressions with Elemental.
Synopsis
This step sends an XQuery expression to an external Elemental database.
| Input port | Primary | Sequence | Content types | Default binding |
|---|---|---|---|---|
| source | ✔ | ✔ | any | p:empty |
| query | text xml |
| Output port | Primary | Sequence | Content types | Default binding |
|---|---|---|---|---|
| result | ✔ | ✔ | any |
| Option name | Type | Default value |
|---|---|---|
| database-uri | xs:anyURI? | () |
| parameters | map(xs:QName,item()*)? | () |
| password | xs:string? | () |
| query-parameters | map(xs:QName, item()*)? | () |
| query-properties | map(xs:QName, item()*)? | () |
| username | xs:string? | () |
| version | xs:string? | () |
<p:import href="https://xmlcalabash.com/ext/library/elemental.xpl"/>Declaration
1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
| <p:input port="source"
| content-types="any"
| sequence="true"
5 | primary="true">
| <p:empty/>
| </p:input>
| <p:input port="query" content-types="text xml"/>
| <p:output port="result" sequence="true" content-types="any"/>
10 | <p:option name="parameters" as="map(xs:QName,item()*)?"/>
| <p:option name="version" as="xs:string?"/>
| <p:option name="database-uri" as="xs:anyURI?"/>
| <p:option name="username" as="xs:string?"/>
| <p:option name="password" as="xs:string?"/>
15 | <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 Elemental with XML Calabash, you must also download the XML Calabash extension
step for Elemental, elemental-3.0.15.zip and add its resources to your classpath. If you
are using Maven, include the Elemental step in your dependencies:
com.xmlcalabash:elemental:3.0.15.
Description
This step is modeled on the p:xquery step, but specifically uses
the Elemental 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:elemental 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://elemental.xyz/.
When Elemental is used as the query processor (with either the cx:elemental
step or when it is used as the default XQuery processor), it always queries
an Elemental 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:elemental step has several additional options beyond
the standard p:xquery options. They are currently the same
as the options on the cx:exist-db step.
The documentation for Elemental is currently under construction. This section will get updated when the documentation is ready.
Configuration
The
cc:xquery-processor element in the
configuration file
provides default values for some Elemental properties.
The following attributes are recognized:
| Attribute name | Attribute value |
|---|---|
name | https://elemental.xyz/ |
database-uri | The REST API endpoint |
username | The username |
password | The 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://elemental.xyz/"
| database-uri="http://localhost:8080/exist/rest/db/"
5 | username="admin" password="secret"
| exist:max="10" ser:omit-xml-declaration="yes"/>