Class ReplaceOne

pymongo/operations.py:318–458

Represents a replace_one operation.

class ReplaceOne(Generic[_DocumentType]):
    """Represents a replace_one operation."""

    __slots__ = (
        "_filter",
        "_doc",
        "_upsert",
        "_collation",
        "_hint",
        "_namespace",
        "_sort",
    )

    def __init__(
        self,
        filter: Mapping[str, Any],
        replacement: Union[_DocumentType, RawBSONDocument],
        upsert: Optional[bool] = None,
        collation: Optional[_CollationIn] = None,
        hint: Optional[_IndexKeyHint] = None,
        namespace: Optional[str] = None,
        sort: Optional[Mapping[str, Any]] = None,
    ) -> None:
        """Create a ReplaceOne instance.

        For use with :meth:`~pymongo.asynchronous.collection.AsyncCollection.bulk_write`, :meth:`~pymongo.collection.Collection.bulk_write`,
        :meth:`~pymongo.asynchronous.mongo_client.AsyncMongoClient.bulk_write` and :meth:`~pymongo.mongo_client.MongoClient.bulk_write`.

        :param filter: A query that matches the document to replace.
        :param replacement: The new document.
        :param upsert: If ``True``, perform an insert if no documents
            match the filter.
        :param collation: An instance of
            :class:`~pymongo.collation.Collation`.
        :param hint: An index to use to support the query
            predicate specified either by its string name, or in the same
            format as passed to
            :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index` or :meth:`~pymongo.collection.Collection.create_index` (e.g.
            ``[('field', ASCENDING)]``). This option is only supported on
            MongoDB 4.2 and above.
        :param sort: Specify which document the operation updates if the query matches
            multiple documents. The first document matched by the sort order will be updated.
        :param namespace: (optional) The namespace in which to replace a document.

        .. versionchanged:: 4.10
            Added ``sort`` option.
        .. versionchanged:: 4.9
           Added the `namespace` option to support `MongoClient.bulk_write`.
        .. versionchanged:: 3.11
           Added the ``hint`` option.
        .. versionchanged:: 3.5
           Added the ``collation`` option.
        """
        if filter is not None:
            validate_is_mapping("filter", filter)
        if upsert is not None:
            validate_boolean("upsert", upsert)
        if hint is not None and not isinstance(hint, str):