32. Zebra indexing software

Auteur Marc Jeurissen
Aanmaak 7 sept 2007
Oud BVV nr 2142

32.1. Abstract

De Zebra indexing software is een qua opzet vrij ingewikkeld pakket dat indexen aanmaakt die via Z39.50 en SRU/SRW kunnen geraadpleegd worden. De documentatie is niet altijd even duidelijk, daarom worden hier een aantal ervaringspunten op een rijtje gezet. Tevens worden een aantal specifieke punten besproken die van pas komen in de opzet en installatie in het kader van de explorator toolcat-applicatie.

Er is een apart qtech project /explorator/zebra waarin een aantal configuratiefiles staan die hieronder verduidelijkt worden.

32.2. Enkele definities

register
Zebra-indexen worden registers genoemd. Alle register-files staan samen in 1 directory die wordt gedefinieerd in de zebra.cfg configuratiefile. Binnen 1 register kunnen meerdere index-databases gedefinieerd worden.
group

Binnen een zebra.cfg configuratiefile zijn een aantal parameters overkoepelend, maar zijn er ook parameters die georganiseerd kunnen worden in groups: recordType, recordId, database, storeKeys, storeData.

In explorator komt elke indexer overeen met een nieuwe group.

database

Dit is de naam van de database waarin de indexen geplaatst worden. In 1 register kunnen meerdere databases voorkomen. De naam van de database moet opgegeven worden bij een Z39.50 of SRU opzoeking.

In explorator komt elke indexnaam die in een indexer opgegeven wordt, overeen met een nieuwe database.

identifier
Dit is geen term van Zebra zelf, maar van explorator. Indexers die met dezelfde identifier werken maken gebruik van dezelfde zebra.cfg configuratiefile en stockeren hun indexen in eenzelfde register maar mogelijk in verschillende index-databases.
record model
Zebra kan met verschillende record modellen werken. Het nieuwste en meest handige om op te zetten is het DOM XML Record model dat dan ook door explorator gebruikt wordt. Voor een overzicht van de andere modellen, zie de Zebra documentatie.

32.3. Zebra configuratiefile

De Zebra configuratiefile, met meestal als naam zebra.cfg, wordt gelezen door zowel de indexeringssoftware (zebraidx), als de retrieval server (zebrasrv).

/explorator/zebra/zebra_default.cfg is de configuratiefile die explorator gebruikt voor identifier default. Als men een andere identifier wil introduceren, moet dus ook een andere /explorator/zebra/zebra_identifier.cfg aangemaakt worden. Deze file bevat de overkoepelende parameters, maar de group parameters worden bij installatie van het project toegevoegd vanuit de meta-informatie van de explorator indexers. De installatie plaatst de file in r4_explorator_process_dir/zebra/config/identifier/zebra.cfg.

De details van de verschillende parameters zijn te vinden in de Zebra documentatie. Enkele toelichtingen:

profilePath
Wordt in explorator samengesteld uit de working directory r4_explorator_process_dir/zebra/config/identifier en de directory waar de configuratiefiles van Zebra bij installatie van het pakket geplaatst worden. Deze directory staat in Delphi waarde r4_zebra_profilepath, gedefinieerd door /explorator/zebra/release.py.
modulePath
Wordt in explorator gedefinieerd door Delphi waarde r4_zebra_modulepath.
recordType

Een group parameter die geplaatst wordt door de install procedure van /explorator/zebra of bij een run van een explorator indexer en waarvan de waarde afkomstig is uit de meta-informatie van die indexer.

Deze parameter bestaat uit 2 delen dom.xmlfile waarbij het eerste deel verwijst naar het DOM XML record model en het tweede deel de naam is van de XML-file die de definitie van de verschillende pipelines bevat. Het is deze XML-file die in de meta-informatie van de explorator indexer ingevuld moet worden.

recordId

Een group parameter die geplaatst wordt door de install procedure van /explorator/zebra of bij een run van een explorator indexer en waarvan de waarde afkomstig is uit de meta-informatie van die indexer.

Deze parameter definieert de unieke recordidentificatie waarmee records door Zebra kunnen teruggevonden worden voor een update of delete actie. Zie ook de Zebra documentatie.

Explorator gebruikt de volgende syntax: $type (bib1,Local-number), verwijzend naar bib-1 use attribute Local-number. Deze attributen zijn terug te vinden in /explorator/zebra/bib1.att en komen overeen met de bib-1 attributen set van Z39.50. Concreet betekent dit dat, als de record-identifier bijvoorbeeld staat in het MARXML controlfield 001, de xslt stylesheet die de indexing pipeline verzorgt (dom-cat.xsl zoals gedefinieerd in dom-cat.xml) er voor moet zorgen dat de waarde van dit veld terecht komt in een Zebra-index met als naam local-number.

storeKeys
Wordt door explorator altijd op 1 gezet omdat het type recordId dat gebruikt wordt, dit vereist.
storeData

In het DOM XML record model heeft deze parameter geen betekenis! Niet terug te vinden in de documentatie, maar vernomen via de Zebra userlist.

For the DOM XML filter, the original record is always stored within Zebra due to the streamed indexing and the fact that we don’t know at which byte offset in the file it occurs. This is the nature of Libxml2 reader and Libxml2 in general, AFIAK. If anyone know how to get it to return the location of some node from the original input, let me know. In short, for this filter setting storeData to 0 has no effect.

32.4. DOM XML filter pipeline configuratie

De details van de pipelines zijn te vinden in de Zebra documentatie.

