filter()¶

filter(*args, **kwargs)¶

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

查找参数（**kwargs）应采用下面字段查找中描述的格式。多个参数在底层 SQL 语句中通过 AND 连接。

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

exclude()¶

exclude(*args, **kwargs)¶

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

查找参数（**kwargs）应采用下面字段查找中描述的格式。多个参数在底层 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()¶

annotate(*args, **kwargs)¶

使用提供的 查询表达式 列表为 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()¶

alias(*args, **kwargs)¶

与 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()¶

order_by(*fields)¶

默认情况下，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()或desc()来按查询表达式排序

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

asc()和desc()具有参数（nulls_first和nulls_last），这些参数控制如何对空值进行排序。

如果您还使用distinct()，请在对相关模型中的字段排序时谨慎操作。有关相关模型排序如何更改预期结果的说明，请参阅distinct()中的注释。

class Event(Model):
    parent = models.ForeignKey(
        "self",
        on_delete=models.CASCADE,
        related_name="children",
    )
    date = models.DateField()


Event.objects.order_by("children__date")

无法指定排序是否应区分大小写。关于区分大小写，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()¶

reverse()¶

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

要检索查询集中“最后”五个项目，您可以执行以下操作

my_queryset.reverse()[:5]

请注意，这与在 Python 中从序列末尾切片并不完全相同。上面的示例将首先返回最后一个项目，然后是倒数第二个项目，依此类推。如果我们有一个 Python 序列并查看seq[-5:]，我们将看到倒数第五个项目首先出现。Django 不支持这种访问模式（从末尾切片），因为在 SQL 中无法有效地执行此操作。

此外，请注意，reverse()通常应该只在具有已定义排序的QuerySet上调用（例如，当针对定义默认排序的模型查询时，或当使用order_by()时）。如果未为给定的QuerySet定义此类排序，则在其上调用reverse()实际上没有任何效果（在调用reverse()之前排序未定义，之后也将保持未定义）。

distinct()¶

distinct(*fields)¶

返回一个新的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")
[...]

Entry.objects.order_by("blog").distinct("blog")

values()¶

values(*fields, **expressions)¶

返回一个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，你将获得相同的结果（字典键将与你传入的字段名称匹配）。

  例如

  >>> 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()，因此以下示例是等效的

  >>> 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()¶

values_list(*fields, flat=False, named=False)¶

这类似于 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，则表示返回的结果是单个值，而不是 1 元组。一个例子应该能让区别更清楚

>>> 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()¶

dates(field, kind, order='ASC')¶

返回一个 QuerySet，该 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()¶

datetimes(field_name, kind, order='ASC', tzinfo=None)¶

返回一个 QuerySet，该 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 使用 当前时区。当 USE_TZ 为 False 时，它没有效果。

none()¶

none()¶

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

示例

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

all()¶

all()¶

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

当一个QuerySet被评估时，它通常会缓存其结果。如果数据库中的数据可能在QuerySet被评估后发生了更改，可以通过在之前已评估的QuerySet上调用all()来获取相同查询的更新结果。

union()¶

union(*other_qs, all=False)¶

使用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()¶

intersection(*other_qs)¶

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

>>> qs1.intersection(qs2, qs3)

请参阅union()以了解一些限制。

difference()¶

difference(*other_qs)¶

使用SQL的EXCEPT操作符仅保留存在于QuerySet中但不存在于某些其他QuerySet中的元素。例如

>>> qs1.difference(qs2, qs3)

请参阅union()以了解一些限制。

select_related()¶

select_related(*fields)¶

返回一个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

您可以对任何对象的QuerySet使用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()。这将跟随它能找到的所有非空外键——必须指定可为空的外键。在大多数情况下不建议这样做，因为它可能会使底层查询变得更加复杂，并返回比实际需要的更多数据。

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

>>> without_relations = queryset.select_related(None)

链式调用select_related的方式类似于其他方法——也就是说select_related('foo', 'bar')等效于select_related('foo').select_related('bar')。

prefetch_related()¶

prefetch_related(*lookups)¶

