Databases¶
Wrappers for database frameworks¶
Contains AbstractDB
, an interface for databases.
Currently, implemented wrappers:
-
class
orion.core.io.database.
AbstractDB
(*args, **kwargs)[source]¶ Bases:
object
Base class for database framework wrappers.
- Attributes
- hoststr
- It can be either:
Known hostname or IP address in which database server resides.
URI: A database framework specific connection string.
- namestr
Name of database containing experiments.
- portint
Port that database server listens to for requests.
- usernamestr
Name of user with write/read permissions to database with name name.
- passwordstr
Secret phrase of user, username.
Methods
Disconnect from database, if
AbstractDB
is_connected
.count
(collection_name[, query])Count the number of documents in a collection which match the query.
drop_index
(collection_name, name)Remove index from the database
ensure_index
(collection_name, keys[, unique])Create given indexes if they do not already exist in database.
Get database arguments needed to create a database instance.
index_information
(collection_name)Return dict of names and sorting order of indexes
Connect to database, unless
AbstractDB
is_connected
.read
(collection_name[, query, selection])Read a collection and return a value according to the query.
read_and_write
(collection_name, query, data)Read a collection’s document and update the found document.
remove
(collection_name, query)Delete from a collection document[s] which match the query.
write
(collection_name, data[, query])Write new information to a collection.
-
abstract
close_connection
()[source]¶ Disconnect from database, if
AbstractDB
is_connected
.
-
abstract
count
(collection_name, query=None)[source]¶ Count the number of documents in a collection which match the query.
- Parameters
- collection_namestr
A collection inside database, a table.
- querydict
Filter entries in collection.
-
abstract
ensure_index
(collection_name, keys, unique=False)[source]¶ Create given indexes if they do not already exist in database.
- Parameters
- collection_namestr
A collection inside database, a table.
- keys: str or list of tuples
Can be a string representing a key to index, or a list of tuples with the structure [(key_name, sort_order)]. key_name must be a string and sort_order can be either
AbstractDB.ASCENDING
orAbstractDB.DESCENDING
.- unique: bool, optional
Ensure each document have a different key value. If not, operations like write() and read_and_write() will raise
DuplicateKeyError
. Defaults to False.
Notes
Depending on the backend, the indexing operation might operate in background. This means some operations on the database might occur before the indexes are totally built.
-
abstract classmethod
get_defaults
()[source]¶ Get database arguments needed to create a database instance.
- Returns
- dict
A dictionary mapping an argument name to a default value. If unexpected, default value can be None.
-
abstract
index_information
(collection_name)[source]¶ Return dict of names and sorting order of indexes
- Returns
- dict
Dictionary of indexes where each key is the name in the format {name}_{order} and each value represents whether the index is unique.
-
abstract
initiate_connection
()[source]¶ Connect to database, unless
AbstractDB
is_connected
.- Raises
- DatabaseError
If connection or authentication fails
-
abstract property
is_connected
¶ True, if practical connection has been achieved.
-
abstract
read
(collection_name, query=None, selection=None)[source]¶ Read a collection and return a value according to the query.
- Parameters
- collection_namestr
A collection inside database, a table.
- querydict, optional
Filter entries in collection.
- selectiondict, optional
Elements of matched entries to return, the projection.
- Returns
- list
List of matched document[s]
-
abstract
read_and_write
(collection_name, query, data, selection=None)[source]¶ Read a collection’s document and update the found document.
If many documents are found, the first one is selected.
Returns the updated document, or None if nothing found.
- Parameters
- collection_namestr
A collection inside database, a table.
- querydict
Filter entries in collection.
- datadict or list of dicts
New data that will update the entry.
- selectiondict, optional
Elements of matched entries to return, the projection.
- Returns
- dict or None
Updated first matched document or None if nothing found
- Raises
- DuplicateKeyError
If the operation is creating duplicate keys in two different documents. Only occurs if the keys have unique indexes. See
AbstractDB.ensure_index()
for more information about indexes.
-
abstract
remove
(collection_name, query)[source]¶ Delete from a collection document[s] which match the query.
- Parameters
- collection_namestr
A collection inside database, a table.
- querydict
Filter entries in collection.
- Returns
- int
Number of documents removed
-
abstract
write
(collection_name, data, query=None)[source]¶ Write new information to a collection. Perform insert or update.
- Parameters
- collection_namestr
A collection inside database, a table.
- datadict or list of dicts
New data that will be inserted or that will update entries.
- querydict, optional
Assumes an update operation: filter entries in collection to be updated.
- Returns
- int
Number of new documents if no query, otherwise number of modified documents.
- Raises
- DuplicateKeyError
If the operation is creating duplicate keys in two different documents. Only occurs if the keys have unique indexes. See
AbstractDB.ensure_index()
for more information about indexes.
Notes
In the case of an insert operation, data variable will be updated to contain a unique _id key.
In the case of an update operation, if query fails to find a document that matches, no operation is performed.
-
class
orion.core.io.database.
Database
(*args, **kwargs)[source]¶ Bases:
orion.core.io.database.AbstractDB
Class used to inject dependency on a database framework.
-
exception
orion.core.io.database.
DatabaseError
[source]¶ Bases:
RuntimeError
Exception type used to delegate responsibility from any database implementation’s own Exception types.
-
exception
orion.core.io.database.
DatabaseTimeout
[source]¶ Bases:
orion.core.io.database.DatabaseError
Exception type used when there is a timeout during database operations.
-
exception
orion.core.io.database.
DuplicateKeyError
[source]¶ Bases:
orion.core.io.database.DatabaseError
Exception type used when a write attempt is made but the new document have an index already contained in the database.
-
exception
orion.core.io.database.
OutdatedDatabaseError
[source]¶ Bases:
orion.core.io.database.DatabaseError
Exception type used when the database is outdated.