| 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. |