collection – Collection level operations — PyMongo 3.11.0 documentation (original) (raw)

Get / create a Mongo collection.

Raises TypeError if name is not an instance ofbasestring (str in python 3). RaisesInvalidName if name is not a valid collection name. Any additional keyword arguments will be used as options passed to the create command. Seecreate_collection() for valid options.

If create is True, collation is specified, or any additional keyword arguments are present, a create command will be sent, using session if specified. Otherwise, a create command will not be sent and the collection will be created implicitly on first use. The optional session argument is only used for the createcommand, it is not associated with the collection afterward.

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Support the collation option.

Changed in version 3.2: Added the read_concern option.

Changed in version 3.0: Added the codec_options, read_preference, and write_concern options. Removed the uuid_subtype attribute.Collection no longer returns an instance of Collection for attribute names with leading underscores. You must use dict-style lookups instead::

collection[‘__my_collection__’]

Not:

collection.__my_collection__

Changed in version 2.2: Removed deprecated argument: options

New in version 2.1: uuid_subtype attribute

c[name] || c.name

Get the name sub-collection of Collection c.

Raises InvalidName if an invalid collection name is used.

full_name¶

The full name of this Collection.

The full name is of the form database_name.collection_name.

name¶

The name of this Collection.

database¶

The Database that thisCollection is a part of.

codec_options¶

Read only access to the CodecOptionsof this instance.

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 WriteConcernof this instance.

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

read_concern¶

Read only access to the ReadConcernof this instance.

New in version 3.2.

with_options(codec_options=None, read_preference=None, write_concern=None, read_concern=None)¶

Get a clone of this collection changing the specified settings.

coll1.read_preference Primary() from pymongo import ReadPreference coll2 = coll1.with_options(read_preference=ReadPreference.SECONDARY) coll1.read_preference Primary() coll2.read_preference Secondary(tag_sets=None)

bulk_write(requests, ordered=True, bypass_document_validation=False, session=None)¶

Send a batch of write operations to the server.

Requests are passed as a list of write operation instances (InsertOne,UpdateOne,UpdateMany,ReplaceOne,DeleteOne, orDeleteMany).

for doc in db.test.find({}): ... print(doc) ... {u'x': 1, u'_id': ObjectId('54f62e60fba5226811f634ef')} {u'x': 1, u'_id': ObjectId('54f62e60fba5226811f634f0')}

DeleteMany, UpdateOne, and UpdateMany are also available.

... from pymongo import InsertOne, DeleteOne, ReplaceOne requests = [InsertOne({'y': 1}), DeleteOne({'x': 1}), ... ReplaceOne({'w': 1}, {'z': 1}, upsert=True)] result = db.test.bulk_write(requests) result.inserted_count 1 result.deleted_count 1 result.modified_count 0 result.upserted_ids {2: ObjectId('54f62ee28891e756a6e1abd5')} for doc in db.test.find({}): ... print(doc) ... {u'x': 1, u'_id': ObjectId('54f62e60fba5226811f634f0')} {u'y': 1, u'_id': ObjectId('54f62ee2fba5226811f634f1')} {u'z': 1, u'_id': ObjectId('54f62ee28891e756a6e1abd5')}

Note

bypass_document_validation requires server version>= 3.2

Changed in version 3.6: Added session parameter.

Changed in version 3.2: Added bypass_document_validation support

New in version 3.0.

insert_one(document, bypass_document_validation=False, session=None)¶

Insert a single document.

db.test.count_documents({'x': 1}) 0 result = db.test.insert_one({'x': 1}) result.inserted_id ObjectId('54f112defba522406c9cc208') db.test.find_one({'x': 1}) {u'x': 1, u'_id': ObjectId('54f112defba522406c9cc208')}

Note

bypass_document_validation requires server version>= 3.2

Changed in version 3.6: Added session parameter.

Changed in version 3.2: Added bypass_document_validation support

New in version 3.0.

insert_many(documents, ordered=True, bypass_document_validation=False, session=None)¶

Insert an iterable of documents.

db.test.count_documents({}) 0 result = db.test.insert_many([{'x': i} for i in range(2)]) result.inserted_ids [ObjectId('54f113fffba522406c9cc20e'), ObjectId('54f113fffba522406c9cc20f')] db.test.count_documents({}) 2

Note

