NAME

Bio::DB::Query::BioQuery - Object representing a query on a bioperldb

SYNOPSIS

  # generally
  $q = Bio::DB::Query::BioQuery->new;
  $q->where(["AND", "attA=x", "attB=y", "attC=y"]);
  $adaptor->fetch_by_query($q);

  # more specific example in the context of biosql:
  $query = Bio::DB::Query::BioQuery->new();

  # all mouse sequences loaded under namespace ensembl that
  # have receptor in their description
  $query->datacollections(["Bio::PrimarySeqI e",
                         "Bio::Species => Bio::PrimarySeqI sp",
                         "BioNamespace => Bio::PrimarySeqI db"]);
  $query->where(["sp.binomial like 'Mus *'",
                      "e.desc like '*receptor*'",
                 "db.namespace = 'ensembl'"]);

  # all mouse sequences loaded under namespace ensembl that
  # have receptor in their description, and that also have a
  # cross-reference with SWISS as the database
  $query->datacollections(["Bio::PrimarySeqI e",
                         "Bio::Species => Bio::PrimarySeqI sp",
                         "BioNamespace => Bio::PrimarySeqI db",
                         "Bio::Annotation::DBLink xref",
                         "Bio::PrimarySeqI <=> Bio::Annotation::DBLink"]);
  $query->where(["sp.binomial like 'Mus *'",
                      "e.desc like '*receptor*'",
                      "db.namespace = 'ensembl'",
                      "xref.database = 'SWISS'"]);

  # find a bioentry by primary key
  $query->datacollections(["Bio::PrimarySeqI]);
  $query->where(["Bio::PrimarySeqI::primary_key = 10"]);

  # all bioentries in a sequence cluster (Hs.2 as an example)
  $query->datacollections(
                  ["Bio::PrimarySeqI c::subject",
                   "Bio::PrimarySeqI p::object",
                   "Bio::PrimarySeqI<=>Bio::ClusterI<=>Bio::Ontology::TermI"]);
  $query->where(["p.accession_number = 'Hs.2'",
                 "Bio::Ontology::TermI::name = 'cluster member'"]);

DESCRIPTION

A BioQuery is a high level query on a biological database. It allows queries to be specified regardless of the underlying schema. Although a BioQuery can be translated into a corresponding SQL query or series of SQL queries, it is not always desirable to do so; rather the BioQuery should be translated into SQL querys one at a time, the SQL query executed and the results fed back to the BioQuery processor.

It is the job of the various adaptors to turn BioQuerys into resulting Bio objects via these transformations.

A BioQuery can be specified either as a text string which is converted into a BioQuery object via some grammar, or the object can be created and manipulated directly. The text string would be some kind of language like SQL, one can imagine different languages with different grammars.

Other than being more high level, a BioQuery differs from a SQL Query in that it is object based, not table based.

The BioQuery is a schema-independent representation of a query; it may or may not be tied to the bioperl object model.

STATUS

There is no parser to turn statements like

  "FETCH Seq.* from Seq where species='Human'"

into a BioQuery object; objects have to be built manually

At the moment, everything in this object apart from the query constraints (the $bioquery->where() method) are ignored.

CONTACT

Chris Mungall, cmungall@fruitfly.org

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

new

  Usage:  $bioq = $self->new(-select => ["att1", "att2"],
                                            -where  => ["att3='val1'", "att4='val4'"]);

      OR  $bioq = $self->new(-where => {species=>'human'});

          # NOT IMPLEMENTED:
          $bioq = $self->new("SELECT bioentry.* FROM bioentry WHERE species='Human'");  

  Args: objects, where, select, order, group

        All arguments are optional (select defaults to *).

        The arguments can either be array references or a comma delimited string.

        The where argument can also be passed as a hash reference.

        The from/objects array is optional because this is usually derived
        from the context eg the database adapter used. if used outside this
        context the object is required.

translate_query

 Title   : translate_query
 Usage   :
 Function: Translates this query from objects and class names and
           slot names to tables and column names.

           You will most likely have to call this method before being
           able to generate meaningful SQL from a BioQuery object.

 Example :
 Returns : An object of the same class as this query, but representing
           the translated query.
 Args    : The L<Bio::DB::Persistent::ObjectRelMapperI> to use.
           Optionally, a reference to an empty hash. If provided, upon
           return it will hold a mapping from tables to aliases.

Contact Hilmar Lapp, hlapp at gmx.net, for questions, bugs, flames, praises etc.

Off records, this implementation has grown hideous. It needs to be rewritten. The problem is, it''s not an easy task, and it works currently as far as I can tell ...