LICENSE
Copyright [1999-2015] Wellcome Trust Sanger Institute and the EMBL-European Bioinformatics Institute Copyright [2016-2024] EMBL-European Bioinformatics Institute
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
CONTACT
Please email comments or questions to the public Ensembl
developers list at <http://lists.ensembl.org/mailman/listinfo/dev>.
Questions may also be sent to the Ensembl help desk at
<http://www.ensembl.org/Help/Contact>.NAME
Bio::EnsEMBL::DBSQL::BaseAdaptor - Base Adaptor for DBSQL adaptors
SYNOPSIS
# base adaptor provides
# SQL prepare function
$adaptor->prepare("sql statement");
# get of root DBAdaptor object
$adaptor->db();
# constructor, ok for inheritence
$adaptor = Bio::EnsEMBL::DBSQL::SubClassOfBaseAdaptor->new($dbobj);DESCRIPTION
This is a true base class for Adaptors in the Ensembl DBSQL system.
Adaptors are expected to have the following functions
$obj = $adaptor->fetch_by_dbID($internal_id);which builds the object from the primary key of the object. This function is crucial because it allows adaptors to collaborate relatively independently of each other - in other words, we can change the schema under one adaptor without too many knock on changes through the other adaptors.
Most adaptors will also have
$dbid = $adaptor->store($obj);which stores the object. Currently the storing of an object also causes the objects to set
$obj->dbID();correctly and attach the adaptor.
Other fetch functions go by the convention of
@object_array = @{ $adaptor->fetch_all_by_XXXX($arguments_for_XXXX) };sometimes it returns an array ref denoted by the 'all' in the name of the method, sometimes an individual object. For example
$gene = $gene_adaptor->fetch_by_stable_id($stable_id);or
@fp = @{ $simple_feature_adaptor->fetch_all_by_Slice($slice) };Occassionally adaptors need to provide access to lists of ids. In this case the convention is to go list_XXXX, such as
@gene_ids = @{ $gene_adaptor->list_geneIds() };(note: this method is poorly named)
new
Arg [1] : Bio::EnsEMBL::DBSQL::DBConnection $dbobj
Example : $adaptor = new AdaptorInheritedFromBaseAdaptor($dbobj);
Description: Creates a new BaseAdaptor object. The intent is that this
constructor would be called by an inherited superclass either
automatically or through $self->SUPER::new in an overridden
new method.
Returntype : Bio::EnsEMBL::DBSQL::BaseAdaptor
Exceptions : none
Caller : Bio::EnsEMBL::DBSQL::DBConnection
Status : Stableprepare
Arg [1] : string $string
a SQL query to be prepared by this adaptors database
Example : $sth = $adaptor->prepare("select yadda from blabla")
Description: provides a DBI statement handle from the adaptor. A convenience
function so you dont have to write $adaptor->db->prepare all the
time
Returntype : DBI::StatementHandle
Exceptions : none
Caller : Adaptors inherited from BaseAdaptor
Status : Stabledb
Arg [1] : (optional) Bio::EnsEMBL::DBSQL::DBAdaptor $obj
the database this adaptor is using.
Example : $db = $adaptor->db();
Description: Getter/Setter for the DatabaseConnection that this adaptor is
using.
Returntype : Bio::EnsEMBL::DBSQL::DBAdaptor
Exceptions : none
Caller : Adaptors inherited from BaseAdaptor
Status : Stabledbc
Arg [1] : (optional) Bio::EnsEMBL::DBSQL::DBConnection $obj
the database this adaptor is using.
Example : $db = $adaptor->db();
Description: Getter/Setter for the DatabaseConnection that this adaptor is
using.
Returntype : Bio::EnsEMBL::DBSQL::DBConnection
Exceptions : none
Caller : Adaptors inherited from BaseAdaptor
Status : Stableis_multispecies
Arg [1] : (optional) boolean $arg
Example : if ($adaptor->is_multispecies()) { }
Description: Getter/Setter for the is_multispecies boolean of
to use for this adaptor.
Returntype : boolean
Exceptions : none
Caller : general
Status : Stablespecies_id
Arg [1] : (optional) int $species_id
The internal ID of the species in a multi-species database.
Example : $db = $adaptor->db();
Description: Getter/Setter for the internal ID of the species in a
multi-species database. The default species ID is 1.
Returntype : Integer
Exceptions : none
Caller : Adaptors inherited from BaseAdaptor
Status : Stablebind_param_generic_fetch
Arg [1] : (optional) scalar $param
This is the parameter to bind
Arg [2] : (optional) int $sql_type
Type of the parameter (from DBI (:sql_types))
Example : $adaptor->bind_param_generic_fetch($stable_id,SQL_VARCHAR);
$adaptor->generic_fetch();
Description: When using parameters for the query, will call the bind_param to avoid
some security issues. If there are no arguments, will return the bind_parameters
ReturnType : listref
Exceptions: if called with one argumentgenerate_in_constraint
Arg [1] : ArrayRef or Scalar $list
List or a single value of items to be pushed into an IN statement
Arg [2] : Scalar $column
Column this IN statement is being applied to. Please fully resolve the
column.
Arg [3] : Scalar $param_type
Data type which should be used when binding. Please use DBI data type symbols
Arg [4] : Scalar boolean $inline_variables
Boolean to control if variables are inlined in the constraint. If
false values are bound via bind_param_generic_fetch() (the default behaviour).
Description : Used internally to generate a SQL constraint to restrict a query by an IN statement.
The code generates the complete IN statement.
Returntype : String
Exceptions : If no list is supplied, the list of values is empty or no data type was given
Caller : generalgeneric_fetch
Arg [1] : (optional) string $constraint
An SQL query constraint (i.e. part of the WHERE clause)
Arg [2] : (optional) Bio::EnsEMBL::AssemblyMapper $mapper
A mapper object used to remap features
as they are retrieved from the database
Arg [3] : (optional) Bio::EnsEMBL::Slice $slice
A slice that features should be remapped to
Example : $fts = $a->generic_fetch('contig_id in (1234, 1235)');
Description: Performs a database fetch and returns feature objects in
contig coordinates.
Returntype : listref of Bio::EnsEMBL::SeqFeature in contig coordinates
Exceptions : Thrown if there is an issue with querying the data
Caller : BaseFeatureAdaptor, ProxyDnaAlignFeatureAdaptor::generic_fetch
Status : Stablegeneric_count
Arg [1] : (optional) string $constraint
An SQL query constraint (i.e. part of the WHERE clause)
Example : $number_feats = $a->generic_count('contig_id in (1234, 1235)');
Description: Performs a database fetch and returns a count of those features
found. This is analagous to C<generic_fetch()>
Returntype : Integer count of the elements.
Exceptions : Thrown if there is an issue with querying the datafetch_by_dbID
Arg [1] : int $id
The unique database identifier for the feature to be obtained
Example : $feat = $adaptor->fetch_by_dbID(1234));
$feat = $feat->transform('contig');
Description: Returns the feature created from the database defined by the
the id $id. The feature will be returned in its native
coordinate system. That is, the coordinate system in which it
is stored in the database. In order to convert it to a
particular coordinate system use the transfer() or transform()
method. If the feature is not found in the database then
undef is returned instead
Returntype : Bio::EnsEMBL::Feature or undef
Exceptions : thrown if $id arg is not provided
does not exist
Caller : general
Status : Stablefetch_all_by_dbID_list
Arg [1] : listref of integers $id_list
The unique database identifiers for the features to
be obtained.
Arg [2] : optional - Bio::EnsEMBL::Slice to map features onto.
Example : @feats = @{$adaptor->fetch_all_by_dbID_list([1234, 2131, 982]))};
Description: Returns the features created from the database
defined by the the IDs in contained in the provided
ID list $id_list. The features will be returned
in their native coordinate system. That is, the
coordinate system in which they are stored in the
database. In order to convert the features to a
particular coordinate system use the transfer() or
transform() method. If none of the features are
found in the database a reference to an empty list is
returned.
Returntype : listref of Bio::EnsEMBL::Features
Exceptions : thrown if $id arg is not provided
does not exist
Caller : general
Status : Stable_uncached_fetch_all_by_id_list
Arg [1] : listref of IDs
Arg [2] : (optional) Bio::EnsEMBL::Slice $slice
A slice that features should be remapped to
Arg [3] : String describing the ID type.
Valid values include dbID and stable_id. dbID is an alias for
the primary key, while other names map directly to table columns
of the Feature this adaptor manages.
Arg [4] : Boolean $numeric
Indicates if the incoming data is to be processed as a numeric
or as a String. If arg [3] was set to dbID then we default this to
be true. If arg [3] was set to stable_id then we default this to
be false.
When not using a standard arg[3] the IDs are assumed to be Strings.
Arg [5] : Integer $max_size
Control the maximum number of IDs sent to a database in a single
query. Defaults to 2K for Strings and 16K for integers. Only
provide if you know *exactly* why you need to edit it.
Example : $list_of_features = $adaptor->_uncached_fetch_all_by_id_list(
[qw(ENSG00000101321 ENSG00000101346 ENSG00000101367)],
undef,
"stable_id", 0); #using strings
# Numeric set to true because we are using numerics
$list_of_features = $adaptor->_uncached_fetch_all_by_id_list(
[1,2,3,4],
undef,
"dbID", 1);
# Numeric defaults to true because we are querying using dbID
$list_of_features = $adaptor->_uncached_fetch_all_by_id_list(
[1,2,3,4],
undef,
"dbID");
Description: This is a generic method used to fetch lists of features by IDs.
It avoids caches, meaning it is best suited for block fetching.
See fetch_all_by_dbID_list() for more info.
Returntype : ArrayRef of Bio::EnsEMBL::Feature
Exceptions : Thrown if a list of IDs is not supplied.
Caller : BaseFeatureAdaptor, BaseAdaptor and derived classes.last_insert_id
Arg [1] : (optional) $field the name of the field the inserted ID was pushed
into
Arg [2] : (optional) HashRef used to pass extra attributes through to the
DBD driver
Arg [3] : (optional) $table the name of the table to use if the adaptor
does not implement C<_tables()>
Description : Delegating method which uses DBI to extract the last inserted
identifier. If using MySQL we just call the DBI method
L<DBI::last_insert_id()> since MySQL ignores any extra
arguments. See L<DBI> for more information about this
delegated method.
Example : my $id = $self->last_insert_id('my_id'); my $other_id = $self->last_insert_id();
Returntype : Scalar or undef
insert_ignore_clause
_id_cache
Description : Used to return an instance of a support BaseCache module
which can be used to speed up object access. The method
also respects the DBAdaptor's no_cache() flag and will
return undef in those situations
Example : my $cache = $self->_id_cache();
Returntype : Bio::EnsEMBL::DBSQL::Support::BaseCache
_no_id_cache
Description : Flags if the ID based caching is active or not. This could be
due to the adaptor not wanting to cache or because of
a global no_cache() flag on the DBAdaptor instance
Returntype : Boolean
ignore_cache_override
Description : Method to interfere with no_cache directive from Registry on
a per adaptor basis. This method should be called after new()
in order to trigger the _build_id_cache at first query.
Example : $adaptor->ignore_cache_override(1);
Returntype : Booleanschema_version
Description : Returns the schema version of the currently connected
DBAdaptor. The subroutine also caches this value so
repeated calls continue to be speedy.
Example : $adaptor->schema_version();
Returntype : Integer