进行查询¶

保存 ForeignKey 和 ManyToManyField 字段¶

更新 ForeignKey 字段的方式与保存正常字段完全相同 - 只需将正确类型的对象分配给相关字段。此示例更新 Entry 实例 entry 的 blog 属性，假设 Entry 和 Blog 的适当实例已保存到数据库（因此我们可以在下面检索它们）:

>>> from blog.models import Entry
>>> entry = Entry.objects.get(pk=1)
>>> cheese_blog = Blog.objects.get(name="Cheddar Talk")
>>> entry.blog = cheese_blog
>>> entry.save()

更新 ManyToManyField 的工作方式略有不同 - 使用字段上的 add() 方法向关系中添加记录。此示例将 Author 实例 joe 添加到 entry 对象:

>>> from blog.models import Author
>>> joe = Author.objects.create(name="Joe")
>>> entry.authors.add(joe)

要一次将多个记录添加到 ManyToManyField，请在调用 add() 时包含多个参数，如下所示:

>>> john = Author.objects.create(name="John")
>>> paul = Author.objects.create(name="Paul")
>>> george = Author.objects.create(name="George")
>>> ringo = Author.objects.create(name="Ringo")
>>> entry.authors.add(john, paul, george, ringo)

Django会抱怨如果你试图分配或添加一个错误类型的对象。

检索所有对象¶

从表中检索对象的最简单的方法是获取所有对象。为此，在 Manager 上使用 all() 方法:

>>> all_entries = Entry.objects.all()

all() 方法返回数据库中所有对象的 QuerySet。

使用过滤器检索特定对象¶

all() 返回的 QuerySet 描述数据库表中的所有对象。通常，你需要只选择一组完整的对象的子集。

要创建此类子集，请细化初始 QuerySet，添加过滤条件。改进 QuerySet 的两种最常见的方法是：

filter(**kwargs)

返回包含与给定查找参数匹配的对象的新 QuerySet。

exclude(**kwargs)

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

查找参数（上述函数定义中的 **kwargs）应采用下面 Field lookups 中描述的格式。

例如，要从2006年获得 QuerySet 的博客条目，请使用 filter():

Entry.objects.filter(pub_date__year=2006)

使用默认管理器类，它是相同的:

Entry.objects.all().filter(pub_date__year=2006)

>>> Entry.objects.filter(
...     headline__startswith='What'
... ).exclude(
...     pub_date__gte=datetime.date.today()
... ).filter(
...     pub_date__gte=datetime(2005, 1, 30)
... )

>>> q1 = Entry.objects.filter(headline__startswith="What")
>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())
>>> q3 = q1.filter(pub_date__gte=datetime.date.today())

>>> q = Entry.objects.filter(headline__startswith="What")
>>> q = q.filter(pub_date__lte=datetime.date.today())
>>> q = q.exclude(body_text__icontains="food")
>>> print(q)

使用 get() 检索单个对象¶

filter() 将总是给你一个 QuerySet，即使只有一个对象匹配查询 - 在这种情况下，它将是一个 QuerySet 包含单个元素。

如果您知道只有一个对象与您的查询匹配，您可以在 Manager 上使用 get() 方法，该方法直接返回对象:

>>> one_entry = Entry.objects.get(pk=1)

您可以使用任何查询表达式与 get()，就像 filter() - 再次，请参阅下面的 Field lookups。

注意，在使用 get() 和使用具有 [0] 切片的 filter() 之间存在差异。如果没有匹配查询的结果，get() 将引发 DoesNotExist 异常。此异常是执行查询的模型类的属性 - 因此在上面的代码中，如果没有主键为1的 Entry 对象，Django将提升 Entry.DoesNotExist。

类似地，如果多个项目与 get() 查询匹配，Django将投诉。在这种情况下，它将提高 MultipleObjectsReturned，这也是模型类本身的一个属性。

其他 QuerySet 方法¶