bypass_document_validation requires server version>= 3.2

Changed in version 3.6: Added session parameter.

Changed in version 3.2: Added bypass_document_validation support

New in version 3.0.

replace_one(filter, replacement, upsert=False, bypass_document_validation=False, collation=None, hint=None, session=None)¶

Replace a single document matching the filter.

for doc in db.test.find({}): ... print(doc) ... {u'x': 1, u'_id': ObjectId('54f4c5befba5220aa4d6dee7')} result = db.test.replace_one({'x': 1}, {'y': 1}) result.matched_count 1 result.modified_count 1 for doc in db.test.find({}): ... print(doc) ... {u'y': 1, u'_id': ObjectId('54f4c5befba5220aa4d6dee7')}

The upsert option can be used to insert a new document if a matching document does not exist.

result = db.test.replace_one({'x': 1}, {'x': 1}, True) result.matched_count 0 result.modified_count 0 result.upserted_id ObjectId('54f11e5c8891e756a6e1abd4') db.test.find_one({'x': 1}) {u'x': 1, u'_id': ObjectId('54f11e5c8891e756a6e1abd4')}

Changed in version 3.11: Added hint parameter.

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Added the collation option.

Changed in version 3.2: Added bypass_document_validation support.

New in version 3.0.

update_one(filter, update, upsert=False, bypass_document_validation=False, collation=None, array_filters=None, hint=None, session=None)¶

Update a single document matching the filter.

for doc in db.test.find(): ... print(doc) ... {u'x': 1, u'_id': 0} {u'x': 1, u'_id': 1} {u'x': 1, u'_id': 2} result = db.test.update_one({'x': 1}, {'$inc': {'x': 3}}) result.matched_count 1 result.modified_count 1 for doc in db.test.find(): ... print(doc) ... {u'x': 4, u'_id': 0} {u'x': 1, u'_id': 1} {u'x': 1, u'_id': 2}

Changed in version 3.11: Added hint parameter.

Changed in version 3.9: Added the ability to accept a pipeline as the update.

Changed in version 3.6: Added the array_filters and session parameters.

Changed in version 3.4: Added the collation option.

Changed in version 3.2: Added bypass_document_validation support.

New in version 3.0.

update_many(filter, update, upsert=False, array_filters=None, bypass_document_validation=False, collation=None, hint=None, session=None)¶

Update one or more documents that match the filter.

for doc in db.test.find(): ... print(doc) ... {u'x': 1, u'_id': 0} {u'x': 1, u'_id': 1} {u'x': 1, u'_id': 2} result = db.test.update_many({'x': 1}, {'$inc': {'x': 3}}) result.matched_count 3 result.modified_count 3 for doc in db.test.find(): ... print(doc) ... {u'x': 4, u'_id': 0} {u'x': 4, u'_id': 1} {u'x': 4, u'_id': 2}

Changed in version 3.11: Added hint parameter.

Changed in version 3.9: Added the ability to accept a pipeline as the update.

Changed in version 3.6: Added array_filters and session parameters.

Changed in version 3.4: Added the collation option.

Changed in version 3.2: Added bypass_document_validation support.

New in version 3.0.

delete_one(filter, collation=None, hint=None, session=None)¶

Delete a single document matching the filter.

db.test.count_documents({'x': 1}) 3 result = db.test.delete_one({'x': 1}) result.deleted_count 1 db.test.count_documents({'x': 1}) 2

Changed in version 3.11: Added hint parameter.

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Added the collation option.

New in version 3.0.

delete_many(filter, collation=None, hint=None, session=None)¶

Delete one or more documents matching the filter.

db.test.count_documents({'x': 1}) 3 result = db.test.delete_many({'x': 1}) result.deleted_count 3 db.test.count_documents({'x': 1}) 0

Changed in version 3.11: Added hint parameter.

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Added the collation option.

New in version 3.0.

aggregate(pipeline, session=None, **kwargs)¶

Perform an aggregation using the aggregation framework on this collection.

All optional aggregate command parameters should be passed as keyword arguments to this method. Valid options include, but are not limited to:

