SRU (Search/Retrieval Using URL)

SRU VERSION 1.1 ARCHIVE

Scan Operation

Request Parameters - Response Parameters - Term Parameters - Examples

While the searchRetrieve operation enables searches for a specific term within a list of indexed terms from the records, the scan operation allows the client to request a range of the available terms at a given point within that list. 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 visually 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.

Scan Request Parameters

Parameter Name Mandatory or optional Description

version

mandatory

Indicates the scan version of the request and the highest version the client can support for the response.

scanClause

mandatory

The index to be browsed and the start point within it, expressed as a complete index, relation, term clause in 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 an xml stylesheet. The client requests that the server simply return this URL in the response.

extraRequestData

optional

Provides additional, profile specific information. See Extra Data.

operation

mandatory

The string: 'scan'.

Scan Response Parameters

Parameter Name Mandatory or optional Type Description

version

mandatory

xsd:string

The version of the response. This must be less than or equal to the version requested by the client.

terms

optional

sequence of term. Each term structured; see table below

A sequence of terms which match the request.

diagnostics

optional

sequence of diagnostic

A sequence of non surrogate diagnostics generated during execution.

extraResponseData

optional

xmlFragment

Additional, profile specific information provided by the server along with the response. See Extra Data.

echoedScanRequest

optional

ScanRequest

The request parameters echoed back to the client in a simple XML form.

Sub Parameters for Term

Parameter Name Mandatory or optional Type Description

value

mandatory

xsd:string

The term, exactly as it appears in the index.

numberOfRecords

optional

xsd:non
NegativeInteger

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

optional

xsd:string

A string to display to the end user in place of the term itself. For example this might add back in stopwords which do not appear in the index.

whereInList

optional

xsd:string

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

optional

xml

Additional profile specific information (see extra data) concerning the term

 


Examples

A typical scan request might be:

   http://myserver.com/myurl/?operation=scan&version=1.1
   & scanClause=%2fdc.title%3d%22cat%22&responsePosition=3 &
   maximumTerms=50&stylesheet=http://myserver.com/myStyle
   & x-info-2-auth1.0-authenticationToken=%22XDFPQR5ZZ%22

The response would be of the form:


    <?xml-stylesheet type=text/xsl" href="http:myserver.com/myStyle"?>
    <srw:scanResponse 
             xmlns:srw="http://www.loc.gov/zing/srw/" 
             xmlns:diag="http://www.loc.gov/zing/srw/diagnostic/"
             xmlns:myServer="http://myServer.com/">
      <srw:version>1.1</srw:version>
      <srw:terms>
        <srw:term>
          <srw:value>CARTESIAN 4456345</srw:value>
          <srw:numberOfRecords>35645</srw:numberOfRecords>
          <srw:displayTerm>Carthesian</srw:displayTerm>
          <srw:extraTermData>
            <myserver:ID>4456345</myserver:ID>
          </srw:extraTermData>
        </srw:term>
        <srw:term>
          <srw:value>CARTESIAN 4456376</srw:value>
          <srw:numberOfRecords>2154</srw:numberOfRecords>
          <srw:displayTerm>Carthésian</srw:displayTerm>
          <srw:extraTermData>
             <myServer:ID>4456376</myServer:ID>
          </srw:extraTermData>
        </srw:term>
        <srw:term>
          <srw:value>CAT 4456392</srw:value>
          <srw:numberOfRecords>8739972</srw:numberOfRecords>
          <srw:displayTerm>Cat</srw:displayTerm>
          <srw:extraTermData>
             <myserver:ID>4456392</myserver:ID>
          </srw:extraTermData>
        </srw:term>
        <srw:term>
          <srw:value>CATHOLIC DOGMA 4456888</srw:value>
          <srw:numberOfRecords>35</srw:numberOfRecords>
          <srw:displayTerm>Catholic Dogma</srw:displayTerm>
          <whereInList>last</whereInList>
          <srw:extraTermData>
            <myserver:ID>4456888</myserver:ID>
          </srw:extraTermData>
        </srw:term>
      </srw:terms>
      <srw:extraResponseData> 
        <rob:authenticationToken
          xmlns:rob="info:srw/extension/2/auth-1.0">
              XDFPQR5ZZ
         </rob:authenticationToken>
      </srw:extraResponseData> 
      <srw:echoedScanRequest>
        <srw:version>1.1</srw:version>
        <srw:scanClause>dc.title="cat"</srw:scanClause>  
        <srw:responsePosition>3</srw:responsePosition>
        <srw:maximumTerms>3</srw:maximumTerms>
        <srw:stylesheet>http://myserver.com/myStyle</srw:stylesheet>
      </srw:echoedScanRequest>
    </srw:scanResponse>