QuerySet API 参考Link to this heading#

filter()Link to this heading#

filter(*args, **kwargs)Link to this definition#

返回一个新的 QuerySet，其中包含与给定查找参数相匹配的对象。

查询参数（**kwargs）的格式应在下文 Field lookups 中描述。多个参数通过底层 SQL 语句中的 AND 连接。

如果你需要执行更复杂的查询（例如，带有 OR 语句的查询），你可以使用 Q 对象 （*args）。

exclude()Link to this heading#

exclude(*args, **kwargs)Link to this definition#

返回一个新的 QuerySet，其中包含与给定查找参数不匹配的对象。

查询参数（**kwargs）的格式应在下文 Field lookups 中描述。多个参数通过底层 SQL 语句中的 AND 连接，整个过程用 NOT() 括起来。

这个例子排除了所有 pub_date 晚于 2005-1-3 且 headline 为“Hello”的条目：

Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline="Hello")

用 SQL 术语来说，它的值是：

SELECT ...
WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')

这个例子不包括所有 pub_date 晚于 2005-1-3 或 headline 为“Hello”的条目：

Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline="Hello")

用 SQL 术语来说，它的值是：

SELECT ...
WHERE NOT pub_date > '2005-1-3'
AND NOT headline = 'Hello'

请注意，第二个例子的限制性更强。

如果你需要执行更复杂的查询（例如，带有 OR 语句的查询），你可以使用 Q 对象 （*args）。

annotate()Link to this heading#

annotate(*args, **kwargs)Link to this definition#

用所提供的 查询表达式 列表对 QuerySet 中的每个对象进行注解。表达式可以是一个简单的值，也可以是对模型（或任何相关模型）字段的引用，或者是对与 QuerySet 中的对象相关的对象进行计算的聚合表达式（平均数、总和等）。

annotate() 的每个参数都是一个注解，将被添加到返回的 QuerySet 中的每个对象。

Django 提供的聚合函数在下面的 聚合函数 中介绍。

使用关键字参数指定的注解将使用关键字作为注解的别名。匿名参数将根据聚合函数的名称和被聚合的模型字段为其生成一个别名。只有引用单个字段的聚合表达式才能成为匿名参数。其他一切都必须是关键字参数。

例如，如果你正在操作一个博客列表，你可能想确定每个博客中有多少条条目：

>>> from django.db.models import Count
>>> q = Blog.objects.annotate(Count("entry"))
# The name of the first blog
>>> q[0].name
'Blogasaurus'
# The number of entries on the first blog
>>> q[0].entry__count
42

Blog 模型本身没有定义 entry__count 属性，但通过使用关键字参数来指定聚合函数，你可以控制注释的名称：

>>> q = Blog.objects.annotate(number_of_entries=Count("entry"))
# The number of entries on the first blog, using the name provided
>>> q[0].number_of_entries
42

关于聚合的深入讨论，见 关于聚合的专题指南。

alias()Link to this heading#

alias(*args, **kwargs)Link to this definition#

与 annotate() 相同，但不是注解中的 QuerySet 对象，而是保存表达式，以便以后与其他 QuerySet 方法重复使用。当不需要表达式本身的结果，但用于过滤、排序或作为复杂表达式的一部分时，这很有用。不查找未使用的值可以从数据库中移除多余的工作，这应该会带来更好的性能。

例如，如果你想查找具有超过 5 条条目的博客，但不关心具体的条目数量，你可以这样做：

>>> from django.db.models import Count
>>> blogs = Blog.objects.alias(entries=Count("entry")).filter(entries__gt=5)

alias() 可以与 annotate()、exclude()、filter()、order_by() 和 update() 一起使用。要将别名表达式与其他方法（例如 aggregate()）一起使用，你必须将其提升为注解：

Blog.objects.alias(entries=Count("entry")).annotate(
    entries=F("entries"),
).aggregate(Sum("entries"))

filter() 和 order_by() 可以直接接受表达式，但表达式的构建和使用往往不发生在同一个地方（例如，QuerySet 方法创建表达式，以便以后在视图中使用）。alias() 允许逐步建立复杂的表达式，可能跨越多个方法和模块，用它们的别名指代表达式部分，只用 annotate() 来获得最终结果。

order_by()Link to this heading#

order_by(*fields)Link to this definition#

默认情况下，QuerySet 返回的结果是按照模型 Meta 中的 ordering 选项给出的排序元组排序的。你可以通过使用 order_by 方法在每个 QuerySet 的基础上覆盖这一点。

举例：

Entry.objects.filter(pub_date__year=2005).order_by("-pub_date", "headline")

上述结果将按 pub_date 降序排列，然后按 headline 升序排列。"-pub_date" 前面的负号表示 降序。升序是隐含的。要随机排序，使用 "?"，如：

Entry.objects.order_by("?")

注意：order_by('?') 查询可能会很贵，而且速度很慢，这取决于你使用的数据库后端。

要按不同模型中的字段排序，使用与跨模型关系查询时相同的语法。也就是说，字段的名称，后面是双下划线（__），再后面是新模型中的字段名称，以此类推，想加入多少模型就加入多少。例如：

Entry.objects.order_by("blog__name", "headline")

如果你试图通过与另一个模型有关系的字段进行排序，Django 将使用相关模型上的默认排序，如果没有指定 Meta.ordering，则通过相关模型的主键进行排序。例如，由于 Blog 模型没有指定默认排序：

Entry.objects.order_by("blog")

...等同于：

Entry.objects.order_by("blog__id")

如果 Blog 有 ordering = ['name']，那么第一个查询集将与以下内容相同：

Entry.objects.order_by("blog__name")

你也可以通过在表达式上调用 asc() 或 esc()，按 查询表达式 排序：

Entry.objects.order_by(Coalesce("summary", "headline").desc())

asc() 和 esc() 有参数（nulls_first 和 nulls_last）来控制如何对空值进行排序。

如果你还使用 distinct()，在按相关模型中的字段排序时要谨慎。请参见 distinct() 中的说明，解释相关模型排序如何改变预期结果。

没有办法指定排序是否应该区分大小写。关于大小写敏感，Django 会按照数据库后台的正常排序方式来排序。

你可以用 Lower 将一个字段转换为小写，从而实现大小写一致的排序：

Entry.objects.order_by(Lower("headline").desc())

如果你不想在查询中应用任何排序，甚至是默认的排序，可以不使用参数调用 order_by()。

你可以通过检查 QuerySet.ordered 属性来判断一个查询是否被排序，如果 QuerySet 以任何方式被排序，则该属性为 True。

每次 order_by() 调用都将清除以前的任何排序。例如，此查询将按 pub_date 而不是 headline 排序：

Entry.objects.order_by("headline").order_by("pub_date")

reverse()Link to this heading#

reverse()Link to this definition#

使用 reverse() 方法来反向返回查询集元素的顺序。第二次调用 reverse() 会将顺序恢复到正常方向。

要检索一个查询集中的“最后”五个项目，你可以这样做：

my_queryset.reverse()[:5]

请注意，这与 Python 中从一个序列的末尾切分不太一样。上面的例子会先返回最后一项，然后返回倒数第二项，以此类推。如果我们有一个 Python 序列，看 seq[-5:]，我们会先看到倒数第五项。Django 不支持这种访问模式（从末尾切分），因为在 SQL 中不可能有效地做到这一点。

另外，请注意，reverse() 一般只应在有定义顺序的 QuerySet 上调用（例如，当对定义了默认顺序的模型进行查询时，或者当使用 order_by() 时）。如果没有为一个给定的 QuerySet 定义这样的排序，对它调用 reverse() 没有实际效果（在调用 reverse() 之前，排序是未定义的，之后也将保持未定义）。

distinct()Link to this heading#

distinct(*fields)Link to this definition#

返回一个新的 QuerySet，在其 SQL 查询中使用 SELECT DISTINCT。这将消除查询结果中的重复记录。

默认情况下，QuerySet 不会消除重复的记录。在实践中，这很少是一个问题，因为简单的查询，如 Blog.objects.all() 不会引入重复结果行的可能性。但是，如果你的查询跨越了多个表，当 QuerySet 被执行时，就有可能得到重复的结果。这时就应该使用 distinct()。

仅在 PostgreSQL 上，你可以传递位置参数（*fields），以指定 DISTINCT 应适用的字段名称。这相当于一个 SELECT DISTINCT ON 的 SQL 查询。这其中的区别是，对于普通的 distinct() 调用，数据库在确定哪些行是不同的时候，会比较每行中的 每个 字段。对于带有指定字段名的 distinct() 调用，数据库将只比较指定的字段名。

示例（在第一个示例之后，只能在 PostgreSQL 上运行）：

