doc/tutorial.xml

   1 <chapter id="tutorial">
   2  <!-- $Id: tutorial.xml,v 1.2 2008-02-05 10:15:58 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>.
  23  </para>
  24  <para>
  25     Additional OAI test records can be downloaded by running a shell
  26     script (you may want to abort the script when you have waitet
  27     longer than your coffe brews ..).
  28   <screen>
  29      cd data
  30      ./fetch_OAI_data.sh
  31      cd ../
  32   </screen>
  33  </para>
  34  <para>
  35     To index these &acro.oai; records, type:
  36   <screen>
  37     zebraidx-2.0 -c conf/zebra.cfg init
  38     zebraidx-2.0 -c conf/zebra.cfg update data/oai-caltech.xml
  39     zebraidx-2.0 -c conf/zebra.cfg commit
  40   </screen>
  41    In case you have not installed zebra yet but have compiled the
  42     binaries from this tarball, use the following command form:
  43   <screen>
  44     ../../index/zebraidx -c conf/zebra.cfg this and that
  45   </screen>
  46    On some systems the &zebra; binaries are installed under the
  47    generic names, you need to use  the following command form:
  48   <screen>
  49     zebraidx -c conf/zebra.cfg this and that
  50   </screen>
  51  </para>
  52
  53  <para>
  54   In this command, the word <literal>update</literal> is followed
  55   by the name of a directory: <literal>zebraidx</literal> updates all
  56   files in the hierarchy rooted at that directory. The command option
  57   <literal>-c conf/zebra.cfg</literal> points to the proper
  58   configuration file.
  59  </para>
  60
  61  <para>
  62    You might ask yourself how &acro.xml; content is indexed using &acro.xslt;
  63    stylesheets: to satisfy your curiosity, you might want to run the
  64    indexing transformation on an example debugging &acro.oai; record.
  65    <screen>
  66     xsltproc conf/oai2index.xsl data/debug-record.xml
  67    </screen>
  68     Here you see the &acro.oai; record transformed into the indexing
  69     &acro.xml; format. &zebra; is creating several inverted indexes,
  70     and their name and type are clearly visible in the indexing
  71     &acro.xml; format.
  72  </para>
  73
  74  <para>
  75   If your indexing command was successful, you are now ready to
  76   fire up a server. To start a server on port 9999, type:
  77   <screen>
  78    zebrasrv-2.0 -c conf/zebra.cfg  @:9999
  79   </screen>
  80  </para>
  81
  82  <para>
  83   The &zebra; index that you have just created has a single database
  84   named <literal>Default</literal>.
  85   The database contains  several &acro.oai; records, and the server will
  86   return records in the &acro.xml; format only. The indexing machine
  87   did the splitting into individual records just behind the scenes.
  88  </para>
  89
  90
  91  </sect1>
  92
  93  <sect1 id="tutorial-oai-sru-pqf">
  94   <title>Searching the &acro.oai; database by web service</title>
  95
  96   <para>
  97     &zebra; has a build-in web service, which is close to the
  98     &acro.sru; standard web service. We use it to access our new
  99     database using any   &acro.xml; enabled web browser.
 100     This service is using the  &acro.pqf; query language.
 101     In a later
 102     section we show how to run a fully compliant  &acro.sru; server,
 103     including support for the query language  &acro.cql;
 104    </para>
 105
 106    <para>
 107     Searching and retrieving &acro.xml; records is easy. For example,
 108     you can point your browser to one of the following url's to
 109     search for the term <literal>the</literal>. Just point your
 110     browser at this link:
 111     <ulink url="http://localhost:9999/?version=1.1&amp;operation=searchRetrieve&amp;query=creator=adam">
 112    http://localhost:9999/?version=1.1&amp;operation=searchRetrieve&amp;query=the</ulink>
 113    </para>
 114
 115    <warning>
 116     <para>
 117      These URL's woun't work unless you have indexed the example data
 118      and started an &zebra; server as outlined in the previous section.
 119     </para>
 120    </warning>
 121
 122    <para>
 123     In case we actually want to retrieve one record, we need to alter
 124     our URl to the following
 125    <ulink url="http://localhost:9999/?version=1.1&amp;operation=searchRetrieve&amp;query=the&amp;startRecord=1&amp;maximumRecords=1&amp;recordSchema=dc">
 126    http://localhost:9999/?version=1.1&amp;operation=searchRetrieve&amp;query=the&amp;startRecord=1&amp;maximumRecords=1&amp;recordSchema=dc
 127    </ulink>
 128    </para>
 129
 130    <para>
 131     This way we can page through our result set in chunks of records,
 132     for example, we access the 6th to the 10th record using the URL
 133    <ulink url="http://localhost:9999/?version=1.1&amp;operation=searchRetrieve&amp;query=the&amp;startRecord=6&amp;maximumRecords=5&amp;recordSchema=dc">
 134    http://localhost:9999/?version=1.1&amp;operation=searchRetrieve&amp;query=the&amp;startRecord=6&amp;maximumRecords=5&amp;recordSchema=dc
 135    </ulink>
 136   </para>
 137
 138 <!--
 139    relation tests:
 140
 141     <ulink url="">
 142
 143    http://localhost:9999/?version=1.1&amp;operation=searchRetrieve
 144                       &amp;query=title%3Cthe
 145 -->
 146  </sect1>
 147
 148
 149
 150
 151  <sect1 id="tutorial-oai-sru-present">
 152   <title>Presenting search results in different formats</title>
 153
 154
 155
 156 Z39.50 search:
 157
 158    yaz-client localhost:9999
 159    Z> format xml
 160    Z> querytype prefix
 161    Z> elements oai
 162    Z> find the
 163    Z> show 1+1
 164
 165
 166 Z39.50 presents using presentation stylesheets:
 167
 168    Z> elements dc
 169    Z> show 2+1
 170
 171    Z> elements zebra
 172    Z> show 3+1
 173
 174
 175 Z39.50 buildin Zebra presents (in this configuration only if
 176   started without yaz-frontendserver):
 177
 178    <screen>
 179    Z> elements zebra::meta
 180    Z> show 4+1
 181
 182    Z> elements zebra::meta::sysno
 183    Z> show 5+1
 184
 185    Z> format sutrs
 186    Z> show 5+1
 187    Z> format xml
 188
 189    Z> elements zebra::index
 190    Z> show 6+1
 191
 192    Z> elements zebra::snippet
 193    Z> show 7+1
 194
 195    Z> elements zebra::facet::any:w
 196    Z> show 8+1
 197
 198    Z>  elements zebra::facet::any:w,dc_title:w
 199    Z> show 9+1
 200    </screen>
 201
 202
 203
 204 Z39.50 searches targeted at specific indexes
 205
 206    Z> elements zebra
 207    Z> find @attr 1=oai_identifier @attr 4=3 oai:caltechcstr.library.caltech.edu:4
 208    Z> show 1+1
 209
 210    Z> find @attr 1=oai_datestamp  @attr 4=3 2001-04-20
 211    Z> show 1+1
 212
 213    Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562
 214    Z> show 1+1
 215
 216    Z> find @attr 1=dc_title communication
 217    Z> show 1+1
 218
 219    Z> find @attr 1=dc_identifier @attr 4=3
 220                  http://resolver.caltech.edu/CaltechCSTR:1986.5228-tr-86
 221    Z> show 1+1
 222
 223    etc, etc.
 224
 225    Notice that all indexes defined by 'type="0"' in the
 226    indexing style  sheet must be searched using the '@attr 4=3'
 227    structure attribute instruction.
 228
 229    Notice also that searching and scan on indexes
 230    'dc_contributor',  'dc_language', 'dc_rights', and 'dc_source'
 231    fails, simply because none of the records in this example set
 232    have these fields set, and consequently, these indexes are
 233    _not_ created.
 234
 235
 236  </sect1>
 237
 238
 239
 240   <sect1 id="tutorial-oai-z3950">
 241    <title>Searching the &acro.oai; database by &acro.z3950; protocol</title>
 242
 243
 244    <para>
 245     In this section we repeat the searches and presents we have done so
 246     far using the binary &acro.z3950; protocol, you can use any
 247     &acro.z3950; client.
 248     For instance, you can use the demo command-line client that comes
 249     with &yaz;.
 250    </para>
 251    <para>
 252     Connecting to the server is done by the command
 253   <screen>
 254      yaz-client localhost:9999
 255     </screen>
 256    </para>
 257
 258    <para>
 259     When the client has connected, you can type:
 260     <screen>
 261      Z> format xml
 262      Z> querytype prefix
 263      Z> elements oai
 264      Z> find the
 265      Z> show 1+1
 266     </screen>
 267    </para>
 268
 269    <para>
 270     Z39.50 presents using presentation stylesheets:
 271     <screen>
 272      Z> elements dc
 273      Z> show 2+1
 274
 275      Z> elements zebra
 276      Z> show 3+1
 277     </screen>
 278    </para>
 279
 280    <para>
 281     Z39.50 buildin Zebra presents (in this configuration only if
 282     started without yaz-frontendserver):
 283
 284     <screen>
 285      Z> elements zebra::meta
 286      Z> show 4+1
 287
 288      Z> elements zebra::meta::sysno
 289      Z> show 5+1
 290
 291      Z> format sutrs
 292      Z> show 5+1
 293      Z> format xml
 294
 295      Z> elements zebra::index
 296      Z> show 6+1
 297
 298      Z> elements zebra::snippet
 299      Z> show 7+1
 300
 301      Z> elements zebra::facet::any:w
 302      Z> show 8+1
 303
 304      Z>  elements zebra::facet::any:w,dc_title:w
 305      Z> show 9+1
 306    </screen>
 307    </para>
 308
 309    <para>
 310     Z39.50 searches targeted at specific indexes and boolean
 311     combinations of these can be issued as well.
 312
 313     <srceen>
 314      Z> elements dc
 315      Z> find @attr 1=oai_identifier @attr 4=3 oai:caltechcstr.library.caltech.edu:4
 316      Z> show 1+1
 317
 318      Z> find @attr 1=oai_datestamp  @attr 4=3 2001-04-20
 319      Z> show 1+1
 320
 321      Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562
 322      Z> show 1+1
 323
 324      Z> find @attr 1=dc_title communication
 325      Z> show 1+1
 326
 327      Z> find @attr 1=dc_identifier @attr 4=3
 328      http://resolver.caltech.edu/CaltechCSTR:1986.5228-tr-86
 329      Z> show 1+1
 330     </srceen>
 331    etc, etc.
 332    </para>
 333
 334    <para>
 335    Notice that all indexes defined by 'type="0"' in the
 336    indexing style  sheet must be searched using the '@attr 4=3'
 337    structure attribute instruction.
 338    </para>
 339
 340    <para>
 341    Notice also that searching and scan on indexes
 342    'dc_contributor',  'dc_language', 'dc_rights', and 'dc_source'
 343    might fail, simply because none of the records in the small example set
 344    have these fields set, and consequently, these indexes might not
 345    been created.
 346    </para>
 347
 348  </sect1>
 349
 350
 351
 352  <sect1 id="tutorial-oai-sru-yazfrontend">
 353   <title>Setting up a correct &acro.sru; web service</title>
 354
 355 Or, alternatively, starting the SRU/SRW/Z39.50 server including
 356 PQF and CQL query configuration:
 357
 358    zebrasrv -f yazserver.xml
 359
 360
 361  </sect1>
 362
 363
 364 <!--
 365
 366 Z39.50 presents using presentation stylesheets:
 367
 368    Z> elements dc
 369    Z> show 2+1
 370
 371    Z> elements zebra
 372    Z> show 3+1
 373
 374
 375 Z39.50 buildin Zebra presents (in this configuration only if
 376   started without yaz-frontendserver):
 377
 378    Z> elements zebra::meta
 379    Z> show 4+1
 380
 381    Z> elements zebra::meta::sysno
 382    Z> show 5+1
 383
 384    Z> format sutrs
 385    Z> show 5+1
 386    Z> format xml
 387
 388    Z> elements zebra::index
 389    Z> show 6+1
 390
 391    Z> elements zebra::snippet
 392    Z> show 7+1
 393
 394    Z> elements zebra::facet::any:w
 395    Z> show 8+1
 396
 397    Z>  elements zebra::facet::any:w,dc_title:w
 398    Z> show 9+1
 399
 400
 401
 402 Z39.50 searches targeted at specific indexes
 403
 404    Z> elements zebra
 405    Z> find @attr 1=oai_identifier @attr 4=3 oai:caltechcstr.library.caltech.edu:4
 406    Z> show 1+1
 407
 408    Z> find @attr 1=oai_datestamp  @attr 4=3 2001-04-20
 409    Z> show 1+1
 410
 411    Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562
 412    Z> show 1+1
 413
 414    Z> find @attr 1=dc_title communication
 415    Z> show 1+1
 416
 417    Z> find @attr 1=dc_identifier @attr 4=3
 418                  http://resolver.caltech.edu/CaltechCSTR:1986.5228-tr-86
 419    Z> show 1+1
 420
 421    etc, etc.
 422
 423    Notice that all indexes defined by 'type="0"' in the
 424    indexing style  sheet must be searched using the '@attr 4=3'
 425    structure attribute instruction.
 426
 427    Notice also that searching and scan on indexes
 428    'dc_contributor',  'dc_language', 'dc_rights', and 'dc_source'
 429    fails, simply because none of the records in this example set
 430    have these fields set, and consequently, these indexes are
 431    _not_ created.
 432
 433
 434 XXXXXXXX
 435
 436
 437 Z39.50 scan:
 438
 439    yaz-client localhost:9999
 440    Z> format xml
 441    Z> querytype prefix
 442    Z> scan @attr 1=oai_identifier @attr 4=3 oai
 443    Z> scan @attr 1=oai_datestamp @attr 4=3 1
 444    Z> scan @attr 1=oai_setspec @attr 4=3 2000
 445    Z>
 446    Z> scan @attr 1=dc_title communication
 447    Z> scan @attr 1=dc_identifier @attr 4=3 a
 448
 449    etc, etc,
 450
 451
 452 Z39.50 search using server-side CQL conversion:
 453
 454    Z> format xml
 455    Z> querytype cql
 456    Z> elements dc
 457    Z>
 458    Z> find harry
 459    Z>
 460    Z> find creator = the
 461    Z> find dc.creator = the
 462    Z> find title = the
 463    Z>
 464    Z> find description < the
 465    Z> find title le some
 466    Z> find title ge some
 467    Z> find title > some
 468    Z>
 469    Z> find identifier eq
 470            "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
 471    Z> find relation eq something
 472
 473
 474    etc, etc. Notice that  all indexes defined by 'type="0"' in the
 475    indexing style  sheet must be searched using the 'eq'
 476    relation.
 477
 478    Z> find title <> and
 479
 480    fails as well.  ???
 481
 482
 483 Z39.50 scan using server side CQL conversion:
 484
 485    Unfortunately, this will _never_ work as it is not supported by the
 486    Z39.50 standard.
 487    If you want to use scan using server side CQL conversion, you need to
 488    make an SRW connection using  yaz-client, or a
 489    SRU connection using REST Web Services - any browser will do.
 490
 491
 492 SRU Explain ZeeRex response:
 493
 494    http://localhost:9999/
 495    http://localhost:9999/?version=1.1&operation=explain
 496
 497
 498 SRU Search Retrieve records:
 499
 500    http://localhost:9999/?version=1.1&operation=searchRetrieve
 501                           &query=creator=adam
 502
 503    http://localhost:9999/?version=1.1&operation=searchRetrieve
 504                          &query=date=1978-01-01
 505                          &startRecord=1&maximumRecords=1&recordSchema=dc
 506
 507    http://localhost:9999/?version=1.1&operation=searchRetrieve
 508                          &query=dc.title=the
 509
 510    http://localhost:9999/?version=1.1&operation=searchRetrieve
 511                          &query=description=the
 512
 513
 514    relation tests:
 515
 516    http://localhost:9999/?version=1.1&operation=searchRetrieve
 517                       &query=title%3Cthe
 518
 519
 520 SRU scan:
 521
 522    http://localhost:9999/?version=1.1&operation=scan&scanClause=title=a
 523    http://localhost:9999/?version=1.1&operation=scan
 524                       &scanClause=identifier%20eq%20a
 525
 526    Notice: you need to use the 'eq' relation for all @attr 4=3 indexes
 527
 528
 529
 530 SRW explain with CQL index points:
 531
 532    Z> open http://localhost:9999
 533    Z> explain
 534
 535    Notice: when opening a connection using the 'http.//' prefix, yaz-client
 536    uses SRW SOAP connections, and 'form xml' and 'querytype cql' are
 537    implicitely set.
 538
 539
 540 SRW search using implicit server side CQL:
 541
 542    Z> open http://localhost:9999
 543    Z> find identifier eq
 544         "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
 545    Z> find description < the
 546
 547
 548    In SRW connection mode, the follwing fails due to problem in yaz-client:
 549    Z> elements dc
 550    Z> s 1+1
 551
 552
 553 SRW scan using implicit server side CQL:
 554
 555    yaz-client http://localhost:9999
 556    Z> scan title = communication
 557    Z> scan identifier eq a
 558
 559    Notice: you need to use the 'eq' relation for all @attr 4=3 indexes
 560
 561
 562
 563
 564 -->
 565
 566
 567
 568
 569 </chapter>
 570
 571  <!-- Keep this comment at the end of the file
 572  Local variables:
 573  mode: sgml
 574  sgml-omittag:t
 575  sgml-shorttag:t
 576  sgml-minimize-attributes:nil
 577  sgml-always-quote-attributes:t
 578  sgml-indent-step:1
 579  sgml-indent-data:t
 580  sgml-parent-document: "zebra.xml"
 581  sgml-local-catalogs: nil
 582  sgml-namecase-general:t
 583  End:
 584  -->