`AsyncIOMotorDatabase`¶

class motor.motor_asyncio.AsyncIOMotorDatabase(client, name, **kwargs)¶

db[collection_name] || db.collection_name

Get the collection_name AsyncIOMotorCollection of AsyncIOMotorDatabase 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, session=None, **kwargs)¶

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

Note

add_user is deprecated and will be removed in PyMongo 4.0. Starting with MongoDB 2.6 user management is handled with four database commands, createUser, usersInfo, updateUser, and dropUser.

To create a user:

db.command("createUser", "admin", pwd="password", roles=["root"])

To create a read-only user:

db.command("createUser", "user", pwd="password", roles=["read"])

To change a password:

db.command("updateUser", "user", pwd="newpassword")

Or change roles:

db.command("updateUser", "user", roles=["readWrite"])

Warning

Never create or modify users over an insecure network without the use of TLS. See examples/tls for more information.

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
**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.
session (optional): a ClientSession.

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

DEPRECATED: Authenticate to use this database.

Warning

Starting in MongoDB 3.6, calling authenticate() invalidates all existing cursors. It may also leave logical sessions open on the server for up to 30 minutes until they time out.

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. If no mechanism is specified, PyMongo automatically uses MONGODB-CR when connected to a pre-3.0 version of MongoDB, SCRAM-SHA-1 when connected to MongoDB 3.0 through 3.6, and negotiates the mechanism to use (SCRAM-SHA-1 or SCRAM-SHA-256) when connected to MongoDB 4.0+.
authMechanismProperties (optional): Used to specify authentication mechanism specific options. To specify the service name for GSSAPI authentication pass authMechanismProperties=’SERVICE_NAME:<service name>’

See also

The MongoDB documentation on

authenticate

coroutine collection_names(include_system_collections=True, session=None)¶

DEPRECATED: 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`) session (optional): a `ClientSession`.

coroutine command(command, value=1, check=True, allowable_errors=None, read_preference=None, codec_options=CodecOptions(document_class=dict, tz_aware=False, uuid_representation=PYTHON_LEGACY, unicode_decode_error_handler='strict', tzinfo=None, type_registry=TypeRegistry(type_codecs=[], fallback_encoder=None)), session=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.
session (optional): a ClientSession, created with start_session().
**kwargs (optional): additional keyword arguments will be added to the command document before it is sent

Changed in version 1.2: Added session parameter.

See also

The MongoDB documentation on

commands

coroutine create_collection(name, codec_options=None, read_preference=None, write_concern=None, read_concern=None, session=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.
session (optional): a ClientSession.
**kwargs (optional): additional keyword arguments will be passed as options for the create collection command

coroutine current_op(include_all=False, session=None)¶

DEPRECATED: Get information on operations currently running.

Starting with MongoDB 3.6 this helper is obsolete. The functionality provided by this helper is available in MongoDB 3.6+ using the $currentOp aggregation pipeline stage, which can be used with aggregate(). Note that, while this helper can only return a single document limited to a 16MB result, aggregate() returns a cursor avoiding that limitation.

Users of MongoDB versions older than 3.6 can use the currentOp command directly:

# MongoDB 3.2 and 3.4
client.admin.command("currentOp")

Or query the “inprog” virtual collection:

# MongoDB 2.6 and 3.0
client.admin["$cmd.sys.inprog"].find_one()

Parameters:	include_all (optional): if `True` also list currently idle operations in the result session (optional): a `ClientSession`.

coroutine dereference(dbref, session=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 session (optional): a `ClientSession`. **kwargs (optional): any additional keyword arguments are the same as the arguments to `find()`.

coroutine drop_collection(name_or_collection, session=None)¶

Drop a collection.

Parameters:	name_or_collection: the name of a collection to drop or the collection object itself session (optional): a `ClientSession`.

Note

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

coroutine error()¶: OBSOLETE

coroutine eval(code, *args)¶

DEPRECATED: Evaluate a JavaScript expression in MongoDB.

Parameters:	code: string representation of JavaScript code to be evaluated args (optional): additional positional arguments are passed to the code being evaluated

Warning

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

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()¶: OBSOLETE

coroutine list_collection_names(session=None, filter=None, **kwargs)¶

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

For example, to list all non-system collections:

filter = {"name": {"$regex": r"^(?!system\.)"}}
db.list_collection_names(filter=filter)

Parameters:	session (optional): a `ClientSession`. filter (optional): A query document to filter the list of collections returned from the listCollections command. **kwargs (optional): Optional parameters of the listCollections command can be passed as keyword arguments to this method. The supported options differ by server version.

coroutine list_collections(session=None, filter=None, **kwargs)¶

Get a cursor over the collectons of this database.

Parameters:	session (optional): a `ClientSession`. filter (optional): A query document to filter the list of collections returned from the listCollections command. **kwargs (optional): Optional parameters of the listCollections command can be passed as keyword arguments to this method. The supported options differ by server version.
Returns:	An instance of `CommandCursor`.

coroutine logout()¶: DEPRECATED: Deauthorize use of this database.

Warning

Starting in MongoDB 3.6, calling logout() invalidates all existing cursors. It may also leave logical sessions open on the server for up to 30 minutes until they time out.

coroutine previous_error()¶: OBSOLETE

coroutine profiling_info(session=None)¶

Returns a list containing current profiling information.

Parameters:	session (optional): a `ClientSession`.

See also

The MongoDB documentation on

profiling

coroutine profiling_level(session=None)¶

Get the database’s current profiling level.

Returns one of (OFF, SLOW_ONLY, ALL).

Parameters:	session (optional): a `ClientSession`.

See also

The MongoDB documentation on

profiling

coroutine remove_user(name, session=None)¶

DEPRECATED: Remove user name from this Database.

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

Note

remove_user is deprecated and will be removed in PyMongo 4.0. Use the dropUser command instead:

db.command("dropUser", "user")

Parameters:	name: the name of the user to remove session (optional): a `ClientSession`.

coroutine reset_error_history()¶: OBSOLETE

coroutine set_profiling_level(level, slow_ms=None, session=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. session (optional): a `ClientSession`.

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 also

The MongoDB documentation on

profiling

coroutine validate_collection(name_or_collection, scandata=False, full=False, session=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. session (optional): a `ClientSession`.

client¶: This MotorDatabase’s MotorClient.

codec_options¶: Read only access to the CodecOptions of this instance.

incoming_copying_manipulators¶: DEPRECATED: All incoming SON copying manipulators.

Changed in version 3.5: Deprecated.

New in version 2.0.

incoming_manipulators¶: DEPRECATED: All incoming SON manipulators.

Changed in version 3.5: Deprecated.

New in version 2.0.

name¶: The name of this Database.

outgoing_copying_manipulators¶: DEPRECATED: All outgoing SON copying manipulators.

Changed in version 3.5: Deprecated.

New in version 2.0.

outgoing_manipulators¶: DEPRECATED: All outgoing SON manipulators.

Changed in version 3.5: Deprecated.

New in version 2.0.

read_concern¶: Read only access to the ReadConcern 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.

`AsyncIOMotorDatabase`¶

Previous topic

Next topic

AsyncIOMotorDatabase¶

`AsyncIOMotorDatabase`¶