Databases¶

Modules

Wrappers for database frameworks¶

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

orion.core.io.database.mongodb.MongoDB

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

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

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 drop_index(collection_name, name)[source]¶: Remove index from the database

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

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]¶