Get the name sub-collection of MotorCollection c.
Raises InvalidName if an invalid collection name is used.
The MotorDatabase that this MotorCollection is a part of.
Perform an aggregation using the aggregation framework on this collection.
With MongoReplicaSetClient or MasterSlaveConnection, if the read_preference attribute of this instance is not set to pymongo.read_preferences.ReadPreference.PRIMARY or the (deprecated) slave_okay attribute of this instance is set to True the aggregate command will be sent to a secondary or slave.
| Parameters : |
|
|---|
Note
Requires server version >= 2.1.0
If a callback is passed, returns None, else returns a Future.
Get the number of documents in this collection.
To get the number of documents matching a specific query use pymongo.cursor.Cursor.count().
| Parameters : |
|
|---|
If a callback is passed, returns None, else returns a Future.
Creates an index on this collection.
Takes either a single key or a list of (key, direction) pairs. The key(s) must be an instance of basestring (str in python 3), and the directions must be one of (ASCENDING, DESCENDING, GEO2D). Returns the name of the created index.
To create a single key index on the key 'mike' we just use a string argument:
>>> my_collection.create_index("mike")
For a compound index on 'mike' descending and 'eliot' ascending we need to use a list of tuples:
>>> my_collection.create_index([("mike", pymongo.DESCENDING),
... ("eliot", pymongo.ASCENDING)])
All optional index creation parameters should be passed as keyword arguments to this method. Valid options include:
- name: custom name to use for this index - if none is given, a name will be generated
- unique: should this index guarantee uniqueness?
- dropDups or drop_dups: should we drop duplicates
- background: if this index should be created in the background
- bucketSize or bucket_size: for use with geoHaystack indexes. Number of documents to group together within a certain proximity to a given longitude and latitude.
- min: minimum value for keys in a GEO2D index
- max: maximum value for keys in a GEO2D index
- expireAfterSeconds: <int> Used to create an expiring (TTL) collection. MongoDB will automatically delete documents from this collection after <int> seconds. The indexed field must be a UTC datetime or the data will not expire.
Note
expireAfterSeconds requires server version >= 2.1.2
| Parameters : |
|
|---|
See also
See general MongoDB documentation
If a callback is passed, returns None, else returns a Future.
Get a list of distinct values for key among all documents in this collection.
Raises TypeError if key is not an instance of basestring (str in python 3).
To get the distinct values for a key in the result set of a query use distinct().
| Parameters : |
|
|---|
Note
Requires server version >= 1.1.0
If a callback is passed, returns None, else returns a Future.
Alias for drop_collection().
The following two calls are equivalent:
>>> db.foo.drop()
>>> db.drop_collection("foo")
| Parameters : |
|
|---|
If a callback is passed, returns None, else returns a Future.
Drops the specified index on this collection.
Can be used on non-existant collections or collections with no indexes. Raises OperationFailure on an error. index_or_name can be either an index name (as returned by create_index), or an index specifier (as passed to create_index). An index specifier should be a list of (key, direction) pairs. Raises TypeError if index is not an instance of (str, unicode, list).
Warning
if a custom name was used on index creation (by passing the name parameter to create_index() or ensure_index()) the index must be dropped by name.
| Parameters : |
|
|---|
If a callback is passed, returns None, else returns a Future.
Drops all indexes on this collection.
Can be used on non-existant collections or collections with no indexes. Raises OperationFailure on an error.
| Parameters : |
|
|---|
If a callback is passed, returns None, else returns a Future.
Ensures that an index exists on this collection.
Takes either a single key or a list of (key, direction) pairs. The key(s) must be an instance of basestring (str in python 3), and the direction(s) must be one of (ASCENDING, DESCENDING, GEO2D). See create_index() for a detailed example.
Unlike create_index(), which attempts to create an index unconditionally, ensure_index() takes advantage of some caching within the driver such that it only attempts to create indexes that might not already exist. When an index is created (or ensured) by PyMongo it is “remembered” for cache_for seconds. Repeated calls to ensure_index() within that time limit will be lightweight - they will not attempt to actually create the index.
Care must be taken when the database is being accessed through multiple clients at once. If an index is created using this client and deleted using another, any call to ensure_index() within the cache window will fail to re-create the missing index.
Returns the name of the created index if an index is actually created. Returns None if the index already exists.
All optional index creation parameters should be passed as keyword arguments to this method. Valid options include:
- name: custom name to use for this index - if none is given, a name will be generated
- unique: should this index guarantee uniqueness?
- dropDups or drop_dups: should we drop duplicates during index creation when creating a unique index?
- background: if this index should be created in the background
- bucketSize or bucket_size: for use with geoHaystack indexes. Number of documents to group together within a certain proximity to a given longitude and latitude.
- min: minimum value for keys in a GEO2D index
- max: maximum value for keys in a GEO2D index
- expireAfterSeconds: <int> Used to create an expiring (TTL) collection. MongoDB will automatically delete documents from this collection after <int> seconds. The indexed field must be a UTC datetime or the data will not expire.
Note
expireAfterSeconds requires server version >= 2.1.2
| Parameters : |
|
|---|
See also
If a callback is passed, returns None, else returns a Future.
Create a MotorCursor. Same parameters as for PyMongo’s find.
Note that find() does not take a callback parameter, nor does it return a Future, because find() merely creates a MotorCursor without performing any operations on the server. MotorCursor methods such as to_list() or count() perform actual operations.
Update and return an object.
This is a thin wrapper around the findAndModify command. The positional arguments are designed to match the first three arguments to update() however most options should be passed as named parameters. Either update or remove arguments are required, all others are optional.
Returns either the object before or after modification based on new parameter. If no objects match the query and upsert is false, returns None. If upserting and new is false, returns {}.
If the full_response parameter is True, the return value will be the entire response object from the server, including the ‘ok’ and ‘lastErrorObject’ fields, rather than just the modified object. This is useful mainly because the ‘lastErrorObject’ document holds information about the command’s execution.
| Parameters : |
|
|---|
See general MongoDB documentation
Note
Requires server version >= 1.3.0
If a callback is passed, returns None, else returns a Future.
Get a single document from the database.
All arguments to find() are also valid arguments for find_one(), although any limit argument will be ignored. Returns a single document, or None if no matching document is found.
| Parameters : |
|
|---|
If a callback is passed, returns None, else returns a Future.
Perform a query similar to an SQL group by operation.
Returns an array of grouped items.
The key parameter can be:
- None to use the entire document as a key.
- A list of keys (each a basestring (str in python 3)) to group by.
- A basestring (str in python 3), or Code instance containing a JavaScript function to be applied to each document, returning the key to group by.
With MongoReplicaSetClient or MasterSlaveConnection, if the read_preference attribute of this instance is not set to pymongo.read_preferences.ReadPreference.PRIMARY or pymongo.read_preferences.ReadPreference.PRIMARY_PREFERRED, or the (deprecated) slave_okay attribute of this instance is set to True, the group command will be sent to a secondary or slave.
| Parameters : |
|
|---|
If a callback is passed, returns None, else returns a Future.
Get information on this collection’s indexes.
Returns a dictionary where the keys are index names (as returned by create_index()) and the values are dictionaries containing information about each index. The dictionary is guaranteed to contain at least a single key, "key" which is a list of (key, direction) pairs specifying the index (as passed to create_index()). It will also contain any other information in system.indexes, except for the "ns" and "name" keys, which are cleaned. Example output might look like this:
>>> db.test.ensure_index("x", unique=True)
u'x_1'
>>> db.test.index_information()
{u'_id_': {u'key': [(u'_id', 1)]},
u'x_1': {u'unique': True, u'key': [(u'x', 1)]}}
| Parameters : |
|
|---|
If a callback is passed, returns None, else returns a Future.
Perform an inline map/reduce operation on this collection.
Perform the map/reduce operation on the server in RAM. A result collection is not created. The result set is returned as a list of documents.
If full_response is False (default) returns the result documents in a list. Otherwise, returns the full response from the server to the map reduce command.
With MongoReplicaSetClient or MasterSlaveConnection, if the read_preference attribute of this instance is not set to pymongo.read_preferences.ReadPreference.PRIMARY or pymongo.read_preferences.ReadPreference.PRIMARY_PREFERRED, or the (deprecated) slave_okay attribute of this instance is set to True, the inline map reduce will be run on a secondary or slave.
| Parameters : |
|
|---|
Note
Requires server version >= 1.7.4
If a callback is passed, returns None, else returns a Future.
Insert a document(s) into this collection.
If manipulate is True, the document(s) are manipulated using any SONManipulator instances that have been added to this Database. In this case an "_id" will be added if the document(s) does not already contain one and the "id" (or list of "_id" values for more than one document) will be returned. If manipulate is False and the document(s) does not include an "_id" one will be added by the server. The server does not return the "_id" it created so None is returned.
Write concern options can be passed as keyword arguments, overriding any global defaults. Valid options include w=<int/string>, wtimeout=<int>, j=<bool>, or fsync=<bool>. See the parameter list below for a detailed explanation of these options.
By default an acknowledgment is requested from the server that the insert was successful, raising OperationFailure if an error occurred. Passing ``w=0`` disables write acknowledgement and all other write concern options.
| Parameters : |
|
|---|---|
| Returns : |
|
Note
continue_on_error requires server version >= 1.9.1
See general MongoDB documentation
If a callback is passed, returns None, else returns a Future.
Perform a map/reduce operation on this collection.
If full_response is False (default) returns a Collection instance containing the results of the operation. Otherwise, returns the full response from the server to the map reduce command.
| Parameters : |
|
|---|
Note
Requires server version >= 1.1.1
See general MongoDB documentation
If a callback is passed, returns None, else returns a Future.
Get the options set on this collection.
Returns a dictionary of options and their values - see create_collection() for more information on the possible options. Returns an empty dictionary if the collection has not been created yet.
| Parameters : |
|
|---|
If a callback is passed, returns None, else returns a Future.
Rebuilds all indexes on this collection.
Warning
reindex blocks all other operations (indexes are built in the foreground) and will be slow for large collections.
| Parameters : |
|
|---|
If a callback is passed, returns None, else returns a Future.
Remove a document(s) from this collection.
Warning
Calls to remove() should be performed with care, as removed data cannot be restored.
If spec_or_id is None, all documents in this collection will be removed. This is not equivalent to calling drop_collection(), however, as indexes will not be removed.
Write concern options can be passed as keyword arguments, overriding any global defaults. Valid options include w=<int/string>, wtimeout=<int>, j=<bool>, or fsync=<bool>. See the parameter list below for a detailed explanation of these options.
By default an acknowledgment is requested from the server that the remove was successful, raising OperationFailure if an error occurred. Passing ``w=0`` disables write acknowledgement and all other write concern options.
| Parameters : |
|
|---|---|
| Returns : |
|
See general MongoDB documentation
If a callback is passed, returns None, else returns a Future.
Rename this collection.
If operating in auth mode, client must be authorized as an admin to perform this operation. Raises TypeError if new_name is not an instance of basestring (str in python 3). Raises InvalidName if new_name is not a valid collection name.
| Parameters : |
|
|---|
If a callback is passed, returns None, else returns a Future.
Save a document in this collection.
If to_save already has an "_id" then an update() (upsert) operation is performed and any existing document with that "_id" is overwritten. Otherwise an insert() operation is performed. In this case if manipulate is True an "_id" will be added to to_save and this method returns the "_id" of the saved document. If manipulate is False the "_id" will be added by the server but this method will return None.
Raises TypeError if to_save is not an instance of dict.
Write concern options can be passed as keyword arguments, overriding any global defaults. Valid options include w=<int/string>, wtimeout=<int>, j=<bool>, or fsync=<bool>. See the parameter list below for a detailed explanation of these options.
By default an acknowledgment is requested from the server that the save was successful, raising OperationFailure if an error occurred. Passing ``w=0`` disables write acknowledgement and all other write concern options.
| Parameters : |
|
|---|---|
| Returns : |
|
See general MongoDB documentation
If a callback is passed, returns None, else returns a Future.
Update a document(s) in this collection.
Raises TypeError if either spec or document is not an instance of dict or upsert is not an instance of bool.
Write concern options can be passed as keyword arguments, overriding any global defaults. Valid options include w=<int/string>, wtimeout=<int>, j=<bool>, or fsync=<bool>. See the parameter list below for a detailed explanation of these options.
By default an acknowledgment is requested from the server that the update was successful, raising OperationFailure if an error occurred. Passing ``w=0`` disables write acknowledgement and all other write concern options.
There are many useful update modifiers which can be used when performing updates. For example, here we use the "$set" modifier to modify some fields in a matching document:
>>> db.test.insert({"x": "y", "a": "b"})
ObjectId('...')
>>> list(db.test.find())
[{u'a': u'b', u'x': u'y', u'_id': ObjectId('...')}]
>>> db.test.update({"x": "y"}, {"$set": {"a": "c"}})
{...}
>>> list(db.test.find())
[{u'a': u'c', u'x': u'y', u'_id': ObjectId('...')}]
| Parameters : |
|
|---|---|
| Returns : |
|
See general MongoDB documentation
If a callback is passed, returns None, else returns a Future.
The full name of this Collection.
The full name is of the form database_name.collection_name.
The name of this Collection.
The read preference mode for this instance.
See ReadPreference for available options.
Any replica-set member whose ping time is within secondary_acceptable_latency_ms of the nearest member may accept reads. Defaults to 15 milliseconds.
See ReadPreference.
Note
secondary_acceptable_latency_ms is ignored when talking to a replica set through a mongos. The equivalent is the localThreshold command line option.
Set tag_sets to a list of dictionaries like [{‘dc’: ‘ny’}] to read only from members whose dc tag has the value "ny". To specify a priority-order for tag sets, provide a list of tag sets: [{'dc': 'ny'}, {'dc': 'la'}, {}]. A final, empty tag set, {}, means “read from any member that matches the mode, ignoring tags.” ReplicaSetConnection tries each set of tags in turn until it finds a set of tags with at least one matching member.
See also
This attribute specifies which BSON Binary subtype is used when storing UUIDs. Historically UUIDs have been stored as BSON Binary subtype 3. This attribute is used to switch to the newer BSON binary subtype 4. It can also be used to force legacy byte order and subtype compatibility with the Java and C# drivers. See the bson.binary module for all options.
The default write concern for this instance.
Supports dict style access for getting/setting write concern options. Valid options include:
>>> m = pymongo.MongoClient()
>>> m.write_concern
{}
>>> m.write_concern = {'w': 2, 'wtimeout': 1000}
>>> m.write_concern
{'wtimeout': 1000, 'w': 2}
>>> m.write_concern['j'] = True
>>> m.write_concern
{'wtimeout': 1000, 'j': True, 'w': 2}
>>> m.write_concern = {'j': True}
>>> m.write_concern
{'j': True}
>>> # Disable write acknowledgement and write concern
...
>>> m.write_concern['w'] = 0
Note
Accessing write_concern returns its value (a subclass of dict), not a copy.