methods.ringing.orgHome > For programmers > Query format

The query format

This page describes how to submit a query to the database and receive a response. For more information on the content of the response, see the XML format. The format of the query is closely related to that of the response.

The HTTP query and response

The database communicates with the outside world using HTTP, the same protocol as you are using to read this web page. This means that you can just type a query into your web browser and view the resulting XML document, which is helpful for getting to understand the system. When accessing the database from a program, you will probably want to use either one of our special libraries or a lightweight HTTP client library.

The URL used to reach the database begins like this:

http://methods.ringing.org/cgi-bin/simple.pl

This should be followed by a question mark ? and the query string, which specifies which methods you want to search for.

The response to this request consists of an HTTP status code and a content document. If everything went well, the content document will be an XML document containing the results of your query. If there is an error in the query string, the status code will be 400 and the content will be a plain text document describing what was wrong.

Examples

All this may sound rather complicated, so here are some simple examples. You can select any of these links in your browser; that will actually query the database and show you the result. Depending on your browser, you may need to select View source or something similar to see the XML markup in the result document.

The query string

The query string can be made up of several parts, separated by ampersands (&). Each part is either a search criterion or another instruction to the database server. For example, name=Pudsey is a search criterion asking the database to search for methods with name Pudsey; fields=title|stage|pn is an instruction specifying to the database what fields you want included in the XML for each method returned.

What follows is a simple description of how to write the query string. For more technical information on what is going on, look at the documentation for the Perl module DBIx::XMLServer on CPAN.

Each part of the query string is made up of two sections: the first selects a field, such as name or stage, or another option such as fields or page; the second section specifies something relating to that field, such as =Pudsey or =8.

Special options in the query string

Apart from search criteria, there are a few special options which can be included in the query string. We describe these first.

  • The option pagesize= sets the maximum number of methods to be returned from the query and should be followed by a number. By default this is set to 100, and you cannot set it to anything greater than 100.
  • The option page= tells the server which page of results to return, when there are too many methods to fit in one page. It should be followed by a number.
  • The fields= option allows you to control which parts of the XML structure are returned for each method. For example, using fields=title means that the resulting XML will look something like this:

    <?xml version="1.0"?>
    <methods xmlns="http://methods.ringing.org/NS/method" 
             xmlns:db="http://methods.ringing.org/NS/database" 
             version="0.1" db:page="0" db:pagesize="100" db:rows="4">
      <method id="m3995">
        <title>Pudsey Surprise Royal</title>
      </method>
      <method id="m4579">
        <title>Pudsey Surprise Maximus</title>
      </method>
      <method id="m4747">
        <title>Pudsey Surprise Fourteen</title>
      </method>
      <method id="m8457">
        <title>Pudsey Surprise Major</title>
      </method>
    </methods>
    

    In fact the part to the right of the equals sign is interpreted as an XPath expression which is evaluated in the context of a template method element. This means that to ask for several fields, you should combine them with a vertical bar character; for example fields=title|stage|pn might give the following result:

    <?xml version="1.0"?>
    <methods xmlns="http://methods.ringing.org/NS/method" 
             xmlns:db="http://methods.ringing.org/NS/database" 
             version="0.1" db:page="0" db:pagesize="100" db:rows="2">
      <method id="4329">
        <stage>12</stage>
        <title>Lindum Surprise Maximus</title>
        <pn>
          <symblock>-36-14-5T-16-14-3T-14-5T-14-5T-14-5T</symblock>
          <symblock>12</symblock>
        </pn>
      </method>
      <method id="5851">
        <stage>8</stage>
        <title>Lindum Surprise Major</title>
        <pn>
          <symblock>-36-14-58-16-14-38-14-58</symblock>
          <symblock>12</symblock>
        </pn>
      </method>
    </methods>
    

    This also means that you can select, say, the whole classification element and all its child elements by fields=classification.

  • The order= option specifies that the methods returned should be sorted. After the equals sign should come a list of sorting specifiers, separated by commas. Each sorting specifier is an expression selecting one or more fields, in exactly the same way as for the fields= option above; this may be followed by one of the words ascending or descending.

    For example, to put the methods in alphabetical order by their title, use order=title. To put them in reverse order by the date and time they were last modified, use order=meta/db:timestamp descending. To order by class and, within that, by first tower bell peal date, use order=classes,performances/firsttower/date.

