Databases¶

Modules

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:

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