Databases¶
Wrappers for database frameworks¶
Contains AbstractDB
, an interface for databases.
Currently, implemented wrappers:
-
class
orion.core.io.database.
AbstractDB
(host=None, name=None, port=None, username=None, password=None, **kwargs)[source]¶ Bases:
object
Base class for database framework wrappers.
Attributes: - host : str
- It can be either:
- Known hostname or IP address in which database server resides.
- URI: A database framework specific connection string.
- name : str
Name of database containing experiments.
- port : int
Port that database server listens to for requests.
- username : str
Name of user with write/read permissions to database with name name.
- password : str
Secret phrase of user, username.
Methods
close_connection
()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_defaults
()Get database arguments needed to create a database instance. index_information
(collection_name)Return dict of names and sorting order of indexes initiate_connection
()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. -
close_connection
()[source]¶ Disconnect from database, if
AbstractDB
is_connected
.
-
count
(collection_name, query=None)[source]¶ Count the number of documents in a collection which match the query.
Parameters: - collection_name : str
A collection inside database, a table.
- query : dict
Filter entries in collection.
-
ensure_index
(collection_name, keys, unique=False)[source]¶ Create given indexes if they do not already exist in database.
Parameters: - collection_name : str
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.
-
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.
-
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.
-
initiate_connection
()[source]¶ Connect to database, unless
AbstractDB
is_connected
.Raises: - DatabaseError
If connection or authentication fails
-
is_connected
¶ True, if practical connection has been achieved.
-
read
(collection_name, query=None, selection=None)[source]¶ Read a collection and return a value according to the query.
Parameters: - collection_name : str
A collection inside database, a table.
- query : dict, optional
Filter entries in collection.
- selection : dict, optional
Elements of matched entries to return, the projection.
Returns: - list
List of matched document[s]
-
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_name : str
A collection inside database, a table.
- query : dict
Filter entries in collection.
- data : dict or list of dicts
New data that will update the entry.
- selection : dict, 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.
-
remove
(collection_name, query)[source]¶ Delete from a collection document[s] which match the query.
Parameters: - collection_name : str
A collection inside database, a table.
- query : dict
Filter entries in collection.
Returns: - int
Number of documents removed
-
write
(collection_name, data, query=None)[source]¶ Write new information to a collection. Perform insert or update.
Parameters: - collection_name : str
A collection inside database, a table.
- data : dict or list of dicts
New data that will be inserted or that will update entries.
- query : dict, 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
(host=None, name=None, port=None, username=None, password=None, **kwargs)[source]¶ Bases:
orion.core.io.database.AbstractDB
Class used to inject dependency on a database framework.
Attributes: - instance
-
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.