/ 
Webservice-InterMine-0.9601
River stage one • 1 direct dependent • 1 total dependent
/ Webservice::InterMine::Cookbook::Recipe1

NAME

Webservice::InterMine::Cookbook::Recipe1 - The Bare Basics

SYNOPSIS

# Get a list of the organisms in the database

use Webservice::InterMine ('www.flymine.org/query/service');

my $query = Webservice::InterMine->new_query();

# Specifying a name and a description is purely optional
$query->name('Tutorial 1 Query');
$query->description('A list of all the organisms in the database');

# The view specifies the output columns
$query->add_view('Organism.name');

print $query->results(as => 'string');

# Also get the taxon-id associated with the organism, and sort by id

$query->add_view('Organism.taxonId');

$query->set_sort_order('Organism.taxonId' => 'desc');

print $query->results(as => 'string');

DESCRIPTION

At its heart a query is just a description of what you want to get out of the database - and the first part of that is the view, which specifies the fields for each row of results you get back.

The view is a list of strings which represent 'paths' in Webservice::InterMine terminology. Organism.name is such a path, which says you want to know the name of each organism. The dotted notation resembles object notation on purpose, as in the background the database is populated by objects with fields, which themselves may have further fields. An example of this is Organism.chromosomes.name which refers to the name of a chromosome in an organism, or Organism.genes.name or Organism.chromosomes.genes.name, or Chromosome.organism.name, and so on.

Fields can be either attributes, like name in the above examples, which represent data fields, or references, like chromosomes, genes, or organism, which represent links to other objects in the database. Generally you will want to only have attributes in the view list.

The view list can be specified in a couple of ways, either as a list of paths, as in:

    $query->add_view('Organism.name', 'Organism.taxonId');

or as a space or comma delimited string, as in:

    $query->add_view('Organism.name Organism.taxonId');

or any mixture of the two. add_view can also be called multiple times, with each call appending the view(s) onto the list.

By default the results returned to you will be sorted by the values in the first column (the first item in the view list), and in an ascending direction. You can override this default by specifying any of the view columns to sort by. You do not have to specify a direction - asc will be the default if none is provided. The following are all(1) valid ways of defining the sort order, and would all have the same result:

$query->set_sort_order('Organism.taxonId');

or

$query->set_sort_order('Organism.taxonId', 'asc');

or

$query->set_sort_order('Organism.taxonId' => 'asc');

or

$query->set_sort_order(
    path => 'Organism.taxonId',
    direction => 'asc',
);

The two valid directions are 'asc' or 'desc' (case is irrelevant), and you must specify the view before you select the sort order.

Once we have a defined view, we have a valid query, which can be run and will return results. Without constraints these queries will just return every item of the specified type from the database, so these queries will list all organisms that the www.flymine.org database has data on. Obviously it is more useful to be able to specify which items you want, and for this we need constraints, which we deal with in the next recipe.

CONCLUSION

A query is at heart just a view list with (optionally) some constraints on the items you want back. This recipe demonstrates the mimimum you need to set up a valid query.

FOOTNOTES

1) Perl is famous for its philosophy of TIMTOWTDI (There is more than one way to do it) - and that is in evidence here as well: there are generally serveral ways to call the methods in the Perl API, and none is categorically right or wrong. In the above example with sort_order, you can see a progression from terser to more declarative styles; it is perhaps good practice to use declarative styles if you want your code to be robust and readable, and thus more maintainable.

SEE ALSO

http://www.intermine.org/perlapi

AUTHOR

Alex Kalderimis <perldev@flymine.org>

COPYRIGHT AND LICENSE

Copyright 2004-2010 by Webservice::InterMine

http://www.intermine.org

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.