• allowDiskUse (bool): Enables writing to temporary files. When set to True, aggregation stages can write data to the _tmp subdirectory of the –dbpath directory. The default is False.
• maxTimeMS (int): The maximum amount of time to allow the operation to run in milliseconds.
• batchSize (int): The maximum number of documents to return per batch. Ignored if the connected mongod or mongos does not support returning aggregate results using a cursor, or useCursor isFalse.
• collation (optional): An instance ofCollation. This option is only supported on MongoDB 3.4 and above.
• useCursor (bool): Deprecated. Will be removed in PyMongo 4.0.

The aggregate() method obeys the read_preference of thisCollection, except when $out or $merge are used, in which case PRIMARYis used.

Note

This method does not support the ‘explain’ option. Please use command() instead. An example is included in the Aggregation Framework documentation.

Note

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

Changed in version 3.9: Apply this collection’s read concern to pipelines containing the$out stage when connected to MongoDB >= 4.2. Added support for the $merge pipeline stage. Aggregations that write always use read preferencePRIMARY.

Changed in version 3.6: Added the session parameter. Added the maxAwaitTimeMS option. Deprecated the useCursor option.

Changed in version 3.4: Apply this collection’s write concern automatically to this operation when connected to MongoDB >= 3.4. Support the collation option.

Changed in version 3.0: The aggregate() method always returns a CommandCursor. The pipeline argument must be a list.

Changed in version 2.7: When the cursor option is used, returnCommandCursor instead ofCursor.

Changed in version 2.6: Added cursor support.

New in version 2.3.

aggregate_raw_batches(pipeline, **kwargs)¶

Perform an aggregation and retrieve batches of raw BSON.

Similar to the aggregate() method but returns aRawBatchCursor.

This example demonstrates how to work with raw batches, but in practice raw batches should be passed to an external library that can decode BSON into another data type, rather than used with PyMongo’sbson module.

import bson cursor = db.test.aggregate_raw_batches([ ... {'$project': {'x': {'$multiply': [2, '$x']}}}]) for batch in cursor: ... print(bson.decode_all(batch))

Note

aggregate_raw_batches does not support sessions or auto encryption.

New in version 3.6.

watch(pipeline=None, full_document=None, resume_after=None, max_await_time_ms=None, batch_size=None, collation=None, start_at_operation_time=None, session=None, start_after=None)¶

Watch changes on this collection.

Performs an aggregation with an implicit initial $changeStreamstage and returns aCollectionChangeStream cursor which iterates over changes on this collection.

Introduced in MongoDB 3.6.

with db.collection.watch() as stream: for change in stream: print(change)

The CollectionChangeStream iterable blocks until the next change document is returned or an error is raised. If thenext() method encounters a network error when retrieving a batch from the server, it will automatically attempt to recreate the cursor such that no change events are missed. Any error encountered during the resume attempt indicates there may be an outage and will be raised.

try: with db.collection.watch( [{'$match': {'operationType': 'insert'}}]) as stream: for insert_change in stream: print(insert_change) except pymongo.errors.PyMongoError: # The ChangeStream encountered an unrecoverable error or the # resume attempt failed to recreate the cursor. logging.error('...')

For a precise description of the resume process see thechange streams specification.

Note

Using this helper method is preferred to directly callingaggregate() with a$changeStream stage, for the purpose of supporting resumability.

Warning

This Collection’s read_concern must beReadConcern("majority") in order to use the $changeStreamstage.

Changed in version 3.9: Added the start_after parameter.

Changed in version 3.7: Added the start_at_operation_time parameter.

New in version 3.6.

find(filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, batch_size=0, manipulate=True, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None, session=None)¶

Query the database.

The filter 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 projection 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 ofCursor corresponding to this query.

The find() method obeys the read_preference of this Collection.

Note

There are a number of caveats to usingEXHAUST as cursor_type:

• The limit option can not be used with an exhaust cursor.
• Exhaust cursors are not supported by mongos and can not be used with a sharded cluster.
• A Cursor instance created with theEXHAUST cursor_type requires an exclusive socket connection to MongoDB. If theCursor is discarded without being completely iterated the underlying socketconnection will be closed and discarded without being returned to the connection pool.

Changed in version 3.11: Added the allow_disk_use option. Deprecated the oplog_replay option. Support for this option is deprecated in MongoDB 4.4. The query engine now automatically optimizes queries against the oplog without requiring this option to be set.

