From b039a2293fea59ab3f1f7c25b85755cbb1237e1f Mon Sep 17 00:00:00 2001 From: Ross Lawley Date: Mon, 27 Jun 2011 12:42:26 +0100 Subject: [PATCH] Updated documentation about dereferencing Refs #206 --- docs/changelog.rst | 1 + docs/guide/querying.rst | 16 ++++++++++++++++ 2 files changed, 17 insertions(+) diff --git a/docs/changelog.rst b/docs/changelog.rst index 4fb5d627..cad1b687 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -5,6 +5,7 @@ Changelog Changes in dev ============== +- Added select_related() support - Added support for the positional operator - Updated geo index checking to be recursive and check in embedded documents - Updated default collection naming convention diff --git a/docs/guide/querying.rst b/docs/guide/querying.rst index 4f36e964..b23ea4d1 100644 --- a/docs/guide/querying.rst +++ b/docs/guide/querying.rst @@ -175,6 +175,22 @@ 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