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.
|
Home > For programmers > Query format
