Submit a Query

Verb name: Search
Verb version: 1.0
Required arguments: set [?], field, value, op
Optional arguments: sort, startResult, endResult, authority [?]
MIMETYPE of response: text/xml

Verb Description

Specifies a search request to an index server. Arguments indicate search criteria and the order and amount of search results to be returned. The response is a structured list of documents that match the search criteria, and includes a results summary. It is possible to request the results summary only.

Arguments

The arguments field[n], value[n], op[n], all enumerate, beginning with 1. [if we set a max value for n, we can write a schema to validate responses.]

Supported values for bibliographic field arguments may vary among index servers. The DescribeVerb verb returns the set of field values supported by a particular server. The arguments and values that must be submitted and/or supported are marked "required" in the following:

• set :: [required??] these would be OAI sets. We have no mechanism to indicate multiple sets per query. See 'authority' below.
• sort :: a requested sort order for result sets. Default is ??? Possible values are:
  • title [required?]
  • author
  • date
  • rank based on whatever relevance data is provided by the repository.
• startResult :: the numerical order of the first result to be returned in the response. Value is an integer, 0 or greater; default is 1. If the value is 0, no results will be returned, regardless of the value of endResult.
• endResult :: the numerical order of the last result to be returned in the response. Value is an integer, 0 or greater; default is the last result available. If the value is less than startResult, the default value will be used [or should this be a badArgument error?].
• field[n] :: [required] Following is a list of permitted argument values. Those marked "[required]" must be supported (indexed).
  • title [required]
  • itemno [should this be 'identifier'?]
  • author [required]
  • pubtype [required] indicates whether monograph or serial
  • subject
  • language [required] [are we controlling the format of this in some way?]
  • fullbib [required]
  • abstract
  • pubdate [required]
  • publisher [required]
  • fulltext
• value[n] :: [required] the query string
• op[n] :: [required, if applicable] Defines the relationship between n and n + 1 field/value arguments. Following is a list of permitted argument values. Those marked "[required]" must be supported.
  • and [required]
  • or [required]
  • not
  • within
  • including
• authority :: [I don't think we need this anymore, right?] The name of the authority in the index server to which the search is to be limited. The default is all authorities. The authority argument may be repeated, in which case the the search is carried out in each authority (effectively or'ing the authority arguments).

Operator Precedence: queries are assumed to be submitted using Reverse Polish Notation (RPN)

Rules for field matching: the value of the value argument is treated as a single string (word or phrase) and matched exactly as submitted; the wild card symbol * should be used to indicate truncation.

Response

Unless there is an error, all responses include a single resultsSummary and zero to many record elements.

• <resultsSummary> :: [required] an empty element with data about the results returned. All of the following attributes are included, using defaults if not specified in request. The value of endResult may be less than that requested (if there were fewer results than requested).
  • repositoryIdentifier
  • set
  • sort
  • totalResults
  • startResult
  • endResult
• <record> :: zero to many record elements allowed. Each contains the following elements:
  • <identifier> :: [required] the unique document identifier [do these need to be OAI identifiers? did we agree to that?]
  • <title> :: [required]
  • <author> :: [required if available] Repeatable. Each author is in last, first middle format.
  • <pubdate> :: [required] The date of publication of the document in ISO 8601 format.
  • <rank> :: [required] Relevance data in any form. Should be made as meaningful as possible.

Error Codes

• badArgument :: the request includes illegal arguments or is missing required arguments.
• noRecordsMatch :: no documents match the the submitted search criteria.
• unsupportedArgumentValue :: an argument value was submitted that is not supported by this repository. [This is not in OAI. Perhaps badArgument would suffice, but something more specific could be useful. It could also be broken up into even more specific errors, such as sortArgumentValueUnsupported, fieldArgumentValueUnsupported, etc.]
• noSetHierarchy :: a repository may not have sets?

Examples

Request

http://some.cgm.server/script?protocol=CGM&service=Index
	&verb=Search&ver=1.0&set=math&endResult=100
	&field1=author&value1=todhunter&op1=and
	&field2=title&value2=trigonometry

Response

<?xml version="1.0" encoding="UTF-8"?> <CGM service="Index"> <responseDate>2002-10-01T19:20:30Z</responseDate> <request verb="Search" ver="1.0" set="math" endResult="100" field1="author" value1="todhunter" op1="and" field2="title" value2="trigonometry"> http://some.cgm.server/script</request> <Search ver="1.0"> <resultsSummary repositoryIdentifier="CULmath" set="math" sort="title" totalResults="2" startResult="1" endResult="2" /> <record> <identifier>CULmath:cul.math/98765432</identifier> <title>Fun with Trigonometry</title> <author>Todhunter, I.</author> <author>Disney, W.</author> <pubdate>1888</date> <rank>2859</rank> </record> <record> <identifier>CULmath:cul.math/00640001</identifier> <title>Spherical Trigonometry</title> <author>Todhunter, I.</author> <pubdate>1886</date> <rank>2857</rank> </record> </Search> </CGM>

Request

http://some.cgm.server/script?protocol=CGM&service=Index
	&verb=Search&ver=1.0&set=math&startResult=0
	&field1=fulltext&value1=geometry&op1=and
	&field2=fulltext&value2=trigonometry

Response

<?xml version="1.0" encoding="UTF-8"?> <CGM service="Index"> <responseDate>2002-10-02T19:20:30Z</responseDate> <request verb="Search" ver="1.0" set="math" startResult="0" field1="fulltext" value1="geometry" op1="and" field2="fulltext" value2="trigonometry"> http://some.cgm.server/script</request> <Search ver="1.0"> <resultsSummary repositoryIdentifier="CULmath" set="math" sort="title" totalResults="1024" startResult="0" endResult="0" /> </Search> </CGM>

Request

http://some.cgm.server/script?protocol=CGM&service=Index
	&verb=Search&ver=1.0&set=CULmathbks
	&field1=author&value1=bush&op1=and
	&field2=fullbib&value2=basic%20counting

Response

<?xml version="1.0" encoding="UTF-8"?> <CGM service="Index"> <responseDate>2002-10-02T19:20:30Z</responseDate> <request verb="Search" ver="1.0" set="math" field1="author" value1="bush" op1="and" field2="fullbib" value2="basic counting">http://some.cgm.server/script </request> <error code="noRecordsMatch" /> </CGM>

Verb History

Substantial reworking and extension of Dienst verb SearchBoolean, version 5.0.