>>> Author.objects.distinct()
[...]

>>> Entry.objects.order_by("pub_date").distinct("pub_date")
[...]

>>> Entry.objects.order_by("blog").distinct("blog")
[...]

>>> Entry.objects.order_by("author", "pub_date").distinct("author", "pub_date")
[...]

>>> Entry.objects.order_by("blog__name", "mod_date").distinct("blog__name", "mod_date")
[...]

>>> Entry.objects.order_by("author", "pub_date").distinct("author")
[...]

values()Link to this heading#

values(*fields, **expressions)Link to this definition#

返回一个 QuerySet，当用作可迭代对象时，返回字典，而不是模型实例。

其中每一个字典都代表一个对象，键与模型对象的属性名相对应。

这个示例比较了 values() 的字典与普通的模型对象：

# This list contains a Blog object.
>>> Blog.objects.filter(name__startswith="Beatles")
<QuerySet [<Blog: Beatles Blog>]>

# This list contains a dictionary.
>>> Blog.objects.filter(name__startswith="Beatles").values()
<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>

values() 方法接受可选的位置参数 *fields，它指定了 SELECT 应该被限制的字段名。如果你指定了字段，每个字典将只包含你指定字段的字段键／值。如果不指定字段，每个字典将包含数据库表中每个字段的键和值。

例如：

>>> Blog.objects.values()
<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>
>>> Blog.objects.values("id", "name")
<QuerySet [{'id': 1, 'name': 'Beatles Blog'}]>

values() 方法还接受可选的关键字参数 **expressions，这些参数将传递给 annotate()：

>>> from django.db.models.functions import Lower
>>> Blog.objects.values(lower_name=Lower("name"))
<QuerySet [{'lower_name': 'beatles blog'}]>

你可以在排序中使用内置和 自定义查找。例如：

>>> from django.db.models import CharField
>>> from django.db.models.functions import Lower
>>> CharField.register_lookup(Lower)
>>> Blog.objects.values("name__lower")
<QuerySet [{'name__lower': 'beatles blog'}]>

在 values() 子句内部的聚合在同一 values() 子句内的其他参数之前应用。如果需要按另一个值进行分组，请将其添加到较早的 values() 子句中。例如：

>>> from django.db.models import Count
>>> Blog.objects.values("entry__authors", entries=Count("entry"))
<QuerySet [{'entry__authors': 1, 'entries': 20}, {'entry__authors': 1, 'entries': 13}]>
>>> Blog.objects.values("entry__authors").annotate(entries=Count("entry"))
<QuerySet [{'entry__authors': 1, 'entries': 33}]>

有几个微妙的地方值得一提：

• 如果你有一个名为 foo 的字段是一个 ForeignKey，默认的 values() 调用将返回一个名为 foo_id 的字典键，因为这是存储实际值的隐藏模型属性的名称（foo 属性指的是相关模型）。当你调用 values() 并传递字段名时，你可以传递 foo 或 foo_id，你将得到同样的东西（字典键将与你传递的字段名匹配）。

  例如：

  Python console

  >>> Entry.objects.values()
  <QuerySet [{'blog_id': 1, 'headline': 'First Entry', ...}, ...]>
  
  >>> Entry.objects.values("blog")
  <QuerySet [{'blog': 1}, ...]>
  
  >>> Entry.objects.values("blog_id")
  <QuerySet [{'blog_id': 1}, ...]>
  

• 当使用 values() 与 distinct() 一起使用时，请注意排序会影响结果。详见 distinct() 中的说明。

• 如果在 extra() 调用之后使用 values() 子句，则 extra() 中的 select 参数所定义的任何字段必须明确地包含在 values() 调用中。任何在 values() 调用之后进行的 extra() 调用将忽略其额外选择的字段。

• 在 values() 之后调用 only() 和 defer() 是没有意义的，这样做会引发 TypeError。

• 组合转换和聚合需要使用两个 annotate() 调用，可以显式地使用它们，也可以作为 values() 的关键字参数。与上面一样，如果转换已经在相关字段类型上注册，第一个 annotate() 可以省略，因此以下示例是等效的：

  Python console

  >>> from django.db.models import CharField, Count
  >>> from django.db.models.functions import Lower
  >>> CharField.register_lookup(Lower)
  >>> Blog.objects.values("entry__authors__name__lower").annotate(entries=Count("entry"))
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  >>> Blog.objects.values(entry__authors__name__lower=Lower("entry__authors__name")).annotate(
  ...     entries=Count("entry")
  ... )
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  >>> Blog.objects.annotate(entry__authors__name__lower=Lower("entry__authors__name")).values(
  ...     "entry__authors__name__lower"
  ... ).annotate(entries=Count("entry"))
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  

当你知道你只需要一小部分可用字段的值，而且你不需要模型实例对象的功能时，它就很有用。只选择你需要使用的字段会更高效。

最后要注意的是，你可以在调用 values() 之后调用 filter()、order_by() 等，也就是说这两个调用是相同的：

Blog.objects.values().order_by("id")
Blog.objects.order_by("id").values()

制作 Django 的人喜欢把所有影响 SQL 的方法放在前面，后面（可选的）是任何影响输出的方法（比如 values()），但这并不重要。这是你真正炫耀自己个性的机会。

你还可以通过 OneToOneField、ForeignKey 和 ManyToManyField 属性引用反向关系上的相关模型的字段：

>>> Blog.objects.values("name", "entry__headline")
<QuerySet [{'name': 'My blog', 'entry__headline': 'An entry'},
     {'name': 'My blog', 'entry__headline': 'Another entry'}, ...]>

values_list()Link to this heading#

values_list(*fields, flat=False, named=False)Link to this definition#

这与 values() 类似，不同之处在于在迭代时，它返回元组而不是字典。每个元组包含传递给 values_list() 调用的相应字段或表达式的值 — 因此第一个项是第一个字段，依此类推。例如：

>>> Entry.objects.values_list("id", "headline")
<QuerySet [(1, 'First entry'), ...]>
>>> from django.db.models.functions import Lower
>>> Entry.objects.values_list("id", Lower("headline"))
<QuerySet [(1, 'first entry'), ...]>

如果只传递一个字段，还可以传递 flat 参数。如果为 True，则返回的结果将是单个值，而不是一元组。一个示例可以更清楚地说明区别：

>>> Entry.objects.values_list("id").order_by("id")
<QuerySet[(1,), (2,), (3,), ...]>

>>> Entry.objects.values_list("id", flat=True).order_by("id")
<QuerySet [1, 2, 3, ...]>

当有多个字段时，传入 flat 是错误的。

你可以传递 named=True 以将结果作为 namedtuple() 返回：

>>> Entry.objects.values_list("id", "headline", named=True)
<QuerySet [Row(id=1, headline='First entry'), ...]>

使用命名元组可能会使使用结果更易读，但代价是将结果转化为命名元组时要付出很小的性能代价。

如果你不向 values_list() 传递任何值，它将按照声明的顺序返回模型中的所有字段。

一个常见的需求是获取特定模型实例的特定字段值。要实现这一点，使用 values_list() 后跟一个 get() 调用：

>>> Entry.objects.values_list("headline", flat=True).get(pk=1)
'First entry'

values() 和 values_list() 都是针对特定用例的优化：检索数据的子集，而不需要创建一个模型实例的开销。当处理多对多和其他多值关系（如反向外键的一对多关系）时，这个隐喻就失效了，因为“一行一对象”的假设不成立。

例如，请注意在查询跨越 ManyToManyField 时的行为：

>>> Author.objects.values_list("name", "entry__headline")
<QuerySet [('Noam Chomsky', 'Impressions of Gaza'),
 ('George Orwell', 'Why Socialists Do Not Believe in Fun'),
 ('George Orwell', 'In Defence of English Cooking'),
 ('Don Quixote', None)]>

有多个条目的作者出现多次，没有任何条目的作者的条目标题为 None。

类似地，当查询反向外键时，对于没有任何作者的条目，会显示为 None：

>>> Entry.objects.values_list("authors")
<QuerySet [('Noam Chomsky',), ('George Orwell',), (None,)]>

dates()Link to this heading#

dates(field, kind, order='ASC')Link to this definition#

返回一个 QuerySet，它的值是一个 datetime.date 对象的列表，代表 QuerySet 内容中所有可用的特定日期。

field 应该是你的模型的 DateField 的名称。kind 应该是``"year"、"month"、"week"`` 或 "day"。结果列表中的每个 datetime.date 对象都被“截断”为给定的` type`。

• "year" 返回字段的所有不同年份值的列表。

• "month" 返回该字段所有不同年／月值的列表。

