Django之QuerySet详解

菲宇

互联网工作者

从数据库中查询出来的结果一般是一个集合，这个集合叫做 QuerySet。

一、QuerySet何时被提交

在内部，创建、过滤、切片和传递一个QuerySet不会真实操作数据库，在你对查询集提交之前，不会发生任何实际的数据库操作。可以使用下列方法对QuerySet提交查询操作：

迭代

QuerySet是可迭代的，在首次迭代查询集时执行实际的数据库查询。例如，下面的语句会将数据库中所有Entry的headline打印出来：

for e in Entry.objects.all():

print(e.headline)

切片：如果使用切片的”step“参数，Django 将执行数据库查询并返回一个列表。

Pickling/缓存

repr()

len()：当你对QuerySet调用len()时，将提交数据库操作。

list()：对QuerySet调用list()将强制提交操作entry_list = list(Entry.objects.all())

bool()

测试布尔值，像这样：

if Entry.objects.filter(headline="Test"):

print("There is at least one Entry with the headline Test")

注：如果你需要知道是否存在至少一条记录（而不需要真实的对象），使用exists() 将更加高效。

二、QuerySet

下面是对于QuerySet的正式定义：

class QuerySet(model=None, query=None, using=None)[source]

QuerySet类具有两个公有属性用于内省：

ordered：如果QuerySet是排好序的则为True，否则为False。

db：如果现在执行，则返回使用的数据库。

三、返回新QuerySets的API

以下的方法都将返回一个新的QuerySets。重点是加粗的几个API，其它的使用场景很少。

方法名解释

filter() 过滤查询对象。

exclude() 排除满足条件的对象

annotate() 使用聚合函数

order_by() 对查询集进行排序

reverse() 反向排序

distinct() 对查询集去重

values() 返回包含对象具体值的字典的QuerySet

values_list() 与values()类似，只是返回的是元组而不是字典。

dates() 根据日期获取查询集

datetimes() 根据时间获取查询集

none() 创建空的查询集

all() 获取所有的对象

union() 并集

intersection() 交集

difference() 差集

select_related() 附带查询关联对象

prefetch_related()

预先查询

extra() 附加SQL查询

defer() 不加载指定字段

only() 只加载指定的字段

using() 选择数据库

select_for_update()

锁住选择的对象，直到事务结束。

raw() 接收一个原始的SQL查询

1. filter()

filter(**kwargs)

返回满足查询参数的对象集合。

查找的参数（**kwargs）应该满足下文字段查找中的格式。多个参数之间是和AND的关系。

2. exclude()

exclude(**kwargs)

返回一个新的QuerySet，它包含不满足给定的查找参数的对象。

查找的参数（**kwargs）应该满足下文字段查找中的格式。多个参数通过AND连接，然后所有的内容放入NOT() 中。

下面的示例排除所有pub_date晚于2005-1-3且headline为“Hello” 的记录：

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

下面的示例排除所有pub_date晚于2005-1-3或者headline 为“Hello” 的记录：

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

3. annotate()

annotate(args, *kwargs)

使用提供的聚合表达式查询对象。

表达式可以是简单的值、对模型（或任何关联模型）上的字段的引用或者聚合表达式（平均值、总和等）。

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

关键字参数指定的Annotation将使用关键字作为Annotation 的别名。匿名参数的别名将基于聚合函数的名称和模型的字段生成。只有引用单个字段的聚合表达式才可以使用匿名参数。其它所有形式都必须用关键字参数。

例如，如果正在操作一个Blog列表，你可能想知道每个Blog有多少Entry：

>>> 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属性，但是通过使用一个关键字参数来指定聚合函数，可以控制Annotation的名称：

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

4. order_by()

order_by(*fields)

默认情况下，根据模型的Meta类中的ordering属性对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']，那么第一个QuerySet将等同于：

Entry.objects.order_by('blog__name')

还可以通过调用表达式的desc()或者asc()方法：

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