返回一个QuerySet，它将自动批量检索每个指定查找的相关对象。

这与select_related的目的类似，因为两者都旨在阻止访问相关对象时产生的数据库查询泛滥，但策略却大不相同。

select_related通过创建SQL连接并将相关对象的字段包含在SELECT语句中来工作。因此，select_related在同一个数据库查询中获取相关对象。但是，为了避免因跨“多对多”关系联接而产生的更大结果集，select_related仅限于单值关系——外键和一对一关系。

prefetch_related 另一方面，会为每个关联关系执行单独的查询，并在 Python 中进行“连接”。这使得它能够预取多对多、多对一以及 GenericRelation 对象，而这些对象无法使用 select_related 进行预取。此外，它还支持 select_related 支持的外键和一对一关系。它还支持 GenericForeignKey 的预取，但是，每个 ContentType 的 QuerySet 必须在 GenericPrefetch 的 querysets 参数中提供。

例如，假设您有以下模型

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() 将对 Pizza QuerySet 中的**每个**项目在 Toppings 表上运行查询。

我们可以使用 prefetch_related 将查询减少到仅两个。

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

这意味着每个 Pizza 都执行一次 self.toppings.all()；现在，每次调用 self.toppings.all() 时，它不必访问数据库获取项目，而是在单个查询中填充的预取 QuerySet 缓存中查找它们。

也就是说，所有相关的配料都将在单个查询中获取，并用于创建具有预填充相关结果缓存的 QuerySets；然后在 self.toppings.all() 调用中使用这些 QuerySets。

prefetch_related() 中的额外查询是在 QuerySet 开始评估并且主查询已执行后执行的。

请注意，没有机制可以阻止另一个数据库查询在主查询和额外查询执行之间更改项目，这可能会导致不一致的结果。例如，如果在执行主查询后删除了一个 Pizza，则其配料将不会在额外查询中返回，并且看起来披萨没有配料。

>>> Pizza.objects.prefetch_related("toppings")
#  "Hawaiian" Pizza was deleted in another shell.
<QuerySet [<Pizza: Hawaiian ()>, <Pizza: Seafood (prawns, smoked salmon)>]>

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

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

>>> pizzas = Pizza.objects.prefetch_related("toppings")
>>> [list(pizza.toppings.filter(spicy=True)) for pizza in pizzas]

您还可以使用常规的连接语法来执行关联字段的相关字段。假设我们在上面的示例中添加了一个额外的模型

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 查询时）。始终为您的用例进行性能分析！

如果您使用 iterator() 运行查询，则只有在提供 chunk_size 值时才会观察到 prefetch_related() 调用。

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

在最简单的形式中，Prefetch 等效于传统的基于字符串的查找

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

您可以使用可选的 queryset 参数提供自定义 QuerySet。这可用于更改 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，它对相关模型执行进一步的预取。

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

• 您希望使用性能优化技术，例如 deferred fields

  >>> 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")

>>> prefetch_related("pizzas__toppings", "pizzas")

>>> prefetch_related("pizzas__toppings", Prefetch("pizzas", queryset=Pizza.objects.all()))

>>> prefetch_related("pizza_list__toppings", Prefetch("pizzas", to_attr="pizza_list"))

extra()¶

extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)¶

有时，Django 查询语法本身无法轻松表达复杂的 WHERE 子句。对于这些极端情况，Django 提供了 extra() QuerySet 修饰符——一个用于将特定子句注入 QuerySet 生成的 SQL 的钩子。

>>> qs.extra(
...     select={"val": "select col from sometable where othercol = %s"},
...     select_params=(someparam,),
... )

>>> qs.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,)))

SELECT col FROM sometable WHERE othercol = '%s'  # unsafe!

根据定义，这些额外的查找可能无法移植到不同的数据库引擎（因为您正在显式编写 SQL 代码）并且违反了 DRY 原则，因此您应尽可能避免它们。

指定 params、select、where 或 tables 中的一个或多个。没有参数是必需的，但您应该至少使用其中一个。

