Collection level utilities for Mongo.
Ascending sort order.
Descending sort order.
Index specifier for a 2-dimensional geospatial index.
New in version 1.5.1.
Note
Geo-spatial indexing requires server version >= 1.3.3+.
Get / create a Mongo collection.
Raises TypeError if name is not an instance of basestring. Raises InvalidName if name is not a valid collection name. Any additional keyword arguments will be used as options passed to the create command. See create_collection() for valid options.
If create is True or additional keyword arguments are present a create command will be sent. Otherwise, a create command will not be sent and the collection will be created implicitly on first use.
Parameters : |
|
---|
Changed in version 1.5: deprecating options in favor of kwargs
New in version 1.5: the create parameter
See general MongoDB documentation
Get the name sub-collection of Collection c.
Raises InvalidName if an invalid collection name is used.
The full name of this Collection.
The full name is of the form database_name.collection_name.
Changed in version 1.3: full_name is now a property rather than a method.
The name of this Collection.
Changed in version 1.3: name is now a property rather than a method.
The Database that this Collection is a part of.
Changed in version 1.3: database is now a property rather than a method.
DEPRECATED. Use read_preference instead.
Changed in version 2.0.1+.
New in version 2.0.
The read preference for this instance.
See ReadPreference for available options.
New in version 2.0.1+.
Use getlasterrer with every write operation?
New in version 2.0.
The BSON binary subtype for a UUID used for this collection.
Returns a dict of the getlasterror options set on this instance.
New in version 2.0.
Set getlasterror options for this instance.
Valid options include j=<bool>, w=<int>, wtimeout=<int>, and fsync=<bool>. Implies safe=True.
Parameters : |
|
---|
New in version 2.0.
Unset getlasterror options for this instance.
If no options are passed unsets all getlasterror options. This does not set safe to False.
Parameters : |
|
---|
New in version 2.0.
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.
If safe is True then the insert will be checked for errors, raising OperationFailure if one occurred. Safe inserts wait for a response from the database, while normal inserts do not.
Any additional keyword arguments imply safe=True, and will be used as options for the resultant getLastError command. For example, to wait for replication to 3 nodes, pass w=3.
Parameters : |
|
---|
Note
continue_on_error requires server version >= 1.9.1
New in version 2.0.1+: Support for continue_on_error.
New in version 1.8: Support for passing getLastError options as keyword arguments.
Changed in version 1.1: Bulk insert works with any iterable
See general MongoDB documentation
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. If safe is True then the save will be checked for errors, raising OperationFailure if one occurred. Safe inserts wait for a response from the database, while normal inserts do not.
Any additional keyword arguments imply safe=True, and will be used as options for the resultant getLastError command. For example, to wait for replication to 3 nodes, pass w=3.
Parameters : |
|
---|
New in version 1.8: Support for passing getLastError options as keyword arguments.
See general MongoDB documentation
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. If safe is True then the update will be checked for errors, raising OperationFailure if one occurred. Safe updates require a response from the database, while normal updates do not - thus, setting safe to True will negatively impact performance.
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('...')}]
If safe is True returns the response to the lastError command. Otherwise, returns None.
Any additional keyword arguments imply safe=True, and will be used as options for the resultant getLastError command. For example, to wait for replication to 3 nodes, pass w=3.
Parameters : |
|
---|
New in version 1.8: Support for passing getLastError options as keyword arguments.
Changed in version 1.4: Return the response to lastError if safe is True.
New in version 1.1.1: The multi parameter.
See general MongoDB documentation
Remove a document(s) from this collection.
Warning
Calls to remove() should be performed with care, as removed data cannot be restored.
If safe is True then the remove operation will be checked for errors, raising OperationFailure if one occurred. Safe removes wait for a response from the database, while normal removes do not.
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.
If safe is True returns the response to the lastError command. Otherwise, returns None.
Any additional keyword arguments imply safe=True, and will be used as options for the resultant getLastError command. For example, to wait for replication to 3 nodes, pass w=3.
Parameters : |
|
---|
New in version 1.8: Support for passing getLastError options as keyword arguments.
Changed in version 1.7: Accept any type other than a dict instance for removal by "_id", not just ObjectId instances.
Changed in version 1.4: Return the response to lastError if safe is True.
Changed in version 1.2: The spec_or_id parameter is now optional. If it is not specified all documents in the collection will be removed.
New in version 1.1: The safe parameter.
See general MongoDB documentation
Alias for drop_collection().
The following two calls are equivalent:
>>> db.foo.drop()
>>> db.drop_collection("foo")
New in version 1.8.
Query the database.
The spec argument is a prototype document that all results must match. For example:
>>> db.test.find({"hello": "world"})
only matches documents that have a key “hello” with value “world”. Matches can have other keys in addition to “hello”. The fields argument is used to specify a subset of fields that should be included in the result documents. By limiting results to a certain subset of fields you can cut down on network traffic and decoding time.
Raises TypeError if any of the arguments are of improper type. Returns an instance of Cursor corresponding to this query.
Parameters : |
|
---|
Note
The manipulate parameter may default to False in a future release.
Note
The max_scan parameter requires server version >= 1.5.1
New in version 1.11+: The await_data, partial, and manipulate parameters.
New in version 1.8: The network_timeout parameter.
New in version 1.7: The sort, max_scan and as_class parameters.
Changed in version 1.7: The fields parameter can now be a dict or any iterable in addition to a list.
New in version 1.1: The tailable parameter.
See general MongoDB documentation
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 : |
|
---|
Changed in version 1.7: Allow passing any of the arguments that are valid for find().
Changed in version 1.7: Accept any type other than a dict instance as an "_id" query, not just ObjectId instances.
Get the number of documents in this collection.
To get the number of documents matching a specific query use pymongo.cursor.Cursor.count().
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, 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 paramaters 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
- bucketSize or bucket_size: size of buckets for geoHaystack indexes during index creation when creating a unique index?
- min: minimum value for keys in a GEO2D index
- max: maximum value for keys in a GEO2D index
Parameters : |
|
---|
Changed in version 1.5.1: Accept kwargs to support all index creation options.
New in version 1.5: The name parameter.
See also
See general MongoDB documentation
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, 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 ttl 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 connections at once. If an index is created using PyMongo and then deleted using another connection 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 paramaters 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
- min: minimum value for keys in a GEO2D index
- max: maximum value for keys in a GEO2D index
Parameters : |
|
---|
Changed in version 1.5.1: Accept kwargs to support all index creation options.
New in version 1.5: The name parameter.
See also
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).
Parameters : |
|
---|
Drops all indexes on this collection.
Can be used on non-existant collections or collections with no indexes. Raises OperationFailure on an error.
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.
New in version 1.11+.
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)]}}
Changed in version 1.7: The values in the resultant dictionary are now dictionaries themselves, whose "key" item contains the list that was the value in previous versions of PyMongo.
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.
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) to group by.
- A basestring or Code instance containing a JavaScript function to be applied to each document, returning the key to group by.
With ReplicaSetConnection or MasterSlaveConnection, if the read_preference attribute of this instance is not set to pymongo.ReadPreference.PRIMARY 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 : |
|
---|
Changed in version 1.4: The key argument can now be None or a JavaScript function, in addition to a list of keys.
Changed in version 1.3: The command argument now defaults to True and is deprecated.
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. Raises InvalidName if new_name is not a valid collection name.
Parameters : |
|
---|
New in version 1.7: support for accepting keyword arguments for rename options
Get a list of distinct values for key among all documents in this collection.
Raises TypeError if key is not an instance of basestring.
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
New in version 1.1.1.
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 also
Changed in version 1.11+: DEPRECATED The merge_output and reduce_output parameters.
New in version 1.2.
See general MongoDB documentation
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.
Parameters : |
|
---|
Note
Requires server version >= 1.7.4
New in version 1.10.
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 {}.
Parameters : |
|
---|
See general MongoDB documentation
Note
Requires server version >= 1.3.0
New in version 1.10.