• "week" 返回该字段的所有不同年份／星期值的列表。所有日期都是星期一。

• "day" 返回该字段的所有不同年／月／日值的列表。

order，默认为 'ASC'，应该是 'ASC' 或 'DESC'。这指定了如何对结果进行排序。

举例：

>>> Entry.objects.dates("pub_date", "year")
[datetime.date(2005, 1, 1)]
>>> Entry.objects.dates("pub_date", "month")
[datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)]
>>> Entry.objects.dates("pub_date", "week")
[datetime.date(2005, 2, 14), datetime.date(2005, 3, 14)]
>>> Entry.objects.dates("pub_date", "day")
[datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)]
>>> Entry.objects.dates("pub_date", "day", order="DESC")
[datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)]
>>> Entry.objects.filter(headline__contains="Lennon").dates("pub_date", "day")
[datetime.date(2005, 3, 20)]

datetimes()Link to this heading#

datetimes(field_name, kind, order='ASC', tzinfo=None, is_dst=None)Link to this definition#

返回一个 QuerySet，它的值是一个 datetime.datetime 对象的列表，代表 QuerySet 内容中所有可用的特定日期。

field_name 应该是你的模型中 DateTimeField 的名称。

kind 应该是 "year"、"month"、"week"、"day"、"hour"、"minute" 或 "second"。结果列表中的每个 datetime.datetime 对象都被“截断”为给定的 type。

order，默认为 'ASC'，应该是 'ASC' 或 'DESC'。这指定了如何对结果进行排序。

tzinfo 定义了在截断之前将日期时间转换为的时区。事实上，一个给定的日期时间根据使用的时区有不同的表示方式。这个参数必须是一个 datetime.tzinfo 对象。如果是 None，Django 会使用 current time zone。当 USE_TZ 为 False 时，它没有效果。

is_dst 表示 pytz 是否应该解释夏令时中不存在的和含糊不清的日期。默认情况下（当 is_dst=None），pytz 会对这种日期时间产生异常。

none()Link to this heading#

none()Link to this definition#

调用 none() 将创建一个永远不会返回任何对象的查询集，在访问结果时将不执行任何查询。qs.none() 查询集是 EmptyQuerySet 的一个实例。

举例：

>>> Entry.objects.none()
<QuerySet []>
>>> from django.db.models.query import EmptyQuerySet
>>> isinstance(Entry.objects.none(), EmptyQuerySet)
True

all()Link to this heading#

all()Link to this definition#

返回当前 QuerySet （或 QuerySet 子类）的 副本。 这在以下情况下很有用：你可能想传入一个模型管理器或一个 QuerySet，并对结果做进一步过滤。在任何一个对象上调用 all() 后，你肯定会有一个 QuerySet 可以使用。

当一个 QuerySet 被 执行 时，它通常会缓存其结果。如果数据库中的数据可能在 QuerySet 被评估后发生了变化，你可以通过调用 all() 对以前执行过的 QuerySet 进行更新。

union()Link to this heading#

union(*other_qs, all=False)Link to this definition#

使用 SQL 的 UNION 操作符来组合两个或多个 QuerySet 的结果。例如：

>>> qs1.union(qs2, qs3)

UNION 操作符默认只选择不同的值。要允许重复的值，使用 all=True 参数。

union(), intersection(), 和 difference() 返回第一个 QuerySet 类型的模型实例，即使参数是其他模型的 QuerySet。只要所有 QuerySet 中的 SELECT 列表相同（至少类型相同，名称不重要，只要类型的顺序相同），就可以传递不同的模型。在这种情况下，必须在应用于结果 QuerySet 的 QuerySet 方法中使用来自第一个 QuerySet 的列名。例如：

>>> qs1 = Author.objects.values_list("name")
>>> qs2 = Entry.objects.values_list("headline")
>>> qs1.union(qs2).order_by("name")

此外，只有 LIMIT、OFFSET、COUNT(*)、ORDER BY 和指定列（即切片、count()、exists()、order_by() 与 values() ／ values_list() ）允许在结果 QuerySet 中使用。此外，数据库对组合查询中允许的操作也有限制。例如，大多数数据库不允许在组合查询中使用 LIMIT 或 OFFSET。

intersection()Link to this heading#

intersection(*other_qs)Link to this definition#

使用 SQL 的 INTERSECT 操作符来返回两个或多个 QuerySet 的共享元素。例如：

>>> qs1.intersection(qs2, qs3)

一些限制见 union()。

difference()Link to this heading#

difference(*other_qs)Link to this definition#

使用 SQL 的 EXCEPT 运算符，只保留在一个 QuerySet 中存在而在其他某些 QuerySet 中不存在的元素。例如：

>>> qs1.difference(qs2, qs3)

一些限制见 union()。

select_related()Link to this heading#

select_related(*fields)Link to this definition#

返回一个 QuerySet，它将“跟随”外键关系，在执行查询时选择额外的相关对象数据。这是一个性能提升器，它导致一个更复杂的单一查询，但意味着以后使用外键关系将不需要数据库查询。

下面的例子说明了普通查找和 select_related() 查找之间的区别。下面是标准的查询：

# Hits the database.
e = Entry.objects.get(id=5)

# Hits the database again to get the related Blog object.
b = e.blog

这里是 select_related 查找：

# Hits the database.
e = Entry.objects.select_related("blog").get(id=5)

# Doesn't hit the database, because e.blog has been prepopulated
# in the previous query.
b = e.blog

你可以使用 select_related() 来处理任何对象的查询集：

from django.utils import timezone

# Find all the blogs with entries scheduled to be published in the future.
blogs = set()

for e in Entry.objects.filter(pub_date__gt=timezone.now()).select_related("blog"):
    # Without select_related(), this would make a database query for each
    # loop iteration in order to fetch the related blog for each entry.
    blogs.add(e.blog)

filter() 和 select_related() 的顺序并不重要。这些查询集相当于：

Entry.objects.filter(pub_date__gt=timezone.now()).select_related("blog")
Entry.objects.select_related("blog").filter(pub_date__gt=timezone.now())

你可以用类似于查询外键的方式来跟踪外键。如果你有以下模型：

from django.db import models


class City(models.Model):
    # ...
    pass


class Person(models.Model):
    # ...
    hometown = models.ForeignKey(
        City,
        on_delete=models.SET_NULL,
        blank=True,
        null=True,
    )


class Book(models.Model):
    # ...
    author = models.ForeignKey(Person, on_delete=models.CASCADE)

...然后调用 Book.objects.select_related('author__hometown').get(id=4) 将缓存相关的 Person 和 相关的 City：

# Hits the database with joins to the author and hometown tables.
b = Book.objects.select_related("author__hometown").get(id=4)
p = b.author  # Doesn't hit the database.
c = p.hometown  # Doesn't hit the database.

# Without select_related()...
b = Book.objects.get(id=4)  # Hits the database.
p = b.author  # Hits the database.
c = p.hometown  # Hits the database.

你可以在传递给 select_related() 的字段列表中引用任何 ForeignKey 或 OneToOneField 关系。

你也可以在传递给 select_related 的字段列表中引用一个 OneToOneField 的反方向——也就是说，你可以遍历一个 OneToOneField 回到定义字段的对象上。不指定字段名，而是使用 related_name 作为相关对象上的字段。

在某些情况下，你可能希望调用 select_related() 来处理很多相关对象，或者你不知道所有的关系。在这些情况下，我们可以调用 select_related()，但不使用参数。这将跟随它能找到的所有非空的外键——必须指定可空的外键。在大多数情况下，不建议这样做，因为这可能会使基础查询变得更加复杂，并返回比实际需要的更多数据。

如果需要清除在过去的 select_related 调用中添加的相关字段列表，可以将 None 作为参数传递：

>>> without_relations = queryset.select_related(None)

链式调用 select_related 的工作方式与其他方法类似，即 select_related('foo', 'bar') 等同于 select_related('foo').select_related('bar')。

prefetch_related()Link to this heading#

prefetch_related(*lookups)Link to this definition#

返回一个 QuerySet，它将在一个批次中自动检索每个指定查询的相关对象。

这与 select_related 有类似的目的，二者都是为了阻止因访问相关对象而引起的数据库查询潮，但策略却完全不同。

select_related 的工作方式是创建一个 SQL 连接，并在 SELECT 语句中包含相关对象的字段。出于这个原因，select_related 在同一个数据库查询中得到相关对象。然而，为了避免因跨越“many”关系进行连接而产生更大的结果集，select_related 仅限于单值关系——外键和一对一。