考虑下面的情况，指定一个多值字段来排序（例如，一个ManyToManyField 字段或者ForeignKey 字段的反向关联）：

class Event(Model):

parent = models.ForeignKey(

'self',

on_delete=models.CASCADE,

related_name='children',

)

date = models.DateField()

Event.objects.order_by('children__date')

在这里，每个Event可能有多个排序数据；具有多个children的每个Event将被多次返回到order_by()创建的新的QuerySet中。换句话说，用order_by()方法对QuerySet对象进行操作会返回一个扩大版的新QuerySet对象。因此，使用多值字段对结果进行排序时要格外小心。

没有方法指定排序是否考虑大小写。对于大小写的敏感性，Django将根据数据库中的排序方式排序结果。

可以通过Lower将一个字段转换为小写来排序，它将达到大小写一致的排序：

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

可以通过检查QuerySet.ordered属性来知道查询是否是排序的。

每个order_by()都将清除前面的任何排序。例如下面的查询将按照pub_date排序，而不是headline：

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

5. reverse()

reverse()

反向排序QuerySet中返回的元素。第二次调用reverse()将恢复到原有的排序。

如要获取QuerySet中最后五个元素，可以这样做：

my_queryset.reverse()[:5]

这与Python直接使用负索引有点不一样。 Django不支持负索引，只能曲线救国。

6. distinct()

distinct(*fields)

去除查询结果中重复的行。

默认情况下，QuerySet不会去除重复的行。当查询跨越多张表的数据时，QuerySet可能得到重复的结果，这时候可以使用distinct()进行去重。

7. values()

values(fields, *expressions)

返回一个包含数据的字典的queryset，而不是模型实例。

每个字典表示一个对象，键对应于模型对象的属性名称。

下面的例子将values() 与普通的模型对象进行比较：

# 列表中包含的是Blog对象

>>> Blog.objects.filter(name__startswith='Beatles')

# 列表中包含的是数据字典

>>> Blog.objects.filter(name__startswith='Beatles').values()

该方法接收可选的位置参数*fields，它指定values()应该限制哪些字段。如果指定字段，每个字典将只包含指定的字段的键/值。如果没有指定字段，每个字典将包含数据库表中所有字段的键和值。

例如：

>>> Blog.objects.values()

>>> Blog.objects.values('id', 'name')

values()方法还有关键字参数**expressions，这些参数将传递给annotate()：

>>> from django.db.models.functions import Lower

>>> Blog.objects.values(lower_name=Lower('name'))

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

>>> from django.db.models import Count

>>> Blog.objects.values('author', entries=Count('entry'))

>>> Blog.objects.values('author').annotate(entries=Count('entry'))

注意：

如果你有一个字段foo是一个ForeignKey，默认的foo_id参数返回的字典中将有一个叫做foo 的键，因为这是保存实际值的那个隐藏的模型属性的名称。当调用foo_id并传递字段的名称，传递foo 或values()都可以，得到的结果是相同的。像这样：

>>> Entry.objects.values()

>>> Entry.objects.values('blog')

>>> Entry.objects.values('blog_id')

当values()与distinct()一起使用时，注意排序可能影响最终的结果。

