Managers

• class Manager
• A Manager is the interface through which database query operations areprovided to Django models. At least one Manager exists for every model ina Django application.

The way Manager classes work is documented in Making queries;this document specifically touches on model options that customize Managerbehavior.

Manager names

By default, Django adds a Manager with the name objects to every Djangomodel class. However, if you want to use objects as a field name, or if youwant to use a name other than objects for the Manager, you can renameit on a per-model basis. To rename the Manager for a given class, define aclass attribute of type models.Manager() on that model. For example:

from django.db import models
 
class Person(models.Model):
    #...
    people = models.Manager()

Using this example model, Person.objects will generate anAttributeError exception, but Person.people.all() will provide a listof all Person objects.

Custom managers

You can use a custom Manager in a particular model by extending the baseManager class and instantiating your custom Manager in your model.

There are two reasons you might want to customize a Manager: to add extraManager methods, and/or to modify the initial QuerySet the Managerreturns.

Adding extra manager methods

Adding extra Manager methods is the preferred way to add “table-level”functionality to your models. (For “row-level” functionality – i.e., functionsthat act on a single instance of a model object – use Model methods, not custom Manager methods.)

A custom Manager method can return anything you want. It doesn’t have toreturn a QuerySet.

For example, this custom Manager offers a method with_counts(), whichreturns a list of all OpinionPoll objects, each with an extranum_responses attribute that is the result of an aggregate query:

from django.db import models
 
class PollManager(models.Manager):
    def with_counts(self):
        from django.db import connection
        with connection.cursor() as cursor:
            cursor.execute("""
                SELECT p.id, p.question, p.poll_date, COUNT(*)
                FROM polls_opinionpoll p, polls_response r
                WHERE p.id = r.poll_id
                GROUP BY p.id, p.question, p.poll_date
                ORDER BY p.poll_date DESC""")
            result_list = []
            for row in cursor.fetchall():
                p = self.model(id=row[0], question=row[1], poll_date=row[2])
                p.num_responses = row[3]
                result_list.append(p)
        return result_list
 
class OpinionPoll(models.Model):
    question = models.CharField(max_length=200)
    poll_date = models.DateField()
    objects = PollManager()
 
class Response(models.Model):
    poll = models.ForeignKey(OpinionPoll, on_delete=models.CASCADE)
    person_name = models.CharField(max_length=50)
    response = models.TextField()

With this example, you’d use OpinionPoll.objects.with_counts() to returnthat list of OpinionPoll objects with num_responses attributes.

Another thing to note about this example is that Manager methods canaccess self.model to get the model class to which they’re attached.

Modifying a manager’s initial QuerySet

A Manager’s base QuerySet returns all objects in the system. Forexample, using this model:

from django.db import models
 
class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)

…the statement Book.objects.all() will return all books in the database.

You can override a Manager’s base QuerySet by overriding theManager.get_queryset() method. get_queryset() should return aQuerySet with the properties you require.

For example, the following model has two Managers – one that returnsall objects, and one that returns only the books by Roald Dahl:

# First, define the Manager subclass.
class DahlBookManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(author='Roald Dahl')
 
# Then hook it into the Book model explicitly.
class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)
 
    objects = models.Manager() # The default manager.
    dahl_objects = DahlBookManager() # The Dahl-specific manager.

With this sample model, Book.objects.all() will return all books in thedatabase, but Book.dahl_objects.all() will only return the ones written byRoald Dahl.

Of course, because get_queryset() returns a QuerySet object, you canuse filter(), exclude() and all the other QuerySet methods on it.So these statements are all legal:

Book.dahl_objects.all()
Book.dahl_objects.filter(title='Matilda')
Book.dahl_objects.count()

This example also pointed out another interesting technique: using multiplemanagers on the same model. You can attach as many Manager() instances toa model as you’d like. This is a non-repetitive way to define common “filters”for your models.

For example:

class AuthorManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(role='A')
 
class EditorManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(role='E')
 
class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    role = models.CharField(max_length=1, choices=[('A', _('Author')), ('E', _('Editor'))])
    people = models.Manager()
    authors = AuthorManager()
    editors = EditorManager()

This example allows you to request Person.authors.all(), Person.editors.all(),and Person.people.all(), yielding predictable results.

Default managers

• Model._default_manager
• If you use custom Manager objects, take note that the first ManagerDjango encounters (in the order in which they’re defined in the model) has aspecial status. Django interprets the first Manager defined in a class asthe “default” Manager, and several parts of Django (includingdumpdata) will use that Manager exclusively for that model. As aresult, it’s a good idea to be careful in your choice of default manager inorder to avoid a situation where overriding get_queryset() results in aninability to retrieve objects you’d like to work with.

You can specify a custom default manager using Meta.default_manager_name.

If you’re writing some code that must handle an unknown model, for example, ina third-party app that implements a generic view, use this manager (or_base_manager) rather than assuming the model has an objectsmanager.

Base managers

• Model._base_manager

Using managers for related object access

By default, Django uses an instance of the Model._base_manager managerclass when accessing related objects (i.e. choice.question), not the_default_manager on the related object. This is because Django needs to beable to retrieve the related object, even if it would otherwise be filtered out(and hence be inaccessible) by the default manager.

If the normal base manager class (django.db.models.Manager) isn’tappropriate for your circumstances, you can tell Django which class to use bysetting Meta.base_manager_name.

Base managers aren’t used when querying on related models. For example, if theQuestion model from the tutorial had a deletedfield and a base manager that filters out instances with deleted=True, aqueryset like Choice.objects.filter(questionnamestartswith='What')would include choices related to deleted questions.

Don’t filter away any results in this type of manager subclass

This manager is used to access objects that are related to from some othermodel. In those situations, Django has to be able to see all the objects forthe model it is fetching, so that anything which is referred to can beretrieved.

If you override the get_queryset() method and filter out any rows, Djangowill return incorrect results. Don’t do that. A manager that filters resultsin get_queryset() is not appropriate for use as a base manager.

Calling custom QuerySet methods from the manager

While most methods from the standard QuerySet are accessible directly fromthe Manager, this is only the case for the extra methods defined on acustom QuerySet if you also implement them on the Manager:

class PersonQuerySet(models.QuerySet):
    def authors(self):
        return self.filter(role='A')
 
    def editors(self):
        return self.filter(role='E')
 
class PersonManager(models.Manager):
    def get_queryset(self):
        return PersonQuerySet(self.model, using=self._db)
 
    def authors(self):
        return self.get_queryset().authors()
 
    def editors(self):
        return self.get_queryset().editors()
 
class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    role = models.CharField(max_length=1, choices=[('A', _('Author')), ('E', _('Editor'))])
    people = PersonManager()

This example allows you to call both authors() and editors() directly fromthe manager Person.people.

Creating a manager with QuerySet methods

In lieu of the above approach which requires duplicating methods on both theQuerySet and the Manager, QuerySet.as_manager() can be used to create an instanceof Manager with a copy of a custom QuerySet’s methods:

class Person(models.Model):
    ...
    people = PersonQuerySet.as_manager()

The Manager instance created by QuerySet.as_manager() will be virtuallyidentical to the PersonManager from the previous example.

Not every QuerySet method makes sense at the Manager level; forinstance we intentionally prevent the QuerySet.delete() method from being copied ontothe Manager class.

Methods are copied according to the following rules:

• Public methods are copied by default.
• Private methods (starting with an underscore) are not copied by default.
• Methods with a queryset_only attribute set to False are always copied.
• Methods with a queryset_only attribute set to True are never copied.For example:

