From 4eb26b1659dbb3034c85df34758992b1b5601f73 Mon Sep 17 00:00:00 2001 From: Malcolm Tredinnick Date: Sun, 28 Sep 2008 03:08:30 +0000 Subject: [PATCH] Restored documentation about pickling QuerySets (and how to only pickle 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: http://code.djangoproject.com/svn/django/trunk@9090 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/models/querysets.txt | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index d3fcf9d1a9..9ffb3c34f9 100644 --- a/docs/ref/models/querysets.txt +++ b/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 syntax. + * **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: http://docs.python.org/lib/module-pickle.html + .. _queryset-api: QuerySet API