Changed in version 3.7: Deprecated the snapshot option, which is deprecated in MongoDB 3.6 and removed in MongoDB 4.0. Deprecated the max_scan option. Support for this option is deprecated in MongoDB 4.0. Use max_time_ms instead to limit server-side execution time.

Changed in version 3.6: Added session parameter.

Changed in version 3.5: Added the options return_key, show_record_id, snapshot,hint, max_time_ms, max_scan, min, max, andcomment. Deprecated the modifiers option.

Changed in version 3.4: Added support for the collation option.

Changed in version 3.0: Changed the parameter names spec, fields, timeout, andpartial to filter, projection, no_cursor_timeout, and allow_partial_results respectively. Added the cursor_type, oplog_replay, and modifiersoptions. Removed the network_timeout, read_preference, tag_sets,secondary_acceptable_latency_ms, max_scan, snapshot,tailable, await_data, exhaust, as_class, and slave_okay parameters. Removed compile_re option: PyMongo now always represents BSON regular expressions as Regexobjects. Use try_compile() to attempt to convert from a BSON regular expression to a Python regular expression object. Soft deprecated the manipulate option.

Changed in version 2.7: Added compile_re option. If set to False, PyMongo represented BSON regular expressions as Regex objects instead of attempting to compile BSON regular expressions as Python native regular expressions, thus preventing errors for some incompatible patterns, see PYTHON-500.

Changed in version 2.3: Added the tag_sets and secondary_acceptable_latency_msparameters.

See also

The MongoDB documentation on

find

find_raw_batches(filter=None, projection=None, skip=0, limit=0, no_cursor_timeout=False, cursor_type=CursorType.NON_TAILABLE, sort=None, allow_partial_results=False, oplog_replay=False, modifiers=None, batch_size=0, manipulate=True, collation=None, hint=None, max_scan=None, max_time_ms=None, max=None, min=None, return_key=False, show_record_id=False, snapshot=False, comment=None)¶

Query the database and retrieve batches of raw BSON.

Similar to the find() method but returns aRawBatchCursor.

This example demonstrates how to work with raw batches, but in practice raw batches should be passed to an external library that can decode BSON into another data type, rather than used with PyMongo’sbson module.

import bson cursor = db.test.find_raw_batches() for batch in cursor: ... print(bson.decode_all(batch))

Note

find_raw_batches does not support sessions or auto encryption.

New in version 3.6.

find_one(filter=None, *args, **kwargs)¶

Get a single document from the database.

All arguments to find() are also valid arguments forfind_one(), although any limit argument will be ignored. Returns a single document, or None if no matching document is found.

The find_one() method obeys the read_preference of this Collection.

find_one_and_delete(filter, projection=None, sort=None, hint=None, session=None, **kwargs)¶

Finds a single document and deletes it, returning the document.

db.test.count_documents({'x': 1}) 2 db.test.find_one_and_delete({'x': 1}) {u'x': 1, u'_id': ObjectId('54f4e12bfba5220aa4d6dee8')} db.test.count_documents({'x': 1}) 1

If multiple documents match filter, a sort can be applied.

for doc in db.test.find({'x': 1}): ... print(doc) ... {u'x': 1, u'_id': 0} {u'x': 1, u'_id': 1} {u'x': 1, u'_id': 2} db.test.find_one_and_delete( ... {'x': 1}, sort=[('_id', pymongo.DESCENDING)]) {u'x': 1, u'_id': 2}

The projection option can be used to limit the fields returned.

db.test.find_one_and_delete({'x': 1}, projection={'_id': False}) {u'x': 1}

Changed in version 3.11: Added hint parameter.

Changed in version 3.6: Added session parameter.

Changed in version 3.2: Respects write concern.

Warning

Starting in PyMongo 3.2, this command uses theWriteConcern of thisCollection when connected to MongoDB >= 3.2. Note that using an elevated write concern with this command may be slower compared to using the default write concern.

Changed in version 3.4: Added the collation option.

New in version 3.0.

find_one_and_replace(filter, replacement, projection=None, sort=None, return_document=ReturnDocument.BEFORE, hint=None, session=None, **kwargs)¶

Finds a single document and replaces it, returning either the original or the replaced document.

The find_one_and_replace() method differs fromfind_one_and_update() by replacing the document matched by_filter_, rather than modifying the existing document.

