Submit a Query

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] and value[n] enumerate, beginning with 1. For op[n], see below. [if we set a max value for n (in the 3-5 range), 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 :: an optional grouping construct, identical in definition to OAI's use. With CGM Search, however, multiple sets can be indicated in a single query by using a delimiter ( | ); for example: set=set1|set2|set3. When searching across multiple sets, the complete query is executed within each set (effectively OR'ing the sets). When no set is indicated, the default is either 1) all sets, when a repository supports sets, or 2) all repository content, when the repository does not support sets.
• sort :: a requested sort order for result sets. Default is rank. Possible values are:
  • rank [required] based on whatever relevance data is provided by the repository.
  • title
  • author
  • date
• 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 set to 0, no results will be returned, regardless of the value of resultSize.
• resultSize :: the number of result records requested. Value is an integer, 0 or greater; default is all results. If the value is set to 0, no results will be returned, regardless of the value of startResult.
• field[n] :: [required] Following is a list of permitted argument values. Those marked "[required]" must be supported (indexed).
  • title [required]
  • identifier
  • author [required]
  • pubtype [required] indicates whether monograph or serial
  • subject
  • language [required] use ISO639-1 or ISO639-2
  • fullbib [required]
  • abstract
  • pubdate [required]
  • publisher [required]
  • fulltext
• value[n] :: [required] the query string
• op[n] :: [required] op[n] will normally operate on n and n-1 field/value arguments. See the separate document on RPN Notation. Following is a list of permitted argument values. Those marked "[required]" must be supported.
  • and [required]
  • or [required]
  • not
  • within
  • including

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.

Operator Precedence: queries are assumed to be submitted using Reverse Polish Notation (RPN). See the separate document on RPN Notation

Response

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

A well-formed query that executes properly and yet has no matches is not considered an error. In this case, a resultsSummary would be returned, but no record elements.

• <resultsSummary> :: [required] an empty element with data about the results returned. All of the following attributes must be included, using defaults if not specified in request. These values describe the results actually returned; they may differ from values in the request.
  • set :: If no set was indicated in the response, then return either 1) a list of all sets searched, if sets are supported (set="set1|set2|set3"); or 2) an empty value, if sets are not supported (set="")
  • sort :: use default when not in request.
  • totalResults :: the total number of matches on a query, regardless of how many or which results are returned.
  • startResult :: the order of the first result returned in this response. Value is 0 when no results are returned.
  • resultSize :: the number of results returned in this response. This may be less than the resultSize requested, if there are fewer results than requested.
• <record> :: zero to many record elements allowed. Each contains the following elements:
  • <identifier> :: [required] the unique document identifier. Its format is determined by the repository.
  • <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, is missing required arguments, or contains invalid argument values.
• noSetHierarchy :: the repository does not support sets

Examples

Request

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

Response

<?xml version="1.0" encoding="UTF-8"?>
  <CGM>
    <responseDate>2002-10-01T19:20:30Z</responseDate>
    <request verb="Search" ver="1.0" set="math" resultSize="100"
             field1="author" value1="todhunter" field2="title"
             value2="trigonometry" op2="and">
             http://some.cgm.server/script</request>
    <Search ver="1.0">
      <resultsSummary set="math" sort="title" totalResults="2"
                      startResult="1" resultSize="2" />
      <record>
        <identifier>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>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
	&verb=Search&ver=1.0&set=math&startResult=0
	&field1=fulltext&value1=geometry&field2=fulltext
	&value2=trigonometry&op2=and

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

These two requests are equivalent. The response below is to the first one.

Response

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

Request

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

Response

<?xml version="1.0" encoding="UTF-8"?>
  <CGM>
    <responseDate>2002-10-02T19:20:30Z</responseDate>
    <request verb="Search" ver="1.0" set="math" field1="author"
             value1="bush"field2="fullbib" value2="basic counting"
             op2="and">http://some.cgm.server/script
             </request>
    <Search ver="1.0">
      <resultsSummary set="math" sort="title" totalResults="0"
                      startResult="0" resultSize="0" />
    </Search>
  </CGM>

Verb History

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

Display a Document in Local Viewer

Verb Description

Request to view a document in a repository's local viewer.

Arguments

• id :: the identifier for the document requested.

Response

A repository can display a document however it chooses.

Error Codes

• idDoesNotExist :: the value of the identifier argument is unknown or illegal.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Display&ver=1.0&id=cul.math/00640001

Verb History

New to CGM.