1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
5 <!ENTITY % local SYSTEM "local.ent">
7 <!ENTITY % entities SYSTEM "entities.ent">
9 <!ENTITY % idcommon SYSTEM "common/common.ent">
12 <refentry id="pazpar2_protocol">
14 <productname>Pazpar2</productname>
15 <productnumber>&version;</productnumber>
16 <orgname>Index Data</orgname>
19 <refentrytitle>Pazpar2 protocol</refentrytitle>
20 <manvolnum>7</manvolnum>
21 <refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
25 <refname>pazpar2_protocol</refname>
26 <refpurpose>The webservice protocol of Pazpar2</refpurpose>
30 <title>DESCRIPTION</title>
32 Webservice requests are any that refer to filename "search.pz2". Arguments
33 are GET-style parameters. Argument 'command' is always required and specifies
34 the operation to perform. Any request not recognized as a webservice
35 request is forwarded to the HTTP server specified in the configuration
36 using the proxy setting.
37 This way, a regular webserver can host the user interface (itself dynamic
38 or static HTML), and Ajax-style calls can be used from JS (or any other
39 client-based scripting environment) to interact with the search logic
43 Each command is described in sub sections to follow.
45 <refsect2 id="command-info">
48 Returns version and statistics about the Pazpar2 instance.
51 <refsect2 id="command-init">
54 Initializes a session.
55 Returns session ID to be used in subsequent requests. If
56 a server ID is given in the Pazpar2 server section, then
57 that is included in the session ID as suffix after a period (.).
60 If the init command is performed as a HTTP GET request, service
61 and settings from local files are used. The service parameter
62 may chose a particular local service.
65 If the init command is performed as a HTTP POST request and
66 the content-type is text/xml, then the content is XML parsed
67 and treated as service for the session. The root element should be
68 service. Refer to descripton of the
69 <link linkend="service_conf">service</link> format.
70 The posting of a service appeared in Pazpar2 version 1.2.1.
75 search.pz2?command=init
84 <session>2044502273</session>
88 The init command may take a number of setting parameters, similar to
89 the 'settings' command described below. These settings are immediately
90 applied to the new session. Other parameters for init are:
96 If this is defined and the value is non-zero, the session will
97 not use the predefined databases in the configuration; only those
98 specified in the settings parameters (per session databases).
107 If this is defined it specifies a service ID. Makes the session use
108 the service with this ID. If this is setting is omitted, the
109 session will use the unnamed service in the Pazpar2 configuration.
117 <refsect2 id="command-ping">
120 Keeps a session alive. An idle session will time out after one minute.
121 The ping command can be used to keep the session alive absent other
123 It is suggested that any browser client have a simple alarm handler which
124 sends a ping every 50 seconds or so once a session has been initialized.
129 search.pz?command=ping&session=2044502273
140 <refsect2 id="command-settings">
141 <title>settings</title>
143 The settings command applies session-specific settings to one or more
144 databases. A typical function of this is to enable access to
145 restricted resources for registered users, or to set a user- or
146 library-specific username/password to use against a target.
149 Each setting parameter has the form name[target]=value, where name is the
150 name of the setting (e.g. pz:authentication), target is a target ID,
151 or possibly a wildcard, and value is the desired value for the
156 Because the settings command manipulates potentially sensitive
157 information, it is possible to configure Pazpar2 to only allow access
158 to this command from a trusted site -- usually from server-side
159 scripting, which in turn is responsible for authenticating the user,
160 and possibly determining which resources he has access to, etc.
165 As a shortcut, it is also possible to override settings directly in
171 If the settings command is performed as HTTP POST and the content-type
172 is text/xml, then the content is XML parsed and treated as settings -
173 with a format identical to local
174 <link linkend="target_settings">settings files</link>.
175 The posting of settings appeared in Pazpar version 1.2.1.
181 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
192 <refsect2 id="command-search">
193 <title>search</title>
195 Launches a search, parameters:
218 Limits the search to a given set of targets specified by the
219 filter. The filter consists of a comma separated list of
220 <emphasis>setting</emphasis>+<emphasis>operator</emphasis>+<emphasis>args</emphasis>
221 pairs. The <emphasis>setting</emphasis> is a Pazpar2 setting
222 (such as <literal>pz:id</literal>).
223 The <emphasis>operator</emphasis> is either
224 <literal>=</literal> (string match)
225 or <literal>~</literal> (substring match).
226 The <emphasis>args</emphasis> is a list of values separated
227 by <literal>|</literal> (or , one of the values).
228 The idea is that only targets with a setting matching one of
229 the values given will be included in the search.
237 Narrows the search by one or more fields (typically facets).
238 The limit is sequence of one or more
239 <emphasis>name</emphasis>=<emphasis>args</emphasis> pairs separated
240 by comma. The <emphasis>args</emphasis> is a list of values
241 separated by vertical bar (<literal>|</literal>).
242 The meaning of <literal>|</literal> is alternative, ie OR .
243 A value that contains a comma (<literal>,</literal>),
244 a vertical bar (<literal>|</literal>) or
245 backslash itself must be preceded by backslash (<literal>\</literal>).
246 The <link linkend="limitmap">pz:limitmap</link> configuration
247 item defines how the searches are mapped to a database.
252 <term>startrecs</term>
255 Specifies the first record to retrieve from each target.
256 The first record in a result set for a target is numbered 0, next
257 record is numbered 1. By default startrecs is 0.
265 Specifies the maximum number of records to retrieve from each
266 target. The default value is 100. This setting has same meaning
267 as per-target setting pz:maxrecs . If pz:maxrecs is set, it takes
268 precedence over argument maxrecs.
276 Specifies sort criteria. The argument is a comma-separated list
277 (no whitespace allowed) of sort fields, with the highest-priority
278 field first. A sort field may be followed by a colon followed by
279 the number '0' (decreasing) or '1' (increasing). Default
280 sort order is decreasing.
281 Sort field names can be any field name designated as a sort field
282 in the pazpar2.cfg file, or the special names 'relevance',
283 'retrieval' and 'position'.
286 Sort type 'position' sorts by position/offset for each database.
287 Sort type 'retrieval' sorts by position of retrieval (first record
288 retrieved is 1, second record is 2, etc.).
291 If not specified here or as
292 <link linkend="sort-default">sort-default"</link>
293 in pazpar2.cfg, Pazpar2 will default to the built-in
297 Having sort criteria at search is important for targets that
298 supports native sorting in order to get best results. Pazpar2
299 will trigger a new search if search criteria changes from Pazpar2
300 to target-based sorting or visa-versa.
306 <term>mergekey</term>
309 Sets mergekey for this search and rest of session, or until
310 another mergekey is given for show/search. The mergekey value is a
311 comma separated list with one or more names as they appear
312 in the service description equivalent to
313 <literal>mergekey="optional"</literal> inside a metadata element.
314 If the empty string is given for mergekey it is disabled
315 and rest of session will use the default mergekey from service
319 This facility, "dynamic mergekey", appeared in Pazpar2 version
329 Sets rank method this search and rest of session, or until
330 another rank is given for show/search. The rank value is a
331 comma separated list of pairs field=value pairs. The
332 format is the same as
333 <xref linkend="metadata-rank">rank</xref> for a metadata element.
334 If the empty string is given for rank it is disabled
335 and rest of session will use the default rank from metadata or
339 This facility, "dynamic ranking", appeared in Pazpar2 version
351 search.pz2?session=2044502273&command=search&query=computer+science
363 <refsect2 id="command-stat">
366 Provides status information about an ongoing search. Parameters:
383 search.pz2?session=2044502273&command=stat
388 <activeclients>3</activeclients>
389 <hits>7</hits> -- Total hitcount
390 <records>7</records> -- Total number of records fetched in last query
391 <clients>1</clients> -- Total number of associated clients
392 <unconnected>0</unconnected> -- Number of disconnected clients
393 <connecting>0</connecting> -- Number of clients in connecting state
394 <initializing>0</initializing> -- Number of clients initializing
395 <searching>0</searching> -- ... searching
396 <presenting>0</presenting> -- ... presenting
397 <idle>1</idle> -- ... idle (not doing anything)
398 <failed>0</failed> -- ... Connection failed
399 <error>0</error> -- ... Error was produced somewhere
405 <refsect2 id="command-show">
408 Shows records retrieved. Parameters:
422 <para>First record to show - 0-indexed.</para>
430 Number of records to show If omitted, 20 is used.
439 If block is set to 1, the command will hang until there are records
440 ready to display. Use this to show first records rapidly without
441 requiring rapid polling.
444 If block is set to <literal>preferred</literal>, the command will
445 wait until records have been received from all databases with preferred
455 Specifies sort criteria. The argument is a comma-separated list
456 (no whitespace allowed) of sort fields, with the highest-priority
457 field first. A sort field may be followed by a colon followed by
458 the number '0' (decreasing) or '1' (increasing). Default
459 sort order is decreasing.
460 Sort field names can be any field name designated as a sort field
461 in the pazpar2.cfg file, or the special names 'relevance',
462 'retrieval' and 'position'.
465 Sort type 'position' sorts by position/offset for each database.
466 Sort type 'retrieval' sorts by position of retrieval (first record
467 retrieved is 1, second record is 2, etc.).
470 If not specified here or as
471 <link linkend="sort-default">sort-default"</link>
472 in pazpar2.cfg, pazpar2 will default to the built-in
476 Having sort criteria at search is important for targets that
477 supports native sorting in order to get best results. pazpar2
478 will trigger a new search if search criteria changes from pazpar2
479 to target-based sorting.
482 For targets where If <link linkend="pzsortmap">pz:sortmap</link>
483 is defined, a sort operation will be executed (possibly including
484 extending the search).
490 <term>mergekey</term>
493 Sets mergekey for this show and rest of session, or until
494 another mergekey is given for show/search. The mergekey value is a
495 comma separated list with one or more names as they appear
496 in the service description equivalent to
497 <literal>mergekey="optional"</literal> inside a metadata element.
498 If the empty string is given for mergekey it is disabled
499 and rest of session will use the default mergekey from service
503 This facility, "dynamic mergekey", appeared in Pazpar2 version
513 Sets rank method this show and rest of session, or until
514 another rank is given for show/search. The rank value is a
515 comma separated list of pairs field=value pairs. The
516 format is the same as
517 <xref linkend="metadata-rank">rank</xref> for a metadata element.
518 If the empty string is given for rank it is disabled
519 and rest of session will use the default rank from metadata or
523 This facility, "dynamic ranking", appeared in Pazpar2 version
530 <term>snippets</term>
533 If specified and set to 1 data will include snippets marked
534 with <match> tags. Otherwise snippets will not be included.
537 This facility, "snippets", appeared in Pazpar2 version
548 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
554 <activeclients>3</activeclients> -- How many clients are still working
555 <merged>6</merged> -- Number of merged records
556 <total>7</total> -- Total of all hitcounts
557 <start>0</start> -- The start number you requested
558 <num>2</num> -- Number of records retrieved
560 <md-title>How to program a computer, by Jack Collins</md-title>
561 <count>2</count> -- Number of merged records
562 <recid>6</recid> -- Record ID for this record
566 Computer processing of dynamic images from an Anger scintillation camera :
567 the proceedings of a workshop /
576 <refsect2 id="command-record">
577 <title>record</title>
579 Retrieves a detailed record. Unlike the
580 <link linkend="command-show">show</link> command, this command
581 returns metadata records before merging takes place. Parameters:
597 record ID as provided by the
598 <link linkend="command-show">show</link> command.
607 This optional parameter is an integer which, when given, makes
608 Pazpar2 return the original record for a specific target.
609 The record set from first target is numbered 0,
610 second record set is numbered 1, etc.
611 The nativesyntax setting, as usual, is used to determine how to
612 create XML from the original record - unless parameter
613 <literal>binary</literal> is given in which the record is
614 fetched as "raw" from ZOOM C (raw, original record).
617 When offset/checksum is not given, the Pazpar2 metadata for the record
618 is returned and with metadata for each targets' data specified
619 in a 'location' list.
625 <term>checksum</term>
628 This optional parameter is a string which, when given, makes
629 Pazpar2 return the original record for a specific target. The
630 checksum is returned as attribtue 'checksum' in element
631 'location' for show command and record command (when checksum
632 and offset is NOT given).
633 The nativesyntax setting, as usual, is used to determine how to
634 create XML from the original record - unless parameter
635 <literal>binary</literal> is given in which the record is
636 fetched as "raw" from ZOOM C (raw, original record).
639 When offset/checksum is not given, the Pazpar2 metadata for the record
640 is returned and with metadata for each targets' data specified
641 in a 'location' list.
648 <term>nativesyntax</term>
651 This optional parameter can be used to override pz:nativesyntax
652 as given for the target. This allow an alternative nativesyntax
653 to be used for original records (see parameteroffset above).
662 This optional parameter is the record syntax used for raw
663 transfer (i.e. when offset is specified). If syntax is not given,
664 but offset is used, the value of pz:requestsyntax is used.
673 This optional parameter is the element set name used to retrieval
674 of a raw record (i.e. when offset is specified).
675 If esn is not given, but offset is used, the value of pz:elements
685 This optional parameter enables "binary" response for retrieval
686 of a original record (i.e. when offset is specified). For binary
687 response the record by default is fetched from ZOOM C using
688 the "raw" option or by parameter nativesyntax if given.
694 <term>snippets</term>
697 If specified and set to 1 data will include snippets marked
698 with <match> tags. Otherwise snippets will not be included.
701 This facility, "snippets", appeared in Pazpar2 version
712 search.pz2?session=605047297&command=record&id=3
720 The Puget Sound Region : a portfolio of thematic computer maps /
722 <md-date>1974</md-date>
723 <md-author>Mairs, John W.</md-author>
724 <md-subject>Cartography</md-subject>
730 <refsect2 id="command-stop">
733 Makes Pazpar2 stop further search & retrieval for busy databases.
737 <refsect2 id="command-termlist">
738 <title>termlist</title>
740 Retrieves term list(s). Parameters:
755 comma-separated list of termlist names. If omitted,
756 all termlists are returned.
764 maximum number of entries to return - default is 15.
773 search.pz2?session=2044502273&command=termlist&name=author,subject
778 <activeclients>3</activeclients>
781 <name>Donald Knuth</name>
782 <frequency>10</frequency>
785 <name>Robert Pirsig</name>
786 <frequency>2</frequency>
789 <list name="subject">
791 <name>Computer programming</name>
792 <frequency>10</frequency>
800 For the special termlist name "xtargets", results
801 are returned about the targets which have returned the most hits.
802 The 'term' subtree has additional elements,
803 specifically a state and diagnostic field (in the example below, a
804 target ID is returned in place of 'name'.
805 This may or may not change later.
811 <name>library2.mcmaster.ca</name>
812 <frequency>11734</frequency> -- Number of hits
813 <state>Client_Idle</state> -- See the description of 'bytarget' below
814 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
821 <refsect2 id="command-bytarget">
822 <title>bytarget</title>
824 Returns information about the status of each active client. Parameters:
840 search.pz2?session=605047297&command=bytarget&id=3
849 <id>z3950.loc.gov/voyager/</id>
851 <diagnostic>0</diagnostic>
852 <records>65</records>
853 <state>Client_Presenting</state>
855 <!-- ... more target nodes below as necessary -->
859 The following client states are defined: Client_Connecting,
860 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
861 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
862 Client_Disconnected, Client_Stopped, Client_Continue.
866 <refsect2 id="command-service">
867 <title>service</title>
869 Returns service definition (XML). Parameters:
882 The service command appeared in Pazpar2 version 1.6.32
887 <title>SEE ALSO</title>
891 <refentrytitle>pazpar2</refentrytitle>
892 <manvolnum>8</manvolnum>
896 Pazpar2 Configuration:
898 <refentrytitle>pazpar2_conf</refentrytitle>
899 <manvolnum>5</manvolnum>
905 <!-- Keep this comment at the end of the file