for doc in db.test.find({}): ... print(doc) ... {u'x': 1, u'_id': 0} {u'x': 1, u'_id': 1} {u'x': 1, u'_id': 2} db.test.find_one_and_replace({'x': 1}, {'y': 1}) {u'x': 1, u'_id': 0} for doc in db.test.find({}): ... print(doc) ... {u'y': 1, u'_id': 0} {u'x': 1, u'_id': 1} {u'x': 1, u'_id': 2}

Changed in version 3.11: Added the hint option.

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Added the collation option.

Changed in version 3.2: Respects write concern.

Warning

Starting in PyMongo 3.2, this command uses theWriteConcern of thisCollection when connected to MongoDB >= 3.2. Note that using an elevated write concern with this command may be slower compared to using the default write concern.

New in version 3.0.

find_one_and_update(filter, update, projection=None, sort=None, return_document=ReturnDocument.BEFORE, array_filters=None, hint=None, session=None, **kwargs)¶

Finds a single document and updates it, returning either the original or the updated document.

db.test.find_one_and_update( ... {'_id': 665}, {'$inc': {'count': 1}, '$set': {'done': True}}) {u'_id': 665, u'done': False, u'count': 25}}

Returns None if no document matches the filter.

db.test.find_one_and_update( ... {'_exists': False}, {'$inc': {'count': 1}})

When the filter matches, by default find_one_and_update()returns the original version of the document before the update was applied. To return the updated (or inserted in the case of_upsert_) version of the document instead, use the _return_document_option.

from pymongo import ReturnDocument db.example.find_one_and_update( ... {'_id': 'userid'}, ... {'$inc': {'seq': 1}}, ... return_document=ReturnDocument.AFTER) {u'_id': u'userid', u'seq': 1}

You can limit the fields returned with the projection option.

db.example.find_one_and_update( ... {'_id': 'userid'}, ... {'$inc': {'seq': 1}}, ... projection={'seq': True, '_id': False}, ... return_document=ReturnDocument.AFTER) {u'seq': 2}

The upsert option can be used to create the document if it doesn’t already exist.

db.example.delete_many({}).deleted_count 1 db.example.find_one_and_update( ... {'_id': 'userid'}, ... {'$inc': {'seq': 1}}, ... projection={'seq': True, '_id': False}, ... upsert=True, ... return_document=ReturnDocument.AFTER) {u'seq': 1}

If multiple documents match filter, a sort can be applied.

for doc in db.test.find({'done': True}): ... print(doc) ... {u'_id': 665, u'done': True, u'result': {u'count': 26}} {u'_id': 701, u'done': True, u'result': {u'count': 17}} db.test.find_one_and_update( ... {'done': True}, ... {'$set': {'final': True}}, ... sort=[('_id', pymongo.DESCENDING)]) {u'_id': 701, u'done': True, u'result': {u'count': 17}}

Changed in version 3.11: Added the hint option.

Changed in version 3.9: Added the ability to accept a pipeline as the update.

Changed in version 3.6: Added the array_filters and session options.

Changed in version 3.4: Added the collation option.

Changed in version 3.2: Respects write concern.

Warning

Starting in PyMongo 3.2, this command uses theWriteConcern of thisCollection when connected to MongoDB >= 3.2. Note that using an elevated write concern with this command may be slower compared to using the default write concern.

New in version 3.0.

count_documents(filter, session=None, **kwargs)¶

Count the number of documents in this collection.

Note

For a fast count of the total documents in a collection seeestimated_document_count().

The count_documents() method is supported in a transaction.

All optional parameters should be passed as keyword arguments to this method. Valid options include:

• skip (int): The number of matching documents to skip before returning results.
• limit (int): The maximum number of documents to count. Must be a positive integer. If not provided, no limit is imposed.
• maxTimeMS (int): The maximum amount of time to allow this operation to run, in milliseconds.
• collation (optional): An instance ofCollation. This option is only supported on MongoDB 3.4 and above.
• hint (string or list of tuples): The index to use. Specify either the index name as a string or the index specification as a list of tuples (e.g. [(‘a’, pymongo.ASCENDING), (‘b’, pymongo.ASCENDING)]). This option is only supported on MongoDB 3.6 and above.

The count_documents() method obeys the read_preference of this Collection.

New in version 3.7.

estimated_document_count(**kwargs)¶

