<chapter id="tutorial">
- <!-- $Id: tutorial.xml,v 1.3 2008-02-05 12:16:52 marc Exp $ -->
+ <!-- $Id: tutorial.xml,v 1.4 2008-02-07 12:36:35 marc Exp $ -->
<title>Tutorial</title>
<title>Investigating the content of the indexes</title>
<para>
- How works the magic? What is inside the indexes? Why is a certain
+ How doess the magic work? What is inside the indexes? Why is a certain
record foound by a search, and another not?. The answer is in the
- inverterd indexes. You can easily investigat them using the
+ inverterd indexes. You can easily investigate them using the
special &zebra; schema
<literal>zebra::index::fieldname</literal>. In this example you
can see that the <literal>dc_title</literal> index has both word
</sect1>
+ <sect1 id="tutorial-oai-sru-yazfrontend">
+ <title>Setting up a correct &acro.sru; web service</title>
+
+ <para>
+ The &acro.sru; specification mandates that the &acro.cql; query
+ language is supported and properly configure. Also, the server
+ needs to be able to emmit a proper &acro.explain; &acro.xml;
+ record, which is used to determine the capabilities of the
+ specific server instance.
+ </para>
+
+ <para>
+ In this example configuration we expoit the similarities between
+ the &acro.explain; record and the &acro.cql; query language
+ configuration, we generate the later from the former using an
+ &acro.xslt; transformation.
+ <screen>
+ xsltproc conf/explain2cqlpqftxt.xsl conf/explain.xml > conf/cql2pqf.txt
+ </screen>
+ </para>
+
+ <para>
+ The we are all set to start the &acro.sru;/acro.z3950; server including
+ &acro.pqf; and &acro.cql; query configuration. It uses the &yaz; frontend
+ server configuration - just type
+ <screen>
+ zebrasrv -f conf/yazserver.xml
+ </screen>
+ </para>
+
+ <para>
+ First, we'd like to be sure that we can see the &acro.explain;
+ &acro.xml; response correctly. You might use either of these equivalent
+ requests:
+ <ulink
+ url="http://localhost:9999">http://localhost:9999
+ </ulink>
+ <ulink
+ url="http://localhost:9999/?version=1.1&operation=explain">
+ http://localhost:9999/?version=1.1&operation=explain
+ </ulink>
+
+ </para>
+
+ <para>
+ Now we can issue true &acro.sru; requests. For example,
+ <literal>dc.title=the
+ and dc.description=fish</literal> results in the following page
+ <ulink
+ url="http://localhost:9999/?version=1.1&operation=searchRetrieve&query=dc.title=the
+ and dc.description=fish
+ &startRecord=1&maximumRecords=1&recordSchema=dc">
+ http://localhost:9999/?version=1.1&operation=searchRetrieve&query=dc.title=the
+ and dc.description=fish &startRecord=1&maximumRecords=1&recordSchema=dc
+ </ulink>
+ </para>
+
+ <para>
+ Scan of indexes is a part of the &acro.sru; server business. For example,
+ scanning the <literal>dc.title</literal> index gives us an idea
+ what search terms are found there
+ <ulink
+ url="http://localhost:9999/?version=1.1&operation=scan&scanClause=dc.title=fish">
+ http://localhost:9999/?version=1.1&operation=scan&scanClause=dc.title=fish
+ </ulink>,
+ whereas
+ <ulink
+ url="http://localhost:9999/?version=1.1&operation=scan&scanClause=dc.identifier=fish">
+http://localhost:9999/?version=1.1&operation=scan&scanClause=dc.identifier=fish
+ </ulink>
+ accesses the indexed indentifiers.
+ </para>
+
+ <para>
+ In addition, all &zebra; internal special elemen sets or record
+ schema's of the form
+ <literal>zebra::</literal> just work right out of the box
+ <ulink
+ url="http://localhost:9999/?version=1.1&operation=searchRetrieve&query=dc.title=the
+ and dc.description=fish
+ &startRecord=1&maximumRecords=1&recordSchema=zebra::snippet">
+ http://localhost:9999/?version=1.1&operation=searchRetrieve&query=dc.title=the
+ and dc.description=fish &startRecord=1&maximumRecords=1&recordSchema=zebra::snippet
+ </ulink>
+ </para>
+
+
+
+ </sect1>
+
<sect1 id="tutorial-oai-z3950">
<title>Searching the &acro.oai; database by &acro.z3950; protocol</title>
-
<para>
In this section we repeat the searches and presents we have done so
far using the binary &acro.z3950; protocol, you can use any
</para>
<para>
- Z39.50 presents using presentation stylesheets:
+ &acro.z3950; presents using presentation stylesheets:
<screen>
Z> elements dc
Z> show 2+1
</para>
<para>
- Z39.50 buildin Zebra presents (in this configuration only if
+ &acro.z3950; buildin Zebra presents (in this configuration only if
started without yaz-frontendserver):
<screen>
Z> show 7+1
Z> elements zebra::facet::any:w
- Z> show 8+1
+ Z> show 1+1
- Z> elements zebra::facet::any:w,dc_title:w
- Z> show 9+1
+ Z> elements zebra::facet::dc_publisher:p,dc_title:p
+ Z> show 1+1
</screen>
</para>
<para>
- Z39.50 searches targeted at specific indexes and boolean
+ &acro.z3950; searches targeted at specific indexes and boolean
combinations of these can be issued as well.
<screen>
Z> find @attr 1=oai_identifier @attr 4=3 oai:caltechcstr.library.caltech.edu:4
Z> show 1+1
- Z> find @attr 1=oai_datestamp @attr 4=3 2001-04-20
+ Z> find @attr 1=oai_datestamp @attr 4=3 2001-04-20
Z> show 1+1
Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562
etc, etc.
</para>
- <para>
- Notice that all indexes defined by 'type="0"' in the
- indexing style sheet must be searched using the '@attr 4=3'
- structure attribute instruction.
- </para>
-
<para>
- Notice also that searching and scan on indexes
- 'dc_contributor', 'dc_language', 'dc_rights', and 'dc_source'
- might fail, simply because none of the records in the small example set
- have these fields set, and consequently, these indexes might not
- been created.
+ &acro.z3950; scan:
+ <screen>
+ yaz-client localhost:9999
+ Z> format xml
+ Z> querytype prefix
+ Z> scan @attr 1=oai_identifier @attr 4=3 oai
+ Z> scan @attr 1=oai_datestamp @attr 4=3 1
+ Z> scan @attr 1=oai_setspec @attr 4=3 2000
+ Z>
+ Z> scan @attr 1=dc_title communication
+ Z> scan @attr 1=dc_identifier @attr 4=3 a
+ </screen>
</para>
-
- </sect1>
-
-
-
- <sect1 id="tutorial-oai-sru-yazfrontend">
- <title>Setting up a correct &acro.sru; web service</title>
<para>
- Or, alternatively, starting the SRU/SRW/Z39.50 server including
- PQF and CQL query configuration:
+ &acro.z3950; search using server-side CQL conversion:
<screen>
- zebrasrv -f yazserver.xml
- </screen>
- </para>
-
- </sect1>
-
-
-<!--
-
-Z39.50 presents using presentation stylesheets:
-
- Z> elements dc
- Z> show 2+1
-
- Z> elements zebra
- Z> show 3+1
-
-
-Z39.50 buildin Zebra presents (in this configuration only if
- started without yaz-frontendserver):
-
- Z> elements zebra::meta
- Z> show 4+1
-
- Z> elements zebra::meta::sysno
- Z> show 5+1
-
- Z> format sutrs
- Z> show 5+1
- Z> format xml
-
- Z> elements zebra::index
- Z> show 6+1
-
- Z> elements zebra::snippet
- Z> show 7+1
-
- Z> elements zebra::facet::any:w
- Z> show 8+1
-
- Z> elements zebra::facet::any:w,dc_title:w
- Z> show 9+1
-
-
-
-Z39.50 searches targeted at specific indexes
-
- Z> elements zebra
- Z> find @attr 1=oai_identifier @attr 4=3 oai:caltechcstr.library.caltech.edu:4
- Z> show 1+1
-
- Z> find @attr 1=oai_datestamp @attr 4=3 2001-04-20
- Z> show 1+1
-
- Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562
- Z> show 1+1
-
- Z> find @attr 1=dc_title communication
- Z> show 1+1
-
- Z> find @attr 1=dc_identifier @attr 4=3
- http://resolver.caltech.edu/CaltechCSTR:1986.5228-tr-86
- Z> show 1+1
-
- etc, etc.
-
- Notice that all indexes defined by 'type="0"' in the
- indexing style sheet must be searched using the '@attr 4=3'
- structure attribute instruction.
-
- Notice also that searching and scan on indexes
- 'dc_contributor', 'dc_language', 'dc_rights', and 'dc_source'
- fails, simply because none of the records in this example set
- have these fields set, and consequently, these indexes are
- _not_ created.
-
-
-XXXXXXXX
-
-
-Z39.50 scan:
-
- yaz-client localhost:9999
- Z> format xml
- Z> querytype prefix
- Z> scan @attr 1=oai_identifier @attr 4=3 oai
- Z> scan @attr 1=oai_datestamp @attr 4=3 1
- Z> scan @attr 1=oai_setspec @attr 4=3 2000
- Z>
- Z> scan @attr 1=dc_title communication
- Z> scan @attr 1=dc_identifier @attr 4=3 a
-
- etc, etc,
-
-
-Z39.50 search using server-side CQL conversion:
-
Z> format xml
Z> querytype cql
Z> elements dc
Z>
Z> find harry
Z>
- Z> find creator = the
Z> find dc.creator = the
- Z> find title = the
+ Z> find dc.creator = the
+ Z> find dc.title = the
Z>
- Z> find description < the
- Z> find title le some
- Z> find title ge some
- Z> find title > some
+ Z> find dc.description < the
+ Z> find dc.title > some
Z>
- Z> find identifier eq
- "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
- Z> find relation eq something
-
+ Z> find dc.identifier="http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
+ Z> find dc.relation = something
+ </screen>
+ </para>
+ <!--
etc, etc. Notice that all indexes defined by 'type="0"' in the
indexing style sheet must be searched using the 'eq'
relation.
-
+
Z> find title <> and
fails as well. ???
+ -->
-
-Z39.50 scan using server side CQL conversion:
-
- Unfortunately, this will _never_ work as it is not supported by the
- Z39.50 standard.
+ <tip>
+ <para>
+ &acro.z3950; scan using server side CQL conversion -
+ unfortunately, this will _never_ work as it is not supported by the
+ &acro.z3950; standard.
If you want to use scan using server side CQL conversion, you need to
make an SRW connection using yaz-client, or a
SRU connection using REST Web Services - any browser will do.
+ </para>
+ </tip>
+ <tip>
+ <para>
+ All indexes defined by 'type="0"' in the
+ indexing style sheet must be searched using the '@attr 4=3'
+ structure attribute instruction.
+ </para>
+ </tip>
-SRU Explain ZeeRex response:
-
- http://localhost:9999/
- http://localhost:9999/?version=1.1&operation=explain
-
-
-SRU Search Retrieve records:
-
- http://localhost:9999/?version=1.1&operation=searchRetrieve
- &x-pquery=creator=adam
-
- http://localhost:9999/?version=1.1&operation=searchRetrieve
- &x-pquery=date=1978-01-01
- &startRecord=1&maximumRecords=1&recordSchema=dc
-
- http://localhost:9999/?version=1.1&operation=searchRetrieve
- &x-pquery=dc.title=the
-
- http://localhost:9999/?version=1.1&operation=searchRetrieve
- &x-pquery=description=the
-
-
- relation tests:
-
- http://localhost:9999/?version=1.1&operation=searchRetrieve
- &x-pquery=title%3Cthe
-
-
-SRU scan:
-
- http://localhost:9999/?version=1.1&operation=scan&scanClause=title=a
- http://localhost:9999/?version=1.1&operation=scan
- &scanClause=identifier%20eq%20a
-
- Notice: you need to use the 'eq' relation for all @attr 4=3 indexes
-
-
-
-SRW explain with CQL index points:
-
- Z> open http://localhost:9999
- Z> explain
-
- Notice: when opening a connection using the 'http.//' prefix, yaz-client
- uses SRW SOAP connections, and 'form xml' and 'querytype cql' are
- implicitely set.
-
-
-SRW search using implicit server side CQL:
-
- Z> open http://localhost:9999
- Z> find identifier eq
- "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
- Z> find description < the
-
-
- In SRW connection mode, the follwing fails due to problem in yaz-client:
- Z> elements dc
- Z> s 1+1
-
-
-SRW scan using implicit server side CQL:
-
- yaz-client http://localhost:9999
- Z> scan title = communication
- Z> scan identifier eq a
-
- Notice: you need to use the 'eq' relation for all @attr 4=3 indexes
-
+ <para>
+ Notice that searching and scan on indexes
+ <literal>dc_contributor</literal>, <literal>dc_language</literal>,
+ <literal>dc_rights</literal>, and <literal>dc_source</literal>
+ might fail, simply because none of the records in the small example set
+ have these fields set, and consequently, these indexes might not
+ been created.
+ </para>
+
+ </sect1>
--->
projects / idzebra-moved-to-github.git / commitdiff