Debian Codegraph @

docs/topics/db/managers.txt

raw
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
31 class Person(models.Model):
32 # ...
33 people = models.Manager()
34
35 Using this example model, ``Person.objects`` will generate an
36 ``AttributeError`` exception, but ``Person.people.all()`` will provide a list
37 of all ``Person`` objects.
38
39 .. _custom-managers:
40
41 Custom managers
42 ===============
43
44 You can use a custom ``Manager`` in a particular model by extending the base
45 ``Manager`` class and instantiating your custom ``Manager`` in your model.
46
47 There are two reasons you might want to customize a ``Manager``: to add extra
48 ``Manager`` methods, and/or to modify the initial ``QuerySet`` the ``Manager``
49 returns.
50
51 Adding extra manager methods
52 ----------------------------
53
54 Adding extra ``Manager`` methods is the preferred way to add "table-level"
55 functionality to your models. (For "row-level" functionality -- i.e., functions
56 that act on a single instance of a model object -- use :ref:`Model methods
57 <model-methods>`, not custom ``Manager`` methods.)
58
59 For example, this custom ``Manager`` adds a method ``with_counts()``::
60
61 from django.db import models
62 from django.db.models.functions import Coalesce
63
64
65 class PollManager(models.Manager):
66 def with_counts(self):
67 return self.annotate(num_responses=Coalesce(models.Count("response"), 0))
68
69
70 class OpinionPoll(models.Model):
71 question = models.CharField(max_length=200)
72 objects = PollManager()
73
74
75 class Response(models.Model):
76 poll = models.ForeignKey(OpinionPoll, on_delete=models.CASCADE)
77 # ...
78
79 With this example, you'd use ``OpinionPoll.objects.with_counts()`` to get a
80 ``QuerySet`` of ``OpinionPoll`` objects with the extra ``num_responses``
81 attribute attached.
82
83 A custom ``Manager`` method can return anything you want. It doesn't have to
84 return a ``QuerySet``.
85
86 Another thing to note is that ``Manager`` methods can access ``self.model`` to
87 get the model class to which they're attached.
88
89 Modifying a manager's initial ``QuerySet``
90 ------------------------------------------
91
92 A ``Manager``’s base ``QuerySet`` returns all objects in the system. For
93 example, using this model::
94
95 from django.db import models
96
97
98 class Book(models.Model):
99 title = models.CharField(max_length=100)
100 author = models.CharField(max_length=50)
101
102 ...the statement ``Book.objects.all()`` will return all books in the database.
103
104 You can override a ``Manager``’s base ``QuerySet`` by overriding the
105 ``Manager.get_queryset()`` method. ``get_queryset()`` should return a
106 ``QuerySet`` with the properties you require.
107
108 For example, the following model has *two* ``Manager``\s -- one that returns
109 all objects, and one that returns only the books by Roald Dahl::
110
111 # First, define the Manager subclass.
112 class DahlBookManager(models.Manager):
113 def get_queryset(self):
114 return super().get_queryset().filter(author="Roald Dahl")
115
116
117 # Then hook it into the Book model explicitly.
118 class Book(models.Model):
119 title = models.CharField(max_length=100)
120 author = models.CharField(max_length=50)
121
122 objects = models.Manager() # The default manager.
123 dahl_objects = DahlBookManager() # The Dahl-specific manager.
124
125 With this sample model, ``Book.objects.all()`` will return all books in the
126 database, but ``Book.dahl_objects.all()`` will only return the ones written by
127 Roald Dahl.
128
129 Because ``get_queryset()`` returns a ``QuerySet`` object, you can use
130 ``filter()``, ``exclude()`` and all the other ``QuerySet`` methods on it. So
131 these statements are all legal::
132
133 Book.dahl_objects.all()
134 Book.dahl_objects.filter(title="Matilda")
135 Book.dahl_objects.count()
136
137 This example also pointed out another interesting technique: using multiple
138 managers on the same model. You can attach as many ``Manager()`` instances to
139 a model as you'd like. This is a non-repetitive way to define common "filters"
140 for your models.
141
142 For example::
143
144 class AuthorManager(models.Manager):
145 def get_queryset(self):
146 return super().get_queryset().filter(role="A")
147
148
149 class EditorManager(models.Manager):
150 def get_queryset(self):
151 return super().get_queryset().filter(role="E")
152
153
154 class Person(models.Model):
155 first_name = models.CharField(max_length=50)
156 last_name = models.CharField(max_length=50)
157 role = models.CharField(max_length=1, choices={"A": _("Author"), "E": _("Editor")})
158 people = models.Manager()
159 authors = AuthorManager()
160 editors = EditorManager()
161
162 This example allows you to request ``Person.authors.all()``, ``Person.editors.all()``,
163 and ``Person.people.all()``, yielding predictable results.
164
165 .. _default-managers:
166
167 Default managers
168 ----------------
169
170 .. attribute:: Model._default_manager
171
172 If you use custom ``Manager`` objects, take note that the first ``Manager``
173 Django encounters (in the order in which they're defined in the model) has a
174 special status. Django interprets the first ``Manager`` defined in a class as
175 the "default" ``Manager``, and several parts of Django (including
176 :djadmin:`dumpdata`) will use that ``Manager`` exclusively for that model. As a
177 result, it's a good idea to be careful in your choice of default manager in
178 order to avoid a situation where overriding ``get_queryset()`` results in an
179 inability to retrieve objects you'd like to work with.
180
181 You can specify a custom default manager using :attr:`Meta.default_manager_name
182 <django.db.models.Options.default_manager_name>`.
183
184 If you're writing some code that must handle an unknown model, for example, in
185 a third-party app that implements a generic view, use this manager (or
186 :attr:`~Model._base_manager`) rather than assuming the model has an ``objects``
187 manager.
188
189 Base managers
190 -------------
191
192 .. attribute:: Model._base_manager
193
194 .. _managers-for-related-objects:
195
196 Using managers for related object access
197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198
199 By default, Django uses an instance of the ``Model._base_manager`` manager
200 class when accessing related objects (e.g. ``choice.question``), not the
201 ``_default_manager`` on the related object. This is because Django needs to be
202 able to retrieve the related object, even if it would otherwise be filtered out
203 (and hence be inaccessible) by the default manager.
204
205 If the normal base manager class (:class:`django.db.models.Manager`) isn't
206 appropriate for your circumstances, you can tell Django which class to use by
207 setting :attr:`Meta.base_manager_name
208 <django.db.models.Options.base_manager_name>`.
209
210 Base managers aren't used when querying on related models, or when
211 :ref:`accessing a one-to-many or many-to-many relationship
212 <backwards-related-objects>`. For example, if the ``Question`` model
213 :ref:`from the tutorial <creating-models>` had a ``deleted`` field and a base
214 manager that filters out instances with ``deleted=True``, a queryset like
215 ``Choice.objects.filter(question__name__startswith='What')`` would include
216 choices related to deleted questions.
217
218 Don't filter away any results in this type of manager subclass
219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220
221 This manager is used to access objects that are related to from some other
222 model. In those situations, Django has to be able to see all the objects for
223 the model it is fetching, so that *anything* which is referred to can be
224 retrieved.
225
226 Therefore, you should not override ``get_queryset()`` to filter out any rows.
227 If you do so, Django will return incomplete results.
228
229 .. _calling-custom-queryset-methods-from-manager:
230
231 Calling custom ``QuerySet`` methods from the manager
232 ----------------------------------------------------
233
234 While most methods from the standard ``QuerySet`` are accessible directly from
235 the ``Manager``, this is only the case for the extra methods defined on a
236 custom ``QuerySet`` if you also implement them on the ``Manager``::
237
238 class PersonQuerySet(models.QuerySet):
239 def authors(self):
240 return self.filter(role="A")
241
242 def editors(self):
243 return self.filter(role="E")
244
245
246 class PersonManager(models.Manager):
247 def get_queryset(self):
248 return PersonQuerySet(self.model, using=self._db)
249
250 def authors(self):
251 return self.get_queryset().authors()
252
253 def editors(self):
254 return self.get_queryset().editors()
255
256
257 class Person(models.Model):
258 first_name = models.CharField(max_length=50)
259 last_name = models.CharField(max_length=50)
260 role = models.CharField(max_length=1, choices={"A": _("Author"), "E": _("Editor")})
261 people = PersonManager()
262
263 This example allows you to call both ``authors()`` and ``editors()`` directly from
264 the manager ``Person.people``.
265
266 .. _create-manager-with-queryset-methods:
267
268 Creating a manager with ``QuerySet`` methods
269 --------------------------------------------
270
271 In lieu of the above approach which requires duplicating methods on both the
272 ``QuerySet`` and the ``Manager``, :meth:`QuerySet.as_manager()
273 <django.db.models.query.QuerySet.as_manager>` can be used to create an instance
274 of ``Manager`` with a copy of a custom ``QuerySet``’s methods::
275
276 class Person(models.Model):
277 ...
278 people = PersonQuerySet.as_manager()
279
280 The ``Manager`` instance created by :meth:`QuerySet.as_manager()
281 <django.db.models.query.QuerySet.as_manager>` will be virtually
282 identical to the ``PersonManager`` from the previous example.
283
284 Not every ``QuerySet`` method makes sense at the ``Manager`` level; for
285 instance we intentionally prevent the :meth:`QuerySet.delete()
286 <django.db.models.query.QuerySet.delete>` method from being copied onto
287 the ``Manager`` class.
288
289 Methods are copied according to the following rules:
290
291 - Public methods are copied by default.
292 - Private methods (starting with an underscore) are not copied by default.
293 - Methods with a ``queryset_only`` attribute set to ``False`` are always copied.
294 - Methods with a ``queryset_only`` attribute set to ``True`` are never copied.
295
296 For example::
297
298 class CustomQuerySet(models.QuerySet):
299 # Available on both Manager and QuerySet.
300 def public_method(self):
301 return
302
303 # Available only on QuerySet.
304 def _private_method(self):
305 return
306
307 # Available only on QuerySet.
308 def opted_out_public_method(self):
309 return
310
311 opted_out_public_method.queryset_only = True
312
313 # Available on both Manager and QuerySet.
314 def _opted_in_private_method(self):
315 return
316
317 _opted_in_private_method.queryset_only = False
318
319 ``from_queryset()``
320 ~~~~~~~~~~~~~~~~~~~
321
322 .. classmethod:: from_queryset(queryset_class)
323
324 For advanced usage you might want both a custom ``Manager`` and a custom
325 ``QuerySet``. You can do that by calling ``Manager.from_queryset()`` which
326 returns a *subclass* of your base ``Manager`` with a copy of the custom
327 ``QuerySet`` methods::
328
329 class CustomManager(models.Manager):
330 def manager_only_method(self):
331 return
332
333
334 class CustomQuerySet(models.QuerySet):
335 def manager_and_queryset_method(self):
336 return
337
338
339 class MyModel(models.Model):
340 objects = CustomManager.from_queryset(CustomQuerySet)()
341
342 You may also store the generated class into a variable::
343
344 MyManager = CustomManager.from_queryset(CustomQuerySet)
345
346
347 class MyModel(models.Model):
348 objects = MyManager()
349
350 .. _custom-managers-and-inheritance:
351
352 Custom managers and model inheritance
353 -------------------------------------
354
355 Here's how Django handles custom managers and :ref:`model inheritance
356 <model-inheritance>`:
357
358 #. Managers from base classes are always inherited by the child class,
359 using Python's normal name resolution order (names on the child
360 class override all others; then come names on the first parent class,
361 and so on).
362
363 #. If no managers are declared on a model and/or its parents, Django
364 automatically creates the ``objects`` manager.
365
366 #. The default manager on a class is either the one chosen with
367 :attr:`Meta.default_manager_name
368 <django.db.models.Options.default_manager_name>`, or the first manager
369 declared on the model, or the default manager of the first parent model.
370
371 These rules provide the necessary flexibility if you want to install a
372 collection of custom managers on a group of models, via an abstract base
373 class, but still customize the default manager. For example, suppose you have
374 this base class::
375
376 class AbstractBase(models.Model):
377 # ...
378 objects = CustomManager()
379
380 class Meta:
381 abstract = True
382
383 If you use this directly in a child class, ``objects`` will be the default
384 manager if you declare no managers in the child class::
385
386 class ChildA(AbstractBase):
387 # ...
388 # This class has CustomManager as the default manager.
389 pass
390
391 If you want to inherit from ``AbstractBase``, but provide a different default
392 manager, you can provide the default manager on the child class::
393
394 class ChildB(AbstractBase):
395 # ...
396 # An explicit default manager.
397 default_manager = OtherManager()
398
399 Here, ``default_manager`` is the default. The ``objects`` manager is
400 still available, since it's inherited, but isn't used as the default.
401
402 Finally for this example, suppose you want to add extra managers to the child
403 class, but still use the default from ``AbstractBase``. You can't add the new
404 manager directly in the child class, as that would override the default and you would
405 have to also explicitly include all the managers from the abstract base class.
406 The solution is to put the extra managers in another base class and introduce
407 it into the inheritance hierarchy *after* the defaults::
408
409 class ExtraManager(models.Model):
410 extra_manager = OtherManager()
411
412 class Meta:
413 abstract = True
414
415
416 class ChildC(AbstractBase, ExtraManager):
417 # ...
418 # Default manager is CustomManager, but OtherManager is
419 # also available via the "extra_manager" attribute.
420 pass
421
422 Note that while you can *define* a custom manager on the abstract model, you
423 can't *invoke* any methods using the abstract model. That is::
424
425 ClassA.objects.do_something()
426
427 is legal, but::
428
429 AbstractBase.objects.do_something()
430
431 will raise an exception. This is because managers are intended to encapsulate
432 logic for managing collections of objects. Since you can't have a collection of
433 abstract objects, it doesn't make sense to be managing them. If you have
434 functionality that applies to the abstract model, you should put that functionality
435 in a ``staticmethod`` or ``classmethod`` on the abstract model.
436
437 Implementation concerns
438 -----------------------
439
440 Whatever features you add to your custom ``Manager``, it must be
441 possible to make a shallow copy of a ``Manager`` instance; i.e., the
442 following code must work:
443
444 .. code-block:: pycon
445
446 >>> import copy
447 >>> manager = MyManager()
448 >>> my_copy = copy.copy(manager)
449
450 Django makes shallow copies of manager objects during certain queries;
451 if your Manager cannot be copied, those queries will fail.
452
453 This won't be an issue for most custom managers. If you are just
454 adding simple methods to your ``Manager``, it is unlikely that you
455 will inadvertently make instances of your ``Manager`` uncopyable.
456 However, if you're overriding ``__getattr__`` or some other private
457 method of your ``Manager`` object that controls object state, you
458 should ensure that you don't affect the ability of your ``Manager`` to
459 be copied.