另一方面，prefetch_related 为每个关系执行单独的查找，并在 Python 中执行 'joining'。这使它能够预取不能使用 select_related 完成的多对多、多对一和 GenericRelation 对象，除了 select_related 支持的外键和一对一关系。它还支持预取 GenericForeignKey，但必须限制为同质结果集。例如，只有在查询限制为一个 ContentType 时，才支持预取由 GenericForeignKey 引用的对象。

例如，假设你有这些模型：

from django.db import models


class Topping(models.Model):
    name = models.CharField(max_length=30)


class Pizza(models.Model):
    name = models.CharField(max_length=50)
    toppings = models.ManyToManyField(Topping)

    def __str__(self):
        return "%s (%s)" % (
            self.name,
            ", ".join(topping.name for topping in self.toppings.all()),
        )

并运行：

>>> Pizza.objects.all()
["Hawaiian (ham, pineapple)", "Seafood (prawns, smoked salmon)"...

这样做的问题是，每次 Pizza.__str__() 要求 self.toppings.all() 都要查询数据库，所以 Pizza.objects.all() 会在 Toppings 表上对 Pizza QuerySet 中的 每 项进行查询。

我们可以使用 prefetch_related 减少到只有两个查询：

>>> Pizza.objects.prefetch_related('toppings')

这意味着每一个 Pizza 都有一个 self.toppings.all()；现在每次调用 self.toppings.all() 时，不必再去数据库中寻找这些项目，而是在一次查询中填充的预设 QuerySet 缓存中找到它们。

也就是说，所有相关的顶点都将在一次查询中被获取，并被用来制作 QuerySets，其中有一个预先填充的相关结果的缓存；然后这些 QuerySets 被用于 self.toppings.all() 的调用。

prefetch_related() 中的附加查询是在 QuerySet 开始执行和主要查询被执行后执行的。

如果你有一个作为模型实例的可迭代对象，你可以使用 prefetch_related_objects() 函数在这些实例上预取相关属性。

请注意，主 QuerySet 的结果缓存和所有指定的相关对象将被完全加载到内存中。这改变了 QuerySets 的典型行为，它通常试图避免在需要之前将所有对象加载到内存中，即使在数据库中执行了一个查询之后。

你也可以用普通的 join 语法来做相关字段的相关字段。假设我们在上面的例子中多了一个模型：

class Restaurant(models.Model):
    pizzas = models.ManyToManyField(Pizza, related_name="restaurants")
    best_pizza = models.ForeignKey(
        Pizza, related_name="championed_by", on_delete=models.CASCADE
    )

以下都是合法的：

>>> Restaurant.objects.prefetch_related("pizzas__toppings")

这将预取所有属于餐馆的披萨，以及所有属于这些披萨的配料。这将导致总共 3 个数据库查询——一个查询餐厅，一个查询披萨，一个查询配料。

>>> Restaurant.objects.prefetch_related("best_pizza__toppings")

这将为每家餐厅获取最好的比萨饼和最好的比萨饼的所有配料。这将在 3 个数据库查询中完成——一个查询餐厅，一个查询“最佳披萨”，一个查询配料。

best_pizza 关系也可以使用 select_related 获取，以将查询计数减少到 2：

>>> Restaurant.objects.select_related("best_pizza").prefetch_related("best_pizza__toppings")

由于预取是在主查询之后执行的（其中包括 select_related 所需要的连接），它能够检测到 best_pizza 对象已经被取走了，它将跳过再次取走它们。

链式调用 prefetch_related 将累积预取的查找。要清除任何 prefetch_related 行为，传递 None 作为参数：

>>> non_prefetched = qs.prefetch_related(None)

在使用 prefetch_related 时，需要注意的一个区别是，查询创建的对象可以在与其相关的不同对象之间共享，即一个 Python 模型实例可以出现在返回的对象树的多个点上。这通常会发生在外键关系中。通常情况下，这种行为不会有问题，而且事实上会节省内存和 CPU 时间。

虽然 prefetch_related 支持预取 GenericForeignKey 关系，但查询次数将取决于数据。由于一个 GenericForeignKey 可以引用多个表中的数据，所以需要对每个被引用的表进行一次查询，而不是对所有项目进行一次查询。如果还没有获取相关的行，可以对 ContentType 表进行额外的查询。

prefetch_related 在大多数情况下，将使用使用“IN”操作符的 SQL 查询来实现。这意味着对于一个大的 QuerySet 可能会生成一个大的“IN”子句，这取决于数据库，在解析或执行 SQL 查询时可能会有自己的性能问题。一定要针对自己的用例进行剖析！

你可以使用 Prefetch 对象来进一步控制预取操作。

最简单的形式 Prefetch 相当于传统的基于字符串的查找。

>>> from django.db.models import Prefetch
>>> Restaurant.objects.prefetch_related(Prefetch('pizzas__toppings'))

你可以用可选的 queryset 参数提供一个自定义查询集。这可以用来改变查询集的默认排序。

>>> Restaurant.objects.prefetch_related(
...     Prefetch('pizzas__toppings', queryset=Toppings.objects.order_by('name')))

或者在适用的时候调用 select_related()，以进一步减少查询次数。

>>> Pizza.objects.prefetch_related(
...     Prefetch('restaurants', queryset=Restaurant.objects.select_related('best_pizza')))

你也可以用可选的 to_attr 参数将预取结果分配给一个自定义属性。结果将直接存储在一个列表中。

这允许用不同的 QuerySet 预取同一关系多次；例如：

>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related(
...     Prefetch('pizzas', to_attr='menu'),
...     Prefetch('pizzas', queryset=vegetarian_pizzas, to_attr='vegetarian_menu'))

使用自定义 to_attr 创建的查找仍然可以像往常一样被其他查找遍历。

>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related(
...     Prefetch('pizzas', queryset=vegetarian_pizzas, to_attr='vegetarian_menu'),
...     'vegetarian_menu__toppings')

在对预取结果进行过滤时，建议使用 to_attr，因为它比将过滤后的结果存储在相关管理器的缓存中更不含糊。

>>> queryset = Pizza.objects.filter(vegetarian=True)
>>>
>>> # Recommended:
>>> restaurants = Restaurant.objects.prefetch_related(
...     Prefetch('pizzas', queryset=queryset, to_attr='vegetarian_pizzas'))
>>> vegetarian_pizzas = restaurants[0].vegetarian_pizzas
>>>
>>> # Not recommended:
>>> restaurants = Restaurant.objects.prefetch_related(
...     Prefetch('pizzas', queryset=queryset))
>>> vegetarian_pizzas = restaurants[0].pizzas.all()

自定义预取也适用于单一的相关关系，如前向 ForeignKey 或 OneToOneField。一般来说，你会希望使用 select_related() 来处理这些关系，但在一些情况下，使用自定义 QuerySet 进行预取是有用的。

• 你要使用一个 QuerySet，对相关模型进行进一步的预取。

• 你想只预取相关对象的一个子集。

• 你要使用性能优化技术，比如 递延字段。

  Code

  >>> queryset = Pizza.objects.only('name')
  >>>
  >>> restaurants = Restaurant.objects.prefetch_related(
  ...     Prefetch('best_pizza', queryset=queryset))
  

在使用多个数据库时，Prefetch 将尊重您的数据库选择。如果内部查询没有指定数据库，它将使用外部查询选择的数据库。以下所有方式都是有效的：

>>> # Both inner and outer queries will use the 'replica' database
>>> Restaurant.objects.prefetch_related("pizzas__toppings").using("replica")
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings"),
... ).using("replica")
>>>
>>> # Inner will use the 'replica' database; outer will use 'default' database
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.using("replica")),
... )
>>>
>>> # Inner will use 'replica' database; outer will use 'cold-storage' database
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.using("replica")),
... ).using("cold-storage")

extra()Link to this heading#

extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)Link to this definition#

有时候，Django 查询语法本身并不能很容易地表达一个复杂的 WHERE 子句。对于这些边缘情况，Django 提供了 extra() QuerySet 修饰符——用于将特定的子句注入到由 QuerySet 生成的 SQL 中。

根据定义，这些额外的查找可能无法移植到不同的数据库引擎中（因为你明确地编写了 SQL 代码），并且违反了 DRY 原则，所以你应该尽可能地避免它们。

指定 params、select、where 或 tables 中的一个或多个参数。这些参数都不是必须的，但你应该至少使用其中的一个。