大多数时候，当您需要从数据库中查找对象时，您将使用 all()，get()，filter() 和 exclude()。然而，这远不是所有的；请参阅 QuerySet API参考 获取所有各种 QuerySet 方法的完整列表。

限制 QuerySet¶

使用Python的数组切片语法的一个子集来限制您的 QuerySet 到一定数量的结果。这相当于SQL的 LIMIT 和 OFFSET 子句。

例如，这返回前5个对象（LIMIT 5）:

>>> Entry.objects.all()[:5]

这返回第六到第十个对象（OFFSET 5 LIMIT 5）:

>>> Entry.objects.all()[5:10]

不支持负索引（即 Entry.objects.all()[-1]）。

通常，切片 QuerySet 返回一个新的 QuerySet - 它不评估查询。一个例外是如果你使用Python的slice语法的“step”参数。例如，这将实际执行查询，以返回前10的每个 second 对象的列表:

>>> Entry.objects.all()[:10:2]

要检索 single 对象而不是列表（例如 SELECT foo FROM bar LIMIT 1），请使用简单的索引而不是切片。例如，在按标题字母顺序排序后，这将返回数据库中的第一个 Entry:

>>> Entry.objects.order_by('headline')[0]

这大致相当于:

>>> Entry.objects.order_by('headline')[0:1].get()

注意，但是，第一个将提高 IndexError，而第二个将提高 DoesNotExist，如果没有对象匹配给定的标准。有关详细信息，请参阅 get()。

字段查找¶

字段查找是如何指定SQL WHERE 子句的内容。它们被指定为 QuerySet 方法 filter()，exclude() 和 get() 的关键字参数。

基本查找关键字参数采用 field__lookuptype=value 的形式。 （这是一个双下划线）。例如:

>>> Entry.objects.filter(pub_date__lte='2006-01-01')

翻译（大致）到以下SQL：

SELECT * FROM blog_entry WHERE pub_date <= '2006-01-01';

在查找中指定的字段必须是模型字段的名称。有一个例外，但是在 ForeignKey 的情况下，您可以指定字段名称后缀为 _id。在这种情况下，value参数应包含外部模型主键的原始值。例如：

>>> Entry.objects.filter(blog_id=4)

如果传递一个无效的关键字参数，查找函数将引发 TypeError。

数据库API支持大约二十种查找类型；一个完整的参考可以在 字段查找引用 中找到。为了让您了解可用的功能，以下是您可能会使用的一些常见查找：

exact

“完全匹配”。例如:

>>> Entry.objects.get(headline__exact="Cat bites dog")

将按照以下行生成SQL：

SELECT ... WHERE headline = 'Cat bites dog';

如果不提供查找类型 - 即，如果关键字参数不包含双下划线，则查找类型假定为 exact。

例如，以下两个语句是等效的:

>>> Blog.objects.get(id__exact=14)  # Explicit form
>>> Blog.objects.get(id=14)         # __exact is implied

这是为了方便，因为 exact 查找是常见的情况。

iexact

不区分大小写的匹配。所以，查询:

>>> Blog.objects.get(name__iexact="beatles blog")

将匹配 Blog 标题为 "Beatles Blog"，"beatles blog"，甚至 "BeAtlES blOG"。

contains

区分敏感遏制试验。例如:

Entry.objects.get(headline__contains='Lennon')

大致翻译成这个SQL：

SELECT ... WHERE headline LIKE '%Lennon%';

注意这将匹配标题 'Today Lennon honored'，但不是 'today lennon honored'。

还有一个不区分大小写的版本，icontains。

startswith，endswith

开始和结束 - 分别与搜索。还有称为 istartswith 和 iendswith 的不区分大小写的版本。

同样，这只是划伤表面。完整的参考可以在 字段查找引用 中找到。

查找跨关系¶

