Databases

Modules

orion.core.io.database – Wrappers for database frameworks

Contains AbstractDB, an interface for databases. Currently, implemented wrappers:

class orion.core.io.database.AbstractDB(host='localhost', 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:
  1. Known hostname or IP address in which database server resides.
  2. 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(self) Disconnect from database, if AbstractDB is_connected.
count(self, collection_name[, query]) Count the number of documents in a collection which match the query.
drop_index(self, collection_name, name) Remove index from the database
ensure_index(self, collection_name, keys[, …]) Create given indexes if they do not already exist in database.
index_information(self, collection_name) Return dict of names and sorting order of indexes
initiate_connection(self) Connect to database, unless AbstractDB is_connected.
read(self, collection_name[, query, selection]) Read a collection and return a value according to the query.
read_and_write(self, collection_name, query, …) Read a collection’s document and update the found document.
remove(self, collection_name, query) Delete from a collection document[s] which match the query.
write(self, collection_name, data[, query]) Write new information to a collection.
close_connection(self)[source]

Disconnect from database, if AbstractDB is_connected.

count(self, 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.
drop_index(self, collection_name, name)[source]

Remove index from the database

ensure_index(self, 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 or AbstractDB.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.

index_information(self, 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(self)[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(self, 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(self, 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(self, 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(self, 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='localhost', 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
is_connected

True, if practical connection has been achieved.

Methods

close_connection(self) Disconnect from database, if AbstractDB is_connected.
count(self, collection_name[, query]) Count the number of documents in a collection which match the query.
drop_index(self, collection_name, name) Remove index from the database
ensure_index(self, collection_name, keys[, …]) Create given indexes if they do not already exist in database.
index_information(self, collection_name) Return dict of names and sorting order of indexes
initiate_connection(self) Connect to database, unless AbstractDB is_connected.
read(self, collection_name[, query, selection]) Read a collection and return a value according to the query.
read_and_write(self, collection_name, query, …) Read a collection’s document and update the found document.
remove(self, collection_name, query) Delete from a collection document[s] which match the query.
write(self, collection_name, data[, query]) Write new information to a collection.
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.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.

class orion.core.io.database.ReadOnlyDB(database)[source]

Bases: object

Read-only view on a database.