class CustomQuerySet(models.QuerySet):
    # Available on both Manager and QuerySet.
    def public_method(self):
        return
 
    # Available only on QuerySet.
    def _private_method(self):
        return
 
    # Available only on QuerySet.
    def opted_out_public_method(self):
        return
    opted_out_public_method.queryset_only = True
 
    # Available on both Manager and QuerySet.
    def _opted_in_private_method(self):
        return
    _opted_in_private_method.queryset_only = False

from_queryset()

• classmethod fromqueryset(_queryset_class)
• For advanced usage you might want both a custom Manager and a customQuerySet. You can do that by calling Manager.fromqueryset() whichreturns a _subclass of your base Manager with a copy of the customQuerySet methods:

class BaseManager(models.Manager):
    def manager_only_method(self):
        return
 
class CustomQuerySet(models.QuerySet):
    def manager_and_queryset_method(self):
        return
 
class MyModel(models.Model):
    objects = BaseManager.from_queryset(CustomQuerySet)()

You may also store the generated class into a variable:

CustomManager = BaseManager.from_queryset(CustomQuerySet)
 
class MyModel(models.Model):
    objects = CustomManager()

Custom managers and model inheritance

Here’s how Django handles custom managers and model inheritance:

• Managers from base classes are always inherited by the child class,using Python’s normal name resolution order (names on the childclass override all others; then come names on the first parent class,and so on).
• If no managers are declared on a model and/or its parents, Djangoautomatically creates the objects manager.
• The default manager on a class is either the one chosen withMeta.default_manager_name, or the first managerdeclared on the model, or the default manager of the first parent model.These rules provide the necessary flexibility if you want to install acollection of custom managers on a group of models, via an abstract baseclass, but still customize the default manager. For example, suppose you havethis base class:

class AbstractBase(models.Model):
    # ...
    objects = CustomManager()
 
    class Meta:
        abstract = True

If you use this directly in a subclass, objects will be the defaultmanager if you declare no managers in the base class:

class ChildA(AbstractBase):
    # ...
    # This class has CustomManager as the default manager.
    pass

If you want to inherit from AbstractBase, but provide a different defaultmanager, you can provide the default manager on the child class:

class ChildB(AbstractBase):
    # ...
    # An explicit default manager.
    default_manager = OtherManager()

Here, default_manager is the default. The objects manager isstill available, since it’s inherited, but isn’t used as the default.

Finally for this example, suppose you want to add extra managers to the childclass, but still use the default from AbstractBase. You can’t add the newmanager directly in the child class, as that would override the default and you wouldhave to also explicitly include all the managers from the abstract base class.The solution is to put the extra managers in another base class and introduceit into the inheritance hierarchy after the defaults:

class ExtraManager(models.Model):
    extra_manager = OtherManager()
 
    class Meta:
        abstract = True
 
class ChildC(AbstractBase, ExtraManager):
    # ...
    # Default manager is CustomManager, but OtherManager is
    # also available via the "extra_manager" attribute.
    pass

Note that while you can define a custom manager on the abstract model, youcan’t invoke any methods using the abstract model. That is:

ClassA.objects.do_something()

is legal, but:

AbstractBase.objects.do_something()

will raise an exception. This is because managers are intended to encapsulatelogic for managing collections of objects. Since you can’t have a collection ofabstract objects, it doesn’t make sense to be managing them. If you havefunctionality that applies to the abstract model, you should put that functionalityin a staticmethod or classmethod on the abstract model.

Implementation concerns

Whatever features you add to your custom Manager, it must bepossible to make a shallow copy of a Manager instance; i.e., thefollowing code must work:

>>> import copy
>>> manager = MyManager()
>>> my_copy = copy.copy(manager)

Django makes shallow copies of manager objects during certain queries;if your Manager cannot be copied, those queries will fail.

This won’t be an issue for most custom managers. If you are justadding simple methods to your Manager, it is unlikely that youwill inadvertently make instances of your Manager uncopyable.However, if you’re overriding getattr or some other privatemethod of your Manager object that controls object state, youshould ensure that you don’t affect the ability of your Manager tobe copied.