X-Git-Url: http://git.indexdata.com/?p=idzebra-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzebrasrv.xml;h=3e7a1542d15926d6aca608722598e9663647822c;hp=15401e7d267864c26e7c3b5da67541cc4f0f0324;hb=d5bb5b72d912f673c7d123fc54d735dee2146003;hpb=b19b79e382ef8196f1625763db1af3a82b1e0c81 diff --git a/doc/zebrasrv.xml b/doc/zebrasrv.xml index 15401e7..3e7a154 100644 --- a/doc/zebrasrv.xml +++ b/doc/zebrasrv.xml @@ -1,23 +1,24 @@ - %local; %entities; - - %common; + + %idcommon; ]> - zebra &version; + Index Data zebrasrv 8 + Commands @@ -31,11 +32,11 @@ 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 + formats (e.g. email, &acro.xml;, &acro.marc;) and allows access to them through exact boolean search expressions and relevance-ranked free-text queries. - zebrasrv is the &z3950; and &sru; frontend + zebrasrv is the &acro.z3950; and &acro.sru; frontend server for the Zebra search engine and indexer. @@ -60,14 +61,14 @@ - &z3950; Protocol Support and Behavior + &acro.z3950; Protocol Support and Behavior - &z3950; Initialization + &acro.z3950; Initialization During initialization, the server will negotiate to version 3 of the - &z3950; protocol, and the option bits for Search, Present, Scan, + &acro.z3950; protocol, and the option bits for Search, Present, Scan, NamedResultSets, and concurrentOperations will be set, if requested by the client. The maximum PDU size is negotiated down to a maximum of 1 MB by default. @@ -76,7 +77,7 @@ - &z3950; Search + &acro.z3950; Search The supported query type are 1 and 101. All operators are currently @@ -96,17 +97,17 @@ - &z3950; Present + &acro.z3950; Present The present facility is supported in a standard fashion. The requested record syntax is matched against the ones supported by the profile of - each record retrieved. If no record syntax is given, &sutrs; is the + each record retrieved. If no record syntax is given, &acro.sutrs; is the default. The requested element set name, again, is matched against any provided by the relevant record profiles. - &z3950; Scan + &acro.z3950; Scan The attribute combinations provided with the termListAndStartPoint are processed in the same way as operands in a query (see above). @@ -115,10 +116,10 @@ - &z3950; Sort + &acro.z3950; Sort - &z3950; specifies three different types of sort criteria. + &acro.z3950; specifies three different types of sort criteria. Of these Zebra supports the attribute specification type in which case the use attribute specifies the "Sort register". Sort registers are created for those fields that are of type "sort" in @@ -128,14 +129,14 @@ - &z3950; allows the client to specify sorting on one or more input + &acro.z3950; allows the client to specify sorting on one or more input result sets and one output result set. Zebra supports sorting on one result set only which may or may not be the same as the output result set. - &z3950; Close + &acro.z3950; Close If a Close PDU is received, the server will respond with a Close PDU with reason=FINISHED, no matter which protocol version was negotiated @@ -150,10 +151,10 @@ - &z3950; Explain + &acro.z3950; Explain Zebra maintains a "classic" - &z3950; Explain database + &acro.z3950; Explain database on the side. This database is called IR-Explain-1 and can be searched using the attribute set exp-1. @@ -176,54 +177,54 @@ - The &sru; Server + The &acro.sru; Server - In addition to &z3950;, Zebra supports the more recent and - web-friendly IR protocol &sru;. - &sru; can be carried over &soap; or a &rest;-like protocol - that uses HTTP &get; or &post; to request search responses. The request + In addition to &acro.z3950;, Zebra supports the more recent and + web-friendly IR protocol &acro.sru;. + &acro.sru; can be carried over &acro.soap; or a &acro.rest;-like protocol + that uses HTTP &acro.get; or &acro.post; to request search responses. The request itself is made of parameters such as query, startRecord, maximumRecords and recordSchema; - the response is an &xml; document containing hit-count, result-set - records, diagnostics, etc. &sru; can be thought of as a re-casting - of &z3950; semantics in web-friendly terms; or as a standardisation + the response is an &acro.xml; document containing hit-count, result-set + records, diagnostics, etc. &acro.sru; can be thought of as a re-casting + of &acro.z3950; semantics in web-friendly terms; or as a standardisation of the ad-hoc query parameters used by search engines such as Google and AltaVista; or as a superset of A9's OpenSearch (which it predates). - Zebra supports &z3950;, &sru; &get;, SRU &post;, SRU &soap; (&srw;) + Zebra supports &acro.z3950;, &acro.sru; &acro.get;, SRU &acro.post;, SRU &acro.soap; (&acro.srw;) - on the same port, recognising what protocol is used by each incoming requests and handling them accordingly. This is a achieved through the use of Deep Magic; civilians are warned not to stand too close. - Running zebrasrv as an &sru; Server + Running zebrasrv as an &acro.sru; Server Because Zebra supports all protocols on one port, it would - seem to follow that the &sru; server is run in the same way as - the &z3950; server, as described above. This is true, but only in + seem to follow that the &acro.sru; server is run in the same way as + the &acro.z3950; server, as described above. This is true, but only in an uninterestingly vacuous way: a Zebra server run in this manner - will indeed recognise and accept &sru; requests; but since it - doesn't know how to handle the &cql; queries that these protocols + will indeed recognise and accept &acro.sru; requests; but since it + doesn't know how to handle the &acro.cql; queries that these protocols use, all it can do is send failure responses. - It is possible to cheat, by having &sru; search Zebra with - a &pqf; query instead of &cql;, using the + It is possible to cheat, by having &acro.sru; search Zebra with + a &acro.pqf; query instead of &acro.cql;, using the x-pquery parameter instead of query. This is a non-standard extension - of &cql;, and a + of &acro.cql;, and a very naughty - thing to do, but it does give you a way to see Zebra serving &sru; + thing to do, but it does give you a way to see Zebra serving &acro.sru; ``right out of the box''. If you start your favourite Zebra server in the usual way, on port 9999, then you can send your web browser to: @@ -236,20 +237,20 @@ &maximumRecords=1 - This will display the &xml;-formatted &sru; response that includes the + This will display the &acro.xml;-formatted &acro.sru; response that includes the first record in the result-set found by the query - mineral. (For clarity, the &sru; URL is shown - here broken across lines, but the lines should be joined to gether + mineral. (For clarity, the &acro.sru; URL is shown + here broken across lines, but the lines should be joined together to make single-line URL for the browser to submit.) - In order to turn on Zebra's support for &cql; queries, it's necessary + In order to turn on Zebra's support for &acro.cql; queries, it's necessary to have the &yaz; generic front-end (which Zebra uses) translate them - into the &z3950; Type-1 query format that is used internally. And + into the &acro.z3950; Type-1 query format that is used internally. And to do this, the generic front-end's own configuration file must be used. See ; - the salient point for &sru; support is that + the salient point for &acro.sru; support is that zebrasrv must be started with the -f frontendConfigFile @@ -257,7 +258,7 @@ -c zebraConfigFile option, and that the front-end configuration file must include both a - reference to the Zebra configuration file and the &cql;-to-&pqf; + reference to the Zebra configuration file and the &acro.cql;-to-&acro.pqf; translator configuration file. @@ -281,13 +282,13 @@ -c command-line argument, and the <cql2rpn> - element contains the name of the &cql; properties file specifying how - various &cql; indexes, relations, etc. are translated into Type-1 + element contains the name of the &acro.cql; properties file specifying how + various &acro.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: + queried using proper, conformant &acro.sru; URLs with &acro.cql; queries: http://localhost:9999/Default?version=1.1 @@ -299,107 +300,107 @@ - &sru; Protocol Support and Behavior + &acro.sru; Protocol Support and Behavior - Zebra running as an &sru; server supports SRU version 1.1, including - &cql; version 1.1. In particular, it provides support for the + Zebra running as an &acro.sru; server supports SRU version 1.1, including + &acro.cql; version 1.1. In particular, it provides support for the following elements of the protocol. - &sru; Search and Retrieval + &acro.sru; Search and Retrieval Zebra supports the - &sru; searchRetrieve + &acro.sru; searchRetrieve operation. - One of the great strengths of &sru; is that it mandates a standard - query language, &cql;, and that all conforming implementations can + One of the great strengths of &acro.sru; is that it mandates a standard + query language, &acro.cql;, and that all conforming implementations can therefore be trusted to correctly interpret the same queries. It is with some shame, then, that we admit that Zebra also supports an additional query language, our own Prefix Query Format - (&pqf;). - A &pqf; query is submitted by using the extension parameter + (&acro.pqf;). + A &acro.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;. + parameter must be omitted, which makes the request not valid &acro.sru;. Please feel free to use this facility within your own - applications; but be aware that it is not only non-standard &sru; + applications; but be aware that it is not only non-standard &acro.sru; but not even syntactically valid, since it omits the mandatory query parameter. - &sru; Scan + &acro.sru; Scan - Zebra supports &sru; scan + Zebra supports &acro.sru; scan operation. - Scanning using &cql; syntax is the default, where the + Scanning using &acro.cql; syntax is the default, where the standard scanClause parameter is used. In addition, a - mutant form of &sru; scan is supported, using + mutant form of &acro.sru; scan is supported, using the non-standard x-pScanClause parameter in place of the standard scanClause to scan on a - &pqf; query clause. + &acro.pqf; query clause. - &sru; Explain + &acro.sru; Explain - Zebra supports &sru; explain. + Zebra supports &acro.sru; explain. The ZeeRex record explaining a database may be requested either - with a fully fledged &sru; request (with + with a fully fledged &acro.sru; request (with operation=explain and version-number specified) - or with a simple HTTP &get; at the server's basename. + or with a simple HTTP &acro.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 . Unfortunately, the data found in the - &cql;-to-&pqf; text file must be added by hand-craft into the explain + &acro.cql;-to-&acro.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 &z3950; explain model - and the &sru; explain response (well, at least not implemented + There is no linkage whatsoever between the &acro.z3950; explain model + and the &acro.sru; explain response (well, at least not implemented in Zebra, that is ..). Zebra does not provide a means using - &z3950; to obtain the ZeeRex record. + &acro.z3950; to obtain the ZeeRex record. - Other &sru; operations + Other &acro.sru; operations - In the &z3950; protocol, Initialization, Present, Sort and Close - are separate operations. In &sru;, however, these operations do not + In the &acro.z3950; protocol, Initialization, Present, Sort and Close + are separate operations. In &acro.sru;, however, these operations do not exist. - &sru; has no explicit initialization handshake phase, but + &acro.sru; has no explicit initialization handshake phase, but commences immediately with searching, scanning and explain operations. - Neither does &sru; have a close operation, since the protocol is + Neither does &acro.sru; have a close operation, since the protocol is stateless and each request is self-contained. (It is true that - multiple &sru; request/response pairs may be implemented as + multiple &acro.sru; request/response pairs may be implemented as multiple HTTP request/response pairs over a single persistent TCP/IP connection; but the closure of that connection is not a protocol-level operation.) @@ -407,12 +408,12 @@ - Retrieval in &sru; is part of the + Retrieval in &acro.sru; is part of the searchRetrieve operation, in which a search is submitted and the response includes a subset of the records - in the result set. There is no direct analogue of &z3950;'s + in the result set. There is no direct analogue of &acro.z3950;'s Present operation which requests records from an established - result set. In &sru;, this is achieved by sending a subsequent + result set. In &acro.sru;, this is achieved by sending a subsequent searchRetrieve request with the query cql.resultSetId=id where id is the identifier of the previously @@ -421,24 +422,24 @@ - Sorting in &cql; is done within the + Sorting in &acro.cql; is done within the searchRetrieve operation - in v1.1, by an explicit sort parameter, but the forthcoming v1.2 or v2.0 will most likely use an extension of the query - language, &cql; sorting. + language, &acro.cql; sorting. - It can be seen, then, that while Zebra operating as an &sru; server + It can be seen, then, that while Zebra operating as an &acro.sru; server does not provide the same set of operations as when operating as a - &z3950; server, it does provide equivalent functionality. + &acro.z3950; server, it does provide equivalent functionality. - &sru; Examples + &acro.sru; Examples Surf into http://localhost:9999 to get an explain response, or use @@ -462,7 +463,7 @@ ]]> - Even search using &pqf; queries using the extended naughty + Even search using &acro.pqf; queries using the extended naughty parameter x-pquery