Get an estimate of the number of documents in this collection using collection metadata.

The estimated_document_count() method is not supported in a transaction.

All optional parameters should be passed as keyword arguments to this method. Valid options include:

• maxTimeMS (int): The maximum amount of time to allow this operation to run, in milliseconds.

New in version 3.7.

distinct(key, filter=None, session=None, **kwargs)¶

Get a list of distinct values for key among all documents in this collection.

Raises TypeError if key is not an instance ofbasestring (str in python 3).

All optional distinct parameters should be passed as keyword arguments to this method. Valid options include:

• maxTimeMS (int): The maximum amount of time to allow the count command to run, in milliseconds.
• collation (optional): An instance ofCollation. This option is only supported on MongoDB 3.4 and above.

The distinct() method obeys the read_preference of this Collection.

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Support the collation option.

create_index(keys, session=None, **kwargs)¶

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 direction(s) must be one of (ASCENDING, DESCENDING,GEO2D, GEOHAYSTACK,GEOSPHERE, HASHED,TEXT).

To create a single key ascending 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. For example:

my_collection.create_index([("mike", pymongo.DESCENDING)], ... background=True)

Valid options include, but are not limited to:

• name: custom name to use for this index - if none is given, a name will be generated.
• unique: if True, creates a uniqueness constraint on the index.
• background: if True, this index should be created in the background.
• sparse: if True, omit from the index any documents that lack the indexed field.
• bucketSize: 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 GEO2Dindex.
• max: maximum value for keys in a GEO2Dindex.
• expireAfterSeconds: Used to create an expiring (TTL) collection. MongoDB will automatically delete documents from this collection after seconds. The indexed field must be a UTC datetime or the data will not expire.
• partialFilterExpression: A document that specifies a filter for a partial index. Requires MongoDB >=3.2.
• collation (optional): An instance ofCollation. Requires MongoDB >= 3.4.
• wildcardProjection: Allows users to include or exclude specific field paths from a wildcard index using the {“$**” : 1} key pattern. Requires MongoDB >= 4.2.
• hidden: if True, this index will be hidden from the query planner and will not be evaluated as part of query plan selection. Requires MongoDB >= 4.4.

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

Warning

dropDups is not supported by MongoDB 3.0 or newer. The option is silently ignored by the server and unique index builds using the option will fail if a duplicate value is detected.

Note

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

Changed in version 3.11: Added the hidden option.

Changed in version 3.6: Added session parameter. Added support for passing maxTimeMS in kwargs.

Changed in version 3.4: Apply this collection’s write concern automatically to this operation when connected to MongoDB >= 3.4. Support the collation option.

Changed in version 3.2: Added partialFilterExpression to support partial indexes.

Changed in version 3.0: Renamed key_or_list to keys. Removed the cache_for option.create_index() no longer caches index names. Removed support for the drop_dups and bucket_size aliases.

See also

The MongoDB documentation on

indexes

create_indexes(indexes, session=None, **kwargs)¶

Create one or more indexes on this collection.

from pymongo import IndexModel, ASCENDING, DESCENDING index1 = IndexModel([("hello", DESCENDING), ... ("world", ASCENDING)], name="hello_world") index2 = IndexModel([("goodbye", DESCENDING)]) db.test.create_indexes([index1, index2]) ["hello_world", "goodbye_-1"]

Note

create_indexes uses the createIndexes command introduced in MongoDB 2.6 and cannot be used with earlier versions.

Note

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

Changed in version 3.6: Added session parameter. Added support for arbitrary keyword arguments.

Changed in version 3.4: Apply this collection’s write concern automatically to this operation when connected to MongoDB >= 3.4.

New in version 3.0.

drop_index(index_or_name, session=None, **kwargs)¶

Drops the specified index on this collection.

Can be used on non-existant collections or collections with no indexes. Raises OperationFailure on an error (e.g. trying to drop an index that does not exist). index_or_namecan 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() orensure_index()) the index must be dropped by name.

Note

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

Changed in version 3.6: Added session parameter. Added support for arbitrary keyword arguments.

Changed in version 3.4: Apply this collection’s write concern automatically to this operation when connected to MongoDB >= 3.4.

drop_indexes(session=None, **kwargs)¶

Drops all indexes on this collection.

Can be used on non-existant collections or collections with no indexes. Raises OperationFailure on an error.