• select

  select 参数让你在 SELECT 子句中放入额外的字段。 它应该是一个将属性名映射到 SQL 子句的字典，用于计算该属性。

  举例：

  Code

  Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})
  

  因此，每个 Entry 对象将有一个额外的属性，is_recent，一个布尔值，表示该条目的 pub_date 是否大于 2006 年 1 月 1 日。

  Django 将给定的 SQL 片段直接插入到 SELECT 语句中，所以上面例子的 SQL 结果将是这样的。

  SQL

  SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
  FROM blog_entry;
  

  下一个例子更高级；它做了一个子查询，给每个结果的 Blog 对象一个 entry_count 属性，一个相关 Entry 对象的整数：

  Code

  Blog.objects.extra(
      select={
          "entry_count": "SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id"
      },
  )
  

  在这个特殊的情况下，我们利用了这样一个事实，即查询在其 FROM 子句中已经包含 blog_blog 表。

  上述例子的 SQL 结果是：

  SQL

  SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count
  FROM blog_blog;
  

  需要注意的是，大多数数据库引擎要求在子查询周围加上括号，而 Django 的 select 子句则不需要。还需要注意的是，一些数据库后端，比如一些 MySQL 版本，不支持子查询。

  在一些罕见的情况下，你可能希望在 extra(select=...) 中给 SQL 片段传递参数。为此，使用 select_params 参数。

  这样做就可以了，比如：

  Code

  Blog.objects.extra(
      select={"a": "%s", "b": "%s"},
      select_params=("one", "two"),
  )
  

  如果你需要在选择字符串中使用 %s，请使用序列 %%s。

• where／tables

  你可以通过使用 where 来定义明确的 SQL WHERE 子句——也许是为了执行非明确的连接。你可以通过使用 tables 手动添加表到 SQL FROM 子句中。

  where 和 tables 都采用一个字符串列表。所有 where 参数都与任何其他搜索标准“AND”在一起。

  举例：

  Code

  Entry.objects.extra(where=["foo='a' OR bar = 'a'", "baz = 'a'"])
  

  ...翻译成（大致）下面的 SQL：

  SQL

  SELECT * FROM blog_entry WHERE (foo='a' OR bar='a') AND (baz='a')
  

  如果使用 tables 参数时，要注意指定查询中已经使用过的表，当你通过 tables 参数添加额外的表时，Django 会认为你希望额外包含该表，如果已经包含的话。当你通过 tables 参数添加额外的表时，Django 会认为你希望额外地包含该表，如果它已经被包含了。这就会产生一个问题，因为表名会被赋予一个别名。如果一个表在一条 SQL 语句中多次出现，那么第二次和后续的表必须使用别名，这样数据库才能区分它们。如果你指的是你在额外的 where 参数中添加的额外表，这就会造成错误。

  一般情况下，你只会添加查询中还没有出现的额外表。但是，如果确实出现了上面概述的情况，有几种解决办法。首先，看看是否可以不包含额外的表，而使用已经在查询中出现的表。如果不可能的话，把你的 extra() 调用放在查询集构造的前面，这样你的表就是那个表的第一次使用。最后，如果所有其他方法都失败了，看一下产生的查询，重写你的 where 加法，使用给你的额外表的别名。每次以同样的方式构造查询集时，别名都会是一样的，所以你可以信赖别名不会改变。

• order_by

  如果你需要使用你通过 extra() 所包含的一些新字段或表来对结果查询集进行排序，请使用 extra() 的 order_by 参数，并传入一串字符串。这些字符串应该是模型字段（就像在查询集上的普通 order_by() 方法一样），形式为 table_name.column_name 或者是你在 extra() 的 select 参数中指定的列的别名。

  例子：

  Code

  q = Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})
  q = q.extra(order_by=["-is_recent"])
  

  这将把 is_recent 为真的所有项目排在结果集的前面（True 按降序排列在 False 之前）。

  顺便说一下，这表明你可以多次调用 extra()，它将按照你的期望行事（每次增加新的约束）。

• params

  上面描述的 where 参数可以使用标准的 Python 数据库字符串占位符——'%s' 来表示数据库引擎应该自动引用的参数。params 参数是一个要被替换的额外参数的列表。

  举例：

  Code

  Entry.objects.extra(where=["headline=%s"], params=["Lennon"])
  

  始终使用 params 而不是直接将值嵌入 where，因为 params 将确保根据你的特定后台正确引用值。例如，引号将被正确转义。

  不好的：

  Code

  Entry.objects.extra(where=["headline='Lennon'"])
  

  正确的：

  Code

  Entry.objects.extra(where=["headline=%s"], params=["Lennon"])
  

defer()Link to this heading#

defer(*fields)Link to this definition#

在一些复杂的数据建模情况下，你的模型可能包含很多字段，其中一些字段可能包含很多数据（例如，文本字段），或者需要昂贵的处理来将它们转换为 Python 对象。如果你在某些情况下使用查询集的结果，在最初获取数据时不知道是否需要这些特定的字段，你可以告诉 Django 不要从数据库中检索这些字段。

通过将不加载的字段名称传递给 defer()：

Entry.objects.defer("headline", "body")

一个有递延字段的查询集仍然会返回模型实例。如果你访问每个递延字段，将从数据库中检索该字段（一次一个，而不是同时访问所有的递延字段）。

你可以多次调用 defer()。每次调用都会在推迟的集合中增加新的字段：

# Defers both the body and headline fields.
Entry.objects.defer("body").filter(rating=5).defer("headline")

字段被添加到递延集的顺序并不重要。用已经被递延的字段名调用 defer() 是无害的（该字段仍将被递延）。

你可以通过使用标准的双下划线符号来分隔相关的字段，来推迟加载相关模型中的字段（如果相关模型是通过 select_related() 加载的）：

Blog.objects.select_related().defer("entry__headline", "entry__body")

如果你想清除一组递延字段，将 None 作为参数传递给 defer()：

# Load all fields immediately.
my_queryset.defer(None)

模型中的一些字段不会被推迟，即使你要求它们。你永远不能推迟加载主键。如果你使用 select_related() 来检索相关的模型，你不应该推迟从主模型连接到相关模型的字段的加载，这样做会导致一个错误。

类似地，从聚合调用 defer() （或其对应的 only()）包括一个参数是没有意义的（例如使用 annotate() 的结果）。这样做将引发异常。聚合值将始终被提取到生成的查询集中。

only()Link to this heading#

only(*fields)Link to this definition#

only() 方法实际上是 defer() 的相反。只有传递到此方法中的字段，并且尚未指定为延迟加载的字段，在查询集评估时会立即加载。

如果你有一个几乎所有字段都需要延迟加载的模型，使用 only() 来指定补充的字段集合可以简化代码。

假设你有一个模型，其字段为 name、age 和 biography。就递延字段而言，以下两个查询集是相同的：

Person.objects.defer("age", "biography")
Person.objects.only("name")

每当你调用 only() 时，它就会 替换 要立即加载的字段集。该方法的名称是记号式的：仅 那些字段被立即加载；其余的字段被推迟。因此，连续调用 only() 的结果是只考虑最后的字段：

# This will defer all fields except the headline.
Entry.objects.only("body", "rating").only("headline")

由于 defer() 以递增的方式行事（将字段添加到递延列表中），你可以将对 only() 和 defer() 的调用结合起来，事情就会符合逻辑：

# Final result is that everything except "headline" is deferred.
Entry.objects.only("headline", "body").defer("body")

# Final result loads headline immediately.
Entry.objects.defer("body").only("headline", "body")

defer() 文档注释中的所有注意事项也适用于 only()。谨慎使用，只有在用尽其他选项后才能使用。

使用 only() 并省略使用 select_related() 请求的字段也是错误的。另一方面，如果在没有任何参数的情况下调用 only()，将返回查询集提取的每个字段（包括注释）。

与 defer() 一样，你不能从异步代码中访问未加载的字段并期望它们加载。相反，你将得到一个 SynchronousOnlyOperation 异常。确保你可能访问的所有字段都在你的 only() 调用中。

using()Link to this heading#

using(alias)Link to this definition#

如果你使用多个数据库，该方法用于控制 QuerySet 将针对哪个数据库进行评估。 本方法的唯一参数是数据库的别名，定义在 DATABASES 中。

例如：

# queries the database with the 'default' alias.
>>> Entry.objects.all()

# queries the database with the 'backup' alias
>>> Entry.objects.using("backup")

select_for_update()Link to this heading#

select_for_update(nowait=False, skip_locked=False, of=(), no_key=False)Link to this definition#

返回一个查询集，该查询集将锁定行直到事务结束，从而在受支持的数据库上生成 SELECT ... FOR UPDATE SQL 语句。

例子：

from django.db import transaction

entries = Entry.objects.select_for_update().filter(author=request.user)
with transaction.atomic():
    for entry in entries:
        ...

当查询集被执行时（这里是 for entry in entries），所有匹配的条目将被锁定，直到事务块结束，这意味着其他事务将被阻止改变或获取它们的锁。