Zoals vermeld bij de configuratiefile worden de pipelines gedefinieerd in een XML-file die bij de recordType parameter staat. /explorator/zebra/dom-cat.xml is zo’n recordType file. Wil men een andere pipeline configuratie, dan moet een nieuwe XML-file gemaakt worden in /explorator/zebra en dus ook een nieuwe zebra_identifier.cfg die met deze configuratie werkt.

Het name attribuut dat bij het retrieve element staat, komt overeen met de Z39.50 elementSetName en het SRU recordSchema en moet als dusdanig ook gespecificeerd worden bij een zoekactie. Elk van deze retrieves moet een xslt-stylesheet definieren en moet ook gespecificeerd worden in de YAZ frontend om geconsulteerd te kunnen worden.

32.5. XSLT stylesheets

In /explorator/zebra staat initieel 1 xsl-file die de indexering van een MARCXML record definieert, dom-cat.xsl. Wil men voor een bepaalde indexer een andere indexering, dan moet een nieuwe xsl-file aangemaakt worden in dit qtech project en gespecificeerd in de meta-informatie van de indexer.

Conform met de retrieve elementen in de pipeline configuratiefile moeten xsl-files gemaakt worden die de opgevraagde records in een bepaald formaat teruggeven. Inititieel staan in /explorator/zebra:

  • id.xsl die het MARCXML record als dusdanig teruggeeft,
  • MARC21slim2MODS.xsl die omzet naar mods,
  • MARC21slim2SRWDC.xsl die Dublin Core genereert.

Nog andere xslt-stylesheets zijn te vinden bij Library of Congress.

Voor verdere details zie de Zebra documentatie.

32.6. YAZ frontend

De Zebra-server kan opgestart worden met een YAZ frontend-file waarin de CQL naar RPN mapping gedefinieerd wordt, nodig voor toegankelijkheid van de Zebra-indexen via SRU/SRW, evenals de verschillende retrieval methoden voor record conversie en mogelijke virtuele hosts.

Het syntax attribuut van het retrieval element duidt op de structuur waarin de opgevraagde records moeten gepresenteerd worden. In Z39.50 komt dit overeen met de preferredRecordSyntax parameter. In het DOM record model stockeert en levert Zebra XML records. Wil men bijvoorbeeld marc21 binaire records aangeleverd krijgen, dan kan de ingebouwde marc conversietool opgegeven worden in het backend element.

Zie voor details de Zebra documentatie.

Eén en ander staat ook uitgewerkt in /explorator/zebra/yazsrv_default.cfg, de frontend file die explorator gebruikt voor identifier default. Als men een andere identifier wil introduceren, moet dus ook een andere /explorator/zebra/yazsrv_identifier.cfg aangemaakt worden. De installatie plaatst de file in r4_explorator_process_dir/zebra/config/identifier/yazsrv.cfg.

Het name attribuut komt overeen met de Z39.50 elementSetName en het SRU recordSchema en moet ook in de pipeline configuratie voorkomen.

32.7. CQL naar RPN mapping

Voor een overzicht van het query model zie de Zebra documentatie.

De RPN/PQF queries van Z39.50 worden intern door Zebra ondersteund, maar dit is niet het geval voor de CQL queries van SRU. Daarvoor is een translatiefile nodig die in de frontend-file gespecificeerd wordt.

/explorator/zebra/cqlrpn.cfg is zo’n translatiefile. Daarin staan onder andere de indextags die in de SRU zoekstring kunnen gebruikt worden.

Wil men een andere translatiefile, dan moet deze aangemaakt worden in /explorator/zebra en kenbaar gemaakt in de frontend-file.

De specificaties van de CQL naar RPN mappings zijn terug te vinden in de Zebra documentatie. De syntax van zo’n mapping is: CQL syntax = RPN attribute type = RPN attribute nr. De RPN attributen en attribuut types zijn hier opgesomd.

32.8. Indexrules

De regels voor indexering en gebruikte karakterset staan opgesomd in default.idx, waarvan een standaard versie meegeleverd wordt met de Zebra installatie en terecht komt in r4_zebra_modulepath.

/explorator/zebra/default_default.idx verwijst naar een UTF-8 karaktermap (/explorator/zebra/string.utf8.chr) in plaats van de standaard ascii karaktermap. Wil men een andere default.idx dan moet een file /explorator/zebra/default_identifier.idx aangemaakt worden en moet de indexer die hiervan gebruik wil maken verwijzen naar de nieuwe identifier.

Bij installatie van het qtech project wordt de file geplaatst in r4_explorator_process_dir/zebra/config/identifier/default.idx.

32.9. Zebra indexer

Aanmaak van Zebra indexen wordt opgestart met het commando zebraidx en de nodige parameters. explorator -index indexer voert volgende commando’s uit indien de indexer ingesteld is voor Zebra-indexen:

  • indien geen update modifier meegegeven: zebraidx -c zebra.cfg drop databasename
  • zebraidx -g indexer -c zebra.cfg update databasename path
  • indien gewerkt wordt met shadow indexen: zebraidx -c zebra.cfg commit

32.10. Zebra server

Om de Zebra indexen te kunnen raadplegen moet een server opgestart worden met het commando zebrasrv -f yazsrv.cfg *hostname*:*tcp port [210]*. Het qtech project /explorator/zebra bevat een shell script zebrasrv_default.sh voor identifier default die bij installatie geplaatst wordt in r4_zebra_processdir/config/default/zebrasrv.sh en bijvoorbeeld in procman kan gebruikt worden om de server op te starten.

De server werkt in principe met dezelfde zebra.cfg als de indexer en is dus ook identifier afhankelijk.

Voor opzet van de Zebra omgeving in Anet context, zie msg5371 in Issue 1319: Rel. 3.60: Regelwerk lvd en Z39.50