doc/querymodel.xml

   1  <chapter id="querymodel">
   2   <!-- $Id: querymodel.xml,v 1.21 2006-07-03 11:30:59 marc Exp $ -->
   3   <title>Query Model</title>
   4
   5   <sect1 id="querymodel-overview">
   6    <title>Query Model Overview</title>
   7
   8    <sect2 id="querymodel-query-languages">
   9     <title>Query Languages</title>
  10
  11     <para>
  12      Zebra is born as a networking Information Retrieval engine adhering
  13      to the international standards
  14      <ulink url="&url.z39.50;">Z39.50</ulink> and
  15      <ulink url="&url.sru;">SRU</ulink>,
  16      and implement the
  17      <literal>type-1 Reverse Polish Notation (RPN)</literal> query
  18      model defined there.
  19      Unfortunately, this model has only defined a binary
  20      encoded representation, which is used as transport packaging in
  21      the Z39.50 protocol layer. This representation is not human
  22      readable, nor defines any convenient way to specify queries.
  23     </para>
  24     <para>
  25      Since the <literal>type-1 (RPN)</literal>
  26      query structure has no direct, useful string
  27      representation, every client application needs to provide some
  28      form of mapping from a local query notation or representation to it.
  29     </para>
  30
  31
  32     <sect3 id="querymodel-query-languages-pqf">
  33      <title>Prefix Query Format (PQF)</title>
  34      <para>
  35       Index Data has defined a textual representation in the
  36       <ulink url="&url.yaz.pqf;">Prefix Query Format</ulink>, short
  37       <emphasis>PQF</emphasis>, which maps
  38       one-to-one to binary encoded
  39       <emphasis>type-1 RPN</emphasis> queries.
  40       PQF has been adopted by other
  41       parties developing Z39.50 software, and is often referred to as
  42       <literal>Prefix Query Notation</literal>, or in short
  43       <literal>PQN</literal>. See
  44       <xref linkend="querymodel-pqf"/> for further explanations and
  45       descriptions of Zebra's capabilities.
  46      </para>
  47     </sect3>
  48
  49     <sect3 id="querymodel-query-languages-cql">
  50      <title>Common Query Language (CQL)</title>
  51      <para>
  52       The query model of the type-1 RPN,
  53       expressed in PQF/PQN is natively supported.
  54       On the other hand, the default SRU
  55       web services <emphasis>Common Query Language</emphasis>
  56       <ulink url="&url.cql;">CQL</ulink> is not natively supported.
  57      </para>
  58      <para>
  59       Zebra can be configured to understand and map CQL to PQF. See
  60       <xref linkend="querymodel-cql-to-pqf"/>.
  61      </para>
  62     </sect3>
  63
  64    </sect2>
  65
  66    <sect2 id="querymodel-operation-types">
  67     <title>Operation types</title>
  68     <para>
  69      Zebra supports all of the three different
  70      <literal>Z39.50/SRU</literal> operations defined in the
  71      standards: <literal>explain</literal>, <literal>search</literal>,
  72      and <literal>scan</literal>. A short description of the
  73      functionality and purpose of each is quite in order here.
  74     </para>
  75
  76     <sect3 id="querymodel-operation-type-explain">
  77      <title>Explain Operation</title>
  78      <para>
  79       The <emphasis>syntax</emphasis> of Z39.50/SRU queries is
  80       well known to any client, but the specific
  81       <emphasis>semantics</emphasis> - taking into account a
  82       particular servers functionalities and abilities - must be
  83       discovered from case to case. Enters the
  84       <literal>explain</literal> operation, which provides the means
  85       for learning which
  86       <emphasis>fields</emphasis> (also called
  87       <emphasis>indexes</emphasis> or <emphasis>access points</emphasis>)
  88       are provided, which default parameter the server uses, which
  89       retrieve document formats are defined, and which specific parts
  90       of the general query model are supported.
  91      </para>
  92      <para>
  93       The Z39.50 embeds the <literal>explain</literal> operation
  94       by performing a
  95       <literal>search</literal> in the magic
  96       <literal>IR-Explain-1</literal> database;
  97       see <xref linkend="querymodel-exp1"/>.
  98      </para>
  99      <para>
 100       In SRU, <literal>explain</literal> is an entirely  separate
 101       operation, which returns an  <literal>ZeeRex
 102       XML</literal> record according to the
 103       structure defined by the protocol.
 104      </para>
 105      <para>
 106       In both cases, the information gathered through
 107       <literal>explain</literal> operations can be used to
 108       auto-configure a client user interface to the servers
 109       capabilities.
 110      </para>
 111     </sect3>
 112
 113     <sect3 id="querymodel-operation-type-search">
 114      <title>Search Operation</title>
 115      <para>
 116       Search and retrieve interactions are the raison d'être.
 117       They are used to query the remote database and
 118       return search result documents.  Search queries span from
 119       simple free text searches to nested complex boolean queries,
 120       targeting specific indexes, and possibly enhanced with many
 121       query semantic specifications. Search interactions are the heart
 122       and soul of Z39.50/SRU servers.
 123      </para>
 124     </sect3>
 125
 126     <sect3 id="querymodel-operation-type-scan">
 127      <title>Scan Operation</title>
 128      <para>
 129       The <literal>scan</literal> operation is a helper functionality,
 130        which operates on one index or access point a time.
 131      </para>
 132      <para>
 133       It provides
 134       the means to investigate the content of specific indexes.
 135       Scanning an index returns a handful of terms actually found in
 136       the indexes, and in addition the <literal>scan</literal>
 137       operation returns the number of documents indexed by each term.
 138       A search client can use this information to propose proper
 139       spelling of search terms, to auto-fill search boxes, or to
 140       display  controlled vocabularies.
 141      </para>
 142     </sect3>
 143
 144    </sect2>
 145
 146  </sect1>
 147
 148
 149   <sect1 id="querymodel-pqf">
 150    <title>Prefix Query Format syntax and semantics</title>
 151    <para>
 152     The <ulink url="&url.yaz.pqf;">PQF grammar</ulink>
 153     is documented in the YAZ manual, and shall not be
 154     repeated here. This textual PQF representation
 155     is not transmistted to Zebra during search, but it is in the
 156     client mapped to the equivalent Z39.50 binary
 157     query parse tree.
 158    </para>
 159
 160    <sect2 id="querymodel-pqf-tree">
 161     <title>PQF tree structure</title>
 162     <para>
 163      The PQF parse tree - or the equivalent textual representation -
 164      may start with one specification of the
 165      <emphasis>attribute set</emphasis> used. Following is a query
 166      tree, which
 167      consists of <emphasis>atomic query parts (APT)</emphasis> or
 168      <emphasis>named result sets</emphasis>, eventually
 169      paired by <emphasis>boolean binary operators</emphasis>, and
 170      finally  <emphasis>recursively combined </emphasis> into
 171      complex query trees.
 172     </para>
 173
 174     <sect3 id="querymodel-attribute-sets">
 175      <title>Attribute sets</title>
 176      <para>
 177       Attribute sets define the exact meaning and semantics of queries
 178       issued. Zebra comes with some predefined attribute set
 179       definitions, others can easily be defined and added to the
 180       configuration.
 181      </para>
 182
 183
 184      <table id="querymodel-attribute-sets-table"
 185       frame="all" rowsep="1" colsep="1" align="center">
 186
 187       <caption>Attribute sets predefined in Zebra</caption>
 188
 189        <thead>
 190        <tr>
 191          <td>Attribute set</td>
 192          <td>Short hand</td>
 193          <td>Status</td>
 194          <td>Notes</td>
 195         </tr>
 196       </thead>
 197
 198        <tbody>
 199         <tr>
 200          <td><literal>Explain</literal></td>
 201          <td><literal>exp-1</literal></td>
 202          <td>Special attribute set used on the special automagic
 203           <literal>IR-Explain-1</literal> database to gain information on
 204           server capabilities, database names, and database
 205           and semantics.</td>
 206          <td>predefined</td>
 207         </tr>
 208         <tr>
 209          <td><literal>Bib1</literal></td>
 210          <td><literal>bib-1</literal></td>
 211          <td>Standard PQF query language attribute set which defines the
 212           semantics of Z39.50 searching. In addition, all of the
 213           non-use attributes (type 2-9) define the hard-wired
 214           Zebra internal query
 215           processing.</td>
 216          <td>default</td>
 217         </tr>
 218         <tr>
 219          <td><literal>GILS</literal></td>
 220          <td><literal>gils</literal></td>
 221          <td>Extension to the <literal>Bib1</literal> attribute set.</td>
 222          <td>predefined</td>
 223         </tr>
 224         <!--
 225         <tr>
 226          <td><literal>IDXPATH</literal></td>
 227          <td><literal>idxpath</literal></td>
 228          <td>Hardwired XPATH like attribute set, only available for
 229              indexing with the GRS record model</td>
 230          <td>deprecated</td>
 231         </tr>
 232         -->
 233        </tbody>
 234      </table>
 235     </sect3>
 236
 237     <para>
 238      The <literal>use attributes (type 1)</literal> mappings  the
 239      predefined attribute sets are found in the
 240      attribute set configuration files <filename>tab/*.att</filename>.
 241     </para>
 242
 243     <note>
 244      The Zebra internal query processing is modeled after
 245      the <literal>Bib1</literal> attribute set, and the non-use
 246      attributes type 2-6 are hard-wired in. It is therefore essential
 247      to be familiar with <xref linkend="querymodel-bib1-nonuse"/>.
 248     </note>
 249
 250
 251     <sect3 id="querymodel-boolean-operators">
 252      <title>Boolean operators</title>
 253      <para>
 254       A pair of sub query trees, or of atomic queries, is combined
 255       using the standard boolean operators into new query trees.
 256       Thus, boolean operators are always internal nodes in the query tree.
 257      </para>
 258
 259      <table id="querymodel-boolean-operators-table"
 260       frame="all" rowsep="1" colsep="1" align="center">
 261
 262       <caption>Boolean operators</caption>
 263        <thead>
 264         <tr>
 265          <td>Keyword</td>
 266          <td>Operator</td>
 267          <td>Description</td>
 268         </tr>
 269       </thead>
 270        <tbody>
 271         <tr><td><literal>@and</literal></td>
 272          <td>binary <literal>AND</literal> operator</td>
 273          <td>Set intersection of two atomic queries hit sets</td>
 274         </tr>
 275         <tr><td><literal>@or</literal></td>
 276          <td>binary <literal>OR</literal> operator</td>
 277          <td>Set union of two atomic queries hit sets</td>
 278         </tr>
 279         <tr><td><literal>@not</literal></td>
 280          <td>binary <literal>AND NOT</literal> operator</td>
 281          <td>Set complement of two atomic queries hit sets</td>
 282         </tr>
 283         <tr><td><literal>@prox</literal></td>
 284          <td>binary <literal>PROXIMITY</literal> operator</td>
 285          <td>Set intersection of two atomic queries hit sets. In
 286           addition, the intersection set is purged for all
 287           documents which do not satisfy the requested query
 288           term proximity. Usually a proper subset of the AND
 289           operation.</td>
 290         </tr>
 291        </tbody>
 292      </table>
 293
 294      <para>
 295       For example, we can combine the terms
 296       <emphasis>information</emphasis> and <emphasis>retrieval</emphasis>
 297       into different searches in the default index of the default
 298       attribute set as follows.
 299       Querying for the union of all documents containing the
 300       terms <emphasis>information</emphasis> OR
 301       <emphasis>retrieval</emphasis>:
 302       <screen>
 303        Z> find @or information retrieval
 304       </screen>
 305      </para>
 306      <para>
 307       Querying for the intersection of all documents containing the
 308       terms <emphasis>information</emphasis> AND
 309       <emphasis>retrieval</emphasis>:
 310       The hit set is a subset of the corresponding
 311       OR query.
 312       <screen>
 313        Z> find @and information retrieval
 314       </screen>
 315      </para>
 316      <para>
 317       Querying for the intersection of all documents containing the
 318       terms <emphasis>information</emphasis> AND
 319       <emphasis>retrieval</emphasis>, taking proximity into account:
 320       The hit set is a subset of the corresponding
 321       AND query
 322       (see the <ulink url="&url.yaz.pqf;">PQF grammar</ulink> for
 323       details on the proximity operator):
 324       <screen>
 325        Z> find @prox 0 3 0 2 k 2 information retrieval
 326       </screen>
 327      </para>
 328      <para>
 329       Querying for the intersection of all documents containing the
 330       terms <emphasis>information</emphasis> AND
 331       <emphasis>retrieval</emphasis>, in the same order and near each
 332       other as described in the term list.
 333       The hit set is a subset of the corresponding
 334       PROXIMITY query.
 335       <screen>
 336        Z> find "information retrieval"
 337       </screen>
 338      </para>
 339     </sect3>
 340
 341
 342     <sect3 id="querymodel-atomic-queries">
 343      <title>Atomic queries (APT)</title>
 344      <para>
 345       Atomic queries are the query parts which work on one access point
 346       only. These consist of <literal>an attribute list</literal>
 347       followed by a <literal>single term</literal> or a
 348       <literal>quoted term list</literal>, and are often called
 349       <emphasis>Attributes-Plus-Terms (APT)</emphasis> queries.
 350      </para>
 351      <para>
 352       Atomic (APT) queries are always leaf nodes in the PQF query tree.
 353       UN-supplied non-use attributes type 2-9 are either inherited from
 354       higher nodes in the query tree, or are set to Zebra's default values.
 355       See <xref linkend="querymodel-bib1"/> for details.
 356      </para>
 357
 358      <table id="querymodel-atomic-queries-table"
 359       frame="all" rowsep="1" colsep="1" align="center">
 360
 361       <caption>Atomic queries (APT)</caption>
 362        <thead>
 363         <tr>
 364          <td>Name</td>
 365          <td>Type</td>
 366          <td>Notes</td>
 367         </tr>
 368       </thead>
 369        <tbody>
 370         <tr>
 371          <td><emphasis>attribute list</emphasis></td>
 372          <td>List of <literal>orthogonal</literal> attributes</td>
 373          <td>Any of the orthogonal attribute types may be omitted,
 374           these are inherited from higher query tree nodes, or if not
 375           inherited, are set to the default Zebra configuration values.
 376          </td>
 377         </tr>
 378         <tr>
 379          <td><emphasis>term</emphasis></td>
 380          <td>single <literal>term</literal>
 381           or <literal>quoted term list</literal>   </td>
 382          <td>Here the search terms or list of search terms is added
 383           to the query</td>
 384         </tr>
 385        </tbody>
 386      </table>
 387      <para>
 388       Querying for the term <emphasis>information</emphasis> in the
 389       default index using the default attribute set, the server choice
 390       of access point/index, and the default non-use attributes.
 391       <screen>
 392        Z> find information
 393       </screen>
 394      </para>
 395      <para>
 396       Equivalent query fully specified including all default values:
 397       <screen>
 398        Z> find @attrset bib-1 @attr 1=1017 @attr 2=3 @attr 3=3 @attr 4=1 @attr 5=100 @attr 6=1 information
 399       </screen>
 400      </para>
 401
 402      <para>
 403       Finding all documents which have the term
 404       <emphasis>debussy</emphasis> in the title field.
 405       <screen>
 406        Z> find @attr 1=4 debussy
 407       </screen>
 408      </para>
 409
 410      <para>
 411       The <literal>scan</literal> operation is only supported with
 412       atomic APT queries, as it is bound to one access point at a
 413       time. Boolean query trees are not allowed during
 414       <literal>scan</literal>.
 415       </para>
 416
 417      <para>
 418       For example, we might want to scan the title index, starting with
 419       the term
 420       <emphasis>debussy</emphasis>, and displaying this and the
 421       following terms in lexicographic order:
 422       <screen>
 423        Z> scan @attr 1=4 debussy
 424       </screen>
 425      </para>
 426     </sect3>
 427
 428
 429     <sect3 id="querymodel-resultset">
 430      <title>Named Result Sets</title>
 431      <para>
 432       Named result sets are supported in Zebra, and result sets can be
 433       used as operands without limitations. It follows that named
 434       result sets are leaf nodes in the PQF query tree, exactly as
 435       atomic APT queries are.
 436      </para>
 437      <para>
 438       After the execution of a search, the result set is available at
 439       the server, such that the client can use it for subsequent
 440       searches or retrieval requests. The Z30.50 standard actually
 441       stresses the fact that result sets are volatile. It may cease
 442       to exist at any time point after search, and the server will
 443       send a diagnostic to the effect that the requested
 444       result set does not exist any more.
 445      </para>
 446
 447      <para>
 448       Defining a named result set and re-using it in the next query,
 449       using <literal>yaz-client</literal>. Notice that the client, not
 450       the server, assigns the string <literal>'1'</literal> to the
 451       named result set.
 452       <screen>
 453        Z> f @attr 1=4 mozart
 454        ...
 455        Number of hits: 43, setno 1
 456        ...
 457        Z> f @and @set 1 @attr 1=4 amadeus
 458        ...
 459        Number of hits: 14, setno 2
 460       </screen>
 461      </para>
 462
 463      <note>
 464       Named result sets are only supported by the Z39.50 protocol.
 465       The SRU web service is stateless, and therefore the notion of
 466       named result sets does not exist when accessing a Zebra server by
 467       the SRU protocol.
 468      </note>
 469     </sect3>
 470
 471
 472     <sect3 id="querymodel-use-string">
 473      <title>Zebra's special access point of type 'string'</title>
 474      <para>
 475       The numeric <literal>use (type 1)</literal> attribute is usually
 476       referred to from a given
 477       attribute set. In addition, Zebra let you use
 478       <emphasis>any internal index
 479        name defined in your configuration</emphasis>
 480       as use attribute value. This is a great feature for
 481       debugging, and when you do
 482       not need the complexity of defined use attribute values. It is
 483       the preferred way of accessing Zebra indexes directly.
 484      </para>
 485      <para>
 486       Finding all documents which have the term list "information
 487       retrieval" in an Zebra index, using it's internal full string
 488       name. Scanning the same index.
 489       <screen>
 490        Z> find @attr 1=sometext "information retrieval"
 491        Z> scan @attr 1=sometext aterm
 492       </screen>
 493      </para>
 494      <para>
 495       Searching or scanning
 496       the bib-1 use attribute 54 using it's string name:
 497       <screen>
 498        Z> find @attr 1=Code-language eng
 499        Z> scan @attr 1=Code-language ""
 500       </screen>
 501      </para>
 502      <para>
 503       It is possible to search
 504       in any silly string index - if it's defined in your
 505       indexation rules and can be parsed by the PQF parser.
 506       This is definitely not the recommended use of
 507       this facility, as it might confuse your users with some very
 508       unexpected results.
 509       <screen>
 510        Z> find @attr 1=silly/xpath/alike[@index]/name "information retrieval"
 511       </screen>
 512      </para>
 513      <para>
 514       See also <xref linkend="querymodel-pqf-apt-mapping"/> for details, and
 515       <xref linkend="server-sru"/>
 516       for the SRU PQF query extension using string names as a fast
 517       debugging facility.
 518      </para>
 519     </sect3>
 520
 521     <sect3 id="querymodel-use-xpath">
 522      <title>Zebra's special access point of type 'XPath'
 523       for GRS filters</title>
 524      <para>
 525       As we have seen above, it is possible (albeit seldom a great
 526       idea) to emulate
 527       <ulink url="http://www.w3.org/TR/xpath">XPath 1.0</ulink> based
 528       search by defining <literal>use (type 1)</literal>
 529       <emphasis>string</emphasis> attributes which in appearance
 530       <emphasis>resemble XPath queries</emphasis>. There are two
 531       problems with this approach: first, the XPath-look-alike has to
 532       be defined at indexation time, no new undefined
 533       XPath queries can entered at search time, and second, it might
 534       confuse users very much that an XPath-alike index name in fact
 535       gets populated from a possible entirely different XML element
 536       than it pretends to access.
 537      </para>
 538      <para>
 539       When using the <literal>GRS Record Model</literal>
 540       (see  <xref linkend="record-model-grs"/>), we have the
 541       possibility to embed <emphasis>life</emphasis>
 542       XPath expressions
 543       in the PQF queries, which are here called
 544       <literal>use (type 1)</literal> <emphasis>xpath</emphasis>
 545       attributes. You must enable the
 546       <literal>xpath enable</literal> directive in your
 547       <literal>.abs</literal> configuration files.
 548      </para>
 549      <note>
 550       Only a <emphasis>very</emphasis> restricted subset of the
 551       <ulink url="http://www.w3.org/TR/xpath">XPath 1.0</ulink>
 552       standard is supported as the GRS record model is simpler than
 553       a full XML DOM structure. See the following examples for
 554       possibilities.
 555      </note>
 556      <para>
 557       Finding all documents which have the term "content"
 558       inside a text node found in a specific XML DOM
 559       <emphasis>subtree</emphasis>, whose starting element is
 560       addressed by XPath.
 561       <screen>
 562        Z> find @attr 1=/root content
 563        Z> find @attr 1=/root/first content
 564       </screen>
 565       <emphasis>Notice that the
 566        XPath must be absolute, i.e., must start with '/', and that the
 567        XPath <literal>descendant-or-self</literal> axis followed by a
 568        text node selection <literal>text()</literal> is implicitly
 569        appended to the stated XPath.
 570       </emphasis>
 571       It follows that the above searches are interpreted as:
 572       <screen>
 573        Z> find @attr 1=/root//text() content
 574        Z> find @attr 1=/root/first//text() content
 575       </screen>
 576      </para>
 577
 578      <para>
 579       Searching inside attribute strings is possible:
 580       <screen>
 581        Z> find @attr 1=/link/@creator morten
 582       </screen>
 583       </para>
 584
 585      <para>
 586       Filter the addressing XPath by a predicate working on exact
 587       string values in
 588       attributes (in the XML sense) can be done: return all those docs which
 589       have the term "english" contained in one of all text sub nodes of
 590       the subtree defined by the XPath
 591       <literal>/record/title[@lang='en']</literal>. And similar
 592       predicate filtering.
 593       <screen>
 594        Z> find @attr 1=/record/title[@lang='en'] english
 595        Z> find @attr 1=/link[@creator='sisse'] sibelius
 596        Z> find @attr 1=/link[@creator='sisse']/description[@xml:lang='da'] sibelius
 597       </screen>
 598      </para>
 599
 600      <para>
 601       Combining numeric indexes, boolean expressions,
 602       and xpath based searches is possible:
 603       <screen>
 604        Z> find @attr 1=/record/title @and foo bar
 605        Z> find @and @attr 1=/record/title foo @attr 1=4 bar
 606       </screen>
 607      </para>
 608      <para>
 609       Escaping PQF keywords and other non-parseable XPath constructs
 610       with <literal>'{ }'</literal> to prevent client-side PQF parsing
 611       syntax errors:
 612       <screen>
 613        Z> find @attr {1=/root/first[@attr='danish']} content
 614        Z> find @attr {1=/record/@set} oai
 615       </screen>
 616      </para>
 617      <warning>
 618       It is worth mentioning that these dynamic performed XPath
 619       queries are a performance bottleneck, as no optimized
 620       specialized indexes can be used. Therefore, avoid the use of
 621       this facility when speed is essential, and the database content
 622       size is medium to large.
 623      </warning>
 624
 625     </sect3>
 626
 627    </sect2>
 628
 629    <sect2 id="querymodel-exp1">
 630     <title>Explain Attribute Set</title>
 631     <para>
 632      The Z39.50 standard defines the
 633      <ulink url="&url.z39.50.explain;">Explain</ulink> attribute set
 634      <literal>Exp-1</literal>, which is used to discover information
 635      about a server's search semantics and functional capabilities
 636      Zebra exposes a  "classic"
 637      Explain database by base name <literal>IR-Explain-1</literal>, which
 638      is populated with system internal information.
 639     </para>
 640    <para>
 641      The attribute-set <literal>exp-1</literal> consists of a single
 642      <literal>use attribute (type 1)</literal>.
 643     </para>
 644     <para>
 645      In addition, the non-Use
 646      <literal>bib-1</literal> attributes, that is, the types
 647      <literal>Relation</literal>, <literal>Position</literal>,
 648      <literal>Structure</literal>, <literal>Truncation</literal>,
 649      and <literal>Completeness</literal> are imported from
 650      the <literal>bib-1</literal> attribute set, and may be used
 651      within any explain query.
 652     </para>
 653
 654     <sect3 id="querymodel-exp1-use">
 655     <title>Use Attributes (type = 1)</title>
 656      <para>
 657       The following Explain search attributes are supported:
 658       <literal>ExplainCategory</literal> (@attr 1=1),
 659       <literal>DatabaseName</literal> (@attr 1=3),
 660       <literal>DateAdded</literal> (@attr 1=9),
 661       <literal>DateChanged</literal>(@attr 1=10).
 662      </para>
 663      <para>
 664       A search in the use attribute  <literal>ExplainCategory</literal>
 665       supports only these predefined values:
 666       <literal>CategoryList</literal>, <literal>TargetInfo</literal>,
 667       <literal>DatabaseInfo</literal>, <literal>AttributeDetails</literal>.
 668      </para>
 669      <para>
 670       See <filename>tab/explain.att</filename> and the
 671       <ulink url="&url.z39.50;">Z39.50</ulink> standard
 672       for more information.
 673      </para>
 674     </sect3>
 675
 676     <sect3>
 677      <title>Explain searches with yaz-client</title>
 678      <para>
 679       Classic Explain only defines retrieval of Explain information
 680       via ASN.1. Practically no Z39.50 clients supports this. Fortunately
 681       they don't have to - Zebra allows retrieval of this information
 682       in other formats:
 683       <literal>SUTRS</literal>, <literal>XML</literal>,
 684       <literal>GRS-1</literal> and  <literal>ASN.1</literal> Explain.
 685      </para>
 686
 687      <para>
 688       List supported categories to find out which explain commands are
 689       supported:
 690       <screen>
 691        Z> base IR-Explain-1
 692        Z> find @attr exp1 1=1 categorylist
 693        Z> form sutrs
 694        Z> show 1+2
 695       </screen>
 696      </para>
 697
 698      <para>
 699       Get target info, that is, investigate which databases exist at
 700       this server endpoint:
 701       <screen>
 702        Z> base IR-Explain-1
 703        Z> find @attr exp1 1=1 targetinfo
 704        Z> form xml
 705        Z> show 1+1
 706        Z> form grs-1
 707        Z> show 1+1
 708        Z> form sutrs
 709        Z> show 1+1
 710       </screen>
 711      </para>
 712
 713      <para>
 714       List all supported databases, the number of hits
 715       is the number of databases found, which most commonly are the
 716       following two:
 717       the <literal>Default</literal> and the
 718       <literal>IR-Explain-1</literal> databases.
 719       <screen>
 720        Z> base IR-Explain-1
 721        Z> find @attr exp1 1=1 databaseinfo
 722        Z> form sutrs
 723        Z> show 1+2
 724       </screen>
 725      </para>
 726
 727      <para>
 728       Get database info record for database <literal>Default</literal>.
 729       <screen>
 730        Z> base IR-Explain-1
 731        Z> find @and @attr exp1 1=1 databaseinfo @attr exp1 1=3 Default
 732       </screen>
 733       Identical query with explicitly specified attribute set:
 734       <screen>
 735        Z> base IR-Explain-1
 736        Z> find @attrset exp1 @and @attr 1=1 databaseinfo @attr 1=3 Default
 737       </screen>
 738      </para>
 739
 740      <para>
 741       Get attribute details record for database
 742       <literal>Default</literal>.
 743       This query is very useful to study the internal Zebra indexes.
 744       If records have been indexed using the <literal>alvis</literal>
 745       XSLT filter, the string representation names of the known indexes can be
 746       found.
 747       <screen>
 748        Z> base IR-Explain-1
 749        Z> find @and @attr exp1 1=1 attributedetails @attr exp1 1=3 Default
 750       </screen>
 751       Identical query with explicitly specified attribute set:
 752       <screen>
 753        Z> base IR-Explain-1
 754        Z> find @attrset exp1 @and @attr 1=1 attributedetails @attr 1=3 Default
 755       </screen>
 756      </para>
 757     </sect3>
 758
 759    </sect2>
 760
 761    <sect2 id="querymodel-bib1">
 762     <title>Bib1 Attribute Set</title>
 763     <para>
 764      Most of the information contained in this section is an excerpt of
 765      the <literal>ATTRIBUTE SET BIB-1 (Z39.50-1995)
 766       SEMANTICS</literal>,
 767      found at <ulink url="&url.z39.50.attset.bib1.1995;">. The BIB-1
 768       Attribute Set Semantics</ulink> from 1995, also in an updated
 769      <ulink url="&url.z39.50.attset.bib1;">Bib-1
 770       Attribute Set</ulink>
 771      version from 2003. Index Data is not the copyright holder of this
 772      information, except for the configuration details, the listing of
 773      Zebra's capabilities, and the example queries.
 774     </para>
 775
 776
 777    <sect3 id="querymodel-bib1-use">
 778      <title>Use Attributes (type 1)</title>
 779
 780     <para>
 781      A use attribute specifies an access point for any atomic query.
 782      These access points are highly dependent on the attribute set used
 783      in the query, and are user configurable using the following
 784      default configuration files:
 785      <filename>tab/bib1.att</filename>,
 786      <filename>tab/dan1.att</filename>,
 787      <filename>tab/explain.att</filename>, and
 788      <filename>tab/gils.att</filename>.
 789      New attribute sets can be added by adding new
 790      <filename>tab/*.att</filename> configuration files, which need to
 791      be sourced in the main configuration <filename>zebra.cfg</filename>.
 792      </para>
 793
 794     <para>
 795      In addition, Zebra allows the access of
 796      <emphasis>internal index names</emphasis> and <emphasis>dynamic
 797      XPath</emphasis> as use attributes; see
 798       <xref linkend="querymodel-use-string"/> and
 799      <xref linkend="querymodel-use-xpath"/>.
 800     </para>
 801
 802     <para>
 803      Phrase search for <emphasis>information retrieval</emphasis> in
 804      the title-register, scanning the same register afterwards:
 805      <screen>
 806       Z> find @attr 1=4 "information retrieval"
 807       Z> scan @attr 1=4 information
 808      </screen>
 809     </para>
 810     </sect3>
 811
 812    </sect2>
 813
 814
 815    <sect2 id="querymodel-bib1-nonuse">
 816      <title>Zebra general Bib1 Non-Use Attributes (type 2-6)</title>
 817
 818     <sect3 id="querymodel-bib1-relation">
 819      <title>Relation Attributes (type 2)</title>
 820
 821      <para>
 822       Relation attributes describe the relationship of the access
 823       point (left side
 824       of the relation) to the search term as qualified by the attributes (right
 825       side of the relation), e.g., Date-publication &lt;= 1975.
 826       </para>
 827
 828      <table id="querymodel-bib1-relation-table"
 829       frame="all" rowsep="1" colsep="1" align="center">
 830
 831       <caption>Relation Attributes (type 2)</caption>
 832       <thead>
 833         <tr>
 834          <td>Relation</td>
 835          <td>Value</td>
 836          <td>Notes</td>
 837         </tr>
 838        </thead>
 839        <tbody>
 840         <tr>
 841          <td> Less than</td>
 842          <td>1</td>
 843          <td>supported</td>
 844         </tr>
 845         <tr>
 846          <td>Less than or equal</td>
 847          <td>2</td>
 848          <td>supported</td>
 849         </tr>
 850         <tr>
 851          <td>Equal</td>
 852          <td>3</td>
 853          <td>default</td>
 854         </tr>
 855         <tr>
 856          <td>Greater or equal</td>
 857          <td>4</td>
 858          <td>supported</td>
 859         </tr>
 860         <tr>
 861          <td>Greater than</td>
 862          <td>5</td>
 863          <td>supported</td>
 864         </tr>
 865         <tr>
 866          <td>Not equal</td>
 867          <td>6</td>
 868          <td>unsupported</td>
 869         </tr>
 870         <tr>
 871          <td>Phonetic</td>
 872          <td>100</td>
 873          <td>unsupported</td>
 874         </tr>
 875         <tr>
 876          <td>Stem</td>
 877          <td>101</td>
 878          <td>unsupported</td>
 879         </tr>
 880         <tr>
 881          <td>Relevance</td>
 882          <td>102</td>
 883          <td>supported</td>
 884         </tr>
 885         <tr>
 886          <td>AlwaysMatches</td>
 887          <td>103</td>
 888          <td>supported</td>
 889         </tr>
 890        </tbody>
 891      </table>
 892
 893      <para>
 894       The relation attributes
 895       <literal>1-5</literal> are supported and work exactly as
 896       expected.
 897       All ordering operations are based on a lexicographical ordering,
 898       <emphasis>expect</emphasis> when the
 899       <literal>structure attribute numeric (109)</literal> is used. In
 900       this case, ordering is numerical. See
 901       <xref linkend="querymodel-bib1-structure"/>.
 902       <screen>
 903        Z>  find @attr 1=Title @attr 2=1 music
 904        ...
 905        Number of hits: 11745, setno 1
 906        ...
 907        Z>  find @attr 1=Title @attr 2=2 music
 908        ...
 909        Number of hits: 11771, setno 2
 910        ...
 911        Z>  find @attr 1=Title @attr 2=3 music
 912        ...
 913        Number of hits: 532, setno 3
 914        ...
 915        Z>  find @attr 1=Title @attr 2=4 music
 916        ...
 917        Number of hits: 11463, setno 4
 918        ...
 919        Z>  find @attr 1=Title @attr 2=5 music
 920        ...
 921        Number of hits: 11419, setno 5
 922       </screen>
 923      </para>
 924
 925      <para>
 926       The relation attribute
 927       <literal>Relevance (102)</literal> is supported, see
 928       <xref linkend="administration-ranking"/> for full information.
 929      </para>
 930
 931      <para>
 932       Ranked search for <emphasis>information retrieval</emphasis> in
 933       the title-register:
 934       <screen>
 935        Z> find @attr 1=4 @attr 2=102 "information retrieval"
 936       </screen>
 937      </para>
 938
 939      <para>
 940       The relation attribute
 941       <literal>AlwaysMatches (103)</literal> is in the default
 942       configuration
 943       supported in conjecture with structure attribute
 944       <literal>Phrase (1)</literal> (which may be omitted by
 945       default).
 946       It can be configured to work with other structure attributes,
 947       see the configuration file
 948       <filename>tab/default.idx</filename> and
 949        <xref linkend="querymodel-pqf-apt-mapping"/>.
 950      </para>
 951      <para>
 952       <literal>AlwaysMatches (103)</literal> is a
 953       great way to discover how many documents have been indexed in a
 954       given field. The search term is ignored, but needed for correct
 955       PQF syntax. An empty search term may be supplied.
 956       <screen>
 957        Z> find @attr 1=Title  @attr 2=103  ""
 958        Z> find @attr 1=Title  @attr 2=103  @attr 4=1 ""
 959       </screen>
 960      </para>
 961
 962
 963     </sect3>
 964
 965     <sect3 id="querymodel-bib1-position">
 966      <title>Position Attributes (type 3)</title>
 967
 968      <para>
 969       The position attribute specifies the location of the search term
 970       within the field or subfield in which it appears.
 971      </para>
 972
 973      <table id="querymodel-bib1-position-table"
 974       frame="all" rowsep="1" colsep="1" align="center">
 975
 976       <caption>Position Attributes (type 3)</caption>
 977       <thead>
 978         <tr>
 979          <td>Position</td>
 980          <td>Value</td>
 981          <td>Notes</td>
 982         </tr>
 983        </thead>
 984        <tbody>
 985         <tr>
 986          <td>First in field </td>
 987          <td>1</td>
 988          <td>unsupported</td>
 989         </tr>
 990         <tr>
 991          <td>First in subfield</td>
 992          <td>2</td>
 993          <td>unsupported</td>
 994         </tr>
 995         <tr>
 996          <td>Any position in field</td>
 997          <td>3</td>
 998          <td>supported</td>
 999         </tr>
1000        </tbody>
1001      </table>
1002
1003     <para>
1004       The position attribute values <literal>first in field (1)</literal>,
1005       and <literal>first in subfield(2)</literal> are unsupported.
1006       Using them silently maps to
1007       <literal>any position in field (3)</literal>. A proper diagnostic
1008       should have been issued.
1009       </para>
1010     </sect3>
1011
1012     <sect3 id="querymodel-bib1-structure">
1013      <title>Structure Attributes (type 4)</title>
1014
1015      <para>
1016       The structure attribute specifies the type of search
1017       term. This causes the search to be mapped on
1018       different Zebra internal indexes, which must have been defined
1019       at index time.
1020      </para>
1021
1022      <para>
1023       The possible values of the
1024       <literal>structure attribute (type 4)</literal> can be defined
1025       using the configuration file <filename>
1026       tab/default.idx</filename>.
1027       The default configuration is summarized in this table.
1028      </para>
1029
1030      <table id="querymodel-bib1-structure-table"
1031       frame="all" rowsep="1" colsep="1" align="center">
1032
1033       <caption>Structure Attributes (type 4)</caption>
1034       <thead>
1035         <tr>
1036          <td>Structure</td>
1037          <td>Value</td>
1038          <td>Notes</td>
1039         </tr>
1040        </thead>
1041        <tbody>
1042         <tr>
1043          <td>Phrase </td>
1044          <td>1</td>
1045          <td>default</td>
1046         </tr>
1047         <tr>
1048          <td>Word</td>
1049          <td>2</td>
1050          <td>supported</td>
1051         </tr>
1052         <tr>
1053          <td>Key</td>
1054          <td>3</td>
1055          <td>supported</td>
1056         </tr>
1057         <tr>
1058          <td>Year</td>
1059          <td>4</td>
1060          <td>supported</td>
1061         </tr>
1062         <tr>
1063          <td>Date (normalized)</td>
1064          <td>5</td>
1065          <td>supported</td>
1066         </tr>
1067         <tr>
1068          <td>Word list</td>
1069          <td>6</td>
1070          <td>supported</td>
1071         </tr>
1072         <tr>
1073          <td>Date (un-normalized)</td>
1074          <td>100</td>
1075          <td>unsupported</td>
1076         </tr>
1077         <tr>
1078          <td>Name (normalized) </td>
1079          <td>101</td>
1080          <td>unsupported</td>
1081         </tr>
1082         <tr>
1083          <td>Name (un-normalized) </td>
1084          <td>102</td>
1085          <td>unsupported</td>
1086         </tr>
1087         <tr>
1088          <td>Structure</td>
1089          <td>103</td>
1090          <td>unsupported</td>
1091         </tr>
1092         <tr>
1093          <td>Urx</td>
1094          <td>104</td>
1095          <td>supported</td>
1096         </tr>
1097         <tr>
1098          <td>Free-form-text</td>
1099          <td>105</td>
1100          <td>supported</td>
1101         </tr>
1102         <tr>
1103          <td>Document-text</td>
1104          <td>106</td>
1105          <td>supported</td>
1106         </tr>
1107         <tr>
1108          <td>Local-number</td>
1109          <td>107</td>
1110          <td>supported</td>
1111         </tr>
1112         <tr>
1113          <td>String</td>
1114          <td>108</td>
1115          <td>unsupported</td>
1116         </tr>
1117         <tr>
1118          <td>Numeric string</td>
1119          <td>109</td>
1120          <td>supported</td>
1121         </tr>
1122        </tbody>
1123      </table>
1124
1125
1126     <para>
1127      The structure attribute values
1128      <literal>Word list (6)</literal>
1129      is supported, and maps to the boolean <literal>AND</literal>
1130      combination of words supplied. The word list is useful when
1131      google-like bag-of-word queries need to be translated from a GUI
1132      query language to PQF.  For example, the following queries
1133      are equivalent:
1134      <screen>
1135       Z> find @attr 1=Title @attr 4=6 "mozart amadeus"
1136       Z> find @attr 1=Title  @and mozart amadeus
1137      </screen>
1138     </para>
1139
1140     <para>
1141      The structure attribute value
1142      <literal>Free-form-text (105)</literal> and
1143      <literal>Document-text (106)</literal>
1144      are supported, and map both to the boolean <literal>OR</literal>
1145      combination of words supplied. The following queries
1146      are equivalent:
1147      <screen>
1148       Z> find @attr 1=Body-of-text @attr 4=105 "bach salieri teleman"
1149       Z> find @attr 1=Body-of-text @attr 4=106 "bach salieri teleman"
1150       Z> find @attr 1=Body-of-text @or bach @or salieri teleman
1151      </screen>
1152      This <literal>OR</literal> list of terms is very useful in
1153      combination with relevance ranking:
1154      <screen>
1155       Z> find @attr 1=Body-of-text @attr 2=102 @attr 4=105 "bach salieri teleman"
1156      </screen>
1157     </para>
1158
1159     <para>
1160      The structure attribute value
1161      <literal>Local number (107)</literal>
1162      is supported, and maps always to the Zebra internal document ID,
1163      irrespectively which use attribute is specified. The following queries
1164      have exactly the same unique record in the hit set:
1165      <screen>
1166       Z> find @attr 4=107 10
1167       Z> find @attr 1=4 @attr 4=107 10
1168       Z> find @attr 1=1010 @attr 4=107 10
1169      </screen>
1170     </para>
1171
1172     <para>
1173      In
1174      the GILS schema (<literal>gils.abs</literal>), the
1175      west-bounding-coordinate is indexed as type <literal>n</literal>,
1176      and is therefore searched by specifying
1177      <emphasis>structure</emphasis>=<emphasis>Numeric String</emphasis>.
1178      To match all those records with west-bounding-coordinate greater
1179      than -114 we use the following query:
1180      <screen>
1181       Z> find @attr 4=109 @attr 2=5 @attr gils 1=2038 -114
1182      </screen>
1183     </para>
1184      <note>
1185       The exact mapping between PQF queries and Zebra internal indexes
1186       and index types is explained in
1187        <xref linkend="querymodel-pqf-apt-mapping"/>.
1188       </note>
1189
1190    </sect3>
1191
1192     <sect3 id="querymodel-bib1-truncation">
1193      <title>Truncation Attributes (type = 5)</title>
1194
1195      <para>
1196       The truncation attribute specifies whether variations of one or
1197       more characters are allowed between search term and hit terms, or
1198       not. Using non-default truncation attributes will broaden the
1199       document hit set of a search query.
1200      </para>
1201
1202      <table id="querymodel-bib1-truncation-table"
1203       frame="all" rowsep="1" colsep="1" align="center">
1204
1205       <caption>Truncation Attributes (type 5)</caption>
1206       <thead>
1207         <tr>
1208          <td>Truncation</td>
1209          <td>Value</td>
1210          <td>Notes</td>
1211         </tr>
1212        </thead>
1213        <tbody>
1214         <tr>
1215          <td>Right truncation </td>
1216          <td>1</td>
1217          <td>supported</td>
1218         </tr>
1219         <tr>
1220          <td>Left truncation</td>
1221          <td>2</td>
1222          <td>supported</td>
1223         </tr>
1224         <tr>
1225          <td>Left and right truncation</td>
1226          <td>3</td>
1227          <td>supported</td>
1228         </tr>
1229         <tr>
1230          <td>Do not truncate</td>
1231          <td>100</td>
1232          <td>default</td>
1233         </tr>
1234         <tr>
1235          <td>Process # in search term</td>
1236          <td>101</td>
1237          <td>supported</td>
1238         </tr>
1239         <tr>
1240          <td>RegExpr-1 </td>
1241          <td>102</td>
1242          <td>supported</td>
1243         </tr>
1244         <tr>
1245          <td>RegExpr-2</td>
1246          <td>103</td>
1247          <td>supported</td>
1248         </tr>
1249        </tbody>
1250      </table>
1251
1252      <para>
1253       The truncation attribute values 1-3 perform the obvious way:
1254       <screen>
1255        Z> scan @attr 1=Body-of-text  schnittke
1256        ...
1257        * schnittke (81)
1258        schnittkes (31)
1259        schnittstelle (1)
1260        ...
1261        Z> find @attr 1=Body-of-text  @attr 5=1 schnittke
1262        ...
1263        Number of hits: 95, setno 7
1264        ...
1265        Z> find @attr 1=Body-of-text  @attr 5=2 schnittke
1266        ...
1267        Number of hits: 81, setno 6
1268        ...
1269        Z> find @attr 1=Body-of-text  @attr 5=3 schnittke
1270        ...
1271        Number of hits: 95, setno 8
1272       </screen>
1273       </para>
1274
1275      <para>
1276       The truncation attribute value
1277       <literal>Process # in search term (101)</literal> is a
1278       poor-man's regular expression search. It maps
1279       each <literal>#</literal> to <literal>.*</literal>, and
1280       performs then a <literal>Regexp-1 (102)</literal> regular
1281       expression search. The following two queries are equivalent:
1282       <screen>
1283        Z> find @attr 1=Body-of-text  @attr 5=101 schnit#ke
1284        Z> find @attr 1=Body-of-text  @attr 5=102 schnit.*ke
1285        ...
1286        Number of hits: 89, setno 10
1287       </screen>
1288      </para>
1289
1290      <para>
1291       The truncation attribute value
1292        <literal>Regexp-1 (102)</literal> is a normal regular search,
1293       see <xref linkend="querymodel-regular"/> for details.
1294       <screen>
1295        Z> find @attr 1=Body-of-text  @attr 5=102 schnit+ke
1296        Z> find @attr 1=Body-of-text  @attr 5=102 schni[a-t]+ke
1297       </screen>
1298      </para>
1299
1300      <para>
1301        The truncation attribute value
1302       <literal>Regexp-2 (103) </literal> is a Zebra specific extension
1303       which allows <emphasis>fuzzy</emphasis> matches. One single
1304       error in spelling of search terms is allowed, i.e., a document
1305       is hit if it includes a term which can be mapped to the used
1306       search term by one character substitution, addition, deletion or
1307       change of position.
1308       <screen>
1309        Z> find @attr 1=Body-of-text  @attr 5=100 schnittke
1310        ...
1311        Number of hits: 81, setno 14
1312        ...
1313        Z> find @attr 1=Body-of-text  @attr 5=103 schnittke
1314        ...
1315        Number of hits: 103, setno 15
1316        ...
1317       </screen>
1318       </para>
1319     </sect3>
1320
1321     <sect3 id="querymodel-bib1-completeness">
1322     <title>Completeness Attributes (type = 6)</title>
1323
1324
1325      <para>
1326       The <literal>Completeness Attributes (type = 6)</literal>
1327       is used to specify that a given search term or term list is  either
1328       part of the terms of a given index/field
1329       (<literal>Incomplete subfield (1)</literal>), or is
1330       what literally is found in the entire field's index
1331       (<literal>Complete field (3)</literal>).
1332       </para>
1333
1334      <table id="querymodel-bib1-completeness-table"
1335       frame="all" rowsep="1" colsep="1" align="center">
1336       <caption>Completeness Attributes (type = 6)</caption>
1337       <thead>
1338         <tr>
1339          <td>Completeness</td>
1340          <td>Value</td>
1341          <td>Notes</td>
1342         </tr>
1343        </thead>
1344        <tbody>
1345         <tr>
1346          <td>Incomplete subfield</td>
1347          <td>1</td>
1348          <td>default</td>
1349         </tr>
1350         <tr>
1351          <td>Complete subfield</td>
1352          <td>2</td>
1353          <td>deprecated</td>
1354         </tr>
1355         <tr>
1356          <td>Complete field</td>
1357          <td>3</td>
1358          <td>supported</td>
1359         </tr>
1360        </tbody>
1361      </table>
1362
1363      <para>
1364       The <literal>Completeness Attributes (type = 6)</literal>
1365       is only partially and conditionally
1366       supported in the sense that it is ignored if the hit index is
1367       not of structure <literal>type="w"</literal> or
1368       <literal>type="p"</literal>.
1369       </para>
1370      <para>
1371       <literal>Incomplete subfield (1)</literal> is the default, and
1372       makes Zebra use
1373       register <literal>type="w"</literal>, whereas
1374       <literal>Complete field (3)</literal> triggers
1375       search and scan in index <literal>type="p"</literal>.
1376      </para>
1377      <para>
1378       The <literal>Complete subfield (2)</literal> is a reminiscens
1379       from the  happy <literal>MARC</literal>
1380       binary format days. Zebra does not support it, but maps silently
1381       to <literal>Complete field (3)</literal>.
1382      </para>
1383
1384      <note>
1385       The exact mapping between PQF queries and Zebra internal indexes
1386       and index types is explained in
1387        <xref linkend="querymodel-pqf-apt-mapping"/>.
1388       </note>
1389     </sect3>
1390    </sect2>
1391
1392    </sect1>
1393
1394
1395   <sect1 id="querymodel-zebra">
1396    <title>Advanced Zebra PQF Features</title>
1397    <para>
1398     The Zebra internal query engine has been extended to specific needs
1399     not covered by the <literal>bib-1</literal> attribute set query
1400     model. These extensions are <emphasis>non-standard</emphasis>
1401     and <emphasis>non-portable</emphasis>: most functional extensions
1402     are modeled over the <literal>bib-1</literal> attribute set,
1403     defining type 7-9 attributes.
1404     There are also the special
1405     <literal>string</literal> type index names for the
1406     <literal>idxpath</literal> attribute set.
1407    </para>
1408
1409    <sect2 id="querymodel-zebra-attr-allrecords">
1410     <title>Zebra specific retrieval of all records</title>
1411     <para>
1412      Zebra defines a hardwired <literal>string</literal> index name
1413      called <literal>_ALLRECORDS</literal>. It matches any record
1414      contained in the database, if used in conjunction with
1415      the relation attribute
1416      <literal>AlwaysMatches (103)</literal>.
1417      </para>
1418     <para>
1419      The <literal>_ALLRECORDS</literal> index name is used for total database
1420      export. The search term is ignored, it may be empty.
1421      <screen>
1422       Z> find @attr 1=_ALLRECORDS @attr 2=103 ""
1423      </screen>
1424     </para>
1425     <para>
1426      Combination with other index types can be made. For example, to
1427      find all records which are <emphasis>not</emphasis> indexed in
1428      the <literal>Title</literal> register, issue one of the two
1429      equivalent queries:
1430      <screen>
1431       Z> find @not @attr 1=_ALLRECORDS @attr 2=103 "" @attr 1=Title @attr 2=103 ""
1432       Z> find @not @attr 1=_ALLRECORDS @attr 2=103 "" @attr 1=4 @attr 2=103 ""
1433      </screen>
1434     </para>
1435     <warning>
1436      The special string index <literal>_ALLRECORDS</literal> is
1437      experimental, and the provided functionality and syntax may very
1438      well change in future releases of Zebra.
1439     </warning>
1440
1441    </sect2>
1442
1443    <sect2 id="querymodel-zebra-attr-search">
1444     <title>Zebra specific Search Extensions to all Attribute Sets</title>
1445     <para>
1446      Zebra extends the Bib1 attribute types, and these extensions are
1447      recognized regardless of attribute
1448      set used in a <literal>search</literal> operation query.
1449     </para>
1450
1451      <table id="querymodel-zebra-attr-search-table"
1452       frame="all" rowsep="1" colsep="1" align="center">
1453
1454       <caption>Zebra Search Attribute Extensions</caption>
1455        <thead>
1456         <tr>
1457          <td>Name</td>
1458          <td>Value</td>
1459          <td>Operation</td>
1460          <td>Zebra version</td>
1461         </tr>
1462       </thead>
1463        <tbody>
1464         <tr>
1465          <td>Embedded Sort</td>
1466          <td>7</td>
1467          <td>search</td>
1468          <td>1.1</td>
1469         </tr>
1470         <tr>
1471          <td>Term Set</td>
1472          <td>8</td>
1473          <td>search</td>
1474          <td>1.1</td>
1475         </tr>
1476         <tr>
1477          <td>Rank Weight</td>
1478          <td>9</td>
1479          <td>search</td>
1480          <td>1.1</td>
1481         </tr>
1482         <tr>
1483          <td>Approx Limit</td>
1484          <td>9</td>
1485          <td>search</td>
1486          <td>1.4</td>
1487         </tr>
1488         <tr>
1489          <td>Term Reference</td>
1490          <td>10</td>
1491          <td>search</td>
1492          <td>1.4</td>
1493         </tr>
1494        </tbody>
1495       </table>
1496
1497     <sect3 id="querymodel-zebra-attr-sorting">
1498      <title>Zebra Extension Embedded Sort Attribute (type 7)</title>
1499     </sect3>
1500     <para>
1501      The embedded sort is a way to specify sort within a query - thus
1502      removing the need to send a Sort Request separately. It is both
1503      faster and does not require clients to deal with the Sort
1504      Facility.
1505     </para>
1506
1507     <para>
1508      All ordering operations are based on a lexicographical ordering,
1509      <emphasis>expect</emphasis> when the
1510      <literal>structure attribute numeric (109)</literal> is used. In
1511      this case, ordering is numerical. See
1512       <xref linkend="querymodel-bib1-structure"/>.
1513     </para>
1514
1515     <para>
1516      The possible values after attribute <literal>type 7</literal> are
1517      <literal>1</literal> ascending and
1518      <literal>2</literal> descending.
1519      The attributes+term (APT) node is separate from the
1520      rest and must be <literal>@or</literal>'ed.
1521      The term associated with APT is the sorting level in integers,
1522      where <literal>0</literal> means primary sort,
1523      <literal>1</literal> means secondary sort, and so forth.
1524      See also <xref linkend="administration-ranking"/>.
1525     </para>
1526     <para>
1527      For example, searching for water, sort by title (ascending)
1528      <screen>
1529       Z> find @or @attr 1=1016 water @attr 7=1 @attr 1=4 0
1530      </screen>
1531     </para>
1532     <para>
1533      Or, searching for water, sort by title ascending, then date descending
1534      <screen>
1535       Z> find @or @or @attr 1=1016 water @attr 7=1 @attr 1=4 0 @attr 7=2 @attr 1=30 1
1536      </screen>
1537     </para>
1538
1539
1540     <!--
1541     Zebra Extension Term Set Attribute
1542     From the manual text, I can not see what is the point with this feature.
1543     I think it makes more sense when there are multiple terms in a query, or
1544     something...
1545
1546     We decided 2006-06-03 to disable this feature, as it is covered by
1547     scan within a resultset. Better use ressources to upgrade this
1548     feature for good performance.
1549     -->
1550
1551     <!--
1552     <sect3 id="querymodel-zebra-attr-estimation">
1553      <title>Zebra Extension Term Set Attribute (type 8)</title>
1554     </sect3>
1555     <para>
1556      The Term Set feature is a facility that allows a search to store
1557      hitting terms in a "pseudo" resultset; thus a search (as usual) +
1558      a scan-like facility. Requires a client that can do named result
1559      sets since the search generates two result sets. The value for
1560      attribute 8 is the name of a result set (string). The terms in
1561      the named term set are returned as SUTRS records.
1562     </para>
1563     <para>
1564      For example, searching  for u in title, right truncated, and
1565      storing the result in term set named 'aset'
1566      <screen>
1567       Z> find @attr 5=1 @attr 1=4 @attr 8=aset u
1568      </screen>
1569     </para>
1570     <warning>
1571      The model has one serious flaw: we don't know the size of term
1572      set. Experimental. Do not use in production code.
1573     </warning>
1574     -->
1575
1576
1577     <sect3 id="querymodel-zebra-attr-weight">
1578      <title>Zebra Extension Rank Weight Attribute (type 9)</title>
1579     </sect3>
1580     <para>
1581      Rank weight is a way to pass a value to a ranking algorithm - so
1582      that one APT has one value - while another as a different one.
1583      See also <xref linkend="administration-ranking"/>.
1584     </para>
1585     <para>
1586      For example, searching  for utah in title with weight 30 as well
1587      as any with weight 20:
1588      <screen>
1589       Z> find @attr 2=102 @or @attr 9=30 @attr 1=4 utah @attr 9=20 utah
1590      </screen>
1591     </para>
1592
1593     <sect3 id="querymodel-zebra-attr-limit">
1594      <title>Zebra Extension Approximative Limit Attribute (type 9)</title>
1595     </sect3>
1596     <para>
1597      Zebra  computes - unless otherwise configured -
1598      the exact hit count for every APT
1599      (leaf) in the query tree. These hit counts are returned as part of
1600      the searchResult-1 facility in the binary encoded Z39.50 search
1601      response packages.
1602     </para>
1603     <para>
1604      By setting an estimation limit size of the resultset of the APT
1605      leaves, Zebra stoppes processing the result set when the limit
1606      length is reached.
1607      Hit counts under this limit are still precise, but hit counts over it
1608      are estimated using the statistics gathered from the chopped
1609      result set.
1610     </para>
1611     <para>
1612      Specifying a limit of <literal>0</literal> resuts in exact hit counts.
1613     </para>
1614      For example, we might be interested in exact hit count for a, but
1615      for b we allow hit count estimates for 1000 and higher.
1616      <screen>
1617       Z> find @and a @attr 9=1000 b
1618      </screen>
1619     </para>
1620     <note>
1621      The estimated hit count facility makes searches faster, as one
1622      only needs to process large hit lists partially.
1623      It is mostly used in huge databases, where you you want trade
1624      exactness of hit counts against speed of execution.
1625     </note>
1626     <warning>
1627      Do not use approximative hit count limits
1628      in conjunction with relevance ranking, as re-sorting of the
1629      result set obviosly only works when the entire result set has
1630      been processed.
1631     </warning>
1632     <warning>
1633      This facility clashes with rank weight, because there all
1634      documents in the hit lists need to be examined for scoring and
1635      re-sorting.
1636      It is an experimental
1637      extension. Do not use in production code.
1638     </warning>
1639
1640     <sect3 id="querymodel-zebra-attr-termref">
1641      <title>Zebra Extension Term Reference Attribute (type 10)</title>
1642     </sect3>
1643     <para>
1644      Zebra supports the <literal>searchResult-1</literal> facility.
1645      If the <literal>Term Reference Attribute (type 10)</literal> is
1646      given, that specifies a subqueryId value returned as part of the
1647      search result. It is a way for a client to name an APT part of a
1648      query.
1649     </para>
1650     <!--
1651     <para>
1652      <screen>
1653      </screen>
1654     </para>
1655     -->
1656     <warning>
1657      Experimental. Do not use in production code.
1658     </warning>
1659
1660
1661    </sect2>
1662
1663
1664    <sect2 id="querymodel-zebra-attr-scan">
1665     <title>Zebra specific Scan Extensions to all Attribute Sets</title>
1666     <para>
1667      Zebra extends the Bib1 attribute types, and these extensions are
1668      recognized regardless of attribute
1669      set used in a <literal>scan</literal> operation query.
1670     </para>
1671      <table id="querymodel-zebra-attr-scan-table"
1672       frame="all" rowsep="1" colsep="1" align="center">
1673
1674       <caption>Zebra Scan Attribute Extensions</caption>
1675        <thead>
1676         <tr>
1677          <td>Name</td>
1678          <td>Type</td>
1679          <td>Operation</td>
1680          <td>Zebra version</td>
1681         </tr>
1682       </thead>
1683        <tbody>
1684         <tr>
1685          <td>Result Set Narrow</td>
1686          <td>8</td>
1687          <td>scan</td>
1688          <td>1.3</td>
1689         </tr>
1690         <tr>
1691          <td>Approximative Limit</td>
1692          <td>9</td>
1693          <td>scan</td>
1694          <td>1.4</td>
1695         </tr>
1696        </tbody>
1697       </table>
1698
1699     <sect3 id="querymodel-zebra-attr-narrow">
1700      <title>Zebra Extension Result Set Narrow (type 8)</title>
1701     </sect3>
1702     <para>
1703      If attribute <literal>Result Set Narrow (type 8)</literal>
1704      is given for <literal>scan</literal>, the value is the name of a
1705      result set. Each hit count in <literal>scan</literal> is
1706      <literal>@and</literal>'ed with the result set given.
1707     </para>
1708     <para>
1709      Consider for example
1710      the case of scanning all title fields around the
1711      scanterm <emphasis>mozart</emphasis>, then refining the scan by
1712      issuing a filtering query for <emphasis>amadeus</emphasis> to
1713      restrict the scan to the result set of the query:
1714      <screen>
1715       Z> scan @attr 1=4 mozart
1716       ...
1717       * mozart (43)
1718         mozartforskningen (1)
1719         mozartiana (1)
1720         mozarts (16)
1721       ...
1722       Z> f @attr 1=4 amadeus
1723       ...
1724       Number of hits: 15, setno 2
1725       ...
1726       Z> scan @attr 1=4 @attr 8=2 mozart
1727       ...
1728       * mozart (14)
1729         mozartforskningen (0)
1730         mozartiana (0)
1731         mozarts (1)
1732       ...
1733      </screen>
1734     </para>
1735
1736     <warning>
1737      Experimental. Do not use in production code.
1738     </warning>
1739
1740     <sect3 id="querymodel-zebra-attr-approx">
1741      <title>Zebra Extension Approximative Limit (type 9)</title>
1742     </sect3>
1743     <para>
1744      The <literal>Zebra Extension Approximative Limit (type
1745       9)</literal> is a way to enable approximate
1746      hit counts for <literal>scan</literal> hit counts, in the same
1747      way as for <literal>search</literal> hit counts.
1748     </para>
1749     <!--
1750     <para>
1751      <screen>
1752      </screen>
1753     </para>
1754     -->
1755     <warning>
1756      Experimental and buggy. Definitely not to be used in production code.
1757     </warning>
1758
1759
1760    </sect2>
1761
1762
1763    <sect2 id="querymodel-idxpath">
1764     <title>Zebra special IDXPATH Attribute Set for GRS indexing</title>
1765     <para>
1766      The attribute-set <literal>idxpath</literal> consists of a single
1767      <literal>Use (type 1)</literal> attribute. All non-use attributes
1768      behave as normal.
1769     </para>
1770     <para>
1771      This feature is enabled when defining the
1772      <literal>xpath enable</literal> option in the GRS filter
1773      <filename>*.abs</filename> configuration files. If one wants to use
1774      the special <literal>idxpath</literal> numeric attribute set, the
1775      main Zebra configuration file <filename>zebra.cfg</filename>
1776      directive <literal>attset: idxpath.att</literal> must be enabled.
1777     </para>
1778     <warning>The <literal>idxpath</literal> is deprecated, may not be
1779      supported in future Zebra versions, and should definitely
1780      not be used in production code.
1781     </warning>
1782
1783     <sect3 id="querymodel-idxpath-use">
1784     <title>IDXPATH Use Attributes (type = 1)</title>
1785      <para>
1786       This attribute set allows one to search GRS filter indexed
1787       records by XPATH like structured index names.
1788      </para>
1789
1790      <warning>The <literal>idxpath</literal> option defines hard-coded
1791       index names, which might clash with your own index names.
1792      </warning>
1793
1794      <table id="querymodel-idxpath-use-table"
1795       frame="all" rowsep="1" colsep="1" align="center">
1796
1797       <caption>Zebra specific IDXPATH Use Attributes (type 1)</caption>
1798       <thead>
1799         <tr>
1800          <td>IDXPATH</td>
1801          <td>Value</td>
1802          <td>String Index</td>
1803          <td>Notes</td>
1804         </tr>
1805        </thead>
1806        <tbody>
1807         <tr>
1808          <td>XPATH Begin</td>
1809          <td>1</td>
1810          <td>_XPATH_BEGIN</td>
1811          <td>deprecated</td>
1812         </tr>
1813         <tr>
1814          <td>XPATH End</td>
1815          <td>2</td>
1816          <td>_XPATH_END</td>
1817          <td>deprecated</td>
1818         </tr>
1819         <tr>
1820          <td>XPATH CData</td>
1821          <td>1016</td>
1822          <td>_XPATH_CDATA</td>
1823          <td>deprecated</td>
1824         </tr>
1825         <tr>
1826          <td>XPATH Attribute Name</td>
1827          <td>3</td>
1828          <td>_XPATH_ATTR_NAME</td>
1829          <td>deprecated</td>
1830         </tr>
1831         <tr>
1832          <td>XPATH Attribute CData</td>
1833          <td>1015</td>
1834          <td>_XPATH_ATTR_CDATA</td>
1835          <td>deprecated</td>
1836         </tr>
1837        </tbody>
1838      </table>
1839
1840
1841      <para>
1842       See <filename>tab/idxpath.att</filename> for more information.
1843      </para>
1844      <para>
1845       Search for all documents starting with root element
1846       <literal>/root</literal> (either using the numeric or the string
1847       use attributes):
1848       <screen>
1849        Z> find @attrset idxpath @attr 1=1 @attr 4=3 root/
1850        Z> find @attr idxpath 1=1 @attr 4=3 root/
1851        Z> find @attr 1=_XPATH_BEGIN @attr 4=3 root/
1852       </screen>
1853      </para>
1854      <para>
1855       Search for all documents where specific nested XPATH
1856       <literal>/c1/c2/../cn</literal> exists. Notice the very
1857       counter-intuitive <emphasis>reverse</emphasis> notation!
1858       <screen>
1859        Z> find @attrset idxpath @attr 1=1 @attr 4=3 cn/cn-1/../c1/
1860        Z> find @attr 1=_XPATH_BEGIN @attr 4=3 cn/cn-1/../c1/
1861       </screen>
1862      </para>
1863      <para>
1864       Search for CDATA string <emphasis>text</emphasis> in any  element
1865       <screen>
1866        Z> find @attrset idxpath @attr 1=1016 text
1867        Z> find @attr 1=_XPATH_CDATA text
1868       </screen>
1869      </para>
1870      <para>
1871        Search for CDATA string <emphasis>anothertext</emphasis> in any
1872        attribute:
1873       <screen>
1874        Z> find @attrset idxpath @attr 1=1015 anothertext
1875        Z> find @attr 1=_XPATH_ATTR_CDATA anothertext
1876       </screen>
1877      </para>
1878      <para>
1879        Search for all documents with have an XML element node
1880        including an XML  attribute named <emphasis>creator</emphasis>
1881       <screen>
1882        Z> find @attrset idxpath @attr 1=3 @attr 4=3 creator
1883        Z> find @attr 1=_XPATH_ATTR_NAME @attr 4=3 creator
1884       </screen>
1885      </para>
1886      <para>
1887       Combining usual <literal>bib-1</literal> attribute set searches
1888       with <literal>idxpath</literal> attribute set searches:
1889       <screen>
1890        Z> find @and @attr idxpath 1=1 @attr 4=3 link/ @attr 1=4 mozart
1891        Z> find @and @attr 1=_XPATH_BEGIN @attr 4=3 link/ @attr 1=_XPATH_CDATA mozart
1892       </screen>
1893      </para>
1894      <para>
1895       Scanning is supported on all <literal>idxpath</literal>
1896       indexes, both specified as numeric use attributes, or as string
1897       index names.
1898       <screen>
1899        Z> scan  @attrset idxpath @attr 1=1016 text
1900        Z> scan  @attr 1=_XPATH_ATTR_CDATA anothertext
1901        Z> scan  @attrset idxpath @attr 1=3 @attr 4=3 ''
1902       </screen>
1903      </para>
1904
1905     </sect3>
1906    </sect2>
1907
1908
1909    <sect2 id="querymodel-pqf-apt-mapping">
1910     <title>Mapping from PQF atomic APT queries to Zebra internal
1911      register indexes</title>
1912     <para>
1913      The rules for PQF APT mapping are rather tricky to grasp in the
1914      first place. We deal first with the rules for deciding which
1915      internal register or string index to use, according to the use
1916      attribute or access point specified in the query. Thereafter we
1917      deal with the rules for determining the correct structure type of
1918      the named register.
1919     </para>
1920
1921    <sect3 id="querymodel-pqf-apt-mapping-accesspoint">
1922     <title>Mapping of PQF APT access points</title>
1923     <para>
1924       Zebra understands four fundamental different types of access
1925       points, of which only the
1926       <emphasis>numeric use attribute</emphasis> type access points
1927       are defined by the  <ulink url="&url.z39.50;">Z39.50</ulink>
1928       standard.
1929       All other access point types are Zebra specific, and non-portable.
1930     </para>
1931
1932      <table id="querymodel-zebra-mapping-accesspoint-types"
1933       frame="all" rowsep="1" colsep="1" align="center">
1934
1935       <caption>Access point name mapping</caption>
1936        <thead>
1937         <tr>
1938          <td>Access Point</td>
1939          <td>Type</td>
1940          <td>Grammar</td>
1941          <td>Notes</td>
1942         </tr>
1943       </thead>
1944       <tbody>
1945        <tr>
1946         <td>Use attribute</td>
1947         <td>numeric</td>
1948         <td>[1-9][1-9]*</td>
1949         <td>directly mapped to string index name</td>
1950        </tr>
1951        <tr>
1952         <td>String index name</td>
1953         <td>string</td>
1954         <td>[a-zA-Z](\-?[a-zA-Z0-9])*</td>
1955         <td>normalized name is used as internal string index name</td>
1956        </tr>
1957        <tr>
1958         <td>Zebra internal index name</td>
1959         <td>zebra</td>
1960         <td>_[a-zA-Z](_?[a-zA-Z0-9])*</td>
1961         <td>hardwired internal string index name</td>
1962        </tr>
1963        <tr>
1964         <td>XPATH special index</td>
1965         <td>XPath</td>
1966         <td>/.*</td>
1967         <td>special xpath search for GRS indexed records</td>
1968        </tr>
1969       </tbody>
1970     </table>
1971
1972     <para>
1973      <literal>Attribute set names</literal> and
1974      <literal>string index names</literal> are normalizes
1975      according to the following rules: all <emphasis>single</emphasis>
1976      hyphens <literal>'-'</literal> are stripped, and all upper case
1977      letters are folded to lower case.
1978      </para>
1979
1980      <para>
1981       <emphasis>Numeric use attributes</emphasis> are mapped
1982       to the Zebra internal
1983       string index according to the attribute set definition in use.
1984       The default attribute set is <literal>Bib-1</literal>, and may be
1985       omitted in the PQF query.
1986      </para>
1987
1988      <para>
1989       According to normalization and numeric
1990       use attribute mapping, it follows that the following
1991       PQF queries are considered equivalent (assuming the default
1992       configuration has not been altered):
1993       <screen>
1994       Z> find  @attr 1=Body-of-text serenade
1995       Z> find  @attr 1=bodyoftext serenade
1996       Z> find  @attr 1=BodyOfText serenade
1997       Z> find  @attr 1=bO-d-Y-of-tE-x-t serenade
1998       Z> find  @attr 1=1010 serenade
1999       Z> find  @attrset Bib-1 @attr 1=1010 serenade
2000       Z> find  @attrset bib1 @attr 1=1010 serenade
2001       Z> find  @attrset Bib1 @attr 1=1010 serenade
2002       Z> find  @attrset b-I-b-1 @attr 1=1010 serenade
2003      </screen>
2004     </para>
2005
2006     <para>
2007       The <emphasis>numerical</emphasis>
2008       <literal>use attributes (type 1)</literal>
2009       are interpreted according to the
2010       attribute sets which have been loaded in the
2011       <literal>zebra.cfg</literal> file, and are matched against specific
2012       fields as specified in the <literal>.abs</literal> file which
2013       describes the profile of the records which have been loaded.
2014       If no use attribute is provided, a default of
2015       <literal>Bib-1 Use Any (1016)</literal> is
2016       assumed.
2017       The predefined <literal>use attribute sets</literal>
2018       can be reconfigured by  tweaking the configuration files
2019       <filename>tab/*.att</filename>, and
2020       new attribute sets can be defined by adding similar files in the
2021       configuration path <literal>profilePath</literal> of the server.
2022     </para>
2023
2024      <para>
2025       <literal>String indexes</literal> can be accessed directly,
2026       independently which attribute set is in use. These are just
2027       ignored. The above mentioned name normalization applies.
2028       <literal>String index names</literal> are defined in the
2029       used indexing  filter configuration files, for example in the
2030       <literal>GRS</literal>
2031       <filename>*.abs</filename> configuration files, or in the
2032       <literal>alvis</literal> filter XSLT indexing stylesheets.
2033      </para>
2034
2035      <para>
2036       <literal>Zebra internal indexes</literal> can be accessed directly,
2037       according to the same rules as the user defined
2038       <literal>string indexes</literal>. The only difference is that
2039       <literal>Zebra internal index names</literal> are hardwired,
2040       all uppercase and
2041       must start with the character <literal>'_'</literal>.
2042      </para>
2043
2044      <para>
2045       Finally, <literal>XPATH</literal> access points are only
2046       available using the <literal>GRS</literal> filter for indexing.
2047       These access point names must start with the character
2048       <literal>'/'</literal>, they are <emphasis>not
2049       normalized</emphasis>, but passed unaltered to the Zebra internal
2050       XPATH engine. See <xref linkend="querymodel-use-xpath"/>.
2051
2052      </para>
2053
2054
2055     </sect3>
2056
2057
2058    <sect3 id="querymodel-pqf-apt-mapping-structuretype">
2059      <title>Mapping of PQF APT structure and completeness to
2060       register type</title>
2061     <para>
2062       Internally Zebra has in it's default configuration several
2063      different types of registers or indexes, whose tokenization and
2064       character normalization rules differ. This reflects the fact that
2065       searching fundamental different tokens like dates, numbers,
2066       bitfields and string based text needs different rule sets.
2067      </para>
2068
2069      <table id="querymodel-zebra-mapping-structure-types"
2070       frame="all" rowsep="1" colsep="1" align="center">
2071
2072       <caption>Structure and completeness mapping to register types</caption>
2073        <thead>
2074         <tr>
2075          <td>Structure</td>
2076          <td>Completeness</td>
2077          <td>Register type</td>
2078          <td>Notes</td>
2079         </tr>
2080       </thead>
2081       <tbody>
2082        <tr>
2083         <td>
2084           phrase (@attr 4=1), word (@attr 4=2),
2085           word-list (@attr 4=6),
2086           free-form-text  (@attr 4=105), or document-text (@attr 4=106)
2087          </td>
2088         <td>Incomplete field (@attr 6=1)</td>
2089         <td>Word ('w')</td>
2090         <td>Traditional tokenized and character normalized word index</td>
2091        </tr>
2092        <tr>
2093         <td>
2094           phrase (@attr 4=1), word (@attr 4=2),
2095           word-list (@attr 4=6),
2096           free-form-text  (@attr 4=105), or document-text (@attr 4=106)
2097          </td>
2098         <td>complete field' (@attr 6=3)</td>
2099         <td>Phrase ('p')</td>
2100         <td>Character normalized, but not tokenized index for phrase
2101           matches
2102          </td>
2103        </tr>
2104        <tr>
2105         <td>urx (@attr 4=104)</td>
2106         <td>ignored</td>
2107         <td>URX/URL ('u')</td>
2108         <td>Special index for URL web addresses</td>
2109        </tr>
2110        <tr>
2111         <td>numeric (@attr 4=109)</td>
2112         <td>ignored</td>
2113         <td>Numeric ('u')</td>
2114         <td>Special index for digital numbers</td>
2115        </tr>
2116        <tr>
2117         <td>key (@attr 4=3)</td>
2118         <td>ignored</td>
2119         <td>Null bitmap ('0')</td>
2120         <td>Used for non-tokenizated and non-normalized bit sequences</td>
2121        </tr>
2122        <tr>
2123         <td>year (@attr 4=4)</td>
2124         <td>ignored</td>
2125         <td>Year ('y')</td>
2126         <td>Non-tokenizated and non-normalized 4 digit numbers</td>
2127        </tr>
2128        <tr>
2129         <td>date (@attr 4=5)</td>
2130         <td>ignored</td>
2131         <td>Date ('d')</td>
2132         <td>Non-tokenizated and non-normalized ISO date strings</td>
2133        </tr>
2134        <tr>
2135         <td>ignored</td>
2136         <td>ignored</td>
2137         <td>Sort ('s')</td>
2138         <td>Used with special sort attribute set (@attr 7=1, @attr 7=2)</td>
2139        </tr>
2140        <tr>
2141         <td>overruled</td>
2142         <td>overruled</td>
2143         <td>special</td>
2144         <td>Internal record ID register, used whenever
2145          Relation Always Matches (@attr 2=103) is specified</td>
2146        </tr>
2147       </tbody>
2148     </table>
2149
2150      <!-- see in util/zebramap.c -->
2151
2152     <para>
2153      If a <emphasis>Structure</emphasis> attribute of
2154      <emphasis>Phrase</emphasis> is used in conjunction with a
2155      <emphasis>Completeness</emphasis> attribute of
2156      <emphasis>Complete (Sub)field</emphasis>, the term is matched
2157      against the contents of the phrase (long word) register, if one
2158      exists for the given <emphasis>Use</emphasis> attribute.
2159      A phrase register is created for those fields in the
2160      GRS <filename>*.abs</filename> file that contains a
2161      <literal>p</literal>-specifier.
2162       <screen>
2163        Z>  scan @attr 1=Title @attr 4=1 @attr 6=3 beethoven
2164        ...
2165        bayreuther festspiele (1)
2166        * beethoven bibliography database (1)
2167        benny carter (1)
2168        ...
2169        Z> find @attr 1=Title @attr 4=1 @attr 6=3 "beethoven bibliography"
2170        ...
2171        Number of hits: 0, setno 5
2172        ...
2173        Z> find @attr 1=Title @attr 4=1 @attr 6=3 "beethoven bibliography database"
2174        ...
2175        Number of hits: 1, setno 6
2176        </screen>
2177     </para>
2178
2179     <para>
2180      If <emphasis>Structure</emphasis>=<emphasis>Phrase</emphasis> is
2181      used in conjunction with <emphasis>Incomplete Field</emphasis> - the
2182      default value for <emphasis>Completeness</emphasis>, the
2183      search is directed against the normal word registers, but if the term
2184      contains multiple words, the term will only match if all of the words
2185      are found immediately adjacent, and in the given order.
2186      The word search is performed on those fields that are indexed as
2187      type <literal>w</literal> in the GRS <filename>*.abs</filename> file.
2188       <screen>
2189        Z>  scan @attr 1=Title @attr 4=1 @attr 6=1 beethoven
2190        ...
2191          beefheart (1)
2192        * beethoven (18)
2193          beethovens (7)
2194        ...
2195        Z> find @attr 1=Title @attr 4=1 @attr 6=1 beethoven
2196        ...
2197        Number of hits: 18, setno 1
2198        ...
2199        Z> find @attr 1=Title @attr 4=1 @attr 6=1 "beethoven  bibliography"
2200        ...
2201        Number of hits: 2, setno 2
2202        ...
2203      </screen>
2204     </para>
2205
2206     <para>
2207      If the <emphasis>Structure</emphasis> attribute is
2208      <emphasis>Word List</emphasis>,
2209      <emphasis>Free-form Text</emphasis>, or
2210      <emphasis>Document Text</emphasis>, the term is treated as a
2211      natural-language, relevance-ranked query.
2212      This search type uses the word register, i.e. those fields
2213      that are indexed as type <literal>w</literal> in the
2214      GRS <filename>*.abs</filename> file.
2215     </para>
2216
2217     <para>
2218      If the <emphasis>Structure</emphasis> attribute is
2219      <emphasis>Numeric String</emphasis> the term is treated as an integer.
2220      The search is performed on those fields that are indexed
2221      as type <literal>n</literal> in the GRS
2222       <filename>*.abs</filename> file.
2223     </para>
2224
2225     <para>
2226      If the <emphasis>Structure</emphasis> attribute is
2227      <emphasis>URX</emphasis> the term is treated as a URX (URL) entity.
2228      The search is performed on those fields that are indexed as type
2229      <literal>u</literal> in the <filename>*.abs</filename> file.
2230     </para>
2231
2232     <para>
2233      If the <emphasis>Structure</emphasis> attribute is
2234      <emphasis>Local Number</emphasis> the term is treated as
2235      native Zebra Record Identifier.
2236     </para>
2237
2238     <para>
2239      If the <emphasis>Relation</emphasis> attribute is
2240      <emphasis>Equals</emphasis> (default), the term is matched
2241      in a normal fashion (modulo truncation and processing of
2242      individual words, if required).
2243      If <emphasis>Relation</emphasis> is <emphasis>Less Than</emphasis>,
2244      <emphasis>Less Than or Equal</emphasis>,
2245      <emphasis>Greater than</emphasis>, or <emphasis>Greater than or
2246       Equal</emphasis>, the term is assumed to be numerical, and a
2247      standard regular expression is constructed to match the given
2248      expression.
2249      If <emphasis>Relation</emphasis> is <emphasis>Relevance</emphasis>,
2250      the standard natural-language query processor is invoked.
2251     </para>
2252
2253     <para>
2254      For the <emphasis>Truncation</emphasis> attribute,
2255      <emphasis>No Truncation</emphasis> is the default.
2256      <emphasis>Left Truncation</emphasis> is not supported.
2257      <emphasis>Process # in search term</emphasis> is supported, as is
2258      <emphasis>Regxp-1</emphasis>.
2259      <emphasis>Regxp-2</emphasis> enables the fault-tolerant (fuzzy)
2260      search. As a default, a single error (deletion, insertion,
2261      replacement) is accepted when terms are matched against the register
2262      contents.
2263     </para>
2264
2265      </sect3>
2266    </sect2>
2267
2268    <sect2  id="querymodel-regular">
2269     <title>Zebra Regular Expressions in Truncation Attribute (type = 5)</title>
2270
2271     <para>
2272      Each term in a query is interpreted as a regular expression if
2273      the truncation value is either <emphasis>Regxp-1 (@attr 5=102)</emphasis>
2274      or <emphasis>Regxp-2 (@attr 5=103)</emphasis>.
2275      Both query types follow the same syntax with the operands:
2276     </para>
2277
2278      <table id="querymodel-regular-operands-table"
2279       frame="all" rowsep="1" colsep="1" align="center">
2280
2281       <caption>Regular Expression Operands</caption>
2282        <!--
2283        <thead>
2284        <tr><td>one</td><td>two</td></tr>
2285       </thead>
2286        -->
2287        <tbody>
2288         <tr>
2289          <td><literal>x</literal></td>
2290          <td>Matches the character <literal>x</literal>.</td>
2291         </tr>
2292         <tr>
2293          <td><literal>.</literal></td>
2294          <td>Matches any character.</td>
2295         </tr>
2296         <tr>
2297          <td><literal>[ .. ]</literal></td>
2298          <td>Matches the set of characters specified;
2299          such as <literal>[abc]</literal> or <literal>[a-c]</literal>.</td>
2300         </tr>
2301        </tbody>
2302       </table>
2303
2304     <para>
2305      The above operands can be combined with the following operators:
2306     </para>
2307
2308      <table id="querymodel-regular-operators-table"
2309       frame="all" rowsep="1" colsep="1" align="center">
2310       <caption>Regular Expression Operators</caption>
2311        <!--
2312        <thead>
2313        <tr><td>one</td><td>two</td></tr>
2314       </thead>
2315        -->
2316        <tbody>
2317         <tr>
2318          <td><literal>x*</literal></td>
2319          <td>Matches <literal>x</literal> zero or more times.
2320           Priority: high.</td>
2321         </tr>
2322         <tr>
2323          <td><literal>x+</literal></td>
2324          <td>Matches <literal>x</literal> one or more times.
2325           Priority: high.</td>
2326         </tr>
2327         <tr>
2328          <td><literal>x?</literal></td>
2329          <td> Matches <literal>x</literal> zero or once.
2330           Priority: high.</td>
2331         </tr>
2332         <tr>
2333          <td><literal>xy</literal></td>
2334          <td> Matches <literal>x</literal>, then <literal>y</literal>.
2335          Priority: medium.</td>
2336         </tr>
2337         <tr>
2338          <td><literal>x|y</literal></td>
2339          <td> Matches either <literal>x</literal> or <literal>y</literal>.
2340          Priority: low.</td>
2341         </tr>
2342         <tr>
2343          <td><literal>( )</literal></td>
2344          <td>The order of evaluation may be changed by using parentheses.</td>
2345         </tr>
2346        </tbody>
2347       </table>
2348
2349     <para>
2350      If the first character of the <literal>Regxp-2</literal> query
2351      is a plus character (<literal>+</literal>) it marks the
2352      beginning of a section with non-standard specifiers.
2353      The next plus character marks the end of the section.
2354      Currently Zebra only supports one specifier, the error tolerance,
2355      which consists one digit.
2356      <!-- TODO Nice thing, but what does
2357      that error tolerance digit *mean*? Maybe an example would be nice? -->
2358     </para>
2359
2360     <para>
2361      Since the plus operator is normally a suffix operator the addition to
2362      the query syntax doesn't violate the syntax for standard regular
2363      expressions.
2364     </para>
2365
2366     <para>
2367      For example, a phrase search with regular expressions  in
2368      the title-register is performed like this:
2369      <screen>
2370       Z> find @attr 1=4 @attr 5=102 "informat.* retrieval"
2371      </screen>
2372     </para>
2373
2374     <para>
2375      Combinations with other attributes are possible. For example, a
2376      ranked search with a regular expression:
2377      <screen>
2378       Z> find @attr 1=4 @attr 5=102 @attr 2=102 "informat.* retrieval"
2379      </screen>
2380     </para>
2381    </sect2>
2382
2383
2384    <!--
2385    <para>
2386     The RecordType parameter in the <literal>zebra.cfg</literal> file, or
2387     the <literal>-t</literal> option to the indexer tells Zebra how to
2388     process input records.
2389     Two basic types of processing are available - raw text and structured
2390     data. Raw text is just that, and it is selected by providing the
2391     argument <literal>text</literal> to Zebra. Structured records are
2392     all handled internally using the basic mechanisms described in the
2393     subsequent sections.
2394     Zebra can read structured records in many different formats.
2395    </para>
2396    -->
2397   </sect1>
2398
2399
2400   <sect1 id="querymodel-cql-to-pqf">
2401    <title>Server Side CQL to PQF Query Translation</title>
2402    <para>
2403     Using the
2404     <literal>&lt;cql2rpn&gt;l2rpn.txt&lt;/cql2rpn&gt;</literal>
2405       YAZ Frontend Virtual
2406     Hosts option, one can configure
2407     the YAZ Frontend CQL-to-PQF
2408     converter, specifying the interpretation of various
2409     <ulink url="&url.cql;">CQL</ulink>
2410     indexes, relations, etc. in terms of Type-1 query attributes.
2411     <!-- The  yaz-client config file -->
2412    </para>
2413    <para>
2414     For example, using server-side CQL-to-PQF conversion, one might
2415     query a zebra server like this:
2416     <screen>
2417     <![CDATA[
2418      yaz-client localhost:9999
2419      Z> querytype cql
2420      Z> find text=(plant and soil)
2421      ]]>
2422     </screen>
2423      and - if properly configured - even static relevance ranking can
2424      be performed using CQL query syntax:
2425     <screen>
2426     <![CDATA[
2427      Z> find text = /relevant (plant and soil)
2428      ]]>
2429      </screen>
2430    </para>
2431
2432    <para>
2433     By the way, the same configuration can be used to
2434     search using client-side CQL-to-PQF conversion:
2435     (the only difference is <literal>querytype cql2rpn</literal>
2436     instead of
2437     <literal>querytype cql</literal>, and the call specifying a local
2438     conversion file)
2439     <screen>
2440     <![CDATA[
2441      yaz-client -q local/cql2pqf.txt localhost:9999
2442      Z> querytype cql2rpn
2443      Z> find text=(plant and soil)
2444      ]]>
2445      </screen>
2446    </para>
2447
2448    <para>
2449     Exhaustive information can be found in the
2450     Section "Specification of CQL to RPN mappings" in the YAZ manual.
2451     <ulink url="http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map">
2452      http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map</ulink>,
2453    and shall therefore not be repeated here.
2454    </para>
2455   <!--
2456   <para>
2457     See
2458       <ulink url="http://www.loc.gov/z3950/agency/zing/cql/dc-indexes.html">
2459       http://www.loc.gov/z3950/agency/zing/cql/dc-indexes.html</ulink>
2460     for the Maintenance Agency's work-in-progress mapping of Dublin Core
2461     indexes to Attribute Architecture (util, XD and BIB-2)
2462     attributes.
2463    </para>
2464    -->
2465  </sect1>
2466
2467
2468
2469 </chapter>
2470
2471  <!-- Keep this comment at the end of the file
2472  Local variables:
2473  mode: sgml
2474  sgml-omittag:t
2475  sgml-shorttag:t
2476  sgml-minimize-attributes:nil
2477  sgml-always-quote-attributes:t
2478  sgml-indent-step:1
2479  sgml-indent-data:t
2480  sgml-parent-document: "zebra.xml"
2481  sgml-local-catalogs: nil
2482  sgml-namecase-general:t
2483  End:
2484  -->