通常情况下，如果另一个事务已经获得了所选行的锁，那么查询将被阻塞，直到锁被释放。如果这不是你想要的行为，调用 select_for_update(nowait=True)。这将使调用非阻塞。如果一个冲突的锁已经被另一个事务获取，那么当查询集被评估时，将引发 DatabaseError。你也可以通过使用 select_for_update( skip_locked=True) 来忽略锁定的记录。nowait 和 skip_locked 是相互排斥的，在启用这两个选项的情况下调用 select_for_update() 会导致一个 ValueError。

默认情况下，select_for_update() 锁定所有被查询选择的行。例如，在 select_related() 中指定的相关对象的行，除了查询集模型的行之外，也会被锁定。如果不希望这样，可以在 select_for_update(of=(...)) 中使用与 select_related() 相同的字段语法指定你要锁定的相关对象。使用 'self' 来表示查询集的模型。

仅在 PostgreSQL 上，你可以通过 no_key=True 来获得一个较弱的锁，这仍然允许在锁存在的情况下，创建仅仅引用锁定的行（例如，通过外键）。PostgreSQL 文档中有更多关于 行级锁模式的细节 。

你不能在可空关联上使用 select_for_update()：

>>> Person.objects.select_related("hometown").select_for_update()
Traceback (most recent call last):
...
django.db.utils.NotSupportedError: FOR UPDATE cannot be applied to the nullable side of an outer join

为了避免这个限制，如果你不关心空对象，可以将它们排除在外：

>>> Person.objects.select_related("hometown").select_for_update().exclude(hometown=None)
<QuerySet [<Person: ...)>, ...]>

postgresql、oracle 和 mysql 数据库后端支持 select_for_update()。但是，MariaDB 仅支持 nowait 参数，MariaDB 10.6+ 还支持 skip_locked 参数，而 MySQL 8.0.1+ 支持 nowait、skip_locked 和 of 参数。no_key 参数仅在 PostgreSQL 上受支持。

在使用不支持这些选项的数据库后端（如 MySQL）向 select_for_update()``传递 ``nowait=True、skip_locked=True、no_key=True 或 of，会产生一个 NotSupportedError。这可以防止代码意外地阻塞。

在支持 SELECT ... FOR UPDATE 的后端上，用 select_for_update() 在自动提交模式下执行一个查询集是一个 TransactionManagementError 错误，因为在这种情况下行没有被锁定。如果允许这样做，这将促进数据损坏，并且很容易通过调用期望在一个事务之外的事务中运行的代码而引起。

在不支持 SELECT ... FOR UPDATE 的后端（比如 SQLite）使用 select_for_update() 不会有任何影响。SELECT ... FOR UPDATE 不会被添加到查询中，如果 select_for_update() 在自动提交模式下使用，也不会出现错误。

raw()Link to this heading#

raw(raw_query, params=(), translations=None, using=None)Link to this definition#

获取一个原始 SQL 查询，执行它，并返回一个 django.db.models.query.RawQuerySet 实例。这个 RawQuerySet 实例可以像普通的 QuerySet 一样进行迭代，提供对象实例。

更多信息请参见 执行原生 SQL 查询。

AND（&）Link to this heading#

使用 SQL 的 AND 运算符以类似于链接过滤器的方式合并两个 QuerySet。

以下的都是相同的：

Model.objects.filter(x=1) & Model.objects.filter(y=2)
Model.objects.filter(x=1).filter(y=2)

SQL 等价于：

SELECT ... WHERE x=1 AND y=2

OR（|）Link to this heading#

使用 SQL OR 操作符将两个 QuerySet 组合起来。

以下的都是相同的：

Model.objects.filter(x=1) | Model.objects.filter(y=2)
from django.db.models import Q

Model.objects.filter(Q(x=1) | Q(y=2))

SQL 等价于：

SELECT ... WHERE x=1 OR y=2

| 不是一个换元运算，因为可能会产生不同的（虽然是等价的）查询。

XOR (^)Link to this heading#

使用 SQL 的 XOR 运算符合并两个 QuerySet。

以下的都是相同的：

Model.objects.filter(x=1) ^ Model.objects.filter(y=2)
from django.db.models import Q

Model.objects.filter(Q(x=1) ^ Q(y=2))

SQL 等价于：

SELECT ... WHERE x=1 XOR y=2

get()Link to this heading#

get(*args, **kwargs)Link to this definition#

aget(*args, **kwargs)Link to this definition#

异步版本: aget()

返回与给定的查找参数相匹配的对象，其格式应该在 Field lookups 中描述。你应该使用保证唯一的查询，比如主键或唯一约束中的字段。例如：

Entry.objects.get(id=1)
Entry.objects.get(Q(blog=blog) & Q(entry_number=1))

如果你希望一个查询集已经返回一条记录，你可以在没有任何参数的情况下使用 get() 来返回该行的对象：

Entry.objects.filter(pk=1).get()

如果 get() 没有找到任何对象，它会引发一个 Model.DoesNotExist 异常：

Entry.objects.get(id=-999)  # raises Entry.DoesNotExist

如果 get() 发现多个对象，会引发一个 Model.MultipleObjectsReturned 异常：

Entry.objects.get(name="A Duplicated Name")  # raises Entry.MultipleObjectsReturned

这两个异常类都是模型类的属性，并且特定于该模型。如果你想对不同模型的多个 get() 调用处理这样的异常，可以使用它们的通用基类。例如，你可以使用 django.core.exceptions.ObjectDoesNotExist 来处理 DoesNotExist 来自多个模型的异常：

from django.core.exceptions import ObjectDoesNotExist

try:
    blog = Blog.objects.get(id=1)
    entry = Entry.objects.get(blog=blog, entry_number=1)
except ObjectDoesNotExist:
    print("Either the blog or entry doesn't exist.")

create()Link to this heading#

create(**kwargs)Link to this definition#

acreate(**kwargs)Link to this definition#

异步版本: acreate()

一种方便的方法，用于创建一个对象并一步到位地保存。 因此：

p = Person.objects.create(first_name="Bruce", last_name="Springsteen")

和：

p = Person(first_name="Bruce", last_name="Springsteen")
p.save(force_insert=True)

是等效的。

force_insert 参数在其他地方有说明，但它的意思是总是会创建一个新的对象。通常情况下，你不需要担心这个问题。但是，如果你的模型中包含了一个你设置的手动主键值，而且如果这个值已经存在于数据库中，那么对 create() 的调用就会以一个 IntegrityError 失败，因为主键必须是唯一的。如果使用手动主键，要做好处理异常的准备。

get_or_create()Link to this heading#

get_or_create(defaults=None, **kwargs)Link to this definition#

aget_or_create(defaults=None, **kwargs)Link to this definition#

异步版本: aget_or_create()

一个方便的方法，用于查找具有给定 kwargs 的对象（如果你的模型对所有字段都有默认值，则可能为空），必要时创建一个对象。

返回 (object, created) 的元组，其中 object 是检索或创建的对象，created 是指定是否创建新对象的布尔值。

这是为了防止在并行进行请求时创建重复的对象，并作为样板代码的快捷方式。 例如：

try:
    obj = Person.objects.get(first_name="John", last_name="Lennon")
except Person.DoesNotExist:
    obj = Person(first_name="John", last_name="Lennon", birthday=date(1940, 10, 9))
    obj.save()

在这里，如果是并发请求，可能会多次尝试用相同的参数保存一个 Person。为了避免这种竞争条件，可以使用 get_or_create() 重写上面的例子，比如：

obj, created = Person.objects.get_or_create(
    first_name="John",
    last_name="Lennon",
    defaults={"birthday": date(1940, 10, 9)},
)

任何传递给 get_or_create() 的关键字参数—— 除了 一个叫 defaults 的可选参数——都将在 get() 调用中使用。如果找到了一个对象，get_or_create() 返回该对象的元组和 False。

你可以通过将 get_or_create() 和 filter() 串联起来，并使用 Q 对象 为检索对象指定更复杂的条件。例如，如果 Robert 或 Bob Marley 存在，则检索 Robert 或 Bob Marley，否则创建后者：

from django.db.models import Q

obj, created = Person.objects.filter(
    Q(first_name="Bob") | Q(first_name="Robert"),
).get_or_create(last_name="Marley", defaults={"first_name": "Bob"})

如果找到多个对象，get_or_create() 会引发 MultipleObjectsReturned。如果没有找到对象，get_or_create() 将实例化并保存一个新对象，返回一个新对象的元组和 True。新对象将大致按照以下算法创建：

params = {k: v for k, v in kwargs.items() if "__" not in k}
params.update({k: v() if callable(v) else v for k, v in defaults.items()})
obj = self.model(**params)
obj.save()

