---
title: "Managers"
version: 2.1
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/2.1/topics/db/managers/
canonical: https://djangodocs.dev/zh-hans/2.1/topics/db/managers/
---
# Managers

#### `class Manager`

A `Manager` is the interface through which database query operations are
provided to Django models. At least one `Manager` exists for every model in
a Django application.

The way `Manager` classes work is documented in [进行查询](/zh-hans/2.1/topics/db/queries/);
this document specifically touches on model options that customize `Manager`
behavior.

## Manager names

By default, Django adds a `Manager` with the name `objects` to every Django
model class. However, if you want to use `objects` as a field name, or if you
want to use a name other than `objects` for the `Manager`, you can rename
it on a per-model basis. To rename the `Manager` for a given class, define a
class 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 an
`AttributeError` exception, but `Person.people.all()` will provide a list
of all `Person` objects.

## Custom managers

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

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

### 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., functions
that act on a single instance of a model object -- use [Model methods](/zh-hans/2.1/topics/db/models/#model-methods), not custom `Manager` methods.)

A custom `Manager` method can return anything you want. It doesn't have to
return a `QuerySet`.

For example, this custom `Manager` offers a method `with_counts()`, which
returns a list of all `OpinionPoll` objects, each with an extra
`num_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 return
that list of `OpinionPoll` objects with `num_responses` attributes.

Another thing to note about this example is that `Manager` methods can
access `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. For
example, 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 the
`Manager.get_queryset()` method. `get_queryset()` should return a
`QuerySet` with the properties you require.

For example, the following model has *two* `Manager`s -- one that returns
all 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 the
database, but `Book.dahl_objects.all()` will only return the ones written by
Roald Dahl.

Of course, because `get_queryset()` returns a `QuerySet` object, you can
use `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 multiple
managers on the same model. You can attach as many `Manager()` instances to
a model as you'd like. This is an easy way to define common "filters" for your
models.

例如:

```
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 `Manager`
Django encounters (in the order in which they're defined in the model) has a
special status. Django interprets the first `Manager` defined in a class as
the "default" `Manager`, and several parts of Django (including
[`dumpdata`](/zh-hans/2.1/ref/django-admin/#django-admin-dumpdata)) will use that `Manager` exclusively for that model. As a
result, it's a good idea to be careful in your choice of default manager in
order to avoid a situation where overriding `get_queryset()` results in an
inability to retrieve objects you'd like to work with.

You can specify a custom default manager using [`Meta.default_manager_name`](/zh-hans/2.1/ref/models/options/#django.db.models.Options.default_manager_name).

If you're writing some code that must handle an unknown model, for example, in
a third-party app that implements a generic view, use this manager (or
[`_base_manager`](#django.db.models.Model._base_manager)) rather than assuming the model has an `objects`
manager.

### Base managers

#### `Model._base_manager`

#### Using managers for related object access

By default, Django uses an instance of the `Model._base_manager` manager
class when accessing related objects (i.e. `choice.question`), not the
`_default_manager` on the related object. This is because Django needs to be
able 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`](#django.db.models.Manager)) isn't
appropriate for your circumstances, you can tell Django which class to use by
setting [`Meta.base_manager_name`](/zh-hans/2.1/ref/models/options/#django.db.models.Options.base_manager_name).

Base managers aren't used when querying on related models. For example, if the
`Question` model [from the tutorial](/zh-hans/2.1/intro/tutorial02/#creating-models) had a `deleted`
field and a base manager that filters out instances with `deleted=True`, a
queryset like `Choice.objects.filter(question__name__startswith='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 other
model. In those situations, Django has to be able to see all the objects for
the model it is fetching, so that *anything* which is referred to can be
retrieved.

If you override the `get_queryset()` method and filter out any rows, Django
will return incorrect results. Don't do that. A manager that filters results
in `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 from
the `Manager`, this is only the case for the extra methods defined on a
custom `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 from
the manager `Person.people`.

### Creating a manager with `QuerySet` methods

In lieu of the above approach which requires duplicating methods on both the
`QuerySet` and the `Manager`, [`QuerySet.as_manager()`](/zh-hans/2.1/ref/models/querysets/#django.db.models.query.QuerySet.as_manager) can be used to create an instance
of `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()`](/zh-hans/2.1/ref/models/querysets/#django.db.models.query.QuerySet.as_manager) will be virtually
identical to the `PersonManager` from the previous example.

Not every `QuerySet` method makes sense at the `Manager` level; for
instance we intentionally prevent the [`QuerySet.delete()`](/zh-hans/2.1/ref/models/querysets/#django.db.models.query.QuerySet.delete) method from being copied onto
the `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.

例如:

```
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 from_queryset(queryset_class)`

For advanced usage you might want both a custom `Manager` and a custom
`QuerySet`. You can do that by calling `Manager.from_queryset()` which
returns a *subclass* of your base `Manager` with a copy of the custom
`QuerySet` 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)()
```

还可以将生成的类存储到变量中：

```
CustomManager = BaseManager.from_queryset(CustomQuerySet)

class MyModel(models.Model):
    objects = CustomManager()
```

### 自定义管理器和模型继承

下面是Django如何处理自定义管理器和 [model inheritance](/zh-hans/2.1/topics/db/models/#model-inheritance)：

1. 基类的管理者总是由子类继承，使用Python的正常名称解析顺序（子类上的名称覆盖所有其他类；然后在第一个父类上命名）等等。
2. 如果没有在模型和/或其父母上宣布管理人员，Django就会自动创建\`\`objects\`\`管理器。
3. 类上的默认管理器要么是使用:attr:Meta.default\_manager\_name \<django.db.models.Options.default\_manager\_name\>，要么是在模型上声明的第一个管理器，或者是第一个父模型的默认管理器。

如果您想通过抽象基类在一组模型上安装自定义管理器集合，但仍然自定义默认管理器，则这些规则提供了必要的灵活性。

```
class AbstractBase(models.Model):
    # ...
    objects = CustomManager()

    class Meta:
        abstract = True
```

如果您在子类中直接使用这一点，如果您在基类中没有声明任何管理器，那么 `objects` 将是默认的管理器：

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

如果您想从\`\`AbstractBase\`\`继承，但提供不同的默认管理器，则可以在子类上提供默认管理器：

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

在这里，```default_manager``是默认的。 ``objects``` 管理器仍然可用，因为它是继承的。它只是没有被用作默认值。

最后，对于这个示例，假设您想要向子类中添加额外的管理器，但是仍然使用来自\`\`AbstractBase\`\`的默认管理器。您不能直接在子类中添加新的管理器，因为这将覆盖默认值，并且您还必须显式地包含来自抽象基类的所有管理器。解决方案是将额外的管理器放到另一个基类中，并在默认值\*之后\*将其引入继承层次结构：

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

请注意，虽然可以在抽象模型上定义\*自定义管理器，但不能使用抽象模型\*调用\*任何方法。即：

```
ClassA.objects.do_something()
```

是合法的，但：

```
AbstractBase.objects.do_something()
```

这将引起一个例外。这是因为管理人员打算封装管理对象集合的逻辑。因为您不能拥有抽象对象的集合，所以管理抽象对象是没有意义的。如果您有适用于抽象模型的功能，则应该将该功能放在抽象模型上的 `静态方法` 或\`\`类方法\`\` 中。

### 执行关系

无论您在自定义的 `Manager` 中添加了什么特性，都必须能够对 `Manager` 实例进行简单的复制；也就是说，以下代码必须有效：

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

Django在某些查询期间对管理器对象进行浅拷贝；如果您的管理器无法被复制，那么这些查询将失败。

This won't be an issue for most custom managers. If you are just
adding simple methods to your `Manager`, it is unlikely that you
will inadvertently make instances of your `Manager` uncopyable.
However, if you're overriding `__getattr__` or some other private
method of your `Manager` object that controls object state, you
should ensure that you don't affect the ability of your `Manager` to
be copied.