Django提供了一种强大而直观的方式来“跟踪”查找中的关系，在后台自动处理SQL JOIN s。要跨越关系，只需使用模型之间的相关字段的字段名称（用双下划线分隔），直到找到所需的字段。

此示例检索具有其 name 为 'Beatles Blog' 的 Blog 的所有 Entry 对象:

>>> Entry.objects.filter(blog__name='Beatles Blog')

这个跨度可以像你想要的一样深。

它也向后工作。要引用“反向”关系，只需使用模型的小写名称。

此示例检索具有至少一个其 headline 包含 'Lennon' 的 Entry 的所有 Blog 对象:

>>> Blog.objects.filter(entry__headline__contains='Lennon')

如果您跨多个关系进行过滤，并且其中一个中间模型没有满足过滤条件的值，Django会将其视为空（所有值都是 NULL），但有效，对象。所有这些意味着不会产生错误。例如，在此过滤器中:

Blog.objects.filter(entry__authors__name='Lennon')

（如果存在相关的 Author 模型），如果没有与条目相关联的 author，则将其视为没有附加 name，而不是由于缺少 author 而引起错误。通常这正是你想要发生的。唯一可能会混淆的情况是，如果你使用 isnull。从而:

Blog.objects.filter(entry__authors__name__isnull=True)

将返回在 author 上具有空 name 的 Blog 对象，以及在 entry 上具有空 author 的那些对象。如果你不想要那些后面的对象，你可以写:

Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True)

Blog.objects.filter(entry__headline__contains='Lennon', entry__pub_date__year=2008)

Blog.objects.filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008)

Blog.objects.exclude(
    entry__headline__contains='Lennon',
    entry__pub_date__year=2008,
)

Blog.objects.exclude(
    entry__in=Entry.objects.filter(
        headline__contains='Lennon',
        pub_date__year=2008,
    ),
)

过滤器可以引用模型上的字段¶

在迄今为止给出的例子中，我们构造了将模型字段的值与常数进行比较的过滤器。但是，如果你想比较模型字段的值与同一模型上的另一个字段怎么办？

Django提供 F expressions 允许这样的比较。 F() 的实例充当对查询中的模型字段的引用。然后，可以在查询过滤器中使用这些引用来比较同一模型实例上的两个不同字段的值。

例如，要找到所有博客条目的列表，其中有比pingback更多的评论，我们构造一个 F() 对象来引用pingback计数，并在查询中使用该 F() 对象:

>>> from django.db.models import F
>>> Entry.objects.filter(n_comments__gt=F('n_pingbacks'))

Django支持对 F() 对象使用加法，减法，乘法，除法，模数和幂运算，这两个对象都具有常量和其他 F() 对象。为了找到所有的博客条目具有多于 twice 的许多评论作为pingbacks，我们修改查询:

>>> Entry.objects.filter(n_comments__gt=F('n_pingbacks') * 2)

要查找条目的评分小于pingback计数和注释计数的总和的所有条目，我们将发出查询:

>>> Entry.objects.filter(rating__lt=F('n_comments') + F('n_pingbacks'))

您还可以使用双下划线符号来跨越 F() 对象中的关系。具有双下划线的 F() 对象将引入访问相关对象所需的任何连接。例如，要检索作者的名称与博客名称相同的所有条目，我们可以发出查询:

>>> Entry.objects.filter(authors__name=F('blog__name'))

对于日期和日期/时间字段，可以添加或减去 timedelta 对象。以下内容将返回在发布之后超过3天进行了修改的所有条目:

>>> from datetime import timedelta
>>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3))

F() 对象支持例如 .bitand() 和 .bitor() 的按位操作:

>>> F('somefield').bitand(16)

pk 查找快捷方式¶

为了方便起见，Django提供了一个 pk 查找快捷方式，代表“主键”。

在示例 Blog 模型中，主键是 id 字段，因此这三个语句是等效的:

