doc/tutorial.xml

   1 <chapter id="tutorial">
   2  <!-- $Id: tutorial.xml,v 1.1 2008-02-01 13:54:39 marc Exp $ -->
   3  <title>Tutorial</title>
   4
   5
   6  <sect1 id="tutorial-oai">
   7   <title>A first &acro.oai; indexing example</title>
   8
   9  <para>
  10   In this section, we will test the system by indexing a small set of
  11   sample &acro.oai; records that are included with the &zebra; distribution,
  12   running a &zebra; server against the newly created database, and
  13   searching the indexes with a client that connects to that server.
  14  </para>
  15  <para>
  16   Go to the <literal>examples/oai-pmh</literal> subdirectory of the
  17   distribution archive, or make a deep copy of the Debian installation
  18    directory
  19   <literal>/usr/share/idzebra-2.0.-examples/oai-pmh</literal>.
  20    An XML file containing multiple &acro.oai;
  21    records is located in the  sub
  22    directory <literal>examples/oai-pmh/data</literal>. To index these, type:
  23   <screen>
  24     zebraidx -c conf/zebra.cfg init
  25     zebraidx -c conf/zebra.cfg update data/oai-caltech.xml
  26     zebraidx -c conf/zebra.cfg commit
  27   </screen>
  28    In case you have not installed zebra yet but have compiled the
  29     binaries from this tarball, use the following command form:
  30   <screen>
  31     ../../index/zebraidx -c conf/zebra.cfg this and that
  32   </screen>
  33  </para>
  34
  35  <para>
  36   In this command, the word <literal>update</literal> is followed
  37   by the name of a directory: <literal>zebraidx</literal> updates all
  38   files in the hierarchy rooted at that directory. The command option
  39   <literal>-c conf/zebra.cfg</literal> points to the proper
  40   configuration file.
  41  </para>
  42
  43  <para>
  44    You might ask yourself how &acro.xml; content is indexed using &acro.xslt;
  45    stylesheets: to satisfy your curiosity, you might want to run the
  46    indexing transformation on an example debugging &acro.oai; record.
  47    <screen>
  48     xsltproc conf/oai2index.xsl data/debug-record.xml
  49    </screen>
  50     Here you see the &acro.oai; record transformed into the indexing
  51     &acro.xml; format. &zebra; is creating several inverted indexes,
  52     and their name and type are clearly visible in the indexing
  53     &acro.xml; format.
  54  </para>
  55
  56  <para>
  57   If your indexing command was successful, you are now ready to
  58   fire up a server. To start a server on port 9999, type:
  59   <screen>
  60    zebrasrv -c conf/zebra.cfg  @:9999
  61   </screen>
  62  </para>
  63
  64  <para>
  65   The &zebra; index that you have just created has a single database
  66   named <literal>Default</literal>.
  67   The database contains  several &acro.oai; records, and the server will
  68   return records in the &acro.xml; format only. The indexing machine
  69   di the splitting into individual records just behind the scenes.
  70  </para>
  71
  72  <para>
  73   To test the server, you can use any &acro.z3950; client.
  74   For instance, you can use the demo command-line client that comes
  75   with &yaz;; we start the  SRU/SRW/Z39.50 server in PQF mode only:
  76  </para>
  77  <para>
  78   <screen>
  79    yaz-client localhost:9999
  80   </screen>
  81  </para>
  82
  83  <para>
  84   When the client has connected, you can type:
  85  </para>
  86
  87  <para>
  88   <screen>
  89    Z> format xml
  90    Z> elements oai
  91    Z> find the
  92    Z> show 1+1
  93   </screen>
  94  </para>
  95
  96 <!--
  97
  98 Z39.50 presents using presentation stylesheets:
  99
 100    Z> elements dc
 101    Z> show 2+1
 102
 103    Z> elements zebra
 104    Z> show 3+1
 105
 106
 107 Z39.50 buildin Zebra presents (in this configuration only if
 108   started without yaz-frontendserver):
 109
 110    Z> elements zebra::meta
 111    Z> show 4+1
 112
 113    Z> elements zebra::meta::sysno
 114    Z> show 5+1
 115
 116    Z> format sutrs
 117    Z> show 5+1
 118    Z> format xml
 119
 120    Z> elements zebra::index
 121    Z> show 6+1
 122
 123    Z> elements zebra::snippet
 124    Z> show 7+1
 125
 126    Z> elements zebra::facet::any:w
 127    Z> show 8+1
 128
 129    Z>  elements zebra::facet::any:w,dc_title:w
 130    Z> show 9+1
 131
 132
 133
 134 Z39.50 searches targeted at specific indexes
 135
 136    Z> elements zebra
 137    Z> find @attr 1=oai_identifier @attr 4=3 oai:caltechcstr.library.caltech.edu:4
 138    Z> show 1+1
 139
 140    Z> find @attr 1=oai_datestamp  @attr 4=3 2001-04-20
 141    Z> show 1+1
 142
 143    Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562
 144    Z> show 1+1
 145
 146    Z> find @attr 1=dc_title communication
 147    Z> show 1+1
 148
 149    Z> find @attr 1=dc_identifier @attr 4=3
 150                  http://resolver.caltech.edu/CaltechCSTR:1986.5228-tr-86
 151    Z> show 1+1
 152
 153    etc, etc.
 154
 155    Notice that all indexes defined by 'type="0"' in the
 156    indexing style  sheet must be searched using the '@attr 4=3'
 157    structure attribute instruction.
 158
 159    Notice also that searching and scan on indexes
 160    'dc_contributor',  'dc_language', 'dc_rights', and 'dc_source'
 161    fails, simply because none of the records in this example set
 162    have these fields set, and consequently, these indexes are
 163    _not_ created.
 164
 165
 166 XXXXXXXX
 167
 168
 169 Z39.50 scan:
 170
 171    yaz-client localhost:9999
 172    Z> format xml
 173    Z> querytype prefix
 174    Z> scan @attr 1=oai_identifier @attr 4=3 oai
 175    Z> scan @attr 1=oai_datestamp @attr 4=3 1
 176    Z> scan @attr 1=oai_setspec @attr 4=3 2000
 177    Z>
 178    Z> scan @attr 1=dc_title communication
 179    Z> scan @attr 1=dc_identifier @attr 4=3 a
 180
 181    etc, etc,
 182
 183
 184 Z39.50 search using server-side CQL conversion:
 185
 186    Z> format xml
 187    Z> querytype cql
 188    Z> elements dc
 189    Z>
 190    Z> find harry
 191    Z>
 192    Z> find creator = the
 193    Z> find dc.creator = the
 194    Z> find title = the
 195    Z>
 196    Z> find description < the
 197    Z> find title le some
 198    Z> find title ge some
 199    Z> find title > some
 200    Z>
 201    Z> find identifier eq
 202            "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
 203    Z> find relation eq something
 204
 205
 206    etc, etc. Notice that  all indexes defined by 'type="0"' in the
 207    indexing style  sheet must be searched using the 'eq'
 208    relation.
 209
 210    Z> find title <> and
 211
 212    fails as well.  ???
 213
 214
 215 Z39.50 scan using server side CQL conversion:
 216
 217    Unfortunately, this will _never_ work as it is not supported by the
 218    Z39.50 standard.
 219    If you want to use scan using server side CQL conversion, you need to
 220    make an SRW connection using  yaz-client, or a
 221    SRU connection using REST Web Services - any browser will do.
 222
 223
 224 SRU Explain ZeeRex response:
 225
 226    http://localhost:9999/
 227    http://localhost:9999/?version=1.1&operation=explain
 228
 229
 230 SRU Search Retrieve records:
 231
 232    http://localhost:9999/?version=1.1&operation=searchRetrieve
 233                           &query=creator=adam
 234
 235    http://localhost:9999/?version=1.1&operation=searchRetrieve
 236                          &query=date=1978-01-01
 237                          &startRecord=1&maximumRecords=1&recordSchema=dc
 238
 239    http://localhost:9999/?version=1.1&operation=searchRetrieve
 240                          &query=dc.title=the
 241
 242    http://localhost:9999/?version=1.1&operation=searchRetrieve
 243                          &query=description=the
 244
 245
 246    relation tests:
 247
 248    http://localhost:9999/?version=1.1&operation=searchRetrieve
 249                       &query=title%3Cthe
 250
 251
 252 SRU scan:
 253
 254    http://localhost:9999/?version=1.1&operation=scan&scanClause=title=a
 255    http://localhost:9999/?version=1.1&operation=scan
 256                       &scanClause=identifier%20eq%20a
 257
 258    Notice: you need to use the 'eq' relation for all @attr 4=3 indexes
 259
 260
 261
 262 SRW explain with CQL index points:
 263
 264    Z> open http://localhost:9999
 265    Z> explain
 266
 267    Notice: when opening a connection using the 'http.//' prefix, yaz-client
 268    uses SRW SOAP connections, and 'form xml' and 'querytype cql' are
 269    implicitely set.
 270
 271
 272 SRW search using implicit server side CQL:
 273
 274    Z> open http://localhost:9999
 275    Z> find identifier eq
 276         "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
 277    Z> find description < the
 278
 279
 280    In SRW connection mode, the follwing fails due to problem in yaz-client:
 281    Z> elements dc
 282    Z> s 1+1
 283
 284
 285 SRW scan using implicit server side CQL:
 286
 287    yaz-client http://localhost:9999
 288    Z> scan title = communication
 289    Z> scan identifier eq a
 290
 291    Notice: you need to use the 'eq' relation for all @attr 4=3 indexes
 292
 293
 294
 295
 296 -->
 297
 298
 299 <!--
 300
 301  <para>
 302   The default retrieval syntax for the client is &acro.usmarc;, and the
 303   default element set is <literal>F</literal> (``full record''). To
 304   try other formats and element sets for the same record, try:
 305  </para>
 306  <para>
 307   <screen>
 308    Z&#62;format sutrs
 309    Z&#62;show 1
 310    Z&#62;format grs-1
 311    Z&#62;show 1
 312    Z&#62;format xml
 313    Z&#62;show 1
 314    Z&#62;elements B
 315    Z&#62;show 1
 316   </screen>
 317  </para>
 318
 319  <note>
 320   <para>You may notice that more fields are returned when your
 321    client requests &acro.sutrs;, &acro.grs1; or &acro.xml; records.
 322    This is normal - not all of the GILS data elements have mappings in
 323    the &acro.usmarc; record format.
 324   </para>
 325  </note>
 326
 327  <para>
 328   If you've made it this far, you know that your installation is
 329   working, but there's a certain amount of voodoo going on - for
 330   example, the mysterious incantations in the
 331   <literal>zebra.cfg</literal> file.  In order to help us understand
 332   these fully, the next chapter will work through a series of
 333   increasingly complex example configurations.
 334  </para>
 335
 336
 337 -->
 338
 339  </sect1>
 340
 341  <sect1 id="tutorial-oai-zebra">
 342   <title>Requesting &acro.oai; records in &zebra; specific formats</title>
 343
 344
 345  </sect1>
 346
 347
 348 </chapter>
 349
 350  <!-- Keep this comment at the end of the file
 351  Local variables:
 352  mode: sgml
 353  sgml-omittag:t
 354  sgml-shorttag:t
 355  sgml-minimize-attributes:nil
 356  sgml-always-quote-attributes:t
 357  sgml-indent-step:1
 358  sgml-indent-data:t
 359  sgml-parent-document: "zebra.xml"
 360  sgml-local-catalogs: nil
 361  sgml-namecase-general:t
 362  End:
 363  -->