在英语中，这意味着从任何不包含双下划线的非 'defaults' 关键字参数开始（这将表明一个非精确的查找）。然后添加 defaults 的内容，必要时覆盖任何键，并将结果作为模型类的关键字参数。如果 defaults 中存在任何可调用对象，则对其进行评估。正如上面所提示的，这是对所使用算法的简化，但它包含了所有相关的细节。内部实现有比这更多的错误检查，并处理一些额外的边缘条件；如果你感兴趣，请阅读代码。

如果你有一个名为 defaults 的字段，并且想在 get_or_create() 中使用它作为精确查询，使用 'defaults__exact'，像这样：

Foo.objects.get_or_create(defaults__exact="bar", defaults={"defaults": "baz"})

当你使用手动指定的主键时，get_or_create() 方法的错误行为与 create() 类似。如果需要创建一个对象，而该键已经存在于数据库中，则会引发一个 IntegrityError。

最后，关于在 Django 视图中使用 get_or_create() 的一些建议。请确保只在 POST 请求中使用它，除非你有充分的理由不这样做。GET 请求不应该对数据产生任何影响。相反，只有当对页面的请求对数据产生副作用时，才使用 POST。有关更多信息，请参阅 HTTP 规范中的 Safe methods。

update_or_create()Link to this heading#

update_or_create(defaults=None, **kwargs)Link to this definition#

aupdate_or_create(defaults=None, **kwargs)Link to this definition#

异步版本: aupdate_or_create()

用给定的 kwargs 更新对象的一种方便方法，是必要时创建一个新对象。defaults 是用来更新对象的 (field, value) 对的字典。defaults 中的值可以是可调用对象。

返回 (object, created) 的元组，其中 object 是创建或更新的对象，created 是一个布尔值，指定是否创建了一个新对象。

update_or_create 方法根据给定的 kwargs 尝试从数据库中获取一个对象。如果找到了匹配的对象，它就会更新 defaults 字典中传递的字段。

这是作为一个快捷方式来处理样板代码。例如：

defaults = {"first_name": "Bob"}
try:
    obj = Person.objects.get(first_name="John", last_name="Lennon")
    for key, value in defaults.items():
        setattr(obj, key, value)
    obj.save()
except Person.DoesNotExist:
    new_values = {"first_name": "John", "last_name": "Lennon"}
    new_values.update(defaults)
    obj = Person(**new_values)
    obj.save()

当模型中的字段数量增加时，这种模式就会变得很笨重。上面的例子可以使用 update_or_create() 重写，就像这样：

obj, created = Person.objects.update_or_create(
    first_name="John",
    last_name="Lennon",
    defaults={"first_name": "Bob"},
)

关于如何解决在 kwargs 中传递名字的详细描述，见 get_or_create()。

如上文 get_or_create() 中所述，这种方法容易出现竞争条件，如果不在数据库层面强制执行唯一性，就会导致同时插入多条记录。

就像 get_or_create() 和 create() 一样，如果你使用的是手动指定的主键，需要创建一个对象，但该键已经存在于数据库中，就会引发 IntegrityError。

bulk_create()Link to this heading#

bulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)Link to this definition#

abulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)Link to this definition#

异步版本: abulk_create()

这个方法以高效的方式将提供的对象列表插入数据库中（通常只有 1 个查询，无论有多少对象），并以与提供的顺序相同的顺序返回已创建的对象列表：

>>> objs = Entry.objects.bulk_create(
...     [
...         Entry(headline="This is a test"),
...         Entry(headline="This is only a test"),
...     ]
... )

不过这有一些注意事项：

• 模型的 save() 方法将不会被调用，pre_save 和 post_save 信号将不会被发送。

• 在多表继承的情况下，它不能与子模型一起工作。

• 如果模型的主键是一个 AutoField，主键属性只能在某些数据库（目前是 PostgreSQL，MariaDB 10.5+，和 SQLite 3.35+）上检索到。在其他数据库中，它将不会被设置。

• 对于多对多的关系，它是行不通的。

• 它将 objs 转换为一个列表，如果 objs 是一个生成器，则完全执行 objs。这种转换允许检查所有对象，因此任何具有手动设置主键的对象都可以首先插入。如果你想分批插入对象，而不一次性执行整个生成器，你可以使用这种技术，只要对象没有任何手动设置的主键：

  Code

  from itertools import islice
  
  batch_size = 100
  objs = (Entry(headline="Test %s" % i) for i in range(1000))
  while True:
      batch = list(islice(objs, batch_size))
      if not batch:
          break
      Entry.objects.bulk_create(batch, batch_size)
  

batch_size 参数控制在一次查询中创建多少对象。默认情况是在一个批次中创建所有对象，但 SQLite 除外，默认情况是每个查询最多使用 999 个变量。

在支持的数据库上（除了 Oracle），将 ignore_conflicts 参数设置为 True 告诉数据库忽略插入失败的行，例如违反唯一值约束的行。

在支持的数据库上（除了 Oracle 和 SQLite < 3.24），将 update_conflicts 参数设置为 True，告诉数据库在发生冲突时更新 update_fields。在 PostgreSQL 和 SQLite 上，除了 update_fields，还必须提供可能发生冲突的 unique_fields 列表。

启用 ignore_conflicts 或 update_conflicts 参数会禁用在每个模型实例上设置主键（如果数据库通常支持的话）。

bulk_update()Link to this heading#

bulk_update(objs, fields, batch_size=None)Link to this definition#

abulk_update(objs, fields, batch_size=None)Link to this definition#

异步版本: abulk_update()

这个方法高效地更新提供的模型实例上的给定字段，通常只需一个查询，并返回更新的对象数量：

>>> objs = [
...     Entry.objects.create(headline="Entry 1"),
...     Entry.objects.create(headline="Entry 2"),
... ]
>>> objs[0].headline = "This is entry 1"
>>> objs[1].headline = "This is entry 2"
>>> Entry.objects.bulk_update(objs, ["headline"])
2

QuerySet.update() 用于保存更改，所以这比遍历模型列表并对每个模型调用 save() 更有效，但它有一些注意事项：

• 你不能更新模型的主键。

• 每个模型的 save() 方法没有被调用，而且 pre_save 和 post_save 信号没有被发送。

• 如果更新大量行中的大量列，生成的 SQL 可能非常大。通过指定一个合适的 batch_size 来避免这种情况。

• 更新定义在多表继承祖先上的字段将给每个祖先带来额外的查询。

• 当一个单独的批次包含重复的内容时，只有该批次的第一个实例会导致更新。

• 该函数返回的更新对象的数量可能少于传入的对象的数量。这可能是由于传入的对象重复，在同一批次中被更新，或者是竞赛条件，如对象在数据库中不再存在。

batch_size 参数控制一次查询中保存多少对象。默认值是在一个批次中更新所有对象，但 SQLite 和 Oracle 除外，它们对查询中使用的变量数量有限制。

count()Link to this heading#

count()Link to this definition#

acount()Link to this definition#

异步版本: acount()

返回一个整数，表示数据库中与 QuerySet 匹配的对象数量。

举例：

# Returns the total number of entries in the database.
Entry.objects.count()

# Returns the number of entries whose headline contains 'Lennon'
Entry.objects.filter(headline__contains="Lennon").count()

count() 调用在幕后执行 SELECT COUNT(*)，所以你应该总是使用 count() 而不是将所有的记录加载到 Python 对象中，然后在结果上调用 len() （除非你需要将对象加载到内存中，在这种情况下 len() 会更快）。

请注意，如果你想知道 QuerySet 中的项数，并且也要从它中检索模型实例（例如，通过迭代它），那么使用 len(queryset) 可能更有效，因为它不会像 count() 那样引起额外的数据库查询。

如果查询集已经被完全检索到，count() 将使用该长度，而不是执行额外的数据库查询。

in_bulk()Link to this heading#

in_bulk(id_list=None, *, field_name='pk')Link to this definition#

ain_bulk(id_list=None, *, field_name='pk')Link to this definition#

异步版本: ain_bulk()

接收一个字段值的列表（id_list）和这些值的 field_name，并返回一个字典，将每个值映射到具有给定字段值的对象实例。in_bulk 不会引发任何 django.core.exceptions.ObjectDoesNotExist 异常；也就是说，任何不匹配任何实例的 id_list 值将被简单地忽略掉。如果没有提供 id_list，将返回查询集的所有对象。field_name 必须是一个唯一字段或一个独立的字段（如果只有一个字段在 distinct() 中指定）。field_name 默认为主键。

例如：

