MotorDatabase

class motor.motor_tornado.MotorDatabase(client, name, _delegate=None)
db[collection_name] || db.collection_name

Get the collection_name MotorCollection of MotorDatabase db.

Raises InvalidName if an invalid collection name is used.

add_son_manipulator(manipulator)

Add a new son manipulator to this database.

Newly added manipulators will be applied before existing ones.

Parameters:
  • manipulator: the manipulator to add
coroutine add_user(name, password=None, read_only=None, callback=None, **kwargs)

Create user name with password password.

Add a new user with permissions for this Database.

Note

Will change the password if user name already exists.

Parameters:
  • name: the name of the user to create
  • password (optional): the password of the user to create. Can not be used with the userSource argument.
  • read_only (optional): if True the user will be read only
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

  • **kwargs (optional): optional fields for the user document (e.g. userSource, otherDBRoles, or roles). See http://docs.mongodb.org/manual/reference/privilege-documents for more information.

Note

The use of optional keyword arguments like userSource, otherDBRoles, or roles requires MongoDB >= 2.4.0

If a callback is passed, returns None, else returns a Future.

coroutine authenticate(name=None, password=None, source=None, mechanism='DEFAULT', callback=None, **kwargs)

Authenticate to use this database.

Authentication lasts for the life of the underlying client instance, or until logout() is called.

Raises TypeError if (required) name, (optional) password, or (optional) source is not an instance of basestring (str in python 3).

Note

  • This method authenticates the current connection, and will also cause all new socket connections in the underlying client instance to be authenticated automatically.
  • Authenticating more than once on the same database with different credentials is not supported. You must call logout() before authenticating with new credentials.
  • When sharing a client instance between multiple threads, all threads will share the authentication. If you need different authentication profiles for different purposes you must use distinct client instances.
Parameters:
  • name: the name of the user to authenticate. Optional when mechanism is MONGODB-X509 and the MongoDB server version is >= 3.4.
  • password (optional): the password of the user to authenticate. Not used with GSSAPI or MONGODB-X509 authentication.
  • source (optional): the database to authenticate on. If not specified the current database is used.
  • mechanism (optional): See MECHANISMS for options. By default, use SCRAM-SHA-1 with MongoDB 3.0 and later, MONGODB-CR (MongoDB Challenge Response protocol) for older servers.
  • authMechanismProperties (optional): Used to specify authentication mechanism specific options. To specify the service name for GSSAPI authentication pass authMechanismProperties=’SERVICE_NAME:<service name>’
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

See general MongoDB documentation

authenticate

If a callback is passed, returns None, else returns a Future.

coroutine collection_names(include_system_collections=True, callback=None)

Get a list of all the collection names in this database.

Parameters:
  • include_system_collections (optional): if False list will not include system collections (e.g system.indexes)
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine command(command, value=1, check=True, allowable_errors=None, read_preference=Primary(), codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=None), callback=None, **kwargs)

Issue a MongoDB command.

Send command command to the database and return the response. If command is a string then the command {command: value} will be sent. Otherwise, command must be a dict and will be sent as-is.

Additional keyword arguments are added to the final command document before it is sent.

For example, a command like {buildinfo: 1} can be sent using:

result = yield db.command("buildinfo")

For a command where the value matters, like {collstats: collection_name} we can do:

result = yield db.command("collstats", collection_name)

For commands that take additional arguments we can use kwargs. So {filemd5: object_id, root: file_root} becomes:

result = yield db.command("filemd5", object_id, root=file_root)
Parameters:
  • command: document representing the command to be issued, or the name of the command (for simple commands only).

    Note

    the order of keys in the command document is significant (the “verb” must come first), so commands which require multiple keys (e.g. findandmodify) should use an instance of SON or a string and kwargs instead of a Python dict.

  • value (optional): value to use for the command verb when command is passed as a string

  • check (optional): check the response for errors, raising OperationFailure if there are any

  • allowable_errors: if check is True, error messages in this list will be ignored by error-checking

  • read_preference: The read preference for this operation. See read_preferences for options.

  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

  • **kwargs (optional): additional keyword arguments will be added to the command document before it is sent

See general MongoDB documentation

commands

If a callback is passed, returns None, else returns a Future.

coroutine create_collection(name, codec_options=None, read_preference=None, write_concern=None, read_concern=None, callback=None, **kwargs)

Create a new Collection in this database.

Normally collection creation is automatic. This method should only be used to specify options on creation. CollectionInvalid will be raised if the collection already exists.

Options should be passed as keyword arguments to this method. Supported options vary with MongoDB release. Some examples include:

  • “size”: desired initial size for the collection (in bytes). For capped collections this size is the max size of the collection.
  • “capped”: if True, this is a capped collection
  • “max”: maximum number of objects if capped (optional)

See the MongoDB documentation for a full list of supported options by server version.

Parameters:
  • name: the name of the collection to create
  • codec_options (optional): An instance of CodecOptions. If None (the default) the codec_options of this Database is used.
  • read_preference (optional): The read preference to use. If None (the default) the read_preference of this Database is used.
  • write_concern (optional): An instance of WriteConcern. If None (the default) the write_concern of this Database is used.
  • read_concern (optional): An instance of ReadConcern. If None (the default) the read_concern of this Database is used.
  • collation (optional): An instance of Collation.
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

  • **kwargs (optional): additional keyword arguments will be passed as options for the create collection command

If a callback is passed, returns None, else returns a Future.

coroutine current_op(include_all=False, callback=None)

Get information on operations currently running.

Parameters:
  • include_all (optional): if True also list currently idle operations in the result
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine dereference(dbref, callback=None, **kwargs)