• select

  select 参数允许您在 SELECT 子句中添加额外的字段。它应该是一个字典，将属性名称映射到用于计算该属性的 SQL 子句。

  示例

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

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

  Django 将给定的 SQL 代码片段直接插入到 SELECT 语句中，因此上述示例的结果 SQL 将类似于

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

  下一个示例更高级；它执行一个子查询，为每个结果 Blog 对象提供一个 entry_count 属性，一个关联的 Entry 对象的整数计数

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

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

  上述示例的结果 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 子句中不是必需的。

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

  例如，这将起作用

  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”运算。

  示例

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

  …（大致）转换为以下 SQL

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

  如果要指定查询中已使用的表，则在使用 tables 参数时要小心。当您通过 tables 参数添加额外表时，Django 假设您希望该表额外包含一次，如果它已经包含在内。这会产生问题，因为表名随后将被赋予别名。如果表在 SQL 语句中出现多次，则第二个及后续出现必须使用别名，以便数据库能够区分它们。如果您在额外的 where 参数中引用添加的额外表，这将导致错误。

  通常，您只会添加查询中尚未出现的额外表。但是，如果出现上述情况，则有一些解决方法。首先，查看是否可以在不包含额外表的情况下继续并使用查询中已有的表。如果这不可行，请将您的 extra() 调用放在查询集构造的前面，以便您的表成为该表的首次使用。最后，如果所有其他方法都失败，请查看生成的查询并重写您的 where 添加以使用赋予额外表的别名。每次以相同方式构造查询集时，别名都将相同，因此您可以依靠别名不会更改。

• order_by

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

  例如

  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 参数是任何要替换的额外参数的列表。

  示例

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

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

  错误示例

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

  正确示例

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

defer()¶

defer(*fields)¶

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

这是通过将不需要加载的字段名称传递给 defer() 来完成的。

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

具有延迟字段的 QuerySet 仍然会返回模型实例。如果你访问某个延迟字段，它将从数据库中检索（一次一个，而不是一次检索所有延迟字段）。

你可以多次调用 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() 的结果）是没有意义的：这样做会导致异常。聚合值将始终被获取到结果 QuerySet 中。

class CommonlyUsedModel(models.Model):
    f1 = models.CharField(max_length=10)

    class Meta:
        managed = False
        db_table = "app_largetable"


class ManagedModel(models.Model):
    f1 = models.CharField(max_length=10)
    f2 = models.CharField(max_length=10)

    class Meta:
        db_table = "app_largetable"


# Two equivalent QuerySets:
CommonlyUsedModel.objects.all()
ManagedModel.objects.defer("f2")

only()¶

only(*fields)¶

only() 方法本质上与 defer() 相反。当评估 QuerySet 时，只有传递给此方法且尚未指定为延迟的字段会被立即加载。

如果你有一个模型，其中几乎所有字段都需要延迟加载，则使用 only() 指定互补的字段集可以使代码更简单。

假设你有一个具有字段 name、age 和 biography 的模型。以下两个 QuerySet 在延迟字段方面是相同的。

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()¶

using(alias)¶

如果您使用多个数据库，则此方法用于控制 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()¶

select_for_update(nowait=False, skip_locked=False, of=(), no_key=False)¶

返回一个查询集，该查询集将锁定行直到事务结束，在支持的数据库上生成 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' 来引用查询集的模型。

Restaurant.objects.select_for_update(of=("self", "place_ptr"))

仅在 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 支持 nowait、skip_locked 和 of 参数。no_key 参数仅在 PostgreSQL 上受支持。

使用不支持这些选项的数据库后端（例如 MySQL）将 nowait=True、skip_locked=True、no_key=True 或 of 传递给 select_for_update() 将引发 NotSupportedError。这可以防止代码意外阻塞。

在自动提交模式下评估使用 select_for_update() 的查询集，在支持 SELECT ... FOR UPDATE 的后端上是一个 TransactionManagementError 错误，因为在这种情况下行不会被锁定。如果允许，这将导致数据损坏，并且很容易由在事务之外期望在事务中运行的调用代码引起。

