From 9bfc838029571b54f3e7d85de6f8735425ca7c1d Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Fri, 2 Dec 2011 08:14:25 -0800 Subject: [PATCH] Updated Docs and bumped version Hopefully nearer 0.6 closes #368 --- docs/guide/document-instances.rst | 18 +++++++++--- docs/guide/querying.rst | 47 ++++++++++++++++++++----------- docs/index.rst | 3 ++ mongoengine/__init__.py | 2 +- 4 files changed, 48 insertions(+), 22 deletions(-) diff --git a/docs/guide/document-instances.rst b/docs/guide/document-instances.rst index 317bfef1..4e799ec7 100644 --- a/docs/guide/document-instances.rst +++ b/docs/guide/document-instances.rst @@ -35,13 +35,23 @@ already exist, then any changes will be updated atomically. For example:: * ``list_field.pop(0)`` - *sets* the resulting list * ``del(list_field)`` - *unsets* whole list -To delete a document, call the :meth:`~mongoengine.Document.delete` method. -Note that this will only work if the document exists in the database and has a -valide :attr:`id`. - .. seealso:: :ref:`guide-atomic-updates` +Cascading Saves +--------------- +If your document contains :class:`~mongoengine.ReferenceField` or +:class:`~mongoengine.GenericReferenceField` objects, then by default the +:meth:`~mongoengine.Document.save` method will automatically save any changes to +those objects as well. If this is not desired passing :attr:`cascade` as False +to the save method turns this feature off. + +Deleting documents +------------------ +To delete a document, call the :meth:`~mongoengine.Document.delete` method. +Note that this will only work if the document exists in the database and has a +valid :attr:`id`. + Document IDs ============ Each document in the database has a unique id. This may be accessed through the diff --git a/docs/guide/querying.rst b/docs/guide/querying.rst index 9ebf37f9..a9567e20 100644 --- a/docs/guide/querying.rst +++ b/docs/guide/querying.rst @@ -195,22 +195,6 @@ to be created:: >>> a.name == b.name and a.age == b.age True -Dereferencing results ---------------------- -When iterating the results of :class:`~mongoengine.ListField` or -:class:`~mongoengine.DictField` we automatically dereference any -:class:`~pymongo.dbref.DBRef` objects as efficiently as possible, reducing the -number the queries to mongo. - -There are times when that efficiency is not enough, documents that have -:class:`~mongoengine.ReferenceField` objects or -:class:`~mongoengine.GenericReferenceField` objects at the top level are -expensive as the number of queries to MongoDB can quickly rise. - -To limit the number of queries use -:func:`~mongoengine.queryset.QuerySet.select_related` which converts the -QuerySet to a list and dereferences as efficiently as possible. - Default Document queries ======================== By default, the objects :attr:`~mongoengine.Document.objects` attribute on a @@ -313,8 +297,16 @@ would be generating "tag-clouds":: from operator import itemgetter top_tags = sorted(tag_freqs.items(), key=itemgetter(1), reverse=True)[:10] + +Query efficiency and performance +================================ + +There are a couple of methods to improve efficiency when querying, reducing the +information returned by the query or efficient dereferencing . + Retrieving a subset of fields -============================= +----------------------------- + Sometimes a subset of fields on a :class:`~mongoengine.Document` is required, and for efficiency only these should be retrieved from the database. This issue is especially important for MongoDB, as fields may often be extremely large @@ -347,6 +339,27 @@ will be given:: If you later need the missing fields, just call :meth:`~mongoengine.Document.reload` on your document. +Getting related data +-------------------- + +When iterating the results of :class:`~mongoengine.ListField` or +:class:`~mongoengine.DictField` we automatically dereference any +:class:`~pymongo.dbref.DBRef` objects as efficiently as possible, reducing the +number the queries to mongo. + +There are times when that efficiency is not enough, documents that have +:class:`~mongoengine.ReferenceField` objects or +:class:`~mongoengine.GenericReferenceField` objects at the top level are +expensive as the number of queries to MongoDB can quickly rise. + +To limit the number of queries use +:func:`~mongoengine.queryset.QuerySet.select_related` which converts the +QuerySet to a list and dereferences as efficiently as possible. By default +:func:`~mongoengine.queryset.QuerySet.select_related` only dereferences any +references to the depth of 1 level. If you have more complicated documents and +want to dereference more of the object at once then increasing the :attr:`max_depth` +will dereference more levels of the document. + Advanced queries ================ Sometimes calling a :class:`~mongoengine.queryset.QuerySet` object with keyword diff --git a/docs/index.rst b/docs/index.rst index a574f29c..ef225e44 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,6 +18,9 @@ MongoDB. To install it, simply run :doc:`apireference` The complete API documentation. +:doc:`upgrade` + The Upgrade guide. + :doc:`django` Using MongoEngine and Django diff --git a/mongoengine/__init__.py b/mongoengine/__init__.py index b28c3741..d10d113b 100644 --- a/mongoengine/__init__.py +++ b/mongoengine/__init__.py @@ -14,7 +14,7 @@ __all__ = (document.__all__ + fields.__all__ + connection.__all__ + __author__ = 'Harry Marr' -VERSION = (0, 5, 2) +VERSION = (0, 5, 3) def get_version():