X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fserver.xml;h=4fa607b6d859480b0ed9745fbd588c66bf4254eb;hb=95bb55fadc3ff69e78e6a61b2096f1326979424b;hp=83a5e3c626fd17b216e8fedb7f4027eb0184274b;hpb=b367b4068098c28aa284c447edf42ba2c8d7c42b;p=idzebra-moved-to-github.git diff --git a/doc/server.xml b/doc/server.xml index 83a5e3c..4fa607b 100644 --- a/doc/server.xml +++ b/doc/server.xml @@ -1,5 +1,5 @@ - + The Z39.50 Server @@ -16,7 +16,7 @@ zebrasrv manpage --> - DESCRIPTION + Description Zebra is a high-performance, general-purpose structured text indexing and retrieval engine. It reads structured records in a variety of input formats (eg. email, XML, MARC) and allows access to them through exact @@ -36,12 +36,12 @@ - SYNOPSIS + Synopsis &zebrasrv-synopsis; - OPTIONS + Options The options for zebrasrv are the same @@ -52,19 +52,13 @@ &zebrasrv-options; - VIRTUAL HOSTS - - zebrasrv uses the YAZ server frontend and does - support multiple virtual servers behind multiple listening sockets. - - &zebrasrv-virtual; - - FILES + + Files zebra.cfg - SEE ALSO + See Also zebraidx @@ -76,18 +70,6 @@ - Section "The Z39.50 Server" in the Zebra manual. - http://www.indexdata.dk/zebra/doc/server.tkl - - - Section "Virtual Hosts" in the YAZ manual. - http://www.indexdata.dk/yaz/doc/server.vhosts.tkl - - - Section "Specification of CQL to RPN mappings" in the YAZ manual. - http://www.indexdata.dk/yaz/doc/tools.tkl#tools.cql.map - - The Zebra software is Copyright Index Data http://www.indexdata.dk and distributed under the @@ -497,8 +479,8 @@ - - + + Present @@ -552,6 +534,132 @@ timeout. + + + Explain + + Zebra maintains a "classic" + Explain database + on the side. + This database is called IR-Explain-1 and can be + searched using the attribute set exp-1. + + + The records in the explain database are of type + grs.sgml and can be retrieved as + SUTRS, XML, + GRS-1 and ASN.1 Explain. + + + Classic Explain only defines retrieaval of Explain information + via ASN.1. Pratically no Z39.50 clients supports this. Fortunately + they don't have to - since Zebra allows retrieval of this information + in the other formats. + + + The root element for the Explain grs.sgml records is + explain, thus + explain.abs is used for indexing. + + + + Zebra must be able to locate + explain.abs in order to index the Explain + records properly. Zebra will work without it but the information + will not be searchable. + + + + The following Explain categories are supported: + CategoryList, TargetInfo, + DatabaseInfo, AttributeDetails. + + + The following Explain search atributes are supported: + ExplainCategory (@attr 1=1), + DatabaseName (@attr 1=3), + DateAdded (@attr 1=9), + DateChanged(@ayyt 1=10). + See tab/explain.att for more information. + + + + Example searches with yaz-client + + + + List supported categories to find out which explain commands are + supported: + + Z> base IR-Explain-1 + Z> @attr exp1 1=1 categorylist + Z> form sutrs + Z> show 1+2 + + + + + Get target info, that is, investigate which databases exist at + this server endpoint: + + Z> base IR-Explain-1 + Z> @attr exp1 1=1 targetinfo + Z> form xml + Z> show 1+1 + Z> form grs-1 + Z> show 1+1 + Z> form sutrs + Z> show 1+1 + + + + + List all supported databases, the number of hits + is the number of databases found, which most commonly are the + following two: + the Default and the + IR-Explain-1 databases. + + Z> base IR-Explain-1 + Z> f @attr exp1 1=1 databaseinfo + Z> form sutrs + Z> show 1+2 + + + + + Get database info record for database Default. + + Z> base IR-Explain-1 + Z> @and @attr exp1 1=1 databaseinfo @attr exp1 1=3 Default + + Identical query with explicitly specified attribute set: + + Z> base IR-Explain-1 + Z> @attrset exp1 @and @attr 1=1 databaseinfo @attr 1=3 Default + + + + + Get attribute details record for database + Default. + This query is very useful to study the internal Zebra indexes. + If records have been indexed using the alvis + XSLT filter, the string representation names of the known indexes can be + found. + + Z> base IR-Explain-1 + Z> @and @attr exp1 1=1 attributedetails @attr exp1 1=3 Default + + Identical query with explicitly specified attribute set: + + Z> base IR-Explain-1 + Z> @attrset exp1 @and @attr 1=1 attributedetails @attr 1=3 Default + + + + + @@ -627,11 +735,11 @@ browser to: - http://localhost:9999/Default?version=1.1& - operation=searchRetrieve& - x-pquery=mineral& - startRecord=1& - maximumRecords=1 + http://localhost:9999/Default?version=1.1 + &operation=searchRetrieve + &x-pquery=mineral + &startRecord=1 + &maximumRecords=1 This will display the XML-formatted SRU response that includes the @@ -683,6 +791,17 @@ various CQL indexes, relations, etc. are translated into Type-1 queries. + + A zebra server running with such a configuration can then be + queried using proper, conformant SRU URLs with CQL queries: + + + http://localhost:9999/Default?version=1.1 + &operation=searchRetrieve + &query=title=utah and description=epicent* + &startRecord=1 + &maximumRecords=1 + @@ -708,24 +827,110 @@ is with some shame, then, that we admit that Zebra also supports an additional query language, our own Prefix Query Format (PQF, ). -x-pquery - - + A PQF query is submitted by using the extension parameter + x-pquery, + in which case the + query + parameter must be omitted, which makes the request not valid SRU. + Please don't do this. Scan - ### + Zebra does not support SRU's + scan + operation, as described at + + + + This is a rather embarrassing surprise as the pieces are all + there: Z39.50 scan is supported, and SRU scan requests are + recognised and diagnosed. To add further to the embarrassment, a + mutant form of SRU scan is supported, using + the non-standard x-pScanClause parameter in + place of the standard scanClause to scan on a + PQF query clause. Explain - ### + Zebra fully supports SRU's core + explain + operation, as described at + + + The ZeeRex record explaining a database may be requested either + with a fully fledged SRU request (with + operation=explain + and version-number specified) + or with a simple HTTP GET at the server's basename. + The ZeeRex record returned in response is the one embedded + in the YAZ Frontend Server configuration file that is described in the + Virtual Hosts documentation. + + + Unfortunately, the data found in the + CQL-to-PQF text file must be added by hand-craft into the explain + section of the YAZ Frontend Server configuration file to be able + to provide a suitable explain record. + Too bad, but this is all extreme + new alpha stuff, and a lot of work has yet to be done .. + + + There is no linkeage whatsoever between the Z39.50 explain model + and the SRU/SRW explain response (well, at least not implemented + in Zebra, that is ..). Zebra does not provide a means using + Z39.50 to obtain the ZeeRex record. + + + + + Some SRU Examples + + Surf into http://localhost:9999 + to get an explain response, or use + + + + See number of hits for a query + + + + Fetch record 5-7 in Dublin Core format + + + + Even search using PQF queries using the extended naughty + verb x-pquery + + + + Or scan indexes using the extended extremely naughty + verb x-pScanClause + + Don't do this in production code! + But it's a great fast debugging aid. +