Search criteria in the query string

A search criterion like name=Pudsey consists of two sections: the first section name selects which field is being examined, and the second section =Pudsey specifies what criterion is to be applied to that field. In fact the first section is an XPath expression, but all the possible fields are listed below. What may appear as the second section, the criterion, depends on what type of field is being examined. For example, a text field such as name may be searched using wildcards such as name=Br?stol (matching both Bristol and Brystol) or even regular expressions such as name~L[oi]nd.*um (matching both Lindum and Londinium.) A numeric field such as stage might be searched using stage=6 or stage>=14.

Text fields

The following parts of the XML structure are text fields. See the XML format for more information on what information each contains.

title
The method's title (name, classes and stage)
name
The method's name
classes
The method's classes (for example Surprise or Treble Place)
lead-head
The first lead head of the method
classification/cc-class/@class
The method's classes, in the format described in the cc-class element
classification/lhcode/@code
The method's Central Council lead head code
refs/rwref
A reference to the method's appearance in the Ringing World

Any of these fields can be searched in three ways. As an example, we use the field name.

  • Use an equals sign (=) to search for a given piece of text. You can use the wildcards * to stand for any sequence of zero or more characters, and ? to stand for any one character. For example, name=Br?stol matching both Bristol and Brystol; name=Camb*e matches Cambridge, Cambridgeshire and Camborne.
  • Use a tilde (~) to match against a regular expression. For example, name~L[oi]nd.*um matches both Lindum and Londinium.
  • Use just the field name on its own to search for methods where it is not null; for example, classification/lhcode/@code will find all regular methods.

Numeric fields

The following parts of the XML structure are numeric fields.

@id
The method's unique identifier in the database

Boolean fields

The following parts of the XML structure are Boolean (true or false) fields:

classification/cc-class/@little
Whether the method is Little
classification/cc-class/@differential
Whether the method is Differential

Either of these fields can be searched by the expressions =1, =y, =yes, =true, =0, =n, =no or =false. Specifying the field's name with no further expression is the same as searching for methods where the fields is true. For example, classification/cc-class/@little=true and classification/cc-class/@little both find Little methods.

Date or date-time fields

The following parts of the XML structure are date or date-time fields.

performances/firsttower/date
The date of the first tower bell peal of the method
performances/firsthand/date
The date of the first handbell peal of the method
meta/db:timestamp
The date and time when the database entry for this method was last updated

Any of these fields can be searched using any of the operators =, <, <=, >= and >. The date or time you want to compare with can be specified in almost any way you can think of. For example, performances/firsttower/date<1750 selects methods whose first tower bell peal was before 1750; performances/firsthand/date>1 year ago selects methods first rung to handbell peals in the last year; and meta/db:timestamp>noon last Tuesday selects all methods whose database entry has been updated since then.

Other fields

The stage field can be searched using any of the comparisons =, <, <=, >= and >. For example, stage=8 finds Major methods; stage<5 finds methods on four bells or fewer.

If you use =, you can give a comma-separated list of values to search for: for example, stage=8,10.

The @id field contains the method's unique identifier in the database. You can search by ID either by specifying a single ID, for example @id=m8457; or by specifying a space-separated list of IDs, for example @id=m8457 m4747. Remember that, in a URI-escaped string, a space can be writted as %20 or as +.

One very good reason to search by method ID is that it is fast. Suppose that your user has already searched for a list of methods and is now choosing one or more about which to get further information. If you remember the method IDs from the first request and use them in the second request, you will get a faster response than, say, searching by title.


Valid HTML 4.01!Valid CSS!Powered by MySQLPowered by LibXSLT

Comments to the Webmaster. Last updated 16 November 2005. This site is generously hosted by Mythic Beasts.