operations – Operation class definitions

Operation class definitions.

See also

This module is compatible with both the synchronous and asynchronous PyMongo APIs.

class pymongo.operations.DeleteMany(filter, collation=None, hint=None, namespace=None)

Create a DeleteMany instance.

For use with bulk_write(), bulk_write(), bulk_write() and bulk_write().

Parameters:

  • filter (Mapping[str, Any]) – A query that matches the documents to delete.

  • collation (Optional[_CollationIn]) – An instance of Collation.

  • hint (Optional[_IndexKeyHint]) – An index to use to support the query predicate specified either by its string name, or in the same format as passed to create_index() or create_index() (e.g. [('field', ASCENDING)]). This option is only supported on MongoDB 4.4 and above.

  • namespace (Optional[str]) – (optional) The namespace in which to delete documents.

Changed in version 4.9: Added the namespace option to support MongoClient.bulk_write.

Changed in version 3.11: Added the hint option.

Changed in version 3.5: Added the collation option.

class pymongo.operations.DeleteOne(filter, collation=None, hint=None, namespace=None)

Create a DeleteOne instance.

For use with bulk_write(), bulk_write(), bulk_write() and bulk_write().

Parameters:

  • filter (Mapping[str, Any]) – A query that matches the document to delete.

  • collation (Optional[_CollationIn]) – An instance of Collation.

  • hint (Optional[_IndexKeyHint]) – An index to use to support the query predicate specified either by its string name, or in the same format as passed to create_index() or create_index() (e.g. [('field', ASCENDING)]). This option is only supported on MongoDB 4.4 and above.

  • namespace (Optional[str]) – (optional) The namespace in which to delete a document.

Changed in version 4.9: Added the namespace option to support MongoClient.bulk_write.

Changed in version 3.11: Added the hint option.

Changed in version 3.5: Added the collation option.

class pymongo.operations.IndexModel(keys, **kwargs)

Create an Index instance.

For use with create_indexes() and create_indexes().

Takes either a single key or a list containing (key, direction) pairs or keys. If no direction is given, ASCENDING will be assumed. The key(s) must be an instance of str, and the direction(s) must be one of (ASCENDING, DESCENDING, GEO2D, GEOSPHERE, HASHED, TEXT).

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

  • partialFilterExpression: A document that specifies a filter for a partial index.

  • collation: An instance of Collation that specifies the collation to use.

  • 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.

Parameters:

  • keys (_IndexKeyHint) – a single key or a list containing (key, direction) pairs or keys specifying the index to create.

  • kwargs (Any) – any additional index creation options (see the above list) should be passed as keyword arguments.

Changed in version 3.11: Added the hidden option.

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

property document: dict[str, Any]

An index document suitable for passing to the createIndexes command.

class pymongo.operations.InsertOne(document, namespace=None)

Create an InsertOne instance.

For use with bulk_write(), bulk_write(), bulk_write() and bulk_write().

Parameters:

  • document (_DocumentType) – The document to insert. If the document is missing an _id field one will be added.

  • namespace (Optional[str]) – (optional) The namespace in which to insert a document.

Changed in version 4.9: Added the namespace option to support MongoClient.bulk_write.

class pymongo.operations.ReplaceOne(filter, replacement, upsert=False, collation=None, hint=None, namespace=None)

Create a ReplaceOne instance.

For use with bulk_write(), bulk_write(), bulk_write() and bulk_write().

Parameters:

  • filter (Mapping[str, Any]) – A query that matches the document to replace.

  • replacement (Union[_DocumentType, RawBSONDocument]) – The new document.

  • upsert (bool) – If True, perform an insert if no documents match the filter.

  • collation (Optional[_CollationIn]) – An instance of Collation.

  • hint (Optional[_IndexKeyHint]) – An index to use to support the query predicate specified either by its string name, or in the same format as passed to create_index() or create_index() (e.g. [('field', ASCENDING)]). This option is only supported on MongoDB 4.2 and above.

  • namespace (Optional[str]) – (optional) The namespace in which to replace a document.

Changed in version 4.9: Added the namespace option to support MongoClient.bulk_write.

Changed in version 3.11: Added the hint option.

Changed in version 3.5: Added the collation option.

class pymongo.operations.SearchIndexModel(definition, name=None, type=None, **kwargs)

Create a Search Index instance.

For use with create_search_index() and create_search_indexes().

Parameters:

  • definition (Mapping[str, Any]) – The definition for this index.

  • name (Optional[str]) – The name for this index, if present.

  • type (Optional[str]) – The type for this index which defaults to “search”. Alternative values include “vectorSearch”.

  • kwargs (Any) – Keyword arguments supplying any additional options.

Note

Search indexes require a MongoDB server version 7.0+ Atlas cluster.

Added in version 4.5.

Changed in version 4.7: Added the type and kwargs arguments.

property document: Mapping[str, Any]

The document for this index.

class pymongo.operations.UpdateMany(filter, update, upsert=None, collation=None, array_filters=None, hint=None, namespace=None)

Create an UpdateMany instance.

For use with bulk_write(), bulk_write(), bulk_write() and bulk_write().

Parameters:

  • filter (Mapping[str, Any]) – A query that matches the documents to update.

  • update (Union[Mapping[str, Any], _Pipeline]) – The modifications to apply.

  • upsert (Optional[bool]) – If True, perform an insert if no documents match the filter.

  • collation (Optional[_CollationIn]) – An instance of Collation.

  • array_filters (Optional[list[Mapping[str, Any]]]) – A list of filters specifying which array elements an update should apply.

  • hint (Optional[_IndexKeyHint]) – An index to use to support the query predicate specified either by its string name, or in the same format as passed to create_index() or create_index() (e.g. [('field', ASCENDING)]). This option is only supported on MongoDB 4.2 and above.

  • namespace (Optional[str]) – (optional) The namespace in which to update documents.

Changed in version 4.9: Added the namespace option to support MongoClient.bulk_write.

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 option.

Changed in version 3.5: Added the collation option.

class pymongo.operations.UpdateOne(filter, update, upsert=None, collation=None, array_filters=None, hint=None, namespace=None)

Represents an update_one operation.

For use with bulk_write(), bulk_write(), bulk_write() and bulk_write().

Parameters:

  • filter (Mapping[str, Any]) – A query that matches the document to update.

  • update (Union[Mapping[str, Any], _Pipeline]) – The modifications to apply.

  • upsert (Optional[bool]) – If True, perform an insert if no documents match the filter.

  • collation (Optional[_CollationIn]) – An instance of Collation.

  • array_filters (Optional[list[Mapping[str, Any]]]) – A list of filters specifying which array elements an update should apply.

  • hint (Optional[_IndexKeyHint]) – An index to use to support the query predicate specified either by its string name, or in the same format as passed to create_index() or create_index() (e.g. [('field', ASCENDING)]). This option is only supported on MongoDB 4.2 and above.

  • namespace (Optional[str]) – (optional) The namespace in which to update a document.

Changed in version 4.9: Added the namespace option to support MongoClient.bulk_write.

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 option.

Changed in version 3.5: Added the collation option.