Scan Operation (SRU Version 1.2 Specifications)
While the searchRetrieve operation enables searches for a specific terms within the records, the scan operation allows the client to request a range of the available terms at a given point within a list of indexed terms. This enables clients to present an ordered list of values and, if supported, how many hits there would be for a search on that term. Scan is often used to select terms for subsequent searching or to verify a negative search result.
The index to be browsed and the start point within it is given in the scanClause parameter as a complete index, relation, term clause in CQL. The relation and relation modifiers may be used to determine the format of the terms returned. For example 'dc.title any fish' will return a list of keywords, whereas 'dc.title exact fish' would return a list of full title fields. Range relations, such as <, >=, within and so forth, are prohibited for use with scan, and diagnostic 'info:srw/diagnostic/1/19' should be returned. See below for a clarifying example.
The term given in the clause is the position within the ordered list of terms at which to start, however see the responsePosition parameter below for more information. If the empty term is given, then even if searching for it is unsupported by the server, it may be interpreted as the beginning of the term list.
PARAMETERS
Request
| Name | Mandatory/Optional? | Description |
|---|---|---|
| operation | mandatory | The string: 'scan'. |
| 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 Versions. |
| scanClause | mandatory | The index to be browsed and the start point within it, expressed as a complete index, relation, term clause in CQL. See CQL. |
| responsePosition | optional | The position within the list of terms returned where the client would like the start term to occur. If the position given is 0, then the term should be immediately before the first term in the response. If the position given is 1, then the term should be first in the list, and so forth up to the number of terms requested plus 1, meaning that the term should be immediately after the last term in the response, even if the number of terms returned is less than the number requested. The range of values is 0 to the number of terms requested plus 1. The default value is 1. |
| maximumTerms | optional | The number of terms which the client requests be returned. The actual number returned may be less than this, for example if the end of the term list is reached, but may not be more. The explain record for the database may indicate the maximum number of terms which the server will return at once. All positive integers are valid for this parameter. If not specified, the default is server determined. |
| 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:
Response
| Name | Type | Mandatory/Optional? | 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. |
| terms | sequence of <term> | optional | A sequence of terms which match the request. See Terms |
| 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. |
| echoedScanRequest | <echoedScanRequest> | Optional | The request parameters echoed back to the client in a simple XML form. See Echoing the Request. |
Terms
| Name | Type | Mandatory/Optional? | Description |
|---|---|---|---|
| value | xsd:string | mandatory | The term, exactly as it appears in the index. |
| numberOfRecords | xsd:nonNegativeInteger | optional | The number of records which would be matched if the index in the request's scanClause was searched with the term in the 'value' field. |
| displayTerm | xsd:string | optional | A string to display to the end user in place of the term itself. For example this might add back in diacritics or capitalisation which do not appear in the index. |
| whereInList | xsd:string | optional | A flag to indicate the position of the term within the complete term list. It must be one of the following values: 'first' (the first term), 'last' (the last term), 'only' (the only term) or 'inner' (any other term) |
| extraTermData | xmlFragment | optional | Additional information concerning the term. See Extensions. |
Example:
xmlns:diag="http://www.loc.gov/zing/srw/diagnostic/"
xmlns:myServer="http://myServer.com/">
<sru:version>1.1</sru:version>
<sru:terms>
<sru:term>
<sru:value>cartesian</sru:value>
<sru:numberOfRecords>35645</sru:numberOfRecords>
<sru:displayTerm>Carthesian</sru:displayTerm>
</sru:term>
<sru:term>
<sru:value>carthesian</sru:value>
<sru:numberOfRecords>2154</sru:numberOfRecords>
<sru:displayTerm>Carthésian</sru:displayTerm>
</sru:term>
<sru:term>
<sru:value>cat</sru:value>
<sru:numberOfRecords>8739972</sru:numberOfRecords>
<sru:displayTerm>Cat</sru:displayTerm>
</sru:term>
<sru:term>
<sru:value>catholic</sru:value>
<sru:numberOfRecords>35</sru:numberOfRecords>
<sru:displayTerm>Catholic</sru:displayTerm>
<sru:whereInList>last</sru:whereInList>
<sru:extraTermData>
<myserver:ID>4456888</myserver:ID>
</sru:extraTermData>
</sru:term>
</sru:terms>
<sru:echoedScanRequest>
<sru:version>1.1</sru:version>
<sru:scanClause>dc.title="cat"</sru:scanClause>
<sru:responsePosition>3</sru:responsePosition>
<sru:maximumTerms>3</sru:maximumTerms>
<sru:stylesheet>http://myserver.com/myStyle</sru:stylesheet>
</sru:echoedScanRequest>
</sru:scanResponse>