|
1 ======== |
|
2 Managers |
|
3 ======== |
|
4 |
|
5 .. currentmodule:: django.db.models |
|
6 |
|
7 .. class:: Manager() |
|
8 |
|
9 A ``Manager`` is the interface through which database query operations are |
|
10 provided to Django models. At least one ``Manager`` exists for every model in |
|
11 a Django application. |
|
12 |
|
13 The way ``Manager`` classes work is documented in :doc:`/topics/db/queries`; |
|
14 this document specifically touches on model options that customize ``Manager`` |
|
15 behavior. |
|
16 |
|
17 .. _manager-names: |
|
18 |
|
19 Manager names |
|
20 ============= |
|
21 |
|
22 By default, Django adds a ``Manager`` with the name ``objects`` to every Django |
|
23 model class. However, if you want to use ``objects`` as a field name, or if you |
|
24 want to use a name other than ``objects`` for the ``Manager``, you can rename |
|
25 it on a per-model basis. To rename the ``Manager`` for a given class, define a |
|
26 class attribute of type ``models.Manager()`` on that model. For example:: |
|
27 |
|
28 from django.db import models |
|
29 |
|
30 class Person(models.Model): |
|
31 #... |
|
32 people = models.Manager() |
|
33 |
|
34 Using this example model, ``Person.objects`` will generate an |
|
35 ``AttributeError`` exception, but ``Person.people.all()`` will provide a list |
|
36 of all ``Person`` objects. |
|
37 |
|
38 .. _custom-managers: |
|
39 |
|
40 Custom Managers |
|
41 =============== |
|
42 |
|
43 You can use a custom ``Manager`` in a particular model by extending the base |
|
44 ``Manager`` class and instantiating your custom ``Manager`` in your model. |
|
45 |
|
46 There are two reasons you might want to customize a ``Manager``: to add extra |
|
47 ``Manager`` methods, and/or to modify the initial ``QuerySet`` the ``Manager`` |
|
48 returns. |
|
49 |
|
50 Adding extra Manager methods |
|
51 ---------------------------- |
|
52 |
|
53 Adding extra ``Manager`` methods is the preferred way to add "table-level" |
|
54 functionality to your models. (For "row-level" functionality -- i.e., functions |
|
55 that act on a single instance of a model object -- use :ref:`Model methods |
|
56 <model-methods>`, not custom ``Manager`` methods.) |
|
57 |
|
58 A custom ``Manager`` method can return anything you want. It doesn't have to |
|
59 return a ``QuerySet``. |
|
60 |
|
61 For example, this custom ``Manager`` offers a method ``with_counts()``, which |
|
62 returns a list of all ``OpinionPoll`` objects, each with an extra |
|
63 ``num_responses`` attribute that is the result of an aggregate query:: |
|
64 |
|
65 class PollManager(models.Manager): |
|
66 def with_counts(self): |
|
67 from django.db import connection |
|
68 cursor = connection.cursor() |
|
69 cursor.execute(""" |
|
70 SELECT p.id, p.question, p.poll_date, COUNT(*) |
|
71 FROM polls_opinionpoll p, polls_response r |
|
72 WHERE p.id = r.poll_id |
|
73 GROUP BY 1, 2, 3 |
|
74 ORDER BY 3 DESC""") |
|
75 result_list = [] |
|
76 for row in cursor.fetchall(): |
|
77 p = self.model(id=row[0], question=row[1], poll_date=row[2]) |
|
78 p.num_responses = row[3] |
|
79 result_list.append(p) |
|
80 return result_list |
|
81 |
|
82 class OpinionPoll(models.Model): |
|
83 question = models.CharField(max_length=200) |
|
84 poll_date = models.DateField() |
|
85 objects = PollManager() |
|
86 |
|
87 class Response(models.Model): |
|
88 poll = models.ForeignKey(Poll) |
|
89 person_name = models.CharField(max_length=50) |
|
90 response = models.TextField() |
|
91 |
|
92 With this example, you'd use ``OpinionPoll.objects.with_counts()`` to return |
|
93 that list of ``OpinionPoll`` objects with ``num_responses`` attributes. |
|
94 |
|
95 Another thing to note about this example is that ``Manager`` methods can |
|
96 access ``self.model`` to get the model class to which they're attached. |
|
97 |
|
98 Modifying initial Manager QuerySets |
|
99 ----------------------------------- |
|
100 |
|
101 A ``Manager``'s base ``QuerySet`` returns all objects in the system. For |
|
102 example, using this model:: |
|
103 |
|
104 class Book(models.Model): |
|
105 title = models.CharField(max_length=100) |
|
106 author = models.CharField(max_length=50) |
|
107 |
|
108 ...the statement ``Book.objects.all()`` will return all books in the database. |
|
109 |
|
110 You can override a ``Manager``\'s base ``QuerySet`` by overriding the |
|
111 ``Manager.get_query_set()`` method. ``get_query_set()`` should return a |
|
112 ``QuerySet`` with the properties you require. |
|
113 |
|
114 For example, the following model has *two* ``Manager``\s -- one that returns |
|
115 all objects, and one that returns only the books by Roald Dahl:: |
|
116 |
|
117 # First, define the Manager subclass. |
|
118 class DahlBookManager(models.Manager): |
|
119 def get_query_set(self): |
|
120 return super(DahlBookManager, self).get_query_set().filter(author='Roald Dahl') |
|
121 |
|
122 # Then hook it into the Book model explicitly. |
|
123 class Book(models.Model): |
|
124 title = models.CharField(max_length=100) |
|
125 author = models.CharField(max_length=50) |
|
126 |
|
127 objects = models.Manager() # The default manager. |
|
128 dahl_objects = DahlBookManager() # The Dahl-specific manager. |
|
129 |
|
130 With this sample model, ``Book.objects.all()`` will return all books in the |
|
131 database, but ``Book.dahl_objects.all()`` will only return the ones written by |
|
132 Roald Dahl. |
|
133 |
|
134 Of course, because ``get_query_set()`` returns a ``QuerySet`` object, you can |
|
135 use ``filter()``, ``exclude()`` and all the other ``QuerySet`` methods on it. |
|
136 So these statements are all legal:: |
|
137 |
|
138 Book.dahl_objects.all() |
|
139 Book.dahl_objects.filter(title='Matilda') |
|
140 Book.dahl_objects.count() |
|
141 |
|
142 This example also pointed out another interesting technique: using multiple |
|
143 managers on the same model. You can attach as many ``Manager()`` instances to |
|
144 a model as you'd like. This is an easy way to define common "filters" for your |
|
145 models. |
|
146 |
|
147 For example:: |
|
148 |
|
149 class MaleManager(models.Manager): |
|
150 def get_query_set(self): |
|
151 return super(MaleManager, self).get_query_set().filter(sex='M') |
|
152 |
|
153 class FemaleManager(models.Manager): |
|
154 def get_query_set(self): |
|
155 return super(FemaleManager, self).get_query_set().filter(sex='F') |
|
156 |
|
157 class Person(models.Model): |
|
158 first_name = models.CharField(max_length=50) |
|
159 last_name = models.CharField(max_length=50) |
|
160 sex = models.CharField(max_length=1, choices=(('M', 'Male'), ('F', 'Female'))) |
|
161 people = models.Manager() |
|
162 men = MaleManager() |
|
163 women = FemaleManager() |
|
164 |
|
165 This example allows you to request ``Person.men.all()``, ``Person.women.all()``, |
|
166 and ``Person.people.all()``, yielding predictable results. |
|
167 |
|
168 If you use custom ``Manager`` objects, take note that the first ``Manager`` |
|
169 Django encounters (in the order in which they're defined in the model) has a |
|
170 special status. Django interprets the first ``Manager`` defined in a class as |
|
171 the "default" ``Manager``, and several parts of Django |
|
172 (including :djadmin:`dumpdata`) will use that ``Manager`` |
|
173 exclusively for that model. As a result, it's a good idea to be careful in |
|
174 your choice of default manager in order to avoid a situation where overriding |
|
175 ``get_query_set()`` results in an inability to retrieve objects you'd like to |
|
176 work with. |
|
177 |
|
178 .. _managers-for-related-objects: |
|
179 |
|
180 Using managers for related object access |
|
181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
182 |
|
183 By default, Django uses an instance of a "plain" manager class when accessing |
|
184 related objects (i.e. ``choice.poll``), not the default manager on the related |
|
185 object. This is because Django needs to be able to retrieve the related |
|
186 object, even if it would otherwise be filtered out (and hence be inaccessible) |
|
187 by the default manager. |
|
188 |
|
189 If the normal plain manager class (:class:`django.db.models.Manager`) is not |
|
190 appropriate for your circumstances, you can force Django to use the same class |
|
191 as the default manager for your model by setting the `use_for_related_fields` |
|
192 attribute on the manager class. This is documented fully below_. |
|
193 |
|
194 .. _below: manager-types_ |
|
195 |
|
196 .. _custom-managers-and-inheritance: |
|
197 |
|
198 Custom managers and model inheritance |
|
199 ------------------------------------- |
|
200 |
|
201 Class inheritance and model managers aren't quite a perfect match for each |
|
202 other. Managers are often specific to the classes they are defined on and |
|
203 inheriting them in subclasses isn't necessarily a good idea. Also, because the |
|
204 first manager declared is the *default manager*, it is important to allow that |
|
205 to be controlled. So here's how Django handles custom managers and |
|
206 :ref:`model inheritance <model-inheritance>`: |
|
207 |
|
208 1. Managers defined on non-abstract base classes are *not* inherited by |
|
209 child classes. If you want to reuse a manager from a non-abstract base, |
|
210 redeclare it explicitly on the child class. These sorts of managers are |
|
211 likely to be fairly specific to the class they are defined on, so |
|
212 inheriting them can often lead to unexpected results (particularly as |
|
213 far as the default manager goes). Therefore, they aren't passed onto |
|
214 child classes. |
|
215 |
|
216 2. Managers from abstract base classes are always inherited by the child |
|
217 class, using Python's normal name resolution order (names on the child |
|
218 class override all others; then come names on the first parent class, |
|
219 and so on). Abstract base classes are designed to capture information |
|
220 and behavior that is common to their child classes. Defining common |
|
221 managers is an appropriate part of this common information. |
|
222 |
|
223 3. The default manager on a class is either the first manager declared on |
|
224 the class, if that exists, or the default manager of the first abstract |
|
225 base class in the parent hierarchy, if that exists. If no default |
|
226 manager is explicitly declared, Django's normal default manager is |
|
227 used. |
|
228 |
|
229 These rules provide the necessary flexibility if you want to install a |
|
230 collection of custom managers on a group of models, via an abstract base |
|
231 class, but still customize the default manager. For example, suppose you have |
|
232 this base class:: |
|
233 |
|
234 class AbstractBase(models.Model): |
|
235 ... |
|
236 objects = CustomManager() |
|
237 |
|
238 class Meta: |
|
239 abstract = True |
|
240 |
|
241 If you use this directly in a subclass, ``objects`` will be the default |
|
242 manager if you declare no managers in the base class:: |
|
243 |
|
244 class ChildA(AbstractBase): |
|
245 ... |
|
246 # This class has CustomManager as the default manager. |
|
247 |
|
248 If you want to inherit from ``AbstractBase``, but provide a different default |
|
249 manager, you can provide the default manager on the child class:: |
|
250 |
|
251 class ChildB(AbstractBase): |
|
252 ... |
|
253 # An explicit default manager. |
|
254 default_manager = OtherManager() |
|
255 |
|
256 Here, ``default_manager`` is the default. The ``objects`` manager is |
|
257 still available, since it's inherited. It just isn't used as the default. |
|
258 |
|
259 Finally for this example, suppose you want to add extra managers to the child |
|
260 class, but still use the default from ``AbstractBase``. You can't add the new |
|
261 manager directly in the child class, as that would override the default and you would |
|
262 have to also explicitly include all the managers from the abstract base class. |
|
263 The solution is to put the extra managers in another base class and introduce |
|
264 it into the inheritance hierarchy *after* the defaults:: |
|
265 |
|
266 class ExtraManager(models.Model): |
|
267 extra_manager = OtherManager() |
|
268 |
|
269 class Meta: |
|
270 abstract = True |
|
271 |
|
272 class ChildC(AbstractBase, ExtraManager): |
|
273 ... |
|
274 # Default manager is CustomManager, but OtherManager is |
|
275 # also available via the "extra_manager" attribute. |
|
276 |
|
277 .. _manager-types: |
|
278 |
|
279 Controlling Automatic Manager Types |
|
280 =================================== |
|
281 |
|
282 This document has already mentioned a couple of places where Django creates a |
|
283 manager class for you: `default managers`_ and the "plain" manager used to |
|
284 `access related objects`_. There are other places in the implementation of |
|
285 Django where temporary plain managers are needed. Those automatically created |
|
286 managers will normally be instances of the :class:`django.db.models.Manager` |
|
287 class. |
|
288 |
|
289 .. _default managers: manager-names_ |
|
290 .. _access related objects: managers-for-related-objects_ |
|
291 |
|
292 Throughout this section, we will use the term "automatic manager" to mean a |
|
293 manager that Django creates for you -- either as a default manager on a model |
|
294 with no managers, or to use temporarily when accessing related objects. |
|
295 |
|
296 Sometimes this default class won't be the right choice. One example is in the |
|
297 :mod:`django.contrib.gis` application that ships with Django itself. All ``gis`` |
|
298 models must use a special manager class (:class:`~django.contrib.gis.db.models.GeoManager`) |
|
299 because they need a special queryset (:class:`~django.contrib.gis.db.models.GeoQuerySet`) |
|
300 to be used for interacting with the database. It turns out that models which require |
|
301 a special manager like this need to use the same manager class wherever an automatic |
|
302 manager is created. |
|
303 |
|
304 Django provides a way for custom manager developers to say that their manager |
|
305 class should be used for automatic managers whenever it is the default manager |
|
306 on a model. This is done by setting the ``use_for_related_fields`` attribute on |
|
307 the manager class:: |
|
308 |
|
309 class MyManager(models.Manager): |
|
310 use_for_related_fields = True |
|
311 |
|
312 ... |
|
313 |
|
314 If this attribute is set on the *default* manager for a model (only the |
|
315 default manager is considered in these situations), Django will use that class |
|
316 whenever it needs to automatically create a manager for the class. Otherwise, |
|
317 it will use :class:`django.db.models.Manager`. |
|
318 |
|
319 .. admonition:: Historical Note |
|
320 |
|
321 Given the purpose for which it's used, the name of this attribute |
|
322 (``use_for_related_fields``) might seem a little odd. Originally, the |
|
323 attribute only controlled the type of manager used for related field |
|
324 access, which is where the name came from. As it became clear the concept |
|
325 was more broadly useful, the name hasn't been changed. This is primarily |
|
326 so that existing code will :doc:`continue to work </misc/api-stability>` in |
|
327 future Django versions. |
|
328 |
|
329 Writing Correct Managers For Use In Automatic Manager Instances |
|
330 --------------------------------------------------------------- |
|
331 |
|
332 As already suggested by the `django.contrib.gis` example, above, the |
|
333 ``use_for_related_fields`` feature is primarily for managers that need to |
|
334 return a custom ``QuerySet`` subclass. In providing this functionality in your |
|
335 manager, there are a couple of things to remember. |
|
336 |
|
337 Do not filter away any results in this type of manager subclass |
|
338 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
339 |
|
340 One reason an automatic manager is used is to access objects that are related |
|
341 to from some other model. In those situations, Django has to be able to see |
|
342 all the objects for the model it is fetching, so that *anything* which is |
|
343 referred to can be retrieved. |
|
344 |
|
345 If you override the ``get_query_set()`` method and filter out any rows, Django |
|
346 will return incorrect results. Don't do that. A manager that filters results |
|
347 in ``get_query_set()`` is not appropriate for use as an automatic manager. |
|
348 |
|
349 Set ``use_for_related_fields`` when you define the class |
|
350 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
351 |
|
352 The ``use_for_related_fields`` attribute must be set on the manager *class*, |
|
353 object not on an *instance* of the class. The earlier example shows the |
|
354 correct way to set it, whereas the following will not work:: |
|
355 |
|
356 # BAD: Incorrect code |
|
357 class MyManager(models.Manager): |
|
358 ... |
|
359 |
|
360 # Sets the attribute on an instance of MyManager. Django will |
|
361 # ignore this setting. |
|
362 mgr = MyManager() |
|
363 mgr.use_for_related_fields = True |
|
364 |
|
365 class MyModel(models.Model): |
|
366 ... |
|
367 objects = mgr |
|
368 |
|
369 # End of incorrect code. |
|
370 |
|
371 You also shouldn't change the attribute on the class object after it has been |
|
372 used in a model, since the attribute's value is processed when the model class |
|
373 is created and not subsequently reread. Set the attribute on the manager class |
|
374 when it is first defined, as in the initial example of this section and |
|
375 everything will work smoothly. |
|
376 |