doc/zebrasrv.xml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
   2  "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
   3 [
   4      <!ENTITY % local SYSTEM "local.ent">
   5      %local;
   6      <!ENTITY % entities  SYSTEM "entities.ent">
   7      %entities;
   8      <!ENTITY % idcommon  SYSTEM "common/common.ent">
   9      %idcommon;
  10 ]>
  11 <refentry id="zebrasrv">
  12  <refentryinfo>
  13   <productname>zebra</productname>
  14   <productnumber>&version;</productnumber>
  15  </refentryinfo>
  16
  17  <refmeta>
  18   <refentrytitle>zebrasrv</refentrytitle>
  19   <manvolnum>8</manvolnum>
  20  </refmeta>
  21
  22  <refnamediv>
  23   <refname>zebrasrv</refname>
  24   <refpurpose>Zebra Server</refpurpose>
  25  </refnamediv>
  26
  27  <refsynopsisdiv>
  28   &zebrasrv-synopsis;
  29  </refsynopsisdiv>
  30   <refsect1><title>DESCRIPTION</title>
  31   <para>Zebra is a high-performance, general-purpose structured text indexing
  32    and retrieval engine. It reads structured records in a variety of input
  33    formats (eg. email, &acro.xml;, &acro.marc;) and allows access to them through exact
  34    boolean search expressions and relevance-ranked free-text queries.
  35   </para>
  36   <para>
  37    <command>zebrasrv</command> is the &acro.z3950; and &acro.sru; frontend
  38    server for the <command>Zebra</command> search engine and indexer.
  39   </para>
  40   <para>
  41    On Unix you can run the <command>zebrasrv</command>
  42    server from the command line - and put it
  43    in the background. It may also operate under the inet daemon.
  44    On WIN32 you can run the server as a console application or
  45    as a WIN32 Service.
  46   </para>
  47  </refsect1>
  48  <refsect1>
  49   <title>OPTIONS</title>
  50
  51    <para>
  52    The options for <command>zebrasrv</command> are the same
  53    as those for &yaz;' <command>yaz-ztest</command>.
  54    Option <literal>-c</literal> specifies a Zebra configuration
  55    file - if omitted <filename>zebra.cfg</filename> is read.
  56   </para>
  57
  58   &zebrasrv-options;
  59  </refsect1>
  60
  61  <refsect1 id="protocol-support">
  62   <title>&acro.z3950; Protocol Support and Behavior</title>
  63
  64   <refsect2 id="zebrasrv-initialization">
  65    <title>&acro.z3950; Initialization</title>
  66
  67    <para>
  68     During initialization, the server will negotiate to version 3 of the
  69     &acro.z3950; protocol, and the option bits for Search, Present, Scan,
  70     NamedResultSets, and concurrentOperations will be set, if requested by
  71     the client. The maximum PDU size is negotiated down to a maximum of
  72     1 MB by default.
  73    </para>
  74
  75   </refsect2>
  76
  77   <refsect2 id="zebrasrv-search">
  78    <title>&acro.z3950; Search</title>
  79
  80    <para>
  81     The supported query type are 1 and 101. All operators are currently
  82     supported with the restriction that only proximity units of type "word"
  83     are supported for the proximity operator.
  84     Queries can be arbitrarily complex.
  85     Named result sets are supported, and result sets can be used as operands
  86     without limitations.
  87     Searches may span multiple databases.
  88    </para>
  89
  90    <para>
  91     The server has full support for piggy-backed retrieval (see
  92     also the following section).
  93    </para>
  94
  95    </refsect2>
  96
  97   <refsect2 id="zebrasrv-present">
  98    <title>&acro.z3950; Present</title>
  99    <para>
 100     The present facility is supported in a standard fashion. The requested
 101     record syntax is matched against the ones supported by the profile of
 102     each record retrieved. If no record syntax is given, &acro.sutrs; is the
 103     default. The requested element set name, again, is matched against any
 104     provided by the relevant record profiles.
 105    </para>
 106   </refsect2>
 107   <refsect2 id="zebrasrv-scan">
 108    <title>&acro.z3950; Scan</title>
 109    <para>
 110     The attribute combinations provided with the termListAndStartPoint are
 111     processed in the same way as operands in a query (see above).
 112     Currently, only the term and the globalOccurrences are returned with
 113     the termInfo structure.
 114    </para>
 115   </refsect2>
 116   <refsect2 id="zebrasrv-sort">
 117    <title>&acro.z3950; Sort</title>
 118
 119    <para>
 120     &acro.z3950; specifies three different types of sort criteria.
 121     Of these Zebra supports the attribute specification type in which
 122     case the use attribute specifies the "Sort register".
 123     Sort registers are created for those fields that are of type "sort" in
 124     the default.idx file.
 125     The corresponding character mapping file in default.idx specifies the
 126     ordinal of each character used in the actual sort.
 127    </para>
 128
 129    <para>
 130     &acro.z3950; allows the client to specify sorting on one or more input
 131     result sets and one output result set.
 132     Zebra supports sorting on one result set only which may or may not
 133     be the same as the output result set.
 134    </para>
 135   </refsect2>
 136   <refsect2 id="zebrasrv-close">
 137    <title>&acro.z3950; Close</title>
 138    <para>
 139     If a Close PDU is received, the server will respond with a Close PDU
 140     with reason=FINISHED, no matter which protocol version was negotiated
 141     during initialization. If the protocol version is 3 or more, the
 142     server will generate a Close PDU under certain circumstances,
 143     including a session timeout (60 minutes by default), and certain kinds of
 144     protocol errors. Once a Close PDU has been sent, the protocol
 145     association is considered broken, and the transport connection will be
 146     closed immediately upon receipt of further data, or following a short
 147     timeout.
 148    </para>
 149   </refsect2>
 150
 151    <refsect2 id="zebrasrv-explain">
 152     <title>&acro.z3950; Explain</title>
 153     <para>
 154      Zebra maintains a "classic"
 155     <ulink url="&url.z39.50.explain;">&acro.z3950; Explain</ulink> database
 156     on the side.
 157     This database is called <literal>IR-Explain-1</literal> and can be
 158     searched using the attribute set <literal>exp-1</literal>.
 159    </para>
 160    <para>
 161     The records in the explain database are of type
 162     <literal>grs.sgml</literal>.
 163     The root element for the Explain grs.sgml records is
 164     <literal>explain</literal>, thus
 165     <filename>explain.abs</filename> is used for indexing.
 166    </para>
 167    <note>
 168      <para>
 169      Zebra <emphasis>must</emphasis> be able to locate
 170      <filename>explain.abs</filename> in order to index the Explain
 171      records properly. Zebra will work without it but the information
 172      will not be searchable.
 173     </para>
 174    </note>
 175   </refsect2>
 176  </refsect1>
 177  <refsect1 id="zebrasrv-sru">
 178   <title>The &acro.sru; Server</title>
 179   <para>
 180    In addition to &acro.z3950;, Zebra supports the more recent and
 181    web-friendly IR protocol <ulink url="&url.sru;">&acro.sru;</ulink>.
 182     &acro.sru; can be carried over &acro.soap; or a &acro.rest;-like protocol
 183     that uses HTTP &acro.get; or &acro.post; to request search responses.  The request
 184     itself is made of parameters such as
 185     <literal>query</literal>,
 186     <literal>startRecord</literal>,
 187     <literal>maximumRecords</literal>
 188     and
 189     <literal>recordSchema</literal>;
 190     the response is an &acro.xml; document containing hit-count, result-set
 191     records, diagnostics, etc.  &acro.sru; can be thought of as a re-casting
 192     of &acro.z3950; semantics in web-friendly terms; or as a standardisation
 193     of the ad-hoc query parameters used by search engines such as Google
 194     and AltaVista; or as a superset of A9's OpenSearch (which it
 195     predates).
 196   </para>
 197   <para>
 198    Zebra supports &acro.z3950;, &acro.sru; &acro.get;, SRU &acro.post;, SRU &acro.soap; (&acro.srw;)
 199    - on the same port, recognising what protocol is used by each incoming
 200    requests and handling them accordingly.  This is a achieved through
 201    the use of Deep Magic; civilians are warned not to stand too close.
 202   </para>
 203  <refsect2 id="zebrasrv-sru-run">
 204   <title>Running zebrasrv as an &acro.sru; Server</title>
 205   <para>
 206    Because Zebra supports all protocols on one port, it would
 207    seem to follow that the &acro.sru; server is run in the same way as
 208    the &acro.z3950; server, as described above.  This is true, but only in
 209    an uninterestingly vacuous way: a Zebra server run in this manner
 210    will indeed recognise and accept &acro.sru; requests; but since it
 211    doesn't know how to handle the &acro.cql; queries that these protocols
 212    use, all it can do is send failure responses.
 213   </para>
 214   <note>
 215    <para>
 216     It is possible to cheat, by having &acro.sru; search Zebra with
 217     a &acro.pqf; query instead of &acro.cql;, using the
 218     <literal>x-pquery</literal>
 219     parameter instead of
 220     <literal>query</literal>.
 221     This is a
 222     <emphasis role="strong">non-standard extension</emphasis>
 223     of &acro.cql;, and a
 224     <emphasis role="strong">very naughty</emphasis>
 225     thing to do, but it does give you a way to see Zebra serving &acro.sru;
 226     ``right out of the box''.  If you start your favourite Zebra
 227     server in the usual way, on port 9999, then you can send your web
 228     browser to:
 229   </para>
 230    <screen>
 231     http://localhost:9999/Default?version=1.1
 232      &amp;operation=searchRetrieve
 233      &amp;x-pquery=mineral
 234      &amp;startRecord=1
 235      &amp;maximumRecords=1
 236    </screen>
 237    <para>
 238     This will display the &acro.xml;-formatted &acro.sru; response that includes the
 239     first record in the result-set found by the query
 240     <literal>mineral</literal>.  (For clarity, the &acro.sru; URL is shown
 241     here broken across lines, but the lines should be joined to gether
 242     to make single-line URL for the browser to submit.)
 243    </para>
 244   </note>
 245   <para>
 246    In order to turn on Zebra's support for &acro.cql; queries, it's necessary
 247    to have the &yaz; generic front-end (which Zebra uses) translate them
 248    into the &acro.z3950; Type-1 query format that is used internally.  And
 249    to do this, the generic front-end's own configuration file must be
 250    used.  See <xref linkend="gfs-config"/>;
 251    the salient point for &acro.sru; support is that
 252    <command>zebrasrv</command>
 253    must be started with the
 254    <literal>-f&nbsp;frontendConfigFile</literal>
 255    option rather than the
 256    <literal>-c&nbsp;zebraConfigFile</literal>
 257    option,
 258    and that the front-end configuration file must include both a
 259    reference to the Zebra configuration file and the &acro.cql;-to-&acro.pqf;
 260    translator configuration file.
 261   </para>
 262   <para>
 263    A minimal front-end configuration file that does this would read as
 264    follows:
 265   </para>
 266   <screen>
 267 <![CDATA[
 268         <yazgfs>
 269           <server>
 270             <config>zebra.cfg</config>
 271             <cql2rpn>../../tab/pqf.properties</cql2rpn>
 272           </server>
 273         </yazgfs>
 274 ]]></screen>
 275   <para>
 276    The
 277    <literal>&lt;config&gt;</literal>
 278    element contains the name of the Zebra configuration file that was
 279    previously specified by the
 280    <literal>-c</literal>
 281    command-line argument, and the
 282    <literal>&lt;cql2rpn&gt;</literal>
 283    element contains the name of the &acro.cql; properties file specifying how
 284    various &acro.cql; indexes, relations, etc. are translated into Type-1
 285    queries.
 286   </para>
 287   <para>
 288    A zebra server running with such a configuration can then be
 289    queried using proper, conformant &acro.sru; URLs with &acro.cql; queries:
 290   </para>
 291   <screen>
 292    http://localhost:9999/Default?version=1.1
 293     &amp;operation=searchRetrieve
 294     &amp;query=title=utah and description=epicent*
 295     &amp;startRecord=1
 296     &amp;maximumRecords=1
 297    </screen>
 298   </refsect2>
 299  </refsect1>
 300  <refsect1 id="zebrasrv-sru-support">
 301   <title>&acro.sru; Protocol Support and Behavior</title>
 302   <para>
 303    Zebra running as an &acro.sru; server supports SRU version 1.1, including
 304    &acro.cql; version 1.1.  In particular, it provides support for the
 305    following elements of the protocol.
 306   </para>
 307
 308   <refsect2 id="zebrasrvr-search-and-retrieval">
 309    <title>&acro.sru; Search and Retrieval</title>
 310    <para>
 311     Zebra supports the
 312     <ulink url="&url.sru.searchretrieve;">&acro.sru; searchRetrieve</ulink>
 313     operation.
 314    </para>
 315    <para>
 316     One of the great strengths of &acro.sru; is that it mandates a standard
 317     query language, &acro.cql;, and that all conforming implementations can
 318     therefore be trusted to correctly interpret the same queries.  It
 319     is with some shame, then, that we admit that Zebra also supports
 320     an additional query language, our own Prefix Query Format
 321     (<ulink url="&url.yaz.pqf;">&acro.pqf;</ulink>).
 322     A &acro.pqf; query is submitted by using the extension parameter
 323     <literal>x-pquery</literal>,
 324     in which case the
 325     <literal>query</literal>
 326     parameter must be omitted, which makes the request not valid &acro.sru;.
 327     Please feel free to use this facility within your own
 328     applications; but be aware that it is not only non-standard &acro.sru;
 329     but not even syntactically valid, since it omits the mandatory
 330     <literal>query</literal> parameter.
 331    </para>
 332   </refsect2>
 333
 334   <refsect2 id="zebrasrv-sru-scan">
 335    <title>&acro.sru; Scan</title>
 336    <para>
 337     Zebra supports <ulink url="&url.sru.scan;">&acro.sru; scan</ulink>
 338     operation.
 339     Scanning using &acro.cql; syntax is the default, where the
 340     standard <literal>scanClause</literal> parameter is used.
 341    </para>
 342    <para>
 343     In addition, a
 344     mutant form of &acro.sru; scan is supported, using
 345     the non-standard <literal>x-pScanClause</literal> parameter in
 346     place of the standard <literal>scanClause</literal> to scan on a
 347     &acro.pqf; query clause.
 348    </para>
 349   </refsect2>
 350
 351   <refsect2 id="zebrasrv-sru-explain">
 352    <title>&acro.sru; Explain</title>
 353    <para>
 354     Zebra supports <ulink url="&url.sru.explain;">&acro.sru; explain</ulink>.
 355    </para>
 356    <para>
 357     The ZeeRex record explaining a database may be requested either
 358     with a fully fledged &acro.sru; request (with
 359     <literal>operation</literal>=<literal>explain</literal>
 360     and version-number specified)
 361     or with a simple HTTP &acro.get; at the server's basename.
 362     The ZeeRex record returned in response is the one embedded
 363     in the &yaz; Frontend Server configuration file that is described in the
 364     <xref linkend="gfs-config"/>.
 365    </para>
 366     <para>
 367      Unfortunately, the data found in the
 368     &acro.cql;-to-&acro.pqf; text file must be added by hand-craft into the explain
 369     section of the &yaz; Frontend Server configuration file to be able
 370     to provide a suitable explain record.
 371     Too bad, but this is all extreme
 372     new alpha stuff, and a lot of work has yet to be done ..
 373    </para>
 374    <para>
 375     There is no linkeage whatsoever between the &acro.z3950; explain model
 376     and the &acro.sru; explain response (well, at least not implemented
 377     in Zebra, that is ..).  Zebra does not provide a means using
 378     &acro.z3950; to obtain the ZeeRex record.
 379    </para>
 380   </refsect2>
 381
 382   <refsect2 id="zebrasrv-non-sru-ops">
 383    <title>Other &acro.sru; operations</title>
 384    <para>
 385     In the &acro.z3950; protocol, Initialization, Present, Sort and Close
 386     are separate operations.  In &acro.sru;, however, these operations do not
 387     exist.
 388    </para>
 389    <itemizedlist>
 390     <listitem>
 391      <para>
 392       &acro.sru; has no explicit initialization handshake phase, but
 393       commences immediately with searching, scanning and explain
 394       operations.
 395      </para>
 396     </listitem>
 397     <listitem>
 398      <para>
 399       Neither does &acro.sru; have a close operation, since the protocol is
 400       stateless and each request is self-contained.  (It is true that
 401       multiple &acro.sru; request/response pairs may be implemented as
 402       multiple HTTP request/response pairs over a single persistent
 403       TCP/IP connection; but the closure of that connection is not a
 404       protocol-level operation.)
 405      </para>
 406     </listitem>
 407     <listitem>
 408      <para>
 409       Retrieval in &acro.sru; is part of the
 410       <literal>searchRetrieve</literal> operation, in which a search
 411       is submitted and the response includes a subset of the records
 412       in the result set.  There is no direct analogue of &acro.z3950;'s
 413       Present operation which requests records from an established
 414       result set.  In &acro.sru;, this is achieved by sending a subsequent
 415       <literal>searchRetrieve</literal> request with the query
 416       <literal>cql.resultSetId=</literal><emphasis>id</emphasis> where
 417       <emphasis>id</emphasis> is the identifier of the previously
 418       generated result-set.
 419      </para>
 420     </listitem>
 421     <listitem>
 422      <para>
 423       Sorting in &acro.cql; is done within the
 424       <literal>searchRetrieve</literal> operation - in v1.1, by an
 425       explicit <literal>sort</literal> parameter, but the forthcoming
 426       v1.2 or v2.0 will most likely use an extension of the query
 427       language, <ulink url="&url.cql.sorting;">&acro.cql; sorting</ulink>.
 428      </para>
 429     </listitem>
 430    </itemizedlist>
 431    <para>
 432     It can be seen, then, that while Zebra operating as an &acro.sru; server
 433     does not provide the same set of operations as when operating as a
 434     &acro.z3950; server, it does provide equivalent functionality.
 435    </para>
 436   </refsect2>
 437  </refsect1>
 438
 439  <refsect1 id="zebrasrv-sru-examples">
 440    <title>&acro.sru; Examples</title>
 441     <para>
 442     Surf into <literal>http://localhost:9999</literal>
 443      to get an explain response, or use
 444     <screen><![CDATA[
 445      http://localhost:9999/?version=1.1&operation=explain
 446      ]]></screen>
 447     </para>
 448    <para>
 449     See number of hits for a query
 450     <screen><![CDATA[
 451      http://localhost:9999/?version=1.1&operation=searchRetrieve
 452      &query=text=(plant%20and%20soil)
 453      ]]></screen>
 454    </para>
 455    <para>
 456     Fetch record 5-7 in Dublin Core format
 457     <screen><![CDATA[
 458      http://localhost:9999/?version=1.1&operation=searchRetrieve
 459                        &query=text=(plant%20and%20soil)
 460                        &startRecord=5&maximumRecords=2&recordSchema=dc
 461      ]]></screen>
 462    </para>
 463    <para>
 464     Even search using &acro.pqf; queries using the <emphasis>extended naughty
 465      parameter</emphasis> <literal>x-pquery</literal>
 466     <screen><![CDATA[
 467       http://localhost:9999/?version=1.1&operation=searchRetrieve
 468                        &x-pquery=@attr%201=text%20@and%20plant%20soil
 469      ]]></screen>
 470    </para>
 471    <para>
 472     Or scan indexes using the <emphasis>extended extremely naughty
 473      parameter</emphasis> <literal>x-pScanClause</literal>
 474     <screen><![CDATA[
 475       http://localhost:9999/?version=1.1&operation=scan
 476                        &x-pScanClause=@attr%201=text%20something
 477      ]]></screen>
 478     <emphasis>Don't do this in production code!</emphasis>
 479     But it's a great fast debugging aid.
 480    </para>
 481
 482  </refsect1>
 483
 484  <refsect1 id="gfs-config"><title>&yaz; server virtual hosts</title>
 485   &zebrasrv-virtual;
 486  </refsect1>
 487
 488  <refsect1><title>SEE ALSO</title>
 489   <para>
 490    <citerefentry>
 491     <refentrytitle>zebraidx</refentrytitle>
 492     <manvolnum>1</manvolnum>
 493    </citerefentry>
 494   </para>
 495 </refsect1>
 496 </refentry>
 497
 498  <!-- Keep this comment at the end of the file
 499  Local variables:
 500  mode: sgml
 501  sgml-omittag:t
 502  sgml-shorttag:t
 503  sgml-minimize-attributes:nil
 504  sgml-always-quote-attributes:t
 505  sgml-indent-step:1
 506  sgml-indent-data:t
 507  sgml-parent-document: "zebra.xml"
 508  sgml-local-catalogs: nil
 509  sgml-namecase-general:t
 510  End:
 511  -->