815 lines
30 KiB
Python
815 lines
30 KiB
Python
# Copyright 2015-present MongoDB, Inc.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
"""Operation class definitions.
|
|
|
|
.. seealso:: This module is compatible with both the synchronous and asynchronous PyMongo APIs.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import enum
|
|
from typing import (
|
|
TYPE_CHECKING,
|
|
Any,
|
|
Generic,
|
|
Mapping,
|
|
Optional,
|
|
Sequence,
|
|
Tuple,
|
|
Union,
|
|
)
|
|
|
|
from bson.raw_bson import RawBSONDocument
|
|
from pymongo import helpers_shared
|
|
from pymongo.collation import validate_collation_or_none
|
|
from pymongo.common import validate_is_mapping, validate_list
|
|
from pymongo.errors import InvalidOperation
|
|
from pymongo.helpers_shared import _gen_index_name, _index_document, _index_list
|
|
from pymongo.typings import _CollationIn, _DocumentType, _Pipeline
|
|
from pymongo.write_concern import validate_boolean
|
|
|
|
if TYPE_CHECKING:
|
|
from pymongo.typings import _AgnosticBulk, _AgnosticClientBulk
|
|
|
|
|
|
# Hint supports index name, "myIndex", a list of either strings or index pairs: [('x', 1), ('y', -1), 'z''], or a dictionary
|
|
_IndexList = Union[
|
|
Sequence[Union[str, Tuple[str, Union[int, str, Mapping[str, Any]]]]], Mapping[str, Any]
|
|
]
|
|
_IndexKeyHint = Union[str, _IndexList]
|
|
|
|
|
|
class _Op(str, enum.Enum):
|
|
ABORT = "abortTransaction"
|
|
AGGREGATE = "aggregate"
|
|
BULK_WRITE = "bulkWrite"
|
|
COMMIT = "commitTransaction"
|
|
COUNT = "count"
|
|
CREATE = "create"
|
|
CREATE_INDEXES = "createIndexes"
|
|
CREATE_SEARCH_INDEXES = "createSearchIndexes"
|
|
DELETE = "delete"
|
|
DISTINCT = "distinct"
|
|
DROP = "drop"
|
|
DROP_DATABASE = "dropDatabase"
|
|
DROP_INDEXES = "dropIndexes"
|
|
DROP_SEARCH_INDEXES = "dropSearchIndexes"
|
|
END_SESSIONS = "endSessions"
|
|
FIND_AND_MODIFY = "findAndModify"
|
|
FIND = "find"
|
|
INSERT = "insert"
|
|
LIST_COLLECTIONS = "listCollections"
|
|
LIST_INDEXES = "listIndexes"
|
|
LIST_SEARCH_INDEX = "listSearchIndexes"
|
|
LIST_DATABASES = "listDatabases"
|
|
UPDATE = "update"
|
|
UPDATE_INDEX = "updateIndex"
|
|
UPDATE_SEARCH_INDEX = "updateSearchIndex"
|
|
RENAME = "rename"
|
|
GETMORE = "getMore"
|
|
KILL_CURSORS = "killCursors"
|
|
TEST = "testOperation"
|
|
|
|
|
|
class InsertOne(Generic[_DocumentType]):
|
|
"""Represents an insert_one operation."""
|
|
|
|
__slots__ = (
|
|
"_doc",
|
|
"_namespace",
|
|
)
|
|
|
|
def __init__(self, document: _DocumentType, namespace: Optional[str] = None) -> None:
|
|
"""Create an InsertOne 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 document: The document to insert. If the document is missing an
|
|
_id field one will be added.
|
|
:param namespace: (optional) The namespace in which to insert a document.
|
|
|
|
.. versionchanged:: 4.9
|
|
Added the `namespace` option to support `MongoClient.bulk_write`.
|
|
"""
|
|
self._doc = document
|
|
self._namespace = namespace
|
|
|
|
def _add_to_bulk(self, bulkobj: _AgnosticBulk) -> None:
|
|
"""Add this operation to the _AsyncBulk/_Bulk instance `bulkobj`."""
|
|
bulkobj.add_insert(self._doc) # type: ignore[arg-type]
|
|
|
|
def _add_to_client_bulk(self, bulkobj: _AgnosticClientBulk) -> None:
|
|
"""Add this operation to the _AsyncClientBulk/_ClientBulk instance `bulkobj`."""
|
|
if not self._namespace:
|
|
raise InvalidOperation(
|
|
"MongoClient.bulk_write requires a namespace to be provided for each write operation"
|
|
)
|
|
bulkobj.add_insert(
|
|
self._namespace,
|
|
self._doc, # type: ignore[arg-type]
|
|
)
|
|
|
|
def __repr__(self) -> str:
|
|
if self._namespace:
|
|
return f"{self.__class__.__name__}({self._doc!r}, {self._namespace!r})"
|
|
return f"{self.__class__.__name__}({self._doc!r})"
|
|
|
|
def __eq__(self, other: Any) -> bool:
|
|
if type(other) == type(self):
|
|
return other._doc == self._doc and other._namespace == self._namespace
|
|
return NotImplemented
|
|
|
|
def __ne__(self, other: Any) -> bool:
|
|
return not self == other
|
|
|
|
|
|
class _DeleteOp:
|
|
"""Private base class for delete operations."""
|
|
|
|
__slots__ = (
|
|
"_filter",
|
|
"_collation",
|
|
"_hint",
|
|
"_namespace",
|
|
)
|
|
|
|
def __init__(
|
|
self,
|
|
filter: Mapping[str, Any],
|
|
collation: Optional[_CollationIn] = None,
|
|
hint: Optional[_IndexKeyHint] = None,
|
|
namespace: Optional[str] = None,
|
|
) -> None:
|
|
if filter is not None:
|
|
validate_is_mapping("filter", filter)
|
|
if hint is not None and not isinstance(hint, str):
|
|
self._hint: Union[str, dict[str, Any], None] = helpers_shared._index_document(hint)
|
|
else:
|
|
self._hint = hint
|
|
|
|
self._filter = filter
|
|
self._collation = collation
|
|
self._namespace = namespace
|
|
|
|
def __eq__(self, other: Any) -> bool:
|
|
if type(other) == type(self):
|
|
return (
|
|
other._filter,
|
|
other._collation,
|
|
other._hint,
|
|
other._namespace,
|
|
) == (
|
|
self._filter,
|
|
self._collation,
|
|
self._hint,
|
|
self._namespace,
|
|
)
|
|
return NotImplemented
|
|
|
|
def __ne__(self, other: Any) -> bool:
|
|
return not self == other
|
|
|
|
def __repr__(self) -> str:
|
|
if self._namespace:
|
|
return "{}({!r}, {!r}, {!r}, {!r})".format(
|
|
self.__class__.__name__,
|
|
self._filter,
|
|
self._collation,
|
|
self._hint,
|
|
self._namespace,
|
|
)
|
|
return f"{self.__class__.__name__}({self._filter!r}, {self._collation!r}, {self._hint!r})"
|
|
|
|
|
|
class DeleteOne(_DeleteOp):
|
|
"""Represents a delete_one operation."""
|
|
|
|
__slots__ = ()
|
|
|
|
def __init__(
|
|
self,
|
|
filter: Mapping[str, Any],
|
|
collation: Optional[_CollationIn] = None,
|
|
hint: Optional[_IndexKeyHint] = None,
|
|
namespace: Optional[str] = None,
|
|
) -> None:
|
|
"""Create a DeleteOne 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 delete.
|
|
: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.4 and above.
|
|
:param namespace: (optional) The namespace in which to delete a document.
|
|
|
|
.. 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.
|
|
"""
|
|
super().__init__(filter, collation, hint, namespace)
|
|
|
|
def _add_to_bulk(self, bulkobj: _AgnosticBulk) -> None:
|
|
"""Add this operation to the _AsyncBulk/_Bulk instance `bulkobj`."""
|
|
bulkobj.add_delete(
|
|
self._filter,
|
|
1,
|
|
collation=validate_collation_or_none(self._collation),
|
|
hint=self._hint,
|
|
)
|
|
|
|
def _add_to_client_bulk(self, bulkobj: _AgnosticClientBulk) -> None:
|
|
"""Add this operation to the _AsyncClientBulk/_ClientBulk instance `bulkobj`."""
|
|
if not self._namespace:
|
|
raise InvalidOperation(
|
|
"MongoClient.bulk_write requires a namespace to be provided for each write operation"
|
|
)
|
|
bulkobj.add_delete(
|
|
self._namespace,
|
|
self._filter,
|
|
multi=False,
|
|
collation=validate_collation_or_none(self._collation),
|
|
hint=self._hint,
|
|
)
|
|
|
|
|
|
class DeleteMany(_DeleteOp):
|
|
"""Represents a delete_many operation."""
|
|
|
|
__slots__ = ()
|
|
|
|
def __init__(
|
|
self,
|
|
filter: Mapping[str, Any],
|
|
collation: Optional[_CollationIn] = None,
|
|
hint: Optional[_IndexKeyHint] = None,
|
|
namespace: Optional[str] = None,
|
|
) -> None:
|
|
"""Create a DeleteMany 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 documents to delete.
|
|
: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.4 and above.
|
|
:param namespace: (optional) The namespace in which to delete documents.
|
|
|
|
.. 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.
|
|
"""
|
|
super().__init__(filter, collation, hint, namespace)
|
|
|
|
def _add_to_bulk(self, bulkobj: _AgnosticBulk) -> None:
|
|
"""Add this operation to the _AsyncBulk/_Bulk instance `bulkobj`."""
|
|
bulkobj.add_delete(
|
|
self._filter,
|
|
0,
|
|
collation=validate_collation_or_none(self._collation),
|
|
hint=self._hint,
|
|
)
|
|
|
|
def _add_to_client_bulk(self, bulkobj: _AgnosticClientBulk) -> None:
|
|
"""Add this operation to the _AsyncClientBulk/_ClientBulk instance `bulkobj`."""
|
|
if not self._namespace:
|
|
raise InvalidOperation(
|
|
"MongoClient.bulk_write requires a namespace to be provided for each write operation"
|
|
)
|
|
bulkobj.add_delete(
|
|
self._namespace,
|
|
self._filter,
|
|
multi=True,
|
|
collation=validate_collation_or_none(self._collation),
|
|
hint=self._hint,
|
|
)
|
|
|
|
|
|
class ReplaceOne(Generic[_DocumentType]):
|
|
"""Represents a replace_one operation."""
|
|
|
|
__slots__ = (
|
|
"_filter",
|
|
"_doc",
|
|
"_upsert",
|
|
"_collation",
|
|
"_hint",
|
|
"_namespace",
|
|
)
|
|
|
|
def __init__(
|
|
self,
|
|
filter: Mapping[str, Any],
|
|
replacement: Union[_DocumentType, RawBSONDocument],
|
|
upsert: bool = False,
|
|
collation: Optional[_CollationIn] = None,
|
|
hint: Optional[_IndexKeyHint] = None,
|
|
namespace: Optional[str] = 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 namespace: (optional) The namespace in which to replace a document.
|
|
|
|
.. 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):
|
|
self._hint: Union[str, dict[str, Any], None] = helpers_shared._index_document(hint)
|
|
else:
|
|
self._hint = hint
|
|
|
|
self._filter = filter
|
|
self._doc = replacement
|
|
self._upsert = upsert
|
|
self._collation = collation
|
|
self._namespace = namespace
|
|
|
|
def _add_to_bulk(self, bulkobj: _AgnosticBulk) -> None:
|
|
"""Add this operation to the _AsyncBulk/_Bulk instance `bulkobj`."""
|
|
bulkobj.add_replace(
|
|
self._filter,
|
|
self._doc,
|
|
self._upsert,
|
|
collation=validate_collation_or_none(self._collation),
|
|
hint=self._hint,
|
|
)
|
|
|
|
def _add_to_client_bulk(self, bulkobj: _AgnosticClientBulk) -> None:
|
|
"""Add this operation to the _AsyncClientBulk/_ClientBulk instance `bulkobj`."""
|
|
if not self._namespace:
|
|
raise InvalidOperation(
|
|
"MongoClient.bulk_write requires a namespace to be provided for each write operation"
|
|
)
|
|
bulkobj.add_replace(
|
|
self._namespace,
|
|
self._filter,
|
|
self._doc,
|
|
self._upsert,
|
|
collation=validate_collation_or_none(self._collation),
|
|
hint=self._hint,
|
|
)
|
|
|
|
def __eq__(self, other: Any) -> bool:
|
|
if type(other) == type(self):
|
|
return (
|
|
other._filter,
|
|
other._doc,
|
|
other._upsert,
|
|
other._collation,
|
|
other._hint,
|
|
other._namespace,
|
|
) == (
|
|
self._filter,
|
|
self._doc,
|
|
self._upsert,
|
|
self._collation,
|
|
other._hint,
|
|
self._namespace,
|
|
)
|
|
return NotImplemented
|
|
|
|
def __ne__(self, other: Any) -> bool:
|
|
return not self == other
|
|
|
|
def __repr__(self) -> str:
|
|
if self._namespace:
|
|
return "{}({!r}, {!r}, {!r}, {!r}, {!r}, {!r})".format(
|
|
self.__class__.__name__,
|
|
self._filter,
|
|
self._doc,
|
|
self._upsert,
|
|
self._collation,
|
|
self._hint,
|
|
self._namespace,
|
|
)
|
|
return "{}({!r}, {!r}, {!r}, {!r}, {!r})".format(
|
|
self.__class__.__name__,
|
|
self._filter,
|
|
self._doc,
|
|
self._upsert,
|
|
self._collation,
|
|
self._hint,
|
|
)
|
|
|
|
|
|
class _UpdateOp:
|
|
"""Private base class for update operations."""
|
|
|
|
__slots__ = (
|
|
"_filter",
|
|
"_doc",
|
|
"_upsert",
|
|
"_collation",
|
|
"_array_filters",
|
|
"_hint",
|
|
"_namespace",
|
|
)
|
|
|
|
def __init__(
|
|
self,
|
|
filter: Mapping[str, Any],
|
|
doc: Union[Mapping[str, Any], _Pipeline],
|
|
upsert: Optional[bool],
|
|
collation: Optional[_CollationIn],
|
|
array_filters: Optional[list[Mapping[str, Any]]],
|
|
hint: Optional[_IndexKeyHint],
|
|
namespace: Optional[str],
|
|
):
|
|
if filter is not None:
|
|
validate_is_mapping("filter", filter)
|
|
if upsert is not None:
|
|
validate_boolean("upsert", upsert)
|
|
if array_filters is not None:
|
|
validate_list("array_filters", array_filters)
|
|
if hint is not None and not isinstance(hint, str):
|
|
self._hint: Union[str, dict[str, Any], None] = helpers_shared._index_document(hint)
|
|
else:
|
|
self._hint = hint
|
|
|
|
self._filter = filter
|
|
self._doc = doc
|
|
self._upsert = upsert
|
|
self._collation = collation
|
|
self._array_filters = array_filters
|
|
self._namespace = namespace
|
|
|
|
def __eq__(self, other: object) -> bool:
|
|
if isinstance(other, type(self)):
|
|
return (
|
|
other._filter,
|
|
other._doc,
|
|
other._upsert,
|
|
other._collation,
|
|
other._array_filters,
|
|
other._hint,
|
|
other._namespace,
|
|
) == (
|
|
self._filter,
|
|
self._doc,
|
|
self._upsert,
|
|
self._collation,
|
|
self._array_filters,
|
|
self._hint,
|
|
self._namespace,
|
|
)
|
|
return NotImplemented
|
|
|
|
def __ne__(self, other: Any) -> bool:
|
|
return not self == other
|
|
|
|
def __repr__(self) -> str:
|
|
if self._namespace:
|
|
return "{}({!r}, {!r}, {!r}, {!r}, {!r}, {!r}, {!r})".format(
|
|
self.__class__.__name__,
|
|
self._filter,
|
|
self._doc,
|
|
self._upsert,
|
|
self._collation,
|
|
self._array_filters,
|
|
self._hint,
|
|
self._namespace,
|
|
)
|
|
return "{}({!r}, {!r}, {!r}, {!r}, {!r}, {!r})".format(
|
|
self.__class__.__name__,
|
|
self._filter,
|
|
self._doc,
|
|
self._upsert,
|
|
self._collation,
|
|
self._array_filters,
|
|
self._hint,
|
|
)
|
|
|
|
|
|
class UpdateOne(_UpdateOp):
|
|
"""Represents an update_one operation."""
|
|
|
|
__slots__ = ()
|
|
|
|
def __init__(
|
|
self,
|
|
filter: Mapping[str, Any],
|
|
update: Union[Mapping[str, Any], _Pipeline],
|
|
upsert: Optional[bool] = None,
|
|
collation: Optional[_CollationIn] = None,
|
|
array_filters: Optional[list[Mapping[str, Any]]] = None,
|
|
hint: Optional[_IndexKeyHint] = None,
|
|
namespace: Optional[str] = None,
|
|
) -> None:
|
|
"""Represents an update_one operation.
|
|
|
|
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 update.
|
|
:param update: The modifications to apply.
|
|
:param upsert: If ``True``, perform an insert if no documents
|
|
match the filter.
|
|
:param collation: An instance of
|
|
:class:`~pymongo.collation.Collation`.
|
|
:param array_filters: A list of filters specifying which
|
|
array elements an update should apply.
|
|
: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 namespace: (optional) The namespace in which to update a document.
|
|
|
|
.. versionchanged:: 4.9
|
|
Added the `namespace` option to support `MongoClient.bulk_write`.
|
|
.. versionchanged:: 3.11
|
|
Added the `hint` option.
|
|
.. versionchanged:: 3.9
|
|
Added the ability to accept a pipeline as the `update`.
|
|
.. versionchanged:: 3.6
|
|
Added the `array_filters` option.
|
|
.. versionchanged:: 3.5
|
|
Added the `collation` option.
|
|
"""
|
|
super().__init__(filter, update, upsert, collation, array_filters, hint, namespace)
|
|
|
|
def _add_to_bulk(self, bulkobj: _AgnosticBulk) -> None:
|
|
"""Add this operation to the _AsyncBulk/_Bulk instance `bulkobj`."""
|
|
bulkobj.add_update(
|
|
self._filter,
|
|
self._doc,
|
|
False,
|
|
bool(self._upsert),
|
|
collation=validate_collation_or_none(self._collation),
|
|
array_filters=self._array_filters,
|
|
hint=self._hint,
|
|
)
|
|
|
|
def _add_to_client_bulk(self, bulkobj: _AgnosticClientBulk) -> None:
|
|
"""Add this operation to the _AsyncClientBulk/_ClientBulk instance `bulkobj`."""
|
|
if not self._namespace:
|
|
raise InvalidOperation(
|
|
"MongoClient.bulk_write requires a namespace to be provided for each write operation"
|
|
)
|
|
bulkobj.add_update(
|
|
self._namespace,
|
|
self._filter,
|
|
self._doc,
|
|
False,
|
|
self._upsert,
|
|
collation=validate_collation_or_none(self._collation),
|
|
array_filters=self._array_filters,
|
|
hint=self._hint,
|
|
)
|
|
|
|
|
|
class UpdateMany(_UpdateOp):
|
|
"""Represents an update_many operation."""
|
|
|
|
__slots__ = ()
|
|
|
|
def __init__(
|
|
self,
|
|
filter: Mapping[str, Any],
|
|
update: Union[Mapping[str, Any], _Pipeline],
|
|
upsert: Optional[bool] = None,
|
|
collation: Optional[_CollationIn] = None,
|
|
array_filters: Optional[list[Mapping[str, Any]]] = None,
|
|
hint: Optional[_IndexKeyHint] = None,
|
|
namespace: Optional[str] = None,
|
|
) -> None:
|
|
"""Create an UpdateMany 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 documents to update.
|
|
:param update: The modifications to apply.
|
|
:param upsert: If ``True``, perform an insert if no documents
|
|
match the filter.
|
|
:param collation: An instance of
|
|
:class:`~pymongo.collation.Collation`.
|
|
:param array_filters: A list of filters specifying which
|
|
array elements an update should apply.
|
|
: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 namespace: (optional) The namespace in which to update documents.
|
|
|
|
.. versionchanged:: 4.9
|
|
Added the `namespace` option to support `MongoClient.bulk_write`.
|
|
.. versionchanged:: 3.11
|
|
Added the `hint` option.
|
|
.. versionchanged:: 3.9
|
|
Added the ability to accept a pipeline as the `update`.
|
|
.. versionchanged:: 3.6
|
|
Added the `array_filters` option.
|
|
.. versionchanged:: 3.5
|
|
Added the `collation` option.
|
|
"""
|
|
super().__init__(filter, update, upsert, collation, array_filters, hint, namespace)
|
|
|
|
def _add_to_bulk(self, bulkobj: _AgnosticBulk) -> None:
|
|
"""Add this operation to the _AsyncBulk/_Bulk instance `bulkobj`."""
|
|
bulkobj.add_update(
|
|
self._filter,
|
|
self._doc,
|
|
True,
|
|
bool(self._upsert),
|
|
collation=validate_collation_or_none(self._collation),
|
|
array_filters=self._array_filters,
|
|
hint=self._hint,
|
|
)
|
|
|
|
def _add_to_client_bulk(self, bulkobj: _AgnosticClientBulk) -> None:
|
|
"""Add this operation to the _AsyncClientBulk/_ClientBulk instance `bulkobj`."""
|
|
if not self._namespace:
|
|
raise InvalidOperation(
|
|
"MongoClient.bulk_write requires a namespace to be provided for each write operation"
|
|
)
|
|
bulkobj.add_update(
|
|
self._namespace,
|
|
self._filter,
|
|
self._doc,
|
|
True,
|
|
self._upsert,
|
|
collation=validate_collation_or_none(self._collation),
|
|
array_filters=self._array_filters,
|
|
hint=self._hint,
|
|
)
|
|
|
|
|
|
class IndexModel:
|
|
"""Represents an index to create."""
|
|
|
|
__slots__ = ("__document",)
|
|
|
|
def __init__(self, keys: _IndexKeyHint, **kwargs: Any) -> None:
|
|
"""Create an Index instance.
|
|
|
|
For use with :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_indexes` and :meth:`~pymongo.collection.Collection.create_indexes`.
|
|
|
|
Takes either a single key or a list containing (key, direction) pairs
|
|
or keys. If no direction is given, :data:`~pymongo.ASCENDING` will
|
|
be assumed.
|
|
The key(s) must be an instance of :class:`str`, and the direction(s) must
|
|
be one of (:data:`~pymongo.ASCENDING`, :data:`~pymongo.DESCENDING`,
|
|
:data:`~pymongo.GEO2D`, :data:`~pymongo.GEOSPHERE`,
|
|
:data:`~pymongo.HASHED`, :data:`~pymongo.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 :data:`~pymongo.GEO2D`
|
|
index.
|
|
- `max`: maximum value for keys in a :data:`~pymongo.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 :class:`~pymongo.collation.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.
|
|
|
|
:param keys: a single key or a list containing (key, direction) pairs
|
|
or keys specifying the index to create.
|
|
:param kwargs: any additional index creation
|
|
options (see the above list) should be passed as keyword
|
|
arguments.
|
|
|
|
.. versionchanged:: 3.11
|
|
Added the ``hidden`` option.
|
|
.. versionchanged:: 3.2
|
|
Added the ``partialFilterExpression`` option to support partial
|
|
indexes.
|
|
|
|
.. _wildcard index: https://mongodb.com/docs/master/core/index-wildcard/
|
|
"""
|
|
keys = _index_list(keys)
|
|
if kwargs.get("name") is None:
|
|
kwargs["name"] = _gen_index_name(keys)
|
|
kwargs["key"] = _index_document(keys)
|
|
collation = validate_collation_or_none(kwargs.pop("collation", None))
|
|
self.__document = kwargs
|
|
if collation is not None:
|
|
self.__document["collation"] = collation
|
|
|
|
@property
|
|
def document(self) -> dict[str, Any]:
|
|
"""An index document suitable for passing to the createIndexes
|
|
command.
|
|
"""
|
|
return self.__document
|
|
|
|
|
|
class SearchIndexModel:
|
|
"""Represents a search index to create."""
|
|
|
|
__slots__ = ("__document",)
|
|
|
|
def __init__(
|
|
self,
|
|
definition: Mapping[str, Any],
|
|
name: Optional[str] = None,
|
|
type: Optional[str] = None,
|
|
**kwargs: Any,
|
|
) -> None:
|
|
"""Create a Search Index instance.
|
|
|
|
For use with :meth:`~pymongo.collection.AsyncCollection.create_search_index` and :meth:`~pymongo.collection.AsyncCollection.create_search_indexes`.
|
|
|
|
:param definition: The definition for this index.
|
|
:param name: The name for this index, if present.
|
|
:param type: The type for this index which defaults to "search". Alternative values include "vectorSearch".
|
|
:param kwargs: Keyword arguments supplying any additional options.
|
|
|
|
.. note:: Search indexes require a MongoDB server version 7.0+ Atlas cluster.
|
|
.. versionadded:: 4.5
|
|
.. versionchanged:: 4.7
|
|
Added the type and kwargs arguments.
|
|
"""
|
|
self.__document: dict[str, Any] = {}
|
|
if name is not None:
|
|
self.__document["name"] = name
|
|
self.__document["definition"] = definition
|
|
if type is not None:
|
|
self.__document["type"] = type
|
|
self.__document.update(kwargs)
|
|
|
|
@property
|
|
def document(self) -> Mapping[str, Any]:
|
|
"""The document for this index."""
|
|
return self.__document
|