doc/zebrasrv.xml

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