spec/version-1.1.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html><head><!-- InstanceBegin template="/Templates/sru-template.dwt" codeOutsideHTMLIsLocked="false" --><!-- InstanceBeginEditable name="doctitle" --><title>Common Query Language (SRU: Search and Retrieve via URL - Standards, Library of Congress)</title><!-- InstanceEndEditable --><!-- InstanceBeginEditable name="head" -->
   3
   4
   5
   6
   7
   8 <meta name="keywords" content="sru srw protocol search retrieve via url search retrieve web services standards library of congress common query language cql">
   9 <meta name="description" content="Common Query Language: SRU (Search/Retrieve via URL) is a standard search protocol for Internet search queries, utilizing CQL (Common Query Language), a standard query syntax for representing queries. SRW (Search Retrieve Web Service) is a companion protocol to SRU."><!-- InstanceEndEditable -->
  10
  11 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  12 <link href="cql_files/sru.css" rel="stylesheet" type="text/css">
  13 <script type="text/javascript" src="cql_files/triggerParams.js"></script><script type="text/javascript" src="cql_files/stdLauncher.js"></script><script type="text/javascript">Poll();</script></head><body alink="#660000" link="#663300" text="#333333" vlink="#996633">
  14 <div id="container">
  15   <div id="header">
  16     <div id="highlevel">
  17       <div id="top-left"><a href="http://www.loc.gov/" class="white">The Library
  18           of Congress</a><span class="white-text">&nbsp;»&nbsp;</span><a href="http://www.loc.gov/library/" class="white">Librarians,
  19           Archivists</a><span class="white-text">&nbsp;»</span> <a href="http://www.loc.gov/standards/" class="white">Standards</a></div>
  20       <div id="top-right">
  21         <form action="http://search.loc.gov:8765/query.html" accept-charset="utf-8" name="seek1" method="get">
  22           <input name="col" value="loc" type="hidden">
  23           <input name="sc" value="0" type="hidden">
  24           <input name="ws" value="0" type="hidden">
  25           <input name="la" value="en" type="hidden">
  26           <input name="qm" value="0" type="hidden">
  27           <input name="st" value="1" type="hidden">
  28           <input name="nh" value="10" type="hidden">
  29           <input name="lk" value="1" type="hidden">
  30           <input name="rf" value="0" type="hidden">
  31           <input name="oq" value="" type="hidden">
  32           <input name="si" value="0" type="hidden">
  33           <input name="rq" value="0" type="hidden">
  34           <input name="qc" value="" type="hidden">
  35           <select name="qp" tabindex="1" class="drop-box">
  36             <option value="url:/standards/sru/" selected="selected">SRU Pages</option>
  37             <option value="url:/standards/">All Standards Pages</option>
  38             <option value="">All Library Pages</option>
  39           </select>
  40           <input name="qt" id="keyword" size="16" value="" tabindex="2" class="drop-box" type="text">
  41           <input class="button" id="search_button" name="search_button" value="SEARCH" tabindex="3" type="submit">
  42         </form>
  43       </div>
  44     </div>
  45     <h1 class="graphic"><img src="cql_files/sru-title.gif" alt="SRU: Search/Retrieve via URL - SRU Version 1.1 - 13th February 2004" height="60" width="740"></h1>
  46   </div>
  47   <div id="top-bread"> <a href="http://www.loc.gov/standards/sru/index.html">Home</a> &gt;&gt; <!-- InstanceBeginEditable name="topbreadcrumb" --><span class="selected">CQL</span><!-- InstanceEndEditable --></div>
  48   <div id="body"> <!-- InstanceBeginEditable name="content" -->
  49     <h1>Common Query Language</h1>
  50     <p><strong>CQL <a href="http://www.loc.gov/standards/sru/version.html">Version</a> 1.1</strong> <em>13th February
  51     2004</em></p>
  52     <p class="box"><a href="#sample">Sample Queries</a> - <a href="#bnf">BNF</a> - <a href="#rules"> Rules</a> - <a href="#features"> Features</a> - <a href="#conformance">Conformance</a>
  53 - <a href="#context"> Context Sets</a> - <a href="http://www.loc.gov/standards/sru/cql/cql-context-set.html"> the
  54               CQL Context Set</a> - <a href="#relations">Relations</a> <a href="#relmodifiers">Modifiers</a> - <a href="#masking">Masking</a> - <a href="#resultset">Result
  55     Sets</a> - <a href="#proximity">Proximity</a> - Tutorial (temporarily unavailable)</p>
  56     <p>CQL is a formal language for representing queries to information retrieval
  57       systems such as web indexes, bibliographic catalogs and museum collection
  58       information. The design objective is that queries be human readable and
  59       writable, and that the language be intuitive while maintaining the expressiveness
  60       of more complex languages.</p>
  61     <p>Traditionally, query languages have fallen into two camps: Powerful, expressive
  62       languages, not easily readable nor writable by non-experts (e.g. SQL, PQF,
  63       and XQuery);or simple and intuitive languages not powerful enough to express
  64       complex concepts (e.g. CCL and google). CQL tries to combine simplicity
  65       and intuitiveness of expression  for simple, every
  66       day queries, with the richness of more expressive languages to accommodate
  67       complex concepts when necessary.</p>
  68     <hr>
  69     <h3><a name="sample"></a> Sample Queries</h3>
  70     <p>Following are examples of simple CQL queries. These are all self-explanatory: </p>
  71     <p class="box2">dinosaur<br>
  72 "complete dinosaur"<br>
  73   title = "complete dinosaur"<br>
  74   title exact "the complete dinosaur"<br>
  75   dinosaur or bird<br>
  76   dinosaur and "ice age"<br>
  77   dinosaur not reptile <br>
  78   dinosaur and bird or dinobird <br>
  79   (bird or dinosaur) and (feathers or scales)<br>
  80 "feathered dinosaur" and (yixian or jehol) <br>
  81   publicationYear &lt; 1980 <br>
  82   lengthOfFemur &gt; 2.4<br>
  83   bioMass &gt;= 100 </p>
  84     <p>The following are a bit more complicated:</p>
  85     <table align="center" border="1" cellpadding="5" cellspacing="0" width="95%">
  86       <tbody><tr>
  87         <th scope="col" bgcolor="#fff9e5" width="50%">Example</th>
  88         <th scope="col" bgcolor="#fff9e5" width="50%">Explanation</th>
  89       </tr>
  90       <tr>
  91         <td scope="row"><p>title all "complete dinosaur"</p></td>
  92         <td><p>Title contains all of the words: "complete", and "dinosaur"</p></td>
  93       </tr>
  94       <tr>
  95         <td scope="row"><p><br>
  96         title any "dinosaur bird reptile"</p></td>
  97         <td><p>Title contains any of the words: "dinosaur", "bird",
  98           or "reptile"</p></td>
  99       </tr>
 100       <tr>
 101         <td scope="row"><p>(caudal or dorsal) prox vertebra</p></td>
 102         <td><p><em>A proximity query: either "caudal" or "dorsal" near
 103               'vertebra"</em></p>
 104         </td>
 105       </tr>
 106       <tr>
 107         <td scope="row">
 108           <p>ribs prox/distance&lt;=5 chevrons </p>
 109         </td>
 110         <td><p><em>A more specific proximity query: "ribs" within
 111               5 words of "chevrons"</em></p>
 112         </td>
 113       </tr>
 114       <tr>
 115         <td scope="row"><p>ribs prox/unit=sentence chevrons</p>
 116         </td>
 117         <td>
 118           <p><em>"ribs" in the same sentence as "chevrons"</em></p>
 119         </td>
 120       </tr>
 121       <tr>
 122         <td scope="row">
 123           <p>ribs prox/distance&gt;0/unit=paragraph chevrons </p>
 124         </td>
 125         <td><p><em>"ribs" and "chevrons" occuring
 126               in the same document in different paragraphs</em></p>
 127         </td>
 128       </tr>
 129       <tr>
 130         <td scope="row"><p>subject any/relevant "fish frog"</p>
 131         </td>
 132         <td><p><em>find documents that would seem relevant
 133               either to "fish" or "frog"</em></p>
 134         </td>
 135       </tr>
 136       <tr>
 137         <td scope="row"><p>subject any/rel.lr "fish frog"</p>
 138         </td>
 139         <td><p><em>Same as previous, but use a specific relevance
 140               algorithm (linear regression)</em></p>
 141         </td>
 142       </tr>
 143     </tbody></table>
 144     <hr>
 145     <h2><a name="bnf"></a>Formal Definition: CQL BNF</h2>
 146     <p>Following is the Backus Naur Form (BNF)  definition for CQL. ["::=" represents
 147     "is defined as"]</p>
 148     <table border="0" cellpadding="5" cellspacing="0" width="95%">
 149       <tbody>
 150         <tr>
 151           <td scope="row" align="right" width="24%">
 152               <p>cqlQuery</p>
 153           </td>
 154           <td width="1%"><p>::=</p>
 155           </td>
 156           <td width="75%"><p>prefixAssignment cqlQuery | scopedClause </p>
 157           </td>
 158         </tr>
 159         <tr>
 160         <td scope="row" align="right">
 161               <p>prefixAssignment</p>
 162           </td>
 163           <td><p>::=</p>
 164           </td>
 165           <td><p>'&gt;' prefix '=' uri | '&gt;' uri</p>
 166           </td>
 167         </tr>
 168         <tr>
 169         <td scope="row" align="right">
 170               <p>scopedClause</p>
 171           </td>
 172           <td><p>::=</p>
 173           </td>
 174           <td><p>scopedClause booleanGroup searchClause | searchClause</p>
 175           </td>
 176         </tr>
 177         <tr>
 178         <td scope="row" align="right">
 179               <p>booleanGroup</p>
 180           </td>
 181           <td><p>::=</p>
 182           </td>
 183           <td><p>boolean [modifierList]</p>
 184           </td>
 185         </tr>
 186         <tr>
 187           <td scope="row" align="right" valign="top">
 188               <p>boolean</p>
 189           </td>
 190           <td valign="top"><p>::=</p>
 191           </td>
 192           <td><p>'and' | 'or' | 'not' | 'prox'</p>
 193           </td>
 194         </tr>
 195         <tr>
 196           <td scope="row" align="right" valign="top">
 197               <p>searchClause</p>
 198           </td>
 199           <td valign="top"><p>::=</p>
 200           </td>
 201           <td>
 202             <p>'(' cqlQuery ')'<br>
 203           | index relation searchTerm<br>
 204           | searchTerm</p>
 205           </td>
 206         </tr>
 207         <tr>
 208         <td scope="row" align="right">
 209               <p>relation</p>
 210           </td>
 211           <td><p>::=</p>
 212           </td>
 213           <td><p>comparitor [modifierList]</p>
 214           </td>
 215         </tr>
 216         <tr>
 217         <td scope="row" align="right">
 218               <p>comparitor</p>
 219           </td>
 220           <td><p>::=</p>
 221           </td>
 222           <td><p>comparitorSymbol | namedComparitor</p>
 223           </td>
 224         </tr>
 225         <tr>
 226         <td scope="row" align="right">
 227               <p>comparitorSymbol</p>
 228           </td>
 229           <td><p>::=</p>
 230           </td>
 231           <td><p>'=' | '&gt;' | '&lt;' | '&gt;=' | '&lt;=' | '&lt;&gt;'</p>
 232           </td>
 233         </tr>
 234         <tr>
 235         <td scope="row" align="right">
 236               <p>namedComparitor</p>
 237           </td>
 238           <td><p>::=</p>
 239           </td>
 240           <td><p>identifier</p>
 241           </td>
 242         </tr>
 243         <tr>
 244         <td scope="row" align="right">
 245               <p>modifierList</p>
 246           </td>
 247           <td><p>::=</p>
 248           </td>
 249           <td><p>modifierList modifier<strong> | </strong>modifier</p>
 250           </td>
 251         </tr>
 252         <tr>
 253         <td scope="row" align="right">
 254               <p>modifier</p>
 255           </td>
 256           <td><p>::=</p>
 257           </td>
 258           <td><p>'/' modifierName [comparitorSymbol          modifierValue] </p>
 259           </td>
 260         </tr>
 261         <tr>
 262         <td scope="row" align="right"><p align="right">prefix, uri, modifierName, modifierValue, searchTerm,
 263               index</p>
 264           </td>
 265           <td valign="top"><p>::=</p>
 266           </td>
 267           <td valign="top"><p>term</p>
 268           </td>
 269         </tr>
 270         <tr>
 271         <td scope="row" align="right">
 272               <p>term</p>
 273           </td>
 274           <td><p>::=</p>
 275           </td>
 276           <td><p>identifier | 'and' | 'or' | 'not' | 'prox'</p>
 277           </td>
 278         </tr>
 279         <tr>
 280           <td scope="row" align="right" valign="top">
 281               <p>identifier</p>
 282           </td>
 283           <td valign="top"><p>::=</p>
 284           </td>
 285           <td><p>charString1 | charString2</p>
 286           </td>
 287         </tr>
 288         <tr>
 289           <td scope="row" align="right" valign="top">
 290               <p><em>charString1</em></p>
 291           </td>
 292           <td valign="top"><p>:=</p>
 293           </td>
 294           <td><p><em>Any sequence of characters that does not include any of
 295                 the following:</em> </p>
 296               <blockquote><em>whitespace<br>
 297               </em><em>( (open parenthesis )</em><br>
 298               <em>) (close parenthesis)</em><br>
 299               <em>=<br>
 300               </em><em>&lt;<br>
 301               </em><em>&gt;</em><br>
 302               <em>'"' (double quote)<br>
 303               </em><em>/</em></blockquote>              <p><em> If the final sequence is a reserved word, that token is
 304                   returned instead. Note that '.' (period) may be included, and
 305                   a sequence of digits is also permitted. Reserved words are
 306                   'and', 'or', 'not', and 'prox' (case insensitive). When a reserved
 307                   word is used in a search term, case is preserved. </em> </p>
 308           </td>
 309         </tr>
 310         <tr>
 311           <td scope="row" align="right" valign="top">
 312               <p><em>charString2</em></p>
 313           </td>
 314           <td valign="top"><p>:=</p>
 315           </td>
 316           <td><p><em>Double quotes enclosing a sequence of any characters except
 317                 double quote (unless preceded by backslash (\)). Backslash escapes
 318                 the character following it. The resultant value includes all
 319                 backslash characters except those releasing a double quote (this
 320                 allows other systems to interpret the backslash character). The
 321                 surrounding double quotes are not included. </em></p>
 322           </td>
 323         </tr>
 324       </tbody>
 325     </table>
 326     <hr>
 327     <h2><a name="rules"></a>General Rules</h2>
 328     <ol>
 329       <li>
 330         <p><strong>CQL Query<br>
 331           </strong>A CQL query is essentially a search clause, or multiple search
 332           clauses connected by boolean operators.&nbsp;(In addition it may include
 333           prefix assignments which assign short names to known contexts. See <a href="#context">context
 334           sets</a>.)</p>
 335       </li>
 336       <li>
 337         <p><strong>Search Clause</strong><br>
 338       A search clause consists of an index, relation, and search term, or a search
 339         term alone. Thus every search clause has a search term, but both the
 340         index and relation may be omitted -&nbsp; the clause must include either
 341         both or neither of the index and relation. (Note that the use of the "index" concept
 342         in CQL is not intended to have any implementation implications; it does
 343         not imply the presence of a physical index.)</p>
 344         <p> Examples: &nbsp; <br>
 345 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Index/relation/search term:&nbsp; <strong>title
 346 = cat</strong><br>
 347 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Search term only:&nbsp;&nbsp; <strong>cat</strong>
 348
 349       </p></li><li>
 350         <p><strong>Search Term</strong><br>
 351       Search terms <em>may</em> be enclosed in double quotes. Search terms <em>must</em> be
 352       enclosed in double quotes if they contain any of the following characters: &lt; &gt; =
 353       / ( ) and whitespace. The search term may be empty, but must be present
 354       in a search clause. An empty search term is expressed as "" and has no
 355       defined semantics. </p>
 356       </li>
 357       <li>
 358         <p><strong>Index</strong> <strong>Name</strong><br>
 359       An index name always includes a base name and may also include a prefix,
 360         which provides a context for the index name, the name of the <a href="#context">context
 361         set</a> of which the index is a part. If the context is not supplied,
 362         it is determined by the server.&nbsp; If the index is not supplied it
 363         is determined by the server. (Note that the index may be omitted only
 364         when the relation is also omitted. Either both must be supplied, or both
 365         omitted.)</p>
 366         <p> Examples:<br>
 367 &nbsp;&nbsp;&nbsp; title = cat&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <em>context determined
 368 by the server</em><br>
 369 &nbsp;&nbsp;&nbsp; dc.title = cat&nbsp;&nbsp;&nbsp; <em>index context is dc<br>
 370 &nbsp; &nbsp;&nbsp;</em>cat&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <em>context and
 371 index determined by the server</em></p>
 372       </li>
 373       <li>
 374         <p><strong>Relation<br>
 375           </strong>The relation in a search clause specifies the relationship
 376           between the index and search term.&nbsp; It also always includes a
 377           base name and may also include a prefix providing a context for the
 378           relation. If a relation is supplied with no accompanying context, the
 379           context is 'cql'&nbsp; (the <a href="http://www.loc.gov/standards/sru/cql/cql-context-set.html">cql context
 380           set</a>).&nbsp; If no relation is supplied, then cql.scr (server choice)
 381           is assumed, which means that the relation is determined by the server.
 382           (Note that the relation may be omitted only when the index is also
 383           omitted. Either both must be supplied, or both
 384         omitted.)</p>
 385         <p></p>
 386         <p> Examples:<br>
 387 &nbsp;&nbsp; title = cat&nbsp; <em> context for relation is 'cql' ; fully qualified
 388 relation is cql.=<br>
 389 &nbsp;&nbsp; </em>title cql.any cat&nbsp;&nbsp;&nbsp; <em>relation is 'any';
 390 relation context is 'cql'.&nbsp; Equivalent to: </em>title any cat<em><br>
 391 &nbsp;&nbsp; cat&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; index and relation are determined
 392 by the server (formally the relation is 'cql.scr')</em></p>
 393       </li>
 394       <li><a name="relmods"></a>
 395         <strong>Relation Modifiers</strong><br>
 396       Relation modifiers may accompany a relation. These also may be accompanied
 397         by a context.&nbsp; If a context is not supplied for a modifier, the
 398         default is the <a href="http://www.loc.gov/standards/sru/cql/cql-context-set.html">cql context set</a>. Relation
 399         modifiers are separated from each other and from the relation by slashes
 400         ( /). Whitespace may be present on either side of a / character, but
 401         the relation plus modifiers group may not end in a /.
 402           <p> Examples:<br>
 403 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; dc.title any/relevant/rel.CORI "cat fish" <br>
 404 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <em>&nbsp;the relation 'any'
 405 is modified by (1) 'relevant' whose context is 'cql' and (2) 'CORI' whose context
 406 is 'rel'.</em><br>
 407 &nbsp; &nbsp;&nbsp;&nbsp; dc.author exact/stem "smith, j."&nbsp;&nbsp;&nbsp; <em>the
 408 relation 'exact' is modified by 'stem' whose context is 'cql'</em>.<em><br>
 409 &nbsp;&nbsp;</em></p>
 410       </li>
 411       <li>
 412         <p><strong>Boolean Operators</strong><br>
 413       Search clauses may be linked by boolean operators. These are: <strong>and</strong>, <strong>or</strong>, <strong>not</strong> and <strong>prox</strong>.
 414       (Note that&nbsp; <strong>not</strong> is really and-not, that is, it may
 415        not be used as a unary operator.) Boolean operators all have the same
 416       precedence; they are evaluated left-to-right. Parentheses
 417       may
 418       be used
 419       to
 420       overide left-to-right
 421       evaluation.</p>
 422       </li>
 423       <li>
 424         <p><strong>Boolean Modifiers</strong><br>
 425       As a relation may have  modifiers, similiarly, a
 426         boolean operator may have modifiers, separated by '/' characters. Boolean
 427         modifiers may come from
 428         any context
 429         set. If
 430         not supplied, the context is the <a href="http://www.loc.gov/standards/sru/cql/cql-context-set.html">CQL
 431         context set</a>. (Note that Boolean operators themselves
 432         are limited to the built-in set of four.)</p>
 433         <p> Example:&nbsp; dc.title=cat and/rel.sum dc.title=dog</p></li>
 434       <li>
 435         <p><strong>Case Insensitive</strong> <br>
 436       All parts of CQL are case insensitive apart from user supplied search terms,
 437         which may or may not be case sensitive. 'OR','or', 'Or' and 'oR' are
 438         all the same boolean operator, just as 'dc.title', 'DC.Title' and 'dC.TiTLe'
 439         are all the same context set plus index name. </p>
 440     </li></ol>
 441     <hr>
 442     <h2><a name="features"></a>Additional CQL Features</h2>
 443     <p>The following are all formally defined by the CQL context set but described
 444       here for convenience.</p>
 445     <h3><a name="relations"></a>Relations </h3>
 446     <p><strong>For ordered (e.g. numeric) terms: </strong><strong><br>
 447 &lt;</strong>, <strong>&gt;</strong>, <strong>&lt;=</strong>, <strong>&gt;=</strong>,
 448 and <strong>&lt;&gt;</strong> mean "less than", "greater than", "less
 449 or equal", "greater or equal", and "not equal". </p>
 450     <p></p>
 451     <p><strong>when the term is a list of words</strong>: </p>
 452     <ul>
 453       <li>
 454         <p><strong>&nbsp; '='</strong> is used for word adjacency -- the words
 455           appear in that order with no others intervening.&nbsp; (Note the dual
 456           use of '=', it is used for numeric equality as described above.) </p></li>
 457       <li>
 458         <p>&nbsp; <strong>'any</strong>' means "any of these words" </p></li>
 459       <li>
 460         <p>&nbsp; '<strong>all</strong>' means "all of these words"</p>
 461     </li></ul>
 462     <p><strong>When the term is a character string:<br>
 463     </strong><strong>'</strong><strong>exact</strong>' is used for exact string
 464     matching.
 465     </p>
 466     <p><strong>When the term has multiple dimensions:<br>
 467     </strong><strong>'within</strong>' may be used to search for values that
 468     fall within the range, area or volume described by the search
 469     term.</p>
 470     <p>
 471       <strong>When the index's data has multiple dimensions:<br>
 472       </strong><strong>'encloses</strong>' may be used to search for values of
 473       the database's term fully encloses the search term.
 474     </p>
 475     &nbsp;
 476
 477      Examples:
 478     <table border="1" cellpadding="5" cellspacing="0" width="95%">
 479       <tbody><tr bgcolor="#fff9e5">
 480         <th scope="col" width="28%"><em>This query </em></th>
 481         <th scope="col" width="35%"><em>Would match this </em></th>
 482         <th scope="col" width="37%"><em>but not this</em></th>
 483       </tr>
 484       <tr>
 485         <td scope="row"><p><strong>title =&nbsp; "cat in the hat"</strong></p>
 486         </td>
 487         <td><p>&nbsp;"a day in the life of the cat in the hat"</p>
 488         </td>
 489         <td><p>"hat in the cat" or "cat in the green hat"</p>
 490         </td>
 491       </tr>
 492       <tr>
 493         <td scope="row"><p><strong>title all "cat hat"</strong></p>
 494         </td>
 495         <td><p>"hat in the cat"</p>
 496         </td>
 497         <td><p>"cat in the grass"</p>
 498         </td>
 499       </tr>
 500       <tr>
 501         <td scope="row"><p><strong>title any "cat hat"</strong></p>
 502         </td>
 503         <td><p>"cat in the grass"</p>
 504         </td>
 505         <td><p>"dog in the grass"</p>
 506         </td>
 507       </tr>
 508       <tr>
 509         <td scope="row"><p><strong>title exact "cat in the hat"</strong></p>
 510         </td>
 511         <td><p>"cat in the hat"</p>
 512         </td>
 513         <td><p>"a day in the life of the cat in the hat"</p>
 514         </td>
 515       </tr>
 516       <tr>
 517         <td scope="row"><p><strong>date within "2002 2005"</strong></p></td>
 518         <td><p>2004</p></td>
 519         <td><p>2006</p></td>
 520       </tr>
 521       <tr>
 522         <td scope="row"><p><strong>dateRange encloses 2003</strong></p></td>
 523         <td><p>"2002 2005"</p></td>
 524         <td><p>"2004 2005"</p></td>
 525       </tr>
 526     </tbody></table>
 527     <h3><br>
 528     <a name="relmodifiers"></a>Relation Modifiers <strong>- Term Functions</strong></h3>
 529     <p>These relation modifiers request that the server perform some algorithm
 530       on the term before processing. </p>
 531     <ul>
 532       <li>
 533         <p><strong>stem</strong><br>
 534       The server should apply a stemming algorithm to the words within the term.
 535         for example, walked, walking, walker <i>etc.</i> would all be represented
 536         by the stem word walk. This allows a search like title =/stem "these
 537         completed dinosaurs" to match&nbsp; <i>The Complete Dinosaur</i>. </p></li>
 538       <li>
 539         <p><strong>relevant</strong><br>
 540       The server should use a relevancy algorithm for determining matches and
 541         the order of the result set. </p>
 542         <p> Example: <em>subject any/relevant "fish frog"</em><br>
 543           would find records relevant to "fish" or "frog" and order
 544       the result set by relevance to fish or frog.<i><br>
 545         <br>
 546                   </i></p>
 547     </li></ul>
 548     <h3><strong>Relation Modifiers - Qualifiers</strong></h3>
 549     <p> These modifiers qualify the relation to more precisely determine its
 550       semantics. </p>
 551     <ul>
 552       <li>
 553         <p><strong>word</strong><br>
 554       The term consists of words (rather than      being an opaque string). </p>
 555       </li>
 556       <li>
 557         <p><strong>string</strong><br>
 558       The term is a single item, and should not be broken up. </p></li>
 559       <li>
 560         <p><strong>isoDate</strong><br>
 561       Each item within the term conforms to the ISO 8601 specification for expressing
 562         dates. </p></li>
 563       <li>
 564         <p><strong>number</strong><br>
 565       Each item within the term is a number. </p></li>
 566       <li>
 567         <p><strong>uri</strong><br>
 568       Each item within the term is a URI. </p></li>
 569       <li>
 570         <p><strong>masked</strong><br>
 571        This means that the masking rules (see next) apply. Masking is assumed
 572        even if not specified, unless 'unmasked' is specified (so there is never
 573          any reason to include 'masked').</p>
 574       </li><li><strong>unmasked </strong><br>
 575       Do not apply masking rules.
 576     </li></ul>
 577     <h3><a name="masking"></a>Masking Rules</h3>
 578     <ul>
 579       <li>
 580         <p>A single asterisk (*) is used to mask zero or more characters. </p></li>
 581       <li>
 582         <p>A single question mark (?) is used to mask a single character, thus
 583           N consecutive question-marks means mask N characters. </p></li>
 584       <li>
 585         <p>Carat/hat (^) is used as an anchor character for terms that are word
 586           lists, that is, where the relation is 'all' or 'any', or '=' when used
 587           for word adjacency. It may not be used to anchor a string, that is,
 588           when relation is 'exact' (string matches are, by definition, anchored).
 589           It may occur at the beginning or end of a word (with no intervening
 590           space) to mean right or left anchored."^" has no special meaning when
 591           it occurs within a word (not at the beginning or end) or string but
 592           must be escaped nevertheless. </p>
 593       </li>
 594       <li>
 595         <p> Backslash (\) is used to escape '*', '?', quote (") and '^' , as
 596           well as itself. The use of a backslash not followed immediately by
 597           one of these characters is reserved for future definition.</p>
 598       </li>
 599     </ul>
 600     <p>Masking examples: </p>
 601     <ul>
 602       <li>
 603         <p>dc.title = c*t <i>(matches cat and coast etc.)</i></p></li>
 604       <li>
 605         <p>dc.title = c?t <i>(matches cat and cot, not coast or ct)</i><br>
 606 " ?" <i>(matches any single character)</i> </p></li>
 607       <li>
 608         <p>dc.title = "^cat in the hat" <i>(matches 'cat in the hat' where it
 609         is at the beginning of the field)</i></p>
 610       </li>
 611       <li>
 612         <p>dc.title any "^cat  eats rat" <i>(matches  'cat eats rat', 'cat eats
 613             dog', 'cat', but not 'rat eats cat')</i> </p>
 614       </li>
 615       <li>
 616         <p>
 617           dc.title any "^cat ^dog eats rat" <i>(matches 'cat eats rat',  'dog
 618           eats cat', 'cat
 619           loves bat', but not 'bat loves cat')</i> </p>
 620       </li>
 621       <li>
 622         <p>dc.title = "\"Of Couse\" she said"</p>
 623       </li>
 624     </ul>
 625     <h3><strong><a name="resultset"></a>Result Set Name Used in Query</strong></h3>
 626     <p>A search clause may be a result set name. This is a special case, employing
 627       the context set '<a href="http://www.loc.gov/z3950/agency/zing/cql/context-sets/cql.html">cql</a>'.
 628       The index and relation are expressed as "cql.resultSetId =" and
 629       the term is a result set name that has been returned by the server in the
 630       'resultSetName' parameter of the response. It may be used by itself in
 631       a query to refer to an existing result set from which records are desired.
 632       It may also be used in conjunction with other resultSetName clauses or
 633       other indexes, combined by boolean operators. The semantics of resultSetId
 634       with relations other than "=" is undefined. </p>
 635     <p> Example: cql.resultSetId = "resultA" and cql.resultSetId = "resultB" </p>
 636     <h3><strong><a name="proximity"></a>Proximity</strong></h3>
 637     <p>The proximity boolean boolean operator is expressed in terms of distance,
 638       unit, and ordering.</p>
 639     <p>Examples:</p>
 640     <ul>
 641       <li> dc.title = "cat" prox/distance=1/unit=word dc.title
 642       = "in"</li>
 643       <li>"cat" prox/distance&gt;2/ordered "hat" </li>
 644     </ul>
 645     <p><strong>distance</strong> takes the form:<br>
 646 &nbsp;&nbsp;&nbsp;&nbsp; distance [relation] [value] <br>
 647 where relation is one of: "&lt;", "&gt;" ,"&lt;=" ,"&gt;=" ,"=" , "&lt;&gt;"; <i>default "&lt;="</i><br>
 648 and value is a non-negative integer; <i>default: 1 for word, zero otherwise</i></p>
 649     <p><strong>unit</strong> takes the form<br>
 650       &nbsp;&nbsp;&nbsp;&nbsp; unit=[value] <br>
 651     where value is one of "word", "sentence", "paragraph", or "element"<i>(default "word"</i>),</p>
 652     <p><strong>ordering</strong> is "ordered" or "unordered"; <i>default "unordered"</i></p>
 653     <p>&nbsp; </p>
 654     <hr>
 655     <h2><a name="context"></a>CQL Context Sets</h2>
 656     <p>Context sets permit CQL users to create their own indexes, relations,
 657       relation modifiers and boolean modiers without fear of chosing the same
 658       name as someone else and thereby having an ambiguous query. All of these
 659       four aspects of CQL must come from a context set, however there are rules
 660       for determining the prevailing default if one is not supplied. Context
 661       sets allow CQL to be used by communities in ways which the designers could
 662       not have foreseen, while still maintaining the same rules for parsing which
 663       allow interoperability.</p>
 664     <p>When defining a new context set, it is necessary to provide a description
 665       of the semantics of each item within it. While context sets may contain
 666       indexes, relations, relation modifiers and boolean modifiers, there is
 667       no requirement that all should be present; in fact it is expected that
 668     most context sets will only define indexes.</p>
 669     <p>Each context set has a unique identifier, a URI. When sending the context
 670       set in a query, a short form is used. These short names may be sent as
 671       a mapping within the query itself (see next), or be published by the recipient
 672       of the query in some protocol dependent fashion. The prefix 'cql' is reserved
 673       for the CQL context set, but authors may wish to recommend a short name
 674     for use with their set. </p>
 675     <p> An index, relation, or modifier qualified by a context is represented
 676       in the form <i>prefix</i>.<i>value</i>, where <i>prefix</i> is a short
 677       name for a unique context set identifier. </p>
 678     <p><strong>Binding Short Name to URI<br>
 679     </strong>The binding of short name to
 680         URI is defined either within the query or by the server. A prefix map
 681       may occur at any place in the query and applies to anything which follows.
 682     Example: </p>
 683     <p class="box2">&gt;dc="http://www.dublincore.org/" dc.title = "cat"</p>
 684     <p>
 685     </p><p>In the following query:
 686     </p><p>
 687
 688     </p><p class="box2">&gt;a="http:/x.com/y" a.title=cat and (&gt;a="http:/f.com/g" a.title=hat)
 689     and a.title=rat</p>
 690     <p>
 691     </p><p>both the "a" in "a.title=cat"&nbsp;and in "a.title=rat" refer
 692       to http:/x.com/y, while the "a" in "a.title=rat" refers
 693     to http:/f.com/g.</p>
 694     <p> <strong>Default Context</strong><br>
 695       When no context is attached to a relation, relation modifier,
 696       or boolean modifier, the context is the cql context set.&nbsp; When no
 697       context is attached to an index the context is determined by the server.</p>
 698     <p><strong>Known Context Sets</strong><br>
 699       The following context sets have been defined and made
 700       public. If you wish to have your context set listed here, please provide
 701       the information
 702       to
 703     the <a href="mailto:z950@loc.gov">SRU Maintenance Agency</a>.</p>
 704     <table align="center" border="1" cellpadding="5" cellspacing="0" width="95%">
 705       <tbody>
 706         <tr>
 707           <th scope="col" bgcolor="#fff9e5" width="15%">Short Name</th>
 708           <th scope="col" bgcolor="#fff9e5" width="60%">Identifier</th>
 709           <th scope="col" bgcolor="#fff9e5" width="25%">Reference</th>
 710         </tr>
 711         <tr>
 712         <td scope="row"><p><strong>cql</strong></p>
 713           </td>
 714           <td><p>info:srw/cql-context-set/1/cql-v1.1</p>
 715           </td>
 716           <td><p><a href="http://www.loc.gov/standards/sru/cql/cql-context-set.html">CQL context set</a></p>
 717           </td>
 718         </tr>
 719         <tr>
 720         <td scope="row"><p>dc</p>
 721           </td>
 722           <td><p>info:srw/cql-context-set/1/dc-v1.1</p>
 723           </td>
 724           <td><p><a href="http://www.loc.gov/standards/sru/cql/dc-context-set.html">Dublin Core Context Set</a></p>
 725           </td>
 726         </tr>
 727         <tr>
 728         <td scope="row"><p>bath</p>
 729           </td>
 730           <td>
 731             <p>http://zing.z3950.org/cql/bath/2.0/</p>
 732           </td>
 733           <td><p><a href="http://zing.z3950.org/srw/bath/2.0/#2">Bath Context
 734                 Set</a></p>
 735           </td>
 736         </tr>
 737         <tr>
 738         <td scope="row"><p>zthes</p>
 739           </td>
 740           <td><p>http://zthes.z3950.org/cql/1.0/</p>
 741           </td>
 742           <td><p><a href="http://zthes.z3950.org/cql/">ZThes thesaurus context
 743                 set</a>, v1.0.</p>
 744           </td>
 745         </tr>
 746         <tr>
 747         <td scope="row"><p>ccg</p>
 748           </td>
 749           <td><p>http://srw.cheshire3.org/contextSets/ccg/1.1/</p>
 750           </td>
 751           <td><p><a href="http://srw.cheshire3.org/contextSets/ccg/">Collectable
 752                 card games</a> </p>
 753           </td>
 754         </tr>
 755         <tr>
 756         <td scope="row"><p>rec</p>
 757           </td>
 758           <td><p>info:srw/cql-context-set/2/rec-1.1</p>
 759           </td>
 760           <td><p><a href="http://srw.cheshire3.org/contextSets/rec/1.1/">Record metadata</a></p>
 761           </td>
 762         </tr>
 763         <tr>
 764         <td scope="row"><p>net</p>
 765           </td>
 766           <td><p>info:srw/cql-context-set/2/net-1.0</p>
 767           </td>
 768           <td><p><a href="http://srw.cheshire3.org/contextSets/net/">Network
 769                 resource information</a></p>
 770           </td>
 771         </tr>
 772         <tr>
 773         <td scope="row"><p>music</p>
 774           </td>
 775           <td><p>info:srw/cql-context-set/3/music-1.0 </p>
 776           </td>
 777           <td><p><a href="http://www.ceridwen.com/srw/music-contextset.html">Music
 778                 Context Set</a></p>
 779           </td>
 780         </tr>
 781         <tr>
 782         <td scope="row"><p>rel</p>
 783           </td>
 784           <td><p>info:srw/cql-context-set/2/relevance-1.0</p>
 785           </td>
 786           <td><p><a href="http://srw.cheshire3.org/contextSets/rel/">Relevance
 787                 Ranking</a></p>
 788           </td>
 789         </tr>
 790         <tr>
 791         <td scope="row"><p>zeerex</p>
 792           </td>
 793           <td>
 794             <p>info:srw/cql-context-set/2/zeerex-1.1</p>
 795           </td>
 796           <td><p><a href="http://srw.cheshire3.org/contextSets/ZeeRex/">ZeeRex
 797                 Context Set</a></p>
 798           </td>
 799         </tr>
 800         <tr>
 801           <td scope="row"><p>marc</p>
 802           </td>
 803           <td><p>info:srw/cql-context-set/1/marc-1.0</p></td>
 804           <td><p><a href="http://www.loc.gov/standards/sru/cql/marc-context-set.html">MARC Context Set</a></p></td>
 805         </tr>
 806       </tbody>
 807     </table>
 808     <p>
 809     </p><hr>
 810     <h2><a name="conformance"></a>Conformance</h2>
 811     <p>In order to claim conformance to CQL a server must support one of the
 812       following three levels:</p>
 813     <p><strong>Level 0</strong></p>
 814     <ol>
 815       <li>
 816         <p>Must be able to process a term-only query.<br>
 817       (The term is either a single word or if multiple words separated by spaces
 818         then the entire search term is quoted). If the term includes quote marks,
 819         they must be a escaped by preceding them with a backslash, e.g."raising
 820         the \"titanic\"".)</p>
 821       </li>
 822       <li>
 823         <p>If an unsupported query is supplied, must be able to respond with
 824           a diagnostic to say that the query is not supported.</p>
 825       </li>
 826     </ol>
 827     <p><strong>Level 1</strong></p>
 828     <ol>
 829       <li>
 830         <p> Support for Level 0.</p>
 831       </li>
 832       <li>
 833         <p> Ability to <em>parse</em> both: <br>
 834       (a) search clauses consisting of 'index relation searchTerm'; and <br>
 835       (b) queries where search terms are combined with booleans, e.g. "term1
 836       AND term2" </p></li>
 837       <li>
 838         <p><em>Support</em> for at least one of (a) and (b). </p></li>
 839     </ol>
 840     <p>Note that (b) does not necessarily include queries such as:</p>
 841     <blockquote>
 842       <p> index relation term1 AND index relation term2</p>
 843     </blockquote>
 844     <p> but rather queries where the search clauses are terms-only (do not include
 845       index or relation).</p>
 846     <p><strong>Level 2</strong></p>
 847     <ol>
 848       <li>
 849         <p> Support for Level 1. </p>
 850       </li>
 851       <li>
 852         <p>Ability to <em>parse</em> all of CQL and respond with appropriate
 853           diagnostics.</p>
 854       </li>
 855     </ol>
 856     <p>Note that Level 2 does not require <em>support</em> for all of CQL, it
 857       requires that the server be able to <em>parse</em> all of CQL (and respond
 858       with proper diagnostics for the parts not supported.).</p>
 859     <!-- InstanceEndEditable -->
 860     <div id="bottom-bread"> <a href="http://www.loc.gov/standards/sru/index.html">Home</a> &gt;&gt; <!-- InstanceBeginEditable name="bottombreadcrumb" --><span class="selected">CQL</span><!-- InstanceEndEditable --></div>
 861   </div>
 862   <div id="footer">
 863     <div id="bottom-left"><a href="http://www.loc.gov/" class="white">The Library
 864         of Congress</a><span class="white-text">&nbsp;»&nbsp;</span><a href="http://www.loc.gov/library/" class="white">Librarians,
 865         Archivists</a><span class="white-text">&nbsp;»</span> <a href="http://www.loc.gov/standards/" class="white">Standards</a><br>
 866           <span class="white-text">
 867           <!-- #BeginDate format:Am1 -->March 8, 2007<!-- #EndDate -->
 868         </span></div>
 869     <div class="white-text" id="contactus"><a href="mailto:z3950@loc.gov" class="white">Contact
 870         Us</a></div>
 871   </div>
 872 </div>
 873 <script type="text/javascript" src="cql_files/s_code.js"></script><img src="cql_files/s61224011715843.gif" name="s_i_locgovprod" alt="" border="0" height="1" width="1"><!-- InstanceEnd --></body></html>