Note

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

Changed in version 3.6: Added session parameter. Added support for arbitrary keyword arguments.

Changed in version 3.4: Apply this collection’s write concern automatically to this operation when connected to MongoDB >= 3.4.

reindex(session=None, **kwargs)¶

Rebuilds all indexes on this collection.

DEPRECATED - The reindex() method is deprecated and will be removed in PyMongo 4.0. Use command()to run the reIndex command directly instead:

db.command({"reIndex": ""})

Note

Starting in MongoDB 4.6, the reIndex command can only be run when connected to a standalone mongod.

Warning

reindex blocks all other operations (indexes are built in the foreground) and will be slow for large collections.

Changed in version 3.11: Deprecated.

Changed in version 3.6: Added session parameter. Added support for arbitrary keyword arguments.

Changed in version 3.5: We no longer apply this collection’s write concern to this operation. MongoDB 3.4 silently ignored the write concern. MongoDB 3.6+ returns an error if we include the write concern.

Changed in version 3.4: Apply this collection’s write concern automatically to this operation when connected to MongoDB >= 3.4.

list_indexes(session=None)¶

Get a cursor over the index documents for this collection.

for index in db.test.list_indexes(): ... print(index) ... SON([('v', 2), ('key', SON([('_id', 1)])), ('name', 'id')])

Changed in version 3.6: Added session parameter.

New in version 3.0.

index_information(session=None)¶

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 metadata about the indexes, except for the "ns" and"name" keys, which are cleaned. Example output might look like this:

db.test.create_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 3.6: Added session parameter.

drop(session=None)¶

Alias for drop_collection().

The following two calls are equivalent:

db.foo.drop() db.drop_collection("foo")

Changed in version 3.7: drop() now respects this Collection’s write_concern.

Changed in version 3.6: Added session parameter.

rename(new_name, session=None, **kwargs)¶

Rename this collection.

If operating in auth mode, client must be authorized as an admin to perform this operation. Raises TypeError ifnew_name is not an instance of basestring(str in python 3). Raises InvalidNameif new_name is not a valid collection name.

Note

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

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Apply this collection’s write concern automatically to this operation when connected to MongoDB >= 3.4.

options(session=None)¶

Get the options set on this collection.

Returns a dictionary of options and their values - seecreate_collection() for more information on the possible options. Returns an empty dictionary if the collection has not been created yet.

Changed in version 3.6: Added session parameter.

map_reduce(map, reduce, out, full_response=False, session=None, **kwargs)¶

Perform a map/reduce operation on this collection.

If full_response is False (default) returns aCollection instance containing the results of the operation. Otherwise, returns the full response from the server to the map reduce command.

Note

The map_reduce() method does not obey theread_preference of this Collection. To run mapReduce on a secondary use the inline_map_reduce() method instead.

Note

The write_concern of this collection is automatically applied to this operation (if the output is not inline) when using MongoDB >= 3.4.

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Apply this collection’s write concern automatically to this operation when connected to MongoDB >= 3.4.

Changed in version 3.4: Added the collation option.

Changed in version 2.2: Removed deprecated arguments: merge_output and reduce_output

See also

The MongoDB documentation on

mapreduce

inline_map_reduce(map, reduce, full_response=False, session=None, **kwargs)¶

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.

The inline_map_reduce() method obeys the read_preferenceof this Collection.

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Added the collation option.

parallel_scan(num_cursors, session=None, **kwargs)¶

DEPRECATED: Scan this entire collection in parallel.

Returns a list of up to num_cursors cursors that can be iterated concurrently. As long as the collection is not modified during scanning, each document appears once in one of the cursors result sets.

For example, to process each document in a collection using some thread-safe process_document() function:

def process_cursor(cursor): ... for document in cursor: ... # Some thread-safe processing function: ... process_document(document)

Get up to 4 cursors.

... cursors = collection.parallel_scan(4) threads = [ ... threading.Thread(target=process_cursor, args=(cursor,)) ... for cursor in cursors]

for thread in threads: ... thread.start()

for thread in threads: ... thread.join()

All documents have now been processed.

The parallel_scan() method obeys the read_preference of this Collection.

Note

Requires server version >= 2.5.5.

Changed in version 3.7: Deprecated.

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Added back support for arbitrary keyword arguments. MongoDB 3.4 adds support for maxTimeMS as an option to the parallelCollectionScan command.

