Databases

Wrappers for database frameworks

Contains Database, an interface for databases.

Database objects can be created using database_factory.create(). See orion.core.utils.GenericFactory for more information on the factory.

class orion.core.io.database.Database(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:
  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()

Disconnect from database, if Database 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 Database 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 Database is_connected.

abstract 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.

abstract drop_index(collection_name, name)[source]

Remove index from the database

Parameters
collection_name: str

A collection inside database, a table.

name: str

Index name in the format {name}_{order}

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 Database.ASCENDING or Database.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

Parameters
collection_name: str

A collection inside database, a table.

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 Database 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_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]

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_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 Database.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_name: str

A collection inside database, a table.

query: dict

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_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 Database.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.

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: DatabaseError

Exception type used when there is a timeout during database operations.

exception orion.core.io.database.DuplicateKeyError[source]

Bases: 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: 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.