doc/querymodel.xml

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