XCQL

Version 1.1, 12th January 2004

Introduction

XCQL is the CQL query language expressed in an XML form. XCQL is used to echo a query in a search/retrieve or scan response.  It is not used in search/retrieve or scan requests.  The XML schema is available that defines the elements used in XCQL.

XCQL encodes the structure of the CQL within 'searchClause' and 'triple' elements. Thus the parentheses which record this information in CQL are not used, nor is there a need for a left to right precedence rule as this is explicit in the XML. The 'triple' element contains three elements. The first is the boolean for the triple and the second and third positions are either 'searchClause' or 'triple', wrapped in 'leftOperand' and 'rightOperand' respectively. 'searchClause' may contain 'index', 'relation' and 'term' elements. Each 'triple' or 'searchClause' element may contain a 'prefixes' array which specifies the prefixes used for mapping context sets to their URI identifiers from that point onwards.

Element Guide

<triple>
This element represents a CQL 'triple' which would otherwise be wrapped in parentheses. It contains exactly three elements. The first is 'boolean', the second and third must be one of 'triple' or 'searchClause'.

<searchClause>
This element represents a single index/relation/term search clause within the query. It contains exactly three elements, 'index', 'relation' and 'term' in that order.

<leftOperand>
<rightOperand>
These elements within triple are place holders for SOAP as many toolkits do not allow an unnamed Choice within a Sequence. They contain either a 'triple' or a 'searchClause' element.

<index>
This element contains the index and any index set given for the clause as text, exactly how it would appear in the equivalent CQL. There is no distinction drawn for index set at an element level.

<relation>
This element contains the relation of the search clause and any modifiers that apply to it. It contains one required element, 'value', in which the base relation is recorded. It may also contain a subsequent 'modifiers' element to contain the applied modifiers. See their definitions for further information.

<term>
This element contains the text of the search term. CQL allows for quoted or unquoted term and thus requires " characters to be escaped. Within XCQL " may be left unescaped, but literal \, ^, ? and * must still be escaped with a preceeding \. Additionally due to the encoding rules for XML, < > and & must be encoded as their respective entities within terms. Quotes (") may be encoded as the entity '&quot;'

<boolean>
Similar to 'relation', this element contains a 'value' element with the base boolean and optionally a 'modifiers' element for any proximity modifiers.

<modifiers>
This wrapper element contains any number of 'modifier' elements.

<modifier>
This element may contain either a 'type' element by itself, or a sequence of 'type', 'comparison' and 'value' elements. In the first instance, this is to encode a typed parameter such as the modifiers for the proximity boolean. The first instance with just 'type' is to encode a simple parameter without differentiating by value, such as 'ordered' for the prox boolean or 'stem' for relations. The second style with three elements is to include a value for the modifier, for example the comparison and distance for proximity.

<type>
This element contains a type of a modifier. The type may come from any context set. If a context set is not supplied, it will default to CQL.

<comparison>
Comparison, if present, contains one of: <, <=, =, <>, > or >=.

<value>
This element contains the value of a modifier.

<prefixes>
This element contains a sequence of 'prefix' elements, each of which describes a mapping between a name used for an index set and the identifier which should be used to distinguish it from other index sets.

<prefix>
A single mapping between a name and an identifier.

<name>
The name used in place of an identifier. If this element is empty, then it implies that the following identifier is to be used as a default if none is supplied in the query.

<identifier>
The identifier to which the preceding name is to be mapped.

Example

Nothing helps in understanding XML schemas like an example. Within a SOAP message each element would have the appropriate type encoding added as an attribute. The following XML is the XCQL representation of the CQL query:
> bath="http://www.loc.gov/zing/cql/bath-indexes/" (dc.description any/relevant "cat dog fish" and ( bath.title = "\"of course\"" prox/unit=word "gender")) 


<prefixes>
  <prefix>
    <name>bath</name>
    <identifier>http://www.loc.gov/zing/cql/bath-indexes/</identifier>
  <prefix>
</prefixes>
<triple>
  <boolean>
    <value>and</value>
  </boolean>
  <leftOperand>
    <searchClause>
      <index>dc.description</index>
      <relation>
        <value>any</value>
        <modifiers>
          <modifier><type>relevant</type></modifier>
        </modifiers>
      </relation>
      <term>cat dog fish</term>
    </searchClause>
  </leftOperand>
  <rightOperand>
    <triple>
      <boolean>
        <value>prox</value>
        <modifiers>
          <modifier>
            <type>unit</type>
            <comparison>=</comparison>
            <value>word</value>
          </modifier>
        </modifiers>
      </boolean>
      <leftOperand>
        <searchClause>
          <index>bath.title</index>
          <relation>
            <value>=</value>
          </relation>
          <term>"of course"</term>
        </searchClause>
      </leftOperand>
      <rightOperand>
        <searchClause>
          <index>srw.serverChoice</index>
          <relation>
            <value>scr</value>
          </relation>
          <term>gender</term>
        </searchClause>
      </rightOperand>
    </triple>
  </rightOperand>
</triple>