searchRetrieve Operation (SRU Version 1.2 Specifications)
SECTIONS: Parameters | Records | Result Sets
The searchRetrieve operation is the main operation in SRU. It allows the client to submit a search and retrieve request for matching records from the server.
PARAMETERS
Request Parameters
| Name | Mandatory/Optional? | Description |
|---|---|---|
| operation | mandatory | The string: 'searchRetrieve'. |
| version | mandatory | The version of the request, and a statement by the client that it wants the response to be less than, or preferably equal to, that version. See Version. |
| query | mandatory | Contains a query expressed in CQL to be processed by the server. See CQL. |
| startRecord | optional | The position within the sequence of matched records of the first record to be returned. The first position in the sequence is 1. The value supplied MUST be greater than 0. The default value if not supplied is 1. |
| maximumRecords | optional | The number of records requested to be returned. The value must be 0 or greater. Default value if not supplied is determined by the server. The server MAY return less than this number of records, for example if there are fewer matching records than requested, but MUST NOT return more than this number of records. |
| recordPacking | optional | A string to determine how the record should be escaped in the response. Defined values are 'string' and 'xml'. The default is 'xml'. See Records. |
| recordSchema | optional | The schema in which the records MUST be returned. The value is the
URI identifier for the schema or the short name for it published by
the server. The default value if not supplied is determined by the
server. See Record Schemas. For version 1.1: If the recordXPath parameter is included, it is the abstract schema for purposes of evaluation by the XPath expression. |
| recordXPath (version 1.1 only) |
optional | An XPath expression, to be applied to the records before returning them. It is to be applied relative to the schema supplied in the recordSchema parameter, and response records should assume the SRU XPath schema. |
| resultSetTTL | optional | The number of seconds for which the client requests that the result set created should be maintained. The server MAY choose not to fulfil this request, and may respond with a different number of seconds. If resultSetTTL is not supplied then the server will determine the value. See Result Sets. |
| sortKeys (version 1.1 only) |
optional | Contains a sequence of sort keys to be applied to the results. |
| stylesheet | optional | A URL for a stylesheet. The client requests that the server simply return this URL in the response. See Stylesheets. |
| extraRequestData | optional | Provides additional information for the server to process. See Extensions. |
Example:
This example is a search for the term "dinosaur", requesting that at most one record be returned, according to the 'dc' schema
Response Parameters
The response to an SRU searchRetrieve request is an XML document. The table below provides a summary and description of the elements provided by the XML document. The "Type" column indicates either an XML Schema type ("xsd:") or a type defined within the schema.
| Name | Type | Mandatory/Opetional? | Description |
|---|---|---|---|
| version | xsd:string | Mandatory | The version of the response. This MUST be less than or equal to the version requested by the client. See Versions. |
| numberOfRecords | xsd:integer | Mandatory | The number of records matched by the query. If the query fails this MUST be 0. |
| resultSetId | xsd:string | Optional | The identifier for a result set that was created through the execution of the query. See Result Sets. |
| resultSetIdleTime | xsd:integer | Optional | The number of seconds after which the created result set will be deleted. The result set may also become unavailable before this. See Result Sets. |
| records | sequence of <record> | Optional | A sequence of records matched by the query, or surrogate diagnostics. See Records. |
| nextRecordPosition | xsd:integer | Optional | The next position within the result set following the final returned record. If there are no remaining records, this field MUST be omitted. |
| diagnostics | sequence of <diagnostic> | Optional | A sequence of non surrogate diagnostics generated during execution. See Diagnostics. |
| extraResponseData | <xmlFragment> | Optional | Additional information returned by the server. See Extensions. |
| echoedSearch RetrieveRequest |
<echoedSearch RetrieveRequest> |
Optional | The request parameters echoed back to the client in a simple XML form. See Echoing the Request. |
RECORDS
All records in SRU are transferred in XML. Records are not assumed to be stored in XML. Records which are not natively XML must be first transformed into XML before being transferred. Records in the response may be expressed as a single string, or as embedded XML. If a record is transferred as embedded XML, it must be well-formed and should be validatable against the record schema.
The records parameter in the response is a sequence of record elements, each of which contains either a record or a surrogate diagnostic explaining why that particular record could not be transferred. If the record schema is unknown or the record cannot be rendered in that schema, then the server MUST return a diagnostic.
Each record element is structured into the following elements:
Record Parameters
| Name | Type | Mandatory/Optional? | Description |
|---|---|---|---|
| recordSchema | xsd:string | mandatory | The URI identifier of the XML schema in which the record is encoded. Although the request may use the server's assigned short name, the response must always be the full URI. See Record Schemas. |
| recordPacking | xsd:string | mandatory | The packing used in recordData, as requested by the client or the default. See below. |
| recordData | <stringOrXmlFragment> | mandatory | The record itself, either as a string or embedded XML. |
| recordIdentifier(version 1.2 only) | xsd:string | optional This parameter is excluded in version 1.1. |
An identifier for the record by which it can unambiguously be retrieved in a subsequent operation. For example via the 'rec.identifier' index in CQL. |
| recordPosition | xsd:positiveInteger | optional | The position of the record within the result set. See Result Sets. |
| extraRecordData | <xmlFragment> | optional | Any additional information to be transferred with the record. See Extensions. |
An example record, in the simple Dublin Core schema, packed as XML:
<recordSchema>info:srw/schema/1/dc-v1.1</recordSchema>
<recordPacking>xml</recordPacking>
<recordData>
<srw_dc:dc xmlns:srw_dc="info:srw/schema/1/dc-v1.1">
<dc:title>This is a Sample Record</dc:title>
</srw_dc:dc>
</recordData>
<recordPosition>1</recordPosition>
<extraRecordData>
<rel:score xmlns:rel="info:srw/extensions/2/rel-1.0">
0.965
</rel:rank>
</extraRecordData>
</record>
Record Packing
In order that records which are not well formed do not break the entire message, it is possible to request that they be transferred as a single string with the <, > and & characters escaped to their entity forms. Moreover some toolkits may not be able to distinguish record XML from the XML which forms the response. However, some clients may prefer that the records be transferred as XML in order to manipulate them directly with a stylesheet which renders the records and potentially also the user interface.
This distinction is made via the recordPacking parameter in the request. If the value of the parameter is 'string', then the server should escape the record before transfering it. If the value is 'xml', then it should embed the XML directly into the response. Either way, the data is transfered within the 'recordData' field. If the server cannot comply with this packing request, then it must return a diagnostic.
RESULT SETS
SRU does not assume support of persistent result sets -- that a result set created by one request may necessarily be accessed by a client in a subsequent request. SRU does expect the server to state whether or not it supports persistent result sets, and if so the result set model described below is required.
There are applications in which result sets are critical; on the other hand there are applications in which result sets are not viable. An example of the first might be scientific investigation of a database with comparison of data sets produced at different times. An example of the latter might be a very frequently used database of web pages in which persistent result sets would be an impossible burden on the infrastructure due to the frequency of use.
Even if the server does not make result sets available for public manipulation, the following model is also important to understand in order to allow a single request to both match records and then sort them.
Result Set Model
Processing of a query results in the selection of a set of records, represented by a result set maintained at the server; logically it is an ordered list of references to the records. Once created, a result set cannot be modified. Any operation which would somehow change a result set instead creates a new result set. Each result set is referenced via a unique identifying string, generated by the server when the result set is created.
From the client's point of view, the result set is a set of records each referenced by an ordinal number, beginning at 1. The client may request a given record from a result set according to a specific schema. For example the client may request record 1 in Dublin Core, and subsequently request record 1 in MODS. The requested schema is not a property of the result set (nor of the requested records as a member of the result set); the result set is simply the ordered list of records.
A record might be deleted or otherwise become unavailable while a result sets which references that record still exists. If a client then requests that record, the server is expected to supply a surrogate diagnostic in place of the record. For example, if the record at position 2 in a result set is deleted and then a client requests records 1 through 3, the server should supply, in order: record 1, a surrogate diagnostic for record 2, record 3.
The records in a result set are not necessarily ordered according to any specific or predictable scheme, unless it has been created with a request that contains a sort specification as part of the query. See sorting in CQL for more information regarding the specifics of sorting. If search and sort specifications are supplied on the same request then only the final sorted result set is considered to exist, even if the server internally creates a result set and then sorts it.
resultSetId
If the server supports result sets, it may include a resultSetId in the searchRetrieve response, along with an idle time described below. If another query is submitted then the server will again supply a result set id. If the result of the query would modify an existing result set (for example, a request to sort an existing result set), then the server must supply a new id for this new set. The server should maintain unique names for each result set created, even if the result sets no longer exist, such that clients do not mistakenly request records from the new set when meaning to refer to the previous set with the same identifier.
resultSetIdleTime
The server may supply an idle time along with a result set. The server is making a good-faith estimate that the result set will remain available and unchanged (both in content and order) until a timeout (a period of inactivity exceeding the idle time). The idle time is an integer representing seconds; it must be a positive integer, and should not be so small that a client cannot realistically reference the result set again. If the server does not intend that the result set be referenced, it should omit the result set identifier in the response.