>>> Blog.objects.get(id__exact=14) # Explicit form
>>> Blog.objects.get(id=14) # __exact is implied
>>> Blog.objects.get(pk=14) # pk implies id__exact

pk 的使用不限于 __exact 查询 - 任何查询项都可以与 pk 组合以对模型的主键执行查询:

# Get blogs entries with id 1, 4 and 7
>>> Blog.objects.filter(pk__in=[1,4,7])

# Get all blog entries with id > 14
>>> Blog.objects.filter(pk__gt=14)

pk 查找也在连接之间工作。例如，这三个语句是等效的:

>>> Entry.objects.filter(blog__id__exact=3) # Explicit form
>>> Entry.objects.filter(blog__id=3)        # __exact is implied
>>> Entry.objects.filter(blog__pk=3)        # __pk implies __id__exact

在 LIKE 声明中转义百分号和下划线¶

字段查找等同于 LIKE SQL语句（iexact，contains，icontains，startswith，istartswith，endswith 和 iendswith）将自动转义 LIKE 语句中使用的两个特殊字符 - 百分号和下划线。 （在 LIKE 语句中，百分号表示多字符通配符，下划线表示单字符通配符。）

这意味着事情应该直观，所以抽象不泄漏。例如，要检索包含百分号的所有条目，只需使用百分号作为任何其他字符:

>>> Entry.objects.filter(headline__contains='%')

Django照顾你的报价；结果SQL将看起来像这样：

SELECT ... WHERE headline LIKE '%\%%';

下划线也一样。百分号和下划线都是透明地处理的。

缓存和 QuerySet¶

每个 QuerySet 包含一个缓存以最小化数据库访问。了解其工作原理将允许您编写最有效的代码。

在新创建的 QuerySet 中，高速缓存为空。第一次评估 QuerySet，因此，发生数据库查询 - Django将查询结果保存在 QuerySet 的缓存中，并返回已明确请求的结果（例如，如果正在重复 QuerySet，则返回下一个元素过度）。随后对 QuerySet 的评估重用缓存的结果。

保持这种缓存行为，因为它可能会咬你，如果你不正确使用您的 QuerySet 。例如，以下将创建两个 QuerySet s，评估它们，并将它们丢弃:

>>> print([e.headline for e in Entry.objects.all()])
>>> print([e.pub_date for e in Entry.objects.all()])

这意味着相同的数据库查询将执行两次，有效地将您的数据库负载加倍。另外，两个列表可能不包括相同的数据库记录，因为 Entry 可能已经在两个请求之间的分割秒中被添加或删除。

为了避免这个问题，只需保存 QuerySet 并重用它:

>>> queryset = Entry.objects.all()
>>> print([p.headline for p in queryset]) # Evaluate the query set.
>>> print([p.pub_date for p in queryset]) # Re-use the cache from the evaluation.

>>> queryset = Entry.objects.all()
>>> print(queryset[5]) # Queries the database
>>> print(queryset[5]) # Queries the database again

>>> queryset = Entry.objects.all()
>>> [entry for entry in queryset] # Queries the database
>>> print(queryset[5]) # Uses cache
>>> print(queryset[5]) # Uses cache

>>> [entry for entry in queryset]
>>> bool(queryset)
>>> entry in queryset
>>> list(queryset)

一对多关系¶

>>> e = Entry.objects.get(id=2)
>>> e.blog # Returns the related Blog object.

>>> e = Entry.objects.get(id=2)
>>> e.blog = some_blog
>>> e.save()

>>> e = Entry.objects.get(id=2)
>>> e.blog = None
>>> e.save() # "UPDATE blog_entry SET blog_id = NULL ...;"

>>> e = Entry.objects.get(id=2)
>>> print(e.blog)  # Hits the database to retrieve the associated Blog.
>>> print(e.blog)  # Doesn't hit the database; uses cached version.

>>> e = Entry.objects.select_related().get(id=2)
>>> print(e.blog)  # Doesn't hit the database; uses cached version.
>>> print(e.blog)  # Doesn't hit the database; uses cached version.