在不支持 SELECT ... FOR UPDATE 的后端（如 SQLite）上使用 select_for_update() 将不起作用。SELECT ... FOR UPDATE 不会添加到查询中，并且如果在自动提交模式下使用 select_for_update()，则不会引发错误。

raw()¶

raw(raw_query, params=(), translations=None, using=None)¶

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

请参阅执行原始 SQL 查询以获取更多信息。

AND (&)¶

使用 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 (|)¶

使用 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 (^)¶

使用 SQL XOR 运算符组合两个 QuerySet。 XOR 表达式匹配由奇数个操作数匹配的行。

以下等效

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

(x OR y OR ... OR z) AND
1=MOD(
    (CASE WHEN x THEN 1 ELSE 0 END) +
    (CASE WHEN y THEN 1 ELSE 0 END) +
    ...
    (CASE WHEN z THEN 1 ELSE 0 END),
    2
)

get()¶

get(*args, **kwargs)¶

aget(*args, **kwargs)¶

异步版本：aget()

返回与给定查找参数匹配的对象，这些参数应采用字段查找中描述的格式。你应该使用保证唯一的查找，例如主键或唯一约束中的字段。例如

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

如果你期望 QuerySet 已经返回一行，则可以使用不带任何参数的 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()¶

create(**kwargs)¶

acreate(**kwargs)¶

异步版本：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()¶

get_or_create(defaults=None, **kwargs)¶

aget_or_create(defaults=None, **kwargs)¶

异步版本：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 存在，则检索它们，否则创建后者

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"})

当您使用手动指定的 primary key 时，get_or_create() 方法具有与 create() 类似的错误行为。如果需要创建对象且键已存在于数据库中，则会引发 IntegrityError。

最后，关于在 Django 视图中使用 get_or_create() 的说明。请确保仅在 POST 请求中使用它，除非您有充分的理由不这样做。 GET 请求不应对数据有任何影响。相反，在请求到页面的操作会对您的数据产生副作用时，请使用 POST。更多信息，请参阅 HTTP 规范中的 安全方法。

class Chapter(models.Model):
    title = models.CharField(max_length=255, unique=True)


class Book(models.Model):
    title = models.CharField(max_length=256)
    chapters = models.ManyToManyField(Chapter)

>>> book = Book.objects.create(title="Ulysses")
>>> book.chapters.get_or_create(title="Telemachus")
(<Chapter: Telemachus>, True)
>>> book.chapters.get_or_create(title="Telemachus")
(<Chapter: Telemachus>, False)
>>> Chapter.objects.create(title="Chapter 1")
<Chapter: Chapter 1>
>>> book.chapters.get_or_create(title="Chapter 1")
# Raises IntegrityError

update_or_create()¶

update_or_create(defaults=None, create_defaults=None, **kwargs)¶

aupdate_or_create(defaults=None, create_defaults=None, **kwargs)¶

异步版本: aupdate_or_create()

一个方便的方法，用于使用给定的 kwargs 更新对象，如果必要则创建一个新对象。 create_defaults 和 defaults 都是 (field, value) 对的字典。 create_defaults 和 defaults 中的值都可以是可调用对象。 defaults 用于更新对象，而 create_defaults 用于创建操作。如果未提供 create_defaults，则 defaults 将用于创建操作。

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

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

这旨在作为样板代码的快捷方式。例如

defaults = {"first_name": "Bob"}
create_defaults = {"first_name": "Bob", "birthday": date(1940, 10, 9)}
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(create_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"},
    create_defaults={"first_name": "Bob", "birthday": date(1940, 10, 9)},
)

有关如何解析 kwargs 中传递的名称的详细说明，请参阅 get_or_create()。

如上文 get_or_create() 中所述，此方法容易出现竞争条件，如果未在数据库级别强制执行唯一性，则可能导致同时插入多行。

与 get_or_create() 和 create() 一样，如果您使用手动指定的 primary key 并且需要创建对象但键已存在于数据库中，则会引发 IntegrityError。

bulk_create()¶

bulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)¶

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