X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fadministration.xml;h=773edfda23ef3a233529135ba72cb8c6beff4a6d;hb=3fbdef96a1c730eb52d1ffbd7c90143fb7168f25;hp=34f938c44596dd9ef654709f6804f44c7d674b0a;hpb=94ec3a0012667d2c67e4bdba2a8255e863f88925;p=idzebra-moved-to-github.git diff --git a/doc/administration.xml b/doc/administration.xml index 34f938c..773edfd 100644 --- a/doc/administration.xml +++ b/doc/administration.xml @@ -1,5 +1,5 @@ - + Administrating Zebra Those are in the zebra config file enabled by a directive like (use only one of these a time!): - rank: rank-1 # default - rank: rank-static # dummy - rank: zvrank # TDF-IDF like + rank: rank-1 # default TDF-IDF like + rank: rank-static # dummy do-nothing + rank: zvrank # configurable, experimental TDF-IDF like Notice that the rank-1 and zvrank do not use the static rank @@ -1020,7 +1052,157 @@ function, which is left as an exercise for the reader. - + + + + Invoking dynamic ranking is done in query time (this is why we + call it 'dynamic ranking' in the first place ..). One has to add + the Bib-1 relation attribute with + value "relevance" to the PQF query (that is, @attr + 2=102, see also + + The BIB-1 Attribute Set Semantics). + To find all articles with the word 'Eoraptor' in + the title, and present them relevance ranked, one issues the PQF query: + + Z> f @attr 2=102 @attr 1=4 Eoraptor + + + + + The default rank-1 ranking module implements a + TF-IDF (Term Frequecy over Inverse Document Frequency) like algorithm. + + + + + Notice that dynamic ranking is not compatible + with estimated hit sizes, as all documents in + a hit set must be acessed to compute the correct placing in a + ranking sorted list. Therefore the use attribute setting + @attr 2=102 clashes with + @attr 9=. + + + + + It is possible to apply dynamic ranking on parts of the PQF query + allone: + + Z> f @and @attr 2=102 @attr 1=1010 Utah @attr 1=1018 Springer + + searches for all documents which have the term 'Utah' on the + body of text, and which have the term 'Springer' in the publisher + field, and sort them in the order of the relvance ranking made on + the body of text index only. + + + Rank weight is a way to pass a value to a ranking algorithm - so that + one APT has one value - while another as a different one. For + example, we can + search for 'utah' in use attribute set 'title' with weight 30, as + well as in use attribute set 'any' with weight 20. + + Z> f @attr 2=102 @or @attr 9=30 @attr 1=4 utah @attr 9=20 utah + + + + + The rank weight feature is experimental. It may change in future + releases of zebra, and is not production mature. + + + + + Notice that dynamic ranking can be enabled in + sever side CQL query expansion by adding @attr + 2=102 to the CQL config file. For example + + relationModifier.relevant = 2=102 + + invokes dynamik ranking each time a CQL query of the form + + Z> querytype cql + Z> f alvis.text =/relevant house + + is issued. Dynamic ranking can be enabled on specific CQL indexes + by (for example) setting + + index.alvis.text = 1=text 2=102 + + which then invokes dynamik ranking each time a CQL query of the form + + Z> querytype cql + Z> f alvis.text = house + + is issued. + + + + + + + Sorting + + Sorting is enabled in the configuration of record indexing. For + example, to enable sorting according to the BIB-1 + Date/time-added-to-db field, one could add the line + + xelm /*/@created Date/time-added-to-db:s + + to any .abs record indexing config file, or + similarily, one could add an indexing element of the form + + + + ]]> + to any alvis indexing rule. + + + To trigger a sorting on a pre-defined sorting index of type + s, we can issue a sort with BIB-1 + embedded sort attribute set 7. + The embedded sort is a way to specify sort within a query - thus + removing the need to send a Z39.50 Sort + Request separately. + + + The value after attribute type 7 is + 1 (=ascending), or 2 + (=descending). + The attributes+term (APT) node is separate from the rest of the + PQF query, and must be @or'ed. + The term associated with this attribute is the sorting level, + where + 0 specifies the primary sort key, + 1 the secondary sort key, and so on. + + For example, a search for water, sort by title (ascending), + is expressed by the PQF query + + Z> f @or @attr 1=1016 water @attr 7=1 @attr 1=4 0 + + whereas a search for water, sort by title ascending, + then date descending would be + + Z> f @or @or @attr 1=1016 water @attr 7=1 @attr 1=4 0 @attr 7=2 @attr 1=30 1 + + + + Notice the fundamental differences between dynamic + ranking and sorting: there can only + be one ranking function defined and configured, but there can be + specified multiple sorting indexes dynamically at search + time. Ranking does not need to use specific indexes, which means, + dynamic ranking can be enabled and disabled without + re-indexing. On the other hand, sorting indexes need to be + defined before indexing. + + + + + @@ -1120,10 +1302,139 @@ after each update session in order write your changes from the shadow to the life register space. + + Extended services are also available from the YAZ client layer. An + example of an YAZ-PHP extended service transaction is given here: + + A fine specimen of a record'; - + $options = array('action' => 'recordInsert', + 'syntax' => 'xml', + 'record' => $record, + 'databaseName' => 'mydatabase' + ); + + yaz_es($yaz, 'update', $options); + yaz_es($yaz, 'commit', array()); + yaz_wait(); + + if ($error = yaz_error($yaz)) + echo "$error"; + ]]> + + The action parameter can be any of + recordInsert (will fail if the record already exists), + recordReplace (will fail if the record does not exist), + recordDelete (will fail if the record does not + exist), and + specialUpdate (will insert or update the record + as needed). + + + If a record is inserted + using the action recordInsert + one can specify the optional + recordIdOpaque parameter, which is a + client-supplied, opaque record identifier. This identifier will + replace zebra's own automagic identifier generation. + + + When using the action recordReplace or + recordDelete, one must specify the additional + recordIdNumber parameter, which must be an + existing Zebra internal system ID number. When retrieving existing + records, the ID number is returned in the field + /*/id:idzebra/localnumber in the namespace + xmlns:id="http://www.indexdata.dk/zebra/", + where it can be picked up for later record updates or deletes. + + + + YAZ Frontend Virtual Hosts + + zebrasrv uses the YAZ server frontend and does + support multiple virtual servers behind multiple listening sockets. + + &zebrasrv-virtual; + + + Section "Virtual Hosts" in the YAZ manual. + http://www.indexdata.dk/yaz/doc/server.vhosts.tkl + + + + + + Server Side CQL to PQF Query Translation + + Using the + <cql2rpn>l2rpn.txt</cql2rpn> + YAZ Frontend Virtual + Hosts option, one can configure + the YAZ Frontend CQL-to-PQF + converter, specifying the interpretation of various + CQL + indexes, relations, etc. in terms of Type-1 query attributes. + + + + For example, using server-side CQL-to-PQF conversion, one might + query a zebra server like this: + + querytype cql + Z> find text=(plant and soil) + ]]> + + and - if properly configured - even static relevance ranking can + be performed using CQL query syntax: + + find text = /relevant (plant and soil) + ]]> + + + + + By the way, the same configuration can be used to + search using client-side CQL-to-PQF conversion: + (the only difference is querytype cql2rpn + instead of + querytype cql, and the call specifying a local + conversion file) + + querytype cql2rpn + Z> find text=(plant and soil) + ]]> + + + + + Exhaustive information can be found in the + Section "Specification of CQL to RPN mappings" in the YAZ manual. + + http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map, + and shall therefore not be repeated here. + + + + +