Public Member Functions | |
| def | __call__ |
| def | __cmp__ |
| def | __getattr__ |
| def | __getitem__ |
| def | __init__ |
| def | __iter__ |
| def | __repr__ |
| def | count |
| def | create_index |
| def | database |
| def | distinct |
| def | drop |
| def | drop_index |
| def | drop_indexes |
| def | ensure_index |
| def | find |
| def | find_and_modify |
| def | find_one |
| def | full_name |
| def | group |
| def | index_information |
| def | inline_map_reduce |
| def | insert |
| def | map_reduce |
| def | name |
| def | next |
| def | options |
| def | remove |
| def | rename |
| def | save |
| def | update |
Private Member Functions | |
| def | __create |
Private Attributes | |
| __database | |
| __full_name | |
| __name | |
A Mongo collection.
Definition at line 35 of file collection.py.
| def pymongo::collection::Collection::__call__ | ( | self, | ||
| args, | ||||
| kwargs | ||||
| ) |
This is only here so that some API misusages are easier to debug.
Definition at line 1078 of file collection.py.
| def pymongo::collection::Collection::__cmp__ | ( | self, | ||
| other | ||||
| ) |
Definition at line 132 of file collection.py.
| def pymongo::collection::Collection::__create | ( | self, | ||
| options | ||||
| ) | [private] |
Sends a create command with the given options.
Definition at line 103 of file collection.py.
| def pymongo::collection::Collection::__getattr__ | ( | self, | ||
| name | ||||
| ) |
Get a sub-collection of this collection by name. Raises InvalidName if an invalid collection name is used. :Parameters: - `name`: the name of the collection to get
Definition at line 116 of file collection.py.
| def pymongo::collection::Collection::__getitem__ | ( | self, | ||
| name | ||||
| ) |
Definition at line 126 of file collection.py.
| def pymongo::collection::Collection::__init__ | ( | self, | ||
| database, | ||||
| name, | ||||
options = None, |
||||
create = False, |
||||
| kwargs | ||||
| ) |
Get / create a Mongo collection.
Raises :class:`TypeError` if `name` is not an instance of
:class:`basestring`. Raises
:class:`~pymongo.errors.InvalidName` if `name` is not a valid
collection name. Any additional keyword arguments will be used
as options passed to the create command. See
:meth:`~pymongo.database.Database.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:
- `database`: the database to get a collection from
- `name`: the name of the collection to get
- `options`: DEPRECATED dictionary of collection options
- `create` (optional): if ``True``, force collection
creation even without options being set
- `**kwargs` (optional): additional keyword arguments will
be passed as options for the create collection command
.. versionchanged:: 1.5
deprecating `options` in favor of kwargs
.. versionadded:: 1.5
the `create` parameter
.. mongodoc:: collections
Definition at line 39 of file collection.py.
| def pymongo::collection::Collection::__iter__ | ( | self | ) |
Definition at line 1072 of file collection.py.
| def pymongo::collection::Collection::__repr__ | ( | self | ) |
Definition at line 129 of file collection.py.
| def pymongo::collection::Collection::count | ( | self | ) |
Get the number of documents in this collection. To get the number of documents matching a specific query use :meth:`pymongo.cursor.Cursor.count`.
Definition at line 554 of file collection.py.
| def pymongo::collection::Collection::create_index | ( | self, | ||
| key_or_list, | ||||
deprecated_unique = None, |
||||
ttl = 300, |
||||
| 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 :class:`basestring`, and the
directions must be one of (:data:`~pymongo.ASCENDING`,
:data:`~pymongo.DESCENDING`, :data:`~pymongo.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
during index creation when creating a unique index?
- `min`: minimum value for keys in a :data:`~pymongo.GEO2D`
index
- `max`: maximum value for keys in a :data:`~pymongo.GEO2D`
index
:Parameters:
- `key_or_list`: a single key or a list of (key, direction)
pairs specifying the index to create
- `deprecated_unique`: DEPRECATED - use `unique` as a kwarg
- `ttl` (optional): time window (in seconds) during which
this index will be recognized by subsequent calls to
:meth:`ensure_index` - see documentation for
:meth:`ensure_index` for details
- `**kwargs` (optional): any additional index creation
options (see the above list) should be passed as keyword
arguments
.. versionchanged:: 1.5.1
Accept kwargs to support all index creation options.
.. versionadded:: 1.5
The `name` parameter.
.. seealso:: :meth:`ensure_index`
.. mongodoc:: indexes
Definition at line 562 of file collection.py.
| def pymongo::collection::Collection::database | ( | self | ) |
The :class:`~pymongo.database.Database` that this :class:`Collection` is a part of. .. versionchanged:: 1.3 ``database`` is now a property rather than a method.
Definition at line 159 of file collection.py.
| def pymongo::collection::Collection::distinct | ( | self, | ||
| key | ||||
| ) |
Get a list of distinct values for `key` among all documents in this collection. Raises :class:`TypeError` if `key` is not an instance of :class:`basestring`. To get the distinct values for a key in the result set of a query use :meth:`~pymongo.cursor.Cursor.distinct`. :Parameters: - `key`: name of key for which we want to get the distinct values .. note:: Requires server version **>= 1.1.0** .. versionadded:: 1.1.1
Definition at line 898 of file collection.py.
| def pymongo::collection::Collection::drop | ( | self | ) |
Alias for :meth:`~pymongo.database.Database.drop_collection`.
The following two calls are equivalent:
>>> db.foo.drop()
>>> db.drop_collection("foo")
.. versionadded:: 1.8
Definition at line 365 of file collection.py.
| def pymongo::collection::Collection::drop_index | ( | self, | ||
| index_or_name | ||||
| ) |
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). .. warning:: if a custom name was used on index creation (by passing the `name` parameter to :meth:`create_index` or :meth:`ensure_index`) the index **must** be dropped by name. :Parameters: - `index_or_name`: index (or name of index) to drop
Definition at line 730 of file collection.py.
| def pymongo::collection::Collection::drop_indexes | ( | self | ) |
Drops all indexes on this collection. Can be used on non-existant collections or collections with no indexes. Raises OperationFailure on an error.
Definition at line 720 of file collection.py.
| def pymongo::collection::Collection::ensure_index | ( | self, | ||
| key_or_list, | ||||
deprecated_unique = None, |
||||
ttl = 300, |
||||
| kwargs | ||||
| ) |
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 :class:`basestring`, and the
direction(s) must be one of (:data:`~pymongo.ASCENDING`,
:data:`~pymongo.DESCENDING`, :data:`~pymongo.GEO2D`). See
:meth:`create_index` for a detailed example.
Unlike :meth:`create_index`, which attempts to create an index
unconditionally, :meth:`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 :meth:`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
:meth:`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 :data:`~pymongo.GEO2D`
index
- `max`: maximum value for keys in a :data:`~pymongo.GEO2D`
index
:Parameters:
- `key_or_list`: a single key or a list of (key, direction)
pairs specifying the index to create
- `deprecated_unique`: DEPRECATED - use `unique` as a kwarg
- `ttl` (optional): time window (in seconds) during which
this index will be recognized by subsequent calls to
:meth:`ensure_index`
- `**kwargs` (optional): any additional index creation
options (see the above list) should be passed as keyword
arguments
.. versionchanged:: 1.5.1
Accept kwargs to support all index creation options.
.. versionadded:: 1.5
The `name` parameter.
.. seealso:: :meth:`create_index`
Definition at line 646 of file collection.py.
| def pymongo::collection::Collection::find | ( | self, | ||
| args, | ||||
| kwargs | ||||
| ) |
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 :class:`TypeError` if any of the arguments are of
improper type. Returns an instance of
:class:`~pymongo.cursor.Cursor` corresponding to this query.
:Parameters:
- `spec` (optional): a SON object specifying elements which
must be present for a document to be included in the
result set
- `fields` (optional): a list of field names that should be
returned in the result set ("_id" will always be
included), or a dict specifying the fields to return
- `skip` (optional): the number of documents to omit (from
the start of the result set) when returning the results
- `limit` (optional): the maximum number of results to
return
- `timeout` (optional): if True, any returned cursor will be
subject to the normal timeout behavior of the mongod
process. Otherwise, the returned cursor will never timeout
at the server. Care should be taken to ensure that cursors
with timeout turned off are properly closed.
- `snapshot` (optional): if True, snapshot mode will be used
for this query. Snapshot mode assures no duplicates are
returned, or objects missed, which were present at both
the start and end of the query's execution. For details,
see the `snapshot documentation
<http://dochub.mongodb.org/core/snapshot>`_.
- `tailable` (optional): the result of this find call will
be a tailable cursor - tailable cursors aren't closed when
the last data is retrieved but are kept open and the
cursors location marks the final document's position. if
more data is received iteration of the cursor will
continue from the last document received. For details, see
the `tailable cursor documentation
<http://www.mongodb.org/display/DOCS/Tailable+Cursors>`_.
- `sort` (optional): a list of (key, direction) pairs
specifying the sort order for this query. See
:meth:`~pymongo.cursor.Cursor.sort` for details.
- `max_scan` (optional): limit the number of documents
examined when performing the query
- `as_class` (optional): class to use for documents in the
query result (default is
:attr:`~pymongo.connection.Connection.document_class`)
- `network_timeout` (optional): specify a timeout to use for
this query, which will override the
:class:`~pymongo.connection.Connection`-level default
.. note:: The `max_scan` parameter requires server
version **>= 1.5.1**
.. versionadded:: 1.8
The `network_timeout` parameter.
.. versionadded:: 1.7
The `sort`, `max_scan` and `as_class` parameters.
.. versionchanged:: 1.7
The `fields` parameter can now be a dict or any iterable in
addition to a list.
.. versionadded:: 1.1
The `tailable` parameter.
.. mongodoc:: find
Definition at line 473 of file collection.py.
| def pymongo::collection::Collection::find_and_modify | ( | self, | ||
query = {}, |
||||
update = None, |
||||
upsert = False, |
||||
| kwargs | ||||
| ) |
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 :meth:`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:
- `query`: filter for the update (default ``{}``)
- `sort`: priority if multiple objects match (default ``{}``)
- `update`: see second argument to :meth:`update` (no default)
- `remove`: remove rather than updating (default ``False``)
- `new`: return updated rather than original object
(default ``False``)
- `fields`: see second argument to :meth:`find` (default all)
- `upsert`: insert if object doesn't exist (default ``False``)
- `**kwargs`: any other options the findAndModify_ command
supports can be passed here.
.. mongodoc:: findAndModify
.. _findAndModify: http://dochub.mongodb.org/core/findAndModify
.. note:: Requires server version **>= 1.3.0**
.. versionadded:: 1.10
Definition at line 1013 of file collection.py.
| def pymongo::collection::Collection::find_one | ( | self, | ||
spec_or_id = None, |
||||
| args, | ||||
| kwargs | ||||
| ) |
Get a single document from the database.
All arguments to :meth:`find` are also valid arguments for
:meth:`find_one`, although any `limit` argument will be
ignored. Returns a single document, or ``None`` if no matching
document is found.
:Parameters:
- `spec_or_id` (optional): a dictionary specifying
the query to be performed OR any other type to be used as
the value for a query for ``"_id"``.
- `*args` (optional): any additional positional arguments
are the same as the arguments to :meth:`find`.
- `**kwargs` (optional): any additional keyword arguments
are the same as the arguments to :meth:`find`.
.. versionchanged:: 1.7
Allow passing any of the arguments that are valid for
:meth:`find`.
.. versionchanged:: 1.7 Accept any type other than a ``dict``
instance as an ``"_id"`` query, not just
:class:`~bson.objectid.ObjectId` instances.
Definition at line 438 of file collection.py.
| def pymongo::collection::Collection::full_name | ( | self | ) |
The full name of this :class:`Collection`. The full name is of the form `database_name.collection_name`. .. versionchanged:: 1.3 ``full_name`` is now a property rather than a method.
Definition at line 139 of file collection.py.
| def pymongo::collection::Collection::group | ( | self, | ||
| key, | ||||
| condition, | ||||
| initial, | ||||
| reduce, | ||||
finalize = None, |
||||
command = True | ||||
| ) |
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 :class:`list` of keys (each a :class:`basestring`) to group by.
- A :class:`basestring` or :class:`~bson.code.Code` instance
containing a JavaScript function to be applied to each
document, returning the key to group by.
:Parameters:
- `key`: fields to group by (see above description)
- `condition`: specification of rows to be
considered (as a :meth:`find` query specification)
- `initial`: initial value of the aggregation counter object
- `reduce`: aggregation function as a JavaScript string
- `finalize`: function to be called on each object in output list.
- `command` (optional): DEPRECATED if ``True``, run the group as a
command instead of in an eval - this option is deprecated and
will be removed in favor of running all groups as commands
.. versionchanged:: 1.4
The `key` argument can now be ``None`` or a JavaScript function,
in addition to a :class:`list` of keys.
.. versionchanged:: 1.3
The `command` argument now defaults to ``True`` and is deprecated.
Definition at line 815 of file collection.py.
| def pymongo::collection::Collection::index_information | ( | self | ) |
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)]}}
.. versionchanged:: 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.
Definition at line 759 of file collection.py.
| def pymongo::collection::Collection::inline_map_reduce | ( | self, | ||
| map, | ||||
| reduce, | ||||
full_response = False, |
||||
| 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`_.
:Parameters:
- `map`: map function (as a JavaScript string)
- `reduce`: reduce function (as a JavaScript string)
- `full_response` (optional): if ``True``, return full response to
this command - otherwise just return the result collection
- `**kwargs` (optional): additional arguments to the
`map reduce command`_ may be passed as keyword arguments to this
helper method, e.g.::
>>> db.test.inline_map_reduce(map, reduce, limit=2)
.. note:: Requires server version **>= 1.7.4**
.. versionadded:: 1.10
Definition at line 977 of file collection.py.
| def pymongo::collection::Collection::insert | ( | self, | ||
| doc_or_docs, | ||||
manipulate = True, |
||||
safe = False, |
||||
check_keys = True, |
||||
| kwargs | ||||
| ) |
Insert a document(s) into this collection.
If `manipulate` is set, the document(s) are manipulated using
any :class:`~pymongo.son_manipulator.SONManipulator` instances
that have been added to this
:class:`~pymongo.database.Database`. Returns the ``"_id"`` of
the inserted document or a list of ``"_id"`` values of the
inserted documents. If the document(s) does not already
contain an ``"_id"`` one will be added.
If `safe` is ``True`` then the insert will be checked for
errors, raising :class:`~pymongo.errors.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:
- `doc_or_docs`: a document or list of documents to be
inserted
- `manipulate` (optional): manipulate the documents before
inserting?
- `safe` (optional): check that the insert succeeded?
- `check_keys` (optional): check if keys start with '$' or
contain '.', raising :class:`~pymongo.errors.InvalidName`
in either case
- `**kwargs` (optional): any additional arguments imply
``safe=True``, and will be used as options for the
`getLastError` command
.. versionadded:: 1.8
Support for passing `getLastError` options as keyword
arguments.
.. versionchanged:: 1.1
Bulk insert works with any iterable
.. mongodoc:: insert
Definition at line 214 of file collection.py.
| def pymongo::collection::Collection::map_reduce | ( | self, | ||
| map, | ||||
| reduce, | ||||
| out, | ||||
merge_output = False, |
||||
reduce_output = False, |
||||
full_response = False, |
||||
| kwargs | ||||
| ) |
Perform a map/reduce operation on this collection.
If `full_response` is ``False`` (default) returns a
:class:`~pymongo.collection.Collection` instance containing
the results of the operation. Otherwise, returns the full
response from the server to the `map reduce command`_.
:Parameters:
- `map`: map function (as a JavaScript string)
- `reduce`: reduce function (as a JavaScript string)
- `out` (required): output collection name
- `merge_output` (optional): Merge output into `out`. If the same
key exists in both the result set and the existing output collection,
the new key will overwrite the existing key
- `reduce_output` (optional): If documents exist for a given key
in the result set and in the existing output collection, then a
reduce operation (using the specified reduce function) will be
performed on the two values and the result will be written to
the output collection
- `full_response` (optional): if ``True``, return full response to
this command - otherwise just return the result collection
- `**kwargs` (optional): additional arguments to the
`map reduce command`_ may be passed as keyword arguments to this
helper method, e.g.::
>>> db.test.map_reduce(map, reduce, "myresults", limit=2)
.. note:: Requires server version **>= 1.1.1**
.. seealso:: :doc:`/examples/map_reduce`
.. versionadded:: 1.2
.. _map reduce command: http://www.mongodb.org/display/DOCS/MapReduce
.. mongodoc:: mapreduce
Definition at line 917 of file collection.py.
| def pymongo::collection::Collection::name | ( | self | ) |
The name of this :class:`Collection`. .. versionchanged:: 1.3 ``name`` is now a property rather than a method.
Definition at line 150 of file collection.py.
| def pymongo::collection::Collection::next | ( | self | ) |
Definition at line 1075 of file collection.py.
| def pymongo::collection::Collection::options | ( | self | ) |
Get the options set on this collection. Returns a dictionary of options and their values - see :meth:`~pymongo.database.Database.create_collection` for more information on the possible options. Returns an empty dictionary if the collection has not been created yet.
Definition at line 793 of file collection.py.
| def pymongo::collection::Collection::remove | ( | self, | ||
spec_or_id = None, |
||||
safe = False, |
||||
| kwargs | ||||
| ) |
Remove a document(s) from this collection.
.. warning:: Calls to :meth:`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
:class:`~pymongo.errors.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
:meth:`~pymongo.database.Database.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:
- `spec_or_id` (optional): a dictionary specifying the
documents to be removed OR any other type specifying the
value of ``"_id"`` for the document to be removed
- `safe` (optional): check that the remove succeeded?
- `**kwargs` (optional): any additional arguments imply
``safe=True``, and will be used as options for the
`getLastError` command
.. versionadded:: 1.8
Support for passing `getLastError` options as keyword arguments.
.. versionchanged:: 1.7 Accept any type other than a ``dict``
instance for removal by ``"_id"``, not just
:class:`~bson.objectid.ObjectId` instances.
.. versionchanged:: 1.4
Return the response to *lastError* if `safe` is ``True``.
.. versionchanged:: 1.2
The `spec_or_id` parameter is now optional. If it is
not specified *all* documents in the collection will be
removed.
.. versionadded:: 1.1
The `safe` parameter.
.. mongodoc:: remove
Definition at line 377 of file collection.py.
| def pymongo::collection::Collection::rename | ( | self, | ||
| new_name, | ||||
| kwargs | ||||
| ) |
Rename this collection.
If operating in auth mode, client must be authorized as an
admin to perform this operation. Raises :class:`TypeError` if
`new_name` is not an instance of :class:`basestring`. Raises
:class:`~pymongo.errors.InvalidName` if `new_name` is not a
valid collection name.
:Parameters:
- `new_name`: new name for this collection
- `**kwargs` (optional): any additional rename options
should be passed as keyword arguments
(i.e. ``dropTarget=True``)
.. versionadded:: 1.7
support for accepting keyword arguments for rename options
Definition at line 865 of file collection.py.
| def pymongo::collection::Collection::save | ( | self, | ||
| to_save, | ||||
manipulate = True, |
||||
safe = False, |
||||
| kwargs | ||||
| ) |
Save a document in this collection.
If `to_save` already has an ``"_id"`` then an :meth:`update`
(upsert) operation is performed and any existing document with
that ``"_id"`` is overwritten. Otherwise an ``"_id"`` will be
added to `to_save` and an :meth:`insert` operation is
performed. Returns the ``"_id"`` of the saved document.
Raises :class:`TypeError` if `to_save` is not an instance of
:class:`dict`. If `safe` is ``True`` then the save will be
checked for errors, raising
:class:`~pymongo.errors.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:
- `to_save`: the document to be saved
- `manipulate` (optional): manipulate the document before
saving it?
- `safe` (optional): check that the save succeeded?
- `**kwargs` (optional): any additional arguments imply
``safe=True``, and will be used as options for the
`getLastError` command
.. versionadded:: 1.8
Support for passing `getLastError` options as keyword
arguments.
.. mongodoc:: insert
Definition at line 168 of file collection.py.
| def pymongo::collection::Collection::update | ( | self, | ||
| spec, | ||||
| document, | ||||
upsert = False, |
||||
manipulate = False, |
||||
safe = False, |
||||
multi = False, |
||||
| kwargs | ||||
| ) |
Update a document(s) in this collection.
Raises :class:`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
:class:`~pymongo.errors.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:
.. doctest::
>>> 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:
- `spec`: a ``dict`` or :class:`~bson.son.SON` instance
specifying elements which must be present for a document
to be updated
- `document`: a ``dict`` or :class:`~bson.son.SON`
instance specifying the document to be used for the update
or (in the case of an upsert) insert - see docs on MongoDB
`update modifiers`_
- `upsert` (optional): perform an upsert if ``True``
- `manipulate` (optional): manipulate the document before
updating? If ``True`` all instances of
:mod:`~pymongo.son_manipulator.SONManipulator` added to
this :class:`~pymongo.database.Database` will be applied
to the document before performing the update.
- `safe` (optional): check that the update succeeded?
- `multi` (optional): update all documents that match
`spec`, rather than just the first matching document. The
default value for `multi` is currently ``False``, but this
might eventually change to ``True``. It is recommended
that you specify this argument explicitly for all update
operations in order to prepare your code for that change.
- `**kwargs` (optional): any additional arguments imply
``safe=True``, and will be used as options for the
`getLastError` command
.. versionadded:: 1.8
Support for passing `getLastError` options as keyword
arguments.
.. versionchanged:: 1.4
Return the response to *lastError* if `safe` is ``True``.
.. versionadded:: 1.1.1
The `multi` parameter.
.. _update modifiers: http://www.mongodb.org/display/DOCS/Updating
.. mongodoc:: update
Definition at line 275 of file collection.py.
Definition at line 97 of file collection.py.
Definition at line 99 of file collection.py.
pymongo::collection::Collection::__name [private] |
Definition at line 98 of file collection.py.