Using the PReServ Query interface

The PReServ provenance store supplies a Web Service interface for querying. It has a single operation, query, that takes an XQuery document as input and returns an arbitrary XML document as result.

Writing a provenance store XQuery

The query operation treats the contents of a provenance store as a large XML document conforming to the XML schema, PStruct.xsd, found in directory docs/schemas/version2 of the release. The result of the query operation is exactly that document returned by the XQuery submitted. All XQueries submitted to a provenance store must return a valid XML document, i.e. not just a set of literal values. The XQuery specification can be found http://www.w3.org/TR/xquery/ and several tutorials exist on the Web.

In an XQuery document, the namespaces of elements referred to in the query need to be declared at the start of the document. For convenience, we automatically declare for every query a namespace for the primary schema, PStruct.xsd, and associate it with prefix ps. This means that elements of the provenance store declared in that schema can be referred to using that prefix, e.g. ps:interactionRecord, ps:clientId, ps:actorStatePAssertion etc.

Every XQuery document must refer by name to the document(s) that are to be queried over (as it allows for multiple documents to be queried over). In the case of the provenance store, there is a single variable, $ps:pstruct, bound to the root element of the provenance store contents, corresponding to the same element in the XML schema. So, for example, we can refer to the IDs of all clients of interaction records in the provenance store by the expression: $ps:pstruct//ps:clientId.

Querying using the Client-Side Library

The easiest way to query the provenance store from Java code is via the client-side library, org.pasoa.util.ClientLib, which has a method with signature:

Document query (String xquery, URL provenanceStore)

where xquery is the XQuery document to be resolved, provenanceStore is the URL of the provenance store to send the query to and the return value is the result.

Querying using the Web Service API directly

The provenance store query API WSDL is specified in WSXQuery.wsdl and WSXQuery.xsd in directory docs/schemas/version2/query of the release. The XQuery document is sent inside a query element. When using the Web Service interface directory all < symbols in the XQuery document must be replaced by &lt; and all > symbols by &gt; (this replacement is done automatically by the client-side library so does not have be done when using the library).

Sample queries

Here we give some sample queries as example. The first query below returns the whole contents of the provenance store, within a result element.

<result>
  {for $n in $ps:pstruct return $n}
</result>