如果values()子句位于extra()调用之后，extra()中的select参数定义的字段必须显式包含在values()调用中。 values( 调用后面的extra( 调用将忽略选择的额外的字段。

在values()之后调用only()和defer()不太合理，所以将引发一个NotImplementedError。

可以通过ManyToManyField、ForeignKey 和 OneToOneFiel 属性反向引用关联的模型的字段：

>>> Blog.objects.values('name', 'entry__headline')

<QuerySet [{'name': 'My blog', 'entry__headline': 'An entry'},

{'name': 'My blog', 'entry__headline': 'Another entry'}, ...]>

8. values_list()

values_list(*fields, flat=False)

与values()类似，只是在迭代时返回的是元组而不是字典。每个元组包含传递给values_list()调用的相应字段或表达式的值，因此第一个项目是第一个字段等。像这样：

>>> Entry.objects.values_list('id', 'headline')

>>> from django.db.models.functions import Lower

>>> Entry.objects.values_list('id', Lower('headline'))

如果只传递一个字段，还可以传递flat参数。如果为True，它表示返回的结果为单个值而不是元组。如下所示：

>>> Entry.objects.values_list('id').order_by('id')

<QuerySet[(1,), (2,), (3,), ...]>

>>> Entry.objects.values_list('id', flat=True).order_by('id')

如果有多个字段，传递flat将发生错误。

如果不传递任何值给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。

>>> Entry.objects.values_list('authors')

9. dates()

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

返回一个QuerySet，表示QuerySet内容中特定类型的所有可用日期的datetime.date对象列表。

field参数是模型的DateField的名称。 kind参数应为"year"，"month"或"day"。结果列表中的每个datetime.date对象被截取为给定的类型。

"year" 返回对应该field的所有不同年份值的列表。

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

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

order参数默认为'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', '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)]

10. datetimes()

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

返回QuerySet，为datetime.datetime对象的列表，表示QuerySet内容中特定种类的所有可用日期。

field_name应为模型的DateTimeField的名称。

kind参数应为"hour"，"minute"，"month"，"year"，"second"或"day"。

结果列表中的每个datetime.datetime对象被截取到给定的类型。

order参数默认为'ASC'，或者'DESC'。它指定如何排序结果。

tzinfo参数定义在截取之前将数据时间转换到的时区。

11. none()

none()

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

例子：

>>> Entry.objects.none()

>>> from django.db.models.query import EmptyQuerySet

>>> isinstance(Entry.objects.none(), EmptyQuerySet)

True

12. all()

all()

返回当前QuerySet（或QuerySet子类）的副本。通常用于获取全部QuerySet对象。

13. union()

union(*other_qs, all=False)

Django中的新功能1.11。也就是集合中并集的概念！

使用SQL的UNION运算符组合两个或更多个QuerySet的结果。例如：

>>> qs1.union(qs2, qs3)

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

14. intersection()

intersection(*other_qs)

Django中的新功能1.11。也就是集合中交集的概念！

使用SQL的INTERSECT运算符返回两个或更多个QuerySet的共有元素。例如：

>>> qs1.intersection(qs2, qs3)

15. difference()

difference(*other_qs)

Django中的新功能1.11。也就是集合中差集的概念！

使用SQL的EXCEPT运算符只保留QuerySet中的元素，但不保留其他QuerySet中的元素。例如：

>>> qs1.difference(qs2, qs3)

16. select_related()

select_related(*fields)

沿着外键关系查询关联的对象的数据。这会生成一个复杂的查询并引起性能的损耗，但是在以后使用外键关系时将不需要再次数据库查询。

下面的例子解释了普通查询和select_related()查询的区别。下面是一个标准的查询：

# 访问数据库。

e = Entry.objects.get(id=5)

# 再次访问数据库以得到关联的Blog对象。

b = e.blog

下面是一个select_related查询：

# 访问数据库。

e = Entry.objects.select_related('blog').get(id=5)

# 不会访问数据库，因为e.blog已经在前面的查询中获得了。

b = e.blog

select_related()可用于objects任何的查询集：

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'):

# 没有select_related()，下面的语句将为每次循环迭代生成一个数据库查询,以获得每个entry关联的blog。

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):
    # ...
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：

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.

b = Book.objects.get(id=4) # No select_related() in this example.

p = b.author # Hits the database.

c = p.hometown # Hits the database.

在传递给select_related()的字段中，可以使用任何ForeignKey和OneToOneField。

在传递给select_related的字段中，还可以反向引用OneToOneField。也就是说，可以回溯到定义OneToOneField 的字段。此时，可以使用关联对象字段的related_name，而不要指定字段的名称。

17. prefetch_related()

prefetch_related(*lookups)

在单个批处理中自动检索每个指定查找的相关对象。

与select_related类似，但是策略是完全不同的。

假设有这些模型：

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)