>>> Blog.objects.in_bulk([1])
{1: <Blog: Beatles Blog>}
>>> Blog.objects.in_bulk([1, 2])
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}
>>> Blog.objects.in_bulk([])
{}
>>> Blog.objects.in_bulk()
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>, 3: <Blog: Django Weblog>}
>>> Blog.objects.in_bulk(["beatles_blog"], field_name="slug")
{'beatles_blog': <Blog: Beatles Blog>}
>>> Blog.objects.distinct("name").in_bulk(field_name="name")
{'Beatles Blog': <Blog: Beatles Blog>, 'Cheddar Talk': <Blog: Cheddar Talk>, 'Django Weblog': <Blog: Django Weblog>}

如果你传递 in_bulk() 一个空列表，你将得到一个空字典。

iterator()Link to this heading#

iterator(chunk_size=None)Link to this definition#

aiterator(chunk_size=None)Link to this definition#

异步版本: aiterator()

评估 QuerySet （通过执行查询）并返回结果的迭代器，如果调用其异步版本 aiterator，则返回异步迭代器。

通常，QuerySet 会在内部缓存其结果，以便重复评估不会导致额外的查询。相比之下，iterator() 将直接读取结果，而不会在 QuerySet 级别进行任何缓存（在内部，默认迭代器调用 iterator() 并缓存返回值）。对于返回大量对象且您只需访问一次的 QuerySet，这可以提高性能并显著减少内存使用。

请注意，在已经被执行的 QuerySet 上使用 iterator() 会迫使它再次执行，重复查询。

iterator() 与之前对 prefetch_related() 的调用兼容，只要提供了 chunk_size。较大的值将需要更少的查询来完成预取操作，但代价是更多的内存使用。

在某些数据库（例如 Oracle，SQLite）中，SQL 中的 IN 子句中的最大项数可能会受到限制。因此，应使用低于此限制的值。特别是在跨两个或多个关系进行预取的情况下，chunk_size 应该足够小，以便每个预取关系的预期结果数量仍然保持在限制以下。

只要 QuerySet 不预取任何相关对象，不为 chunk_size 提供值，Django 将使用默认的隐式值 2000。

根据数据库后端，查询结果将被一次性加载或使用服务器端的游标从数据库中流转。

latest()Link to this heading#

latest(*fields)Link to this definition#

alatest(*fields)Link to this definition#

异步版本: alatest()

根据给定的字段，返回表中最新的对象。

这个例子根据 pub_date 字段返回表中最新的 Entry：

Entry.objects.latest("pub_date")

你也可以根据几个字段选择最新的。例如，当两个条目具有相同的 pub_date 时，要选择最早的 expire_date 条目：

Entry.objects.latest("pub_date", "-expire_date")

'-expire_date' 中的负号表示按 降 序排列 expire_date。由于 latest() 得到的是最后一个结果，所以选择了最早的 expire_date 的 Entry。

如果你模型的 Meta 指定了 get_latest_by，你可以省略 earliest() 或 latest() 的任何参数。get_latest_by 中指定的字段将被默认使用。

像 get()、earliest() 和 latest()，如果没有给定参数的对象，就会引发 DoesNotExist。

请注意，earliest() 和 latest() 的存在纯粹是为了方便和可读性。

earliest()Link to this heading#

earliest(*fields)Link to this definition#

aearliest(*fields)Link to this definition#

异步版本: aearliest()

除了方向改变外，其他工作方式都像 last()。

first()Link to this heading#

first()Link to this definition#

afirst()Link to this definition#

异步版本: afirst()

返回查询集匹配的第一个对象，如果没有匹配的对象，则返回 None。如果 QuerySet 没有定义排序，那么查询集自动按主键排序。这可能会影响聚合结果，如 Interaction with order_by() 中所述。

举例：

p = Article.objects.order_by("title", "pub_date").first()

请注意，first() 是一个方便的方法，下面的代码示例相当于上面的例子：

try:
    p = Article.objects.order_by("title", "pub_date")[0]
except IndexError:
    p = None

last()Link to this heading#

last()Link to this definition#

alast()Link to this definition#

异步版本: alast()

与 first() 工作原理相同，但返回的是查询集中的最后一个对象。

aggregate()Link to this heading#

aggregate(*args, **kwargs)Link to this definition#

aaggregate(*args, **kwargs)Link to this definition#

异步版本: aaggregate()

返回对 QuerySet 计算的聚合值（平均值、总和等）的字典。aggregate() 的每个参数都指定了一个将被包含在返回的字典中的值。

Django 提供的聚合函数在下面的 Aggregation Functions 中介绍。由于聚合函数也是 查询表达式，所以你可以将聚合函数与其他聚合函数或值结合起来，创建复杂的聚合函数。

使用关键字参数指定的聚合将使用关键字作为注解的名称。匿名参数将根据聚合函数的名称和被聚合的模型字段为其生成一个名称。复杂的聚合不能使用匿名参数，必须指定一个关键字参数作为别名。

例如，当你处理博客条目时，你可能想要知道有多少位作者贡献了博客条目：

>>> from django.db.models import Count
>>> Blog.objects.aggregate(Count("entry"))
{'entry__count': 16}

通过使用关键字参数来指定聚合函数，你可以控制返回的聚合值的名称：

>>> Blog.objects.aggregate(number_of_entries=Count("entry"))
{'number_of_entries': 16}

关于聚合的深入讨论，见 关于聚合的专题指南。

exists()Link to this heading#

exists()Link to this definition#

aexists()Link to this definition#

异步版本: aexists()

如果 QuerySet 包含任何结果，则返回 True，如果不包含，则返回 False。该函数试图以最简单、最快速的方式执行查询，但它 执行 的查询与普通的 QuerySet 查询几乎相同。

existence() 对于与 QuerySet 中任何对象的存在有关的搜索很有用，特别是在一个大的 QuerySet 的背景下。

要查找一个查询集是否包含任何项目：

if some_queryset.exists():
    print("There is at least one object in some_queryset")

这种方法比下面的方法更快：

if some_queryset:
    print("There is at least one object in some_queryset")

...但程度不高（因此需要大量的查询集才能获得效率提升）。

此外，如果一个 some_queryset 还没有被执行，但你知道它会在某个时候被执行，那么使用 some_queryset.exences() 比使用 bool(some_queryset) 会做更多的总体工作（一个存在性检查的查询加上一个额外的查询，以便以后检索结果），后者检索结果，然后检查是否有任何返回。

contains()Link to this heading#

contains(obj)Link to this definition#

acontains(obj)Link to this definition#

异步版本: acontains()

如果 QuerySet 包含 obj，返回 True，如果不包含 False。这试图以最简单和最快的方式执行查询。

contains() 对于检查一个对象在 QuerySet 中的成员资格很有用，特别是在一个大的 QuerySet 的情况下。

要检查一个查询集是否包含一个特定的项目：

if some_queryset.contains(obj):
    print("Entry contained in queryset")

这将比以下需要执行和迭代整个查询集的方法更快：

if obj in some_queryset:
    print("Entry contained in queryset")

像 exists() 一样，如果 some_queryset 还没有被执行，但你知道它将在某个时候被执行，那么使用 some_queryset.contains(obj) 将进行额外的数据库查询，通常会导致整体性能变慢。

update()Link to this heading#

update(**kwargs)Link to this definition#

aupdate(**kwargs)Link to this definition#

异步版本: aupdate()

对指定的字段执行 SQL 更新查询，并返回匹配的行数（如果有些行已经有了新的值，则可能不等于更新的行数）。

例如，要关闭所有在 2010 年发布的博客条目的评论，你可以这样做：

>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)

（假定你的 Entry 模型有 pub_date 和 comments_on。）

你可以更新多个字段，没有限制。例如，这里我们更新了 comments_on 和 headline 字段：

>>> Entry.objects.filter(pub_date__year=2010).update(
...     comments_on=False, headline="This is old"
... )

update() 方法会立即应用，并且被更新的 QuerySet 的唯一限制是它只能更新模型主表中的列，不能更新相关模型上的列。例如，你不能这样做：

>>> Entry.objects.update(blog__name="foo")  # Won't work!

基于相关字段的过滤仍然是可能的：

>>> Entry.objects.filter(blog__id=1).update(comments_on=True)

你不能在一个 QuerySet 上调用 update()，因为它已经被取走了一个片断或者不能再被过滤。

update() 方法返回受影响的行数：

>>> Entry.objects.filter(id=64).update(comments_on=True)
1

>>> Entry.objects.filter(slug="nonexistent-slug").update(comments_on=True)
0

>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)
132

如果你只是更新一条记录，不需要对模型对象做任何事情，最有效的方法是调用 update()，而不是将模型对象加载到内存中。例如，不要这样做：

e = Entry.objects.get(id=10)
e.comments_on = False
e.save()