Changed in version 3.0: Removed support for arbitrary keyword arguments, since the parallelCollectionScan command has no optional arguments.

initialize_unordered_bulk_op(bypass_document_validation=False)¶

DEPRECATED - Initialize an unordered batch of write operations.

Operations will be performed on the server in arbitrary order, possibly in parallel. All operations will be attempted.

Returns a BulkOperationBuilder instance.

See Unordered Bulk Write Operations for examples.

Note

bypass_document_validation requires server version>= 3.2

Changed in version 3.5: Deprecated. Use bulk_write()instead.

Changed in version 3.2: Added bypass_document_validation support

New in version 2.7.

initialize_ordered_bulk_op(bypass_document_validation=False)¶

DEPRECATED - Initialize an ordered batch of write operations.

Operations will be performed on the server serially, in the order provided. If an error occurs all remaining operations are aborted.

Returns a BulkOperationBuilder instance.

See Ordered Bulk Write Operations for examples.

Note

bypass_document_validation requires server version>= 3.2

Changed in version 3.5: Deprecated. Use bulk_write()instead.

Changed in version 3.2: Added bypass_document_validation support

New in version 2.7.

group(key, condition, initial, reduce, finalize=None, **kwargs)¶

Perform a query similar to an SQL group by operation.

DEPRECATED - The group command was deprecated in MongoDB 3.4. Thegroup() method is deprecated and will be removed in PyMongo 4.0. Use aggregate() with the $group stage or map_reduce()instead.

Changed in version 3.5: Deprecated the group method.

Changed in version 3.4: Added the collation option.

Changed in version 2.2: Removed deprecated argument: command

count(filter=None, session=None, **kwargs)¶

DEPRECATED - Get the number of documents in this collection.

The count() method is deprecated and not supported in a transaction. Please use count_documents() orestimated_document_count() instead.

All optional count parameters should be passed as keyword arguments to this method. Valid options include:

• skip (int): The number of matching documents to skip before returning results.
• limit (int): The maximum number of documents to count. A limit of 0 (the default) is equivalent to setting no limit.
• maxTimeMS (int): The maximum amount of time to allow the count command to run, in milliseconds.
• collation (optional): An instance ofCollation. This option is only supported on MongoDB 3.4 and above.
• hint (string or list of tuples): The index to use. Specify either the index name as a string or the index specification as a list of tuples (e.g. [(‘a’, pymongo.ASCENDING), (‘b’, pymongo.ASCENDING)]).

The count() method obeys the read_preference of this Collection.

Changed in version 3.7: Deprecated.

Changed in version 3.6: Added session parameter.

Changed in version 3.4: Support the collation option.

insert(doc_or_docs, manipulate=True, check_keys=True, continue_on_error=False, **kwargs)¶

Insert a document(s) into this collection.

DEPRECATED - Use insert_one() or insert_many() instead.

Changed in version 3.0: Removed the safe parameter. Pass w=0 for unacknowledged write operations.

save(to_save, manipulate=True, check_keys=True, **kwargs)¶

Save a document in this collection.

DEPRECATED - Use insert_one() or replace_one() instead.

Changed in version 3.0: Removed the safe parameter. Pass w=0 for unacknowledged write operations.

update(spec, document, upsert=False, manipulate=False, multi=False, check_keys=True, **kwargs)¶

Update a document(s) in this collection.

DEPRECATED - Use replace_one(), update_one(), orupdate_many() instead.

Changed in version 3.0: Removed the safe parameter. Pass w=0 for unacknowledged write operations.

remove(spec_or_id=None, multi=True, **kwargs)¶

Remove a document(s) from this collection.

DEPRECATED - Use delete_one() or delete_many() instead.

Changed in version 3.0: Removed the safe parameter. Pass w=0 for unacknowledged write operations.

find_and_modify(query={}, update=None, upsert=False, sort=None, full_response=False, manipulate=False, **kwargs)¶

Update and return an object.

DEPRECATED - Use find_one_and_delete(),find_one_and_replace(), or find_one_and_update() instead.

ensure_index(key_or_list, cache_for=300, **kwargs)¶

DEPRECATED - Ensures that an index exists on this collection.

Changed in version 3.0: DEPRECATED