Browse files

Restored documentation about pickling QuerySets (and how to only pick…

…le the

details for the query, rather than the results) from r7499.

These were accidentally nuked in the docs refactor. We know who the offenders
were. They will be made to sit in the corner on the naughty mat for a while.

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
malcolmt committed Sep 28, 2008
1 parent 788e6c0 commit 4eb26b1659dbb3034c85df34758992b1b5601f73
Showing with 34 additions and 0 deletions.
  1. +34 −0 docs/ref/models/querysets.txt
@@ -39,6 +39,10 @@ You can evaluate a ``QuerySet`` in the following ways:
execute the database query if you use the "step" parameter of slice
+ * **Pickling/Caching.** See the following section for details of what
+ is involved when `pickling QuerySets`_. The important thing for the
+ purposes of this section is that the results are read from the database.
* **repr().** A ``QuerySet`` is evaluated when you call ``repr()`` on it.
This is for convenience in the Python interactive interpreter, so you can
immediately see your results when using the API interactively.
@@ -62,6 +66,36 @@ You can evaluate a ``QuerySet`` in the following ways:
iterating over a ``QuerySet`` will take advantage of your database to
load data and instantiate objects only as you need them.
+.. _pickling QuerySets:
+Pickling QuerySets
+If you pickle_ a ``QuerySet``, this will force all the results to be loaded
+into memory prior to pickling. Pickling is usually used as a precursor to
+caching and when the cached queryset is reloaded, you want the results to
+already be present and ready for use (reading from the database can take some
+time, defeating the purpose of caching). This means that when you unpickle a
+``QuerySet``, it contains the results at the moment it was pickled, rather
+than the results that are currently in the database.
+If you only want to pickle the necessary information to recreate the
+``Queryset`` from the database at a later time, pickle the ``query`` attribute
+of the ``QuerySet``. You can then recreate the original ``QuerySet`` (without
+any results loaded) using some code like this::
+ >>> import pickle
+ >>> query = pickle.loads(s) # Assuming 's' is the pickled string.
+ >>> qs = MyModel.objects.all()
+ >>> qs.query = query # Restore the original 'query'.
+The ``query`` attribute is an opaque object. It represents the internals of
+the query construction and is not part of the public API. However, it is safe
+(and fully supported) to pickle and unpickle the attribute's contents as
+described here.
+.. _pickle:
.. _queryset-api:
QuerySet API

0 comments on commit 4eb26b1

Please sign in to comment.