Dereference a DBRef, getting the document it points to.

Raises TypeError if dbref is not an instance of DBRef. Returns a document, or None if the reference does not point to a valid document. Raises ValueError if dbref has a database specified that is different from the current database.

Parameters:
  • dbref: the reference
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

  • **kwargs (optional): any additional keyword arguments are the same as the arguments to find().

If a callback is passed, returns None, else returns a Future.

coroutine drop_collection(name_or_collection, callback=None)

Drop a collection.

Parameters:
  • name_or_collection: the name of a collection to drop or the collection object itself
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

Note

The write_concern of this database is automatically applied to this operation when using MongoDB >= 3.4.

If a callback is passed, returns None, else returns a Future.

coroutine error(callback=None)

OBSOLETE

Parameters :
    callback (optional): function taking (result, error), executed when operation completescallback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine eval(code, callback=None, *args)

Evaluate a JavaScript expression in MongoDB.

Useful if you need to touch a lot of data lightly; in such a scenario the network transfer of the data could be a bottleneck. The code argument must be a JavaScript function. Additional positional arguments will be passed to that function when it is run on the server.

Raises TypeError if code is not an instance of basestring (str in python 3) or Code. Raises OperationFailure if the eval fails. Returns the result of the evaluation.

Parameters:
  • code: string representation of JavaScript code to be evaluated
  • args (optional): additional positional arguments are passed to the code being evaluated
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

Warning

the eval command is deprecated in MongoDB 3.0 and will be removed in a future server version.

If a callback is passed, returns None, else returns a Future.

get_collection(name, codec_options=None, read_preference=None, write_concern=None, read_concern=None)

Get a Collection with the given name and options.

Useful for creating a Collection with different codec options, read preference, and/or write concern from this Database.

>>> db.read_preference
Primary()
>>> coll1 = db.test
>>> coll1.read_preference
Primary()
>>> from pymongo import ReadPreference
>>> coll2 = db.get_collection(
...     'test', read_preference=ReadPreference.SECONDARY)
>>> coll2.read_preference
Secondary(tag_sets=None)
Parameters:
  • name: The name of the collection - a string.
  • codec_options (optional): An instance of CodecOptions. If None (the default) the codec_options of this Database is used.
  • read_preference (optional): The read preference to use. If None (the default) the read_preference of this Database is used. See read_preferences for options.
  • write_concern (optional): An instance of WriteConcern. If None (the default) the write_concern of this Database is used.
  • read_concern (optional): An instance of ReadConcern. If None (the default) the read_concern of this Database is used.
coroutine last_status(callback=None)

OBSOLETE

Parameters :
    callback (optional): function taking (result, error), executed when operation completescallback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine logout(callback=None)

Deauthorize use of this database for this client instance.

Parameters :
    callback (optional): function taking (result, error), executed when operation completescallback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine previous_error(callback=None)

OBSOLETE

Parameters :
    callback (optional): function taking (result, error), executed when operation completescallback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine profiling_info(callback=None)

Returns a list containing current profiling information.

See general MongoDB documentation

profiling

Parameters :
    callback (optional): function taking (result, error), executed when operation completescallback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine profiling_level(callback=None)

Get the database’s current profiling level.

Returns one of (OFF, SLOW_ONLY, ALL).

See general MongoDB documentation

profiling

Parameters :
    callback (optional): function taking (result, error), executed when operation completescallback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine remove_user(name, callback=None)

Remove user name from this Database.

User name will no longer have permissions to access this Database.

Parameters:
  • name: the name of the user to remove
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine reset_error_history(callback=None)

OBSOLETE

Parameters :
    callback (optional): function taking (result, error), executed when operation completescallback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

coroutine set_profiling_level(level, slow_ms=None, callback=None)

Set the database’s profiling level.

Parameters:
  • level: Specifies a profiling level, see list of possible values below.
  • slow_ms: Optionally modify the threshold for the profile to consider a query or operation. Even if the profiler is off queries slower than the slow_ms level will get written to the logs.
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

Possible level values:

Level Setting
OFF Off. No profiling.
SLOW_ONLY On. Only includes slow operations.
ALL On. Includes all operations.

Raises ValueError if level is not one of (OFF, SLOW_ONLY, ALL).

See general MongoDB documentation

profiling

If a callback is passed, returns None, else returns a Future.

coroutine validate_collection(name_or_collection, scandata=False, full=False, callback=None)

Validate a collection.

Returns a dict of validation info. Raises CollectionInvalid if validation fails.

Parameters:
  • name_or_collection: A Collection object or the name of a collection to validate.
  • scandata: Do extra checks beyond checking the overall structure of the collection.
  • full: Have the server do a more thorough scan of the collection. Use with scandata for a thorough scan of the structure of the collection and the individual documents.
  • callback (optional): function taking (result, error), executed when operation completes

  • callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

client

This MotorDatabase’s MotorClient.

codec_options

Read only access to the CodecOptions of this instance.

incoming_copying_manipulators

All incoming SON copying manipulators installed on this instance.

New in version 2.0.

incoming_manipulators

All incoming SON manipulators installed on this instance.

New in version 2.0.

name

The name of this Database.

outgoing_copying_manipulators

List all outgoing SON copying manipulators installed on this instance.

New in version 2.0.

outgoing_manipulators

List all outgoing SON manipulators installed on this instance.

New in version 2.0.

read_concern

Read only access to the read concern of this instance.

New in version 3.2.

read_preference

Read only access to the read preference of this instance.

Changed in version 3.0: The read_preference attribute is now read only.

write_concern

Read only access to the WriteConcern of this instance.

Changed in version 3.0: The write_concern attribute is now read only.