update.txt

Updating data
=============

Update in Mongokit is as easy as saving an object. Just modify your
document and save it::

    @connection.register
    ... class MyDoc(Document):
    ...    structure = {
    ...        'foo':{
    ...            'bar':[unicode],
    ...            'eggs':{'spam':int},
    ...        },
    ...        'bla':unicode
    ...    }


    >>> doc = self.col.MyDoc()
    >>> doc['_id'] = 3
    >>> doc['foo']['bar'] = [u'mybar', u'yourbar']
    >>> doc['foo']['eggs']['spam'] = 4
    >>> doc['bla'] = u'ble'
    >>> doc.save() 

    Let's modify our doc :

    >>> doc['foo']['eggs']['spam'] = 2
    >>> doc['bla']= u'bli'
    >>> doc.save()

.. IMPORTANT::
    You have to be aware that updating a document like that is not atomic. To do so, please read the next section.


Bulk and atomic updates
-----------------------

As Mongokit exposes all the pymongo API, you can use the pymongo's update on collection:

    >>> con.test.tutorial.update({'title': 'my first blog post'}, {'$set':{'title':u'my very first blog post'}})

For more information, please look at the `pymongo documentation`_.

.. _`pymongo documentation` : http://api.mongodb.org/python/

reload()
--------

If a document was updated in another thread, it would be necessary to refresh the document to
match changes from the database. To do that, use the `reload()` method.

You should know two things before using this method :

 * If no _id is set in the document, a KeyError is raised.
 * If a document is not saved into the database, the OperationFailure exception is raised.
 * using `reload()` will erase all unsaved values !

Example::

    >>> @connection.register
    ... class MyDoc(Document):
    ...    __database__ = 'test'
    ...    __collection__ = 'tutorial'
    ...    structure = {
    ...        'foo':{
    ...            'eggs':{'spam':int},
    ...        },
    ...        'bla':unicode
    ...    }

    >>> doc = connection.MyDoc()
    # calling reload() here will raise a KeyError
    >>> doc['_id'] = 3
    >>> doc['foo']['eggs']['spam'] = 4
    >>> doc['bla'] = u'ble'
    # calling reload() here will raise an OperationFailure
    >>> doc.save()
    >>> doc['bla'] = u'bli' # we don't save this change this will be erased
    >>> connection.test.tutorial.update({'_id':doc['_id']}, {'$set':{'foo.eggs.spam':2}})
    >>> doc.reload()
    >>> doc
    {'_id': 3, 'foo': {u'eggs': {u'spam': 2}}, 'bla': u'ble'}

find_and_modify()
-----------------

    This method allows to return a Document object after or before making an update.

    If you call `find_and_modify` on a Collection object, it will return a dict object::

        >>> d = connection.test.tutorial.find_and_modify({'bla':'ble'}, {'$set':{'foo.eggs.spam':2}})
        >>> isinstance(d, MyDoc)
        False
        >>> isinstance(d, dict)
        True

    If you call `find_and_modify` on a Document object, it will return a Document object::

        >>> d = connection.MyDoc.find_and_modify({'bla':'ble'}, {'$set':{'foo.eggs.spam':2}})
        >>> isinstance(d, MyDoc)
        True

    Please, read the mongodb documentation to learn how to use the `find_and_modify` method.