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.