>>> b = Blog.objects.get(id=1)
>>> b.entry_set.all() # Returns all Entry objects related to Blog.

# b.entry_set is a Manager that returns QuerySets.
>>> b.entry_set.filter(headline__contains='Lennon')
>>> b.entry_set.count()

>>> b = Blog.objects.get(id=1)
>>> b.entries.all() # Returns all Entry objects related to Blog.

# b.entries is a Manager that returns QuerySets.
>>> b.entries.filter(headline__contains='Lennon')
>>> b.entries.count()

from django.db import models

class Entry(models.Model):
    #...
    objects = models.Manager()  # Default Manager
    entries = EntryManager()    # Custom Manager

b = Blog.objects.get(id=1)
b.entry_set(manager='entries').all()

b.entry_set(manager='entries').is_published()

b = Blog.objects.get(id=1)
b.entry_set.set([e1, e2])

多对多关系¶

多对多关系的两端获得对另一端的自动API访问。 API的工作原理与上面的“向后”一对多关系一样。

唯一的区别是属性命名：定义 ManyToManyField 的模型使用该字段本身的属性名称，而“反向”模型使用原始模型的小写模型名称加上 '_set' （就像反向一对一）许多关系）。

一个例子使这更容易理解:

e = Entry.objects.get(id=3)
e.authors.all() # Returns all Author objects for this Entry.
e.authors.count()
e.authors.filter(name__contains='John')

a = Author.objects.get(id=5)
a.entry_set.all() # Returns all Entry objects for this Author.

像 ForeignKey，ManyToManyField 可以指定 related_name。在上述示例中，如果 Entry 中的 ManyToManyField 指定了 related_name='entries'，则每个 Author 实例将具有 entries 属性而不是 entry_set。

一对一的关系¶

一对一关系与多对一关系非常相似。如果在模型上定义 OneToOneField，那么该模型的实例将通过模型的简单属性访问相关对象。

例如:

class EntryDetail(models.Model):
    entry = models.OneToOneField(Entry, on_delete=models.CASCADE)
    details = models.TextField()

ed = EntryDetail.objects.get(id=2)
ed.entry # Returns the related Entry object.

区别在于“反向”查询。在一对一关系中的相关模型也可以访问 Manager 对象，但是 Manager 表示单个对象，而不是对象的集合:

e = Entry.objects.get(id=2)
e.entrydetail # returns the related EntryDetail object

如果没有对象被分配给这个关系，Django将引发一个 DoesNotExist 异常。

可以以与分配正向关系相同的方式将实例分配给反向关系:

e.entrydetail = ed

后向关系如何可能？¶

其他对象关系映射器需要您定义双方的关系。 Django开发人员认为这违反了DRY（Do not Repeat Yourself）原则，因此Django只需要在一端定义关系。

但是这是怎么可能的，因为模型类不知道哪些其他模型类与它相关，直到那些其他模型类加载？

答案在于 app registry。当Django启动时，它会导入 INSTALLED_APPS 中列出的每个应用程序，然后导入每个应用程序中的 models 模块。每当创建一个新的模型类时，Django都会向任何相关模型添加后向关系。如果尚未导入相关模型，Django会跟踪关系，并在最终导入相关模型时添加它们。

因此，在 INSTALLED_APPS 中列出的应用程序中定义您使用的所有模型尤为重要。否则，后向关系可能无法正常工作。

对相关对象的查询¶

涉及相关对象的查询遵循与包含正常值字段的查询相同的规则。指定要匹配的查询的值时，可以使用对象实例本身或对象的主键值。

例如，如果您有一个博客对象 b 与 id=5，以下三个查询将是相同的:

Entry.objects.filter(blog=b) # Query using object instance
Entry.objects.filter(blog=b.id) # Query using id from instance
Entry.objects.filter(blog=5) # Query using id directly