Django QuerySet API 整理

(译自官方文档)

以下操作会真正操作数据库

  • Iteration:在遍历对象时就会执行数据库操作
  • Slicing:对与一个未查询的 QuerySet 切片就会返回另一个未查询的 QuerySet 。使用参数 step 参数时会执行数据库操作
  • Picking/Caching:参见 Picking QuerySet
  • repr():调用该方法时查询会被运行,并可以立即看到查询结果(命令行常用)
  • len():返回查询结果列表的长度。运行时执行数据库操作,使用 count() 会更加高效
  • list():再转化为列表时会执行数据库操作,且占用大量内存。而遍历 QuerySet 时仅使用某个对象时才加载至内存中

Picking QuerySet

import pickle
query = pickle.loads(s) # Assuming 's' is the pickled string.
qs = MyModel.objects.all()
qs.query = query # Restore the original 'query'.

QuerySet API

  • filter(**kwargs):根据筛选条件返回相匹配的对象。参见 Filed lookups
  • exclued(**kwargs):根据筛选条件返回不匹配的对象。
Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline='Hello')
SELECT ...
WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')
  • annotate(args,*kwargs):为 QuerySet 中的每个对象添加注解(可以理解为辅助计算列),具体的函数参见 Aggregation Functions
>>> 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
  • order_by(*fileds):默认情况下,QuerySet 返回的查询结果以 Model 类的 Meta 设置所提供的 ordering 项中定义的排序元组来排序。可以使用 order_by 进行覆盖。通过设置 QuerySet.ordered 属性,可以决定某个查询是否可排序
# 🌰:以 pub_date 升序,再以 headline 倒序,默认倒序
Entry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline')

# 随机排序(占用较多资源)
Entry.objects.order_by('?')

# 根据其他 Model 类的字段排序,若没有指定字段,默认会采用 Meta.ordering 进行排序。否则会以主键排序
Entry.objects.order_by('blog__name', 'headline')

# 也可以使用 asc() 和 desc() 方法
Entry.objects.order_by(Coalesce('summary', 'headline').desc())
  • reverse():对查询结果进行反向排序
# 得到查询结果中最后五个对象
my_queryset.reverse()[:5]
  • distinct():返回一个新的 QuerySet ,在执行查询时使用 select distinct. 默认情况下,QuerySet 会自动剔除重复的记录,但是在多表查询时,可能会用到 Distinct(慎用)
  • values(*fields):返回一个 ValuesQuerySet ,运行后得到的不是 Model 的实例话对象,而是一个可迭代的字典序列
# This list contains a Blog object.
>>> Blog.objects.filter(name__startswith='Beatles')
[<Blog: Beatles Blog>]

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

# 入参可以指定字段,限定 Select 选取的数据
>>> Blog.objects.values()
[{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}],
>>> Blog.objects.values('id', 'name')
[{'id': 1, 'name': 'Beatles Blog'}]
#
  • values_list(*fields):与 values() 类似,不过返回的是元组序列
>>> Entry.objects.values_list('id', 'headline')
[(1, u'First entry'), ...]

# 如果传递了一个字段做为参数,那么使用 flat 参数(值为 True),就意味着返回结果都是单独的值,而不是元组。如下:
>>> Entry.objects.values_list('id').order_by('id')
[(1,), (2,), (3,), ...]

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

# 注意这个方法返回的是 ValuesListQuerySet对象,和列表相似但并不是列表,需要列表操作时需list()转为列表。
  • dates(field , kind , order=’ASC’):返回一个DateQuerySet,提取 QuerySet 查询中所包含的日期,组成一个新的 datetime.date 对象列表
>>> 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)]
  • datetimes(field , kind , order=’ASC’):返回一个 DateTimeQuerySet ,组成一个新的 datetime.datetime 对象列表
  • none():返回一个 EmptyQuerySet ,在运行时只返回一个空列表。适用于你要返回一个空列表,但调用者却需要接收一个 QuerySet 对象。
>>> Entry.objects.none()
[]
>>> from django.db.models.query import EmptyQuerySet
>>> isinstance(Entry.objects.none(), EmptyQuerySet)
True
  • all():返回当前 QuerySet 但一份拷贝。当 QuerySet 运行后,会缓存查询结果,如果数据库发生了改变,调用 all() 可以更新查询
  • select_related():返回一个 QuerySet ,在执行查询时进口可能深入的遍历外键关系,再查询后再使用外键关系获取关联对象时不会再读取数据库(通过库内 Join 进行查询)
  • prefetch_related():与 select_related() 类似,但是是分别查询每个表,然后用 Python 处理他们之间的关系
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): # __unicode__ on Python 2
return "%s (%s)" % (self.name, ", ".join([topping.name
for topping in self.toppings.all()]))



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


class Restaurant(models.Model):
pizzas = models.ManyToMany(Pizza, related_name='restaurants')
best_pizza = models.ForeignKey(Pizza, related_name='championed_by')



>>> Restaurant.objects.prefetch_related('pizzas__toppings')
>>> Restaurant.objects.prefetch_related('best_pizza__toppings')
>>> Restaurant.objects.select_related('best_pizza').prefetch_related('best_pizza__toppings')
  • extra(select=None,where=None,params=None,tables=None,order_by=None,select_params=None)
    extra() 可以修改 QuerySet ,能在生成的SQL语句中注入新的子句。但应尽量避免写 extra ,因为违背了 DRY 原则
  • defer(*field):将不想载入但字段传给 defer() 方法,可以做到延后载入
Entry.objects.defer("lede", "body")

Entry.objects.defer("body").filter(headline="Lennon").defer("lede")

# 也可以延迟载入关联 Model 中的字段,前提是使用 select_related() 载入了关联 Model
Blog.objects.select_related().defer("entry__lede", "entry__body")

# 清除延后载入设置,传入 None
my_queryset.defer(None)
  • only(*field):和 defer() 作用相反,立即载入可以使用 only()
Person.objects.defer("age", "biography")
Person.objects.only("name")

# 连续调用只有最后一个 only() 会生效
Entry.objects.only("body", "lede").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 and body immediately (only() replaces any
# existing set of fields).
Entry.objects.defer("body").only("headline", "body")
  • using(alias):切换数据库,参数是数据库的alias
# queries the database with the 'default' alias.
>>> Entry.objects.all()

# queries the database with the 'backup' alias
>>> Entry.objects.using('backup')
  • select_for_update(nowait=False):返回queryset,并将需要更新的行锁定,类似于SELECT … FOR UPDATE的操作
entries = Entry.objects.select_for_update().filter(author=request.user)
  • raw(raw_query, params=None, translations=None):执行 Raw SQL 查询

不返回查询的方法

这些方法不使用缓存,他们在运行时是直接读取数据库的。

  • get(**kwargs):返回与筛选条件相匹配的对象。返回对象超过一个,抛出 MultipleObjectsReturned 异常,没有返回对象返回 DoesNotExist 异常
# DoesNotExist 异常继承自 django.core.exceptions.ObjectDoesNotExist,可以直接截获 DoesNotExist 异常
from django.core.exceptions import ObjectDoesNotExist
try:
e = Entry.objects.get(id=3)
b = Blog.objects.get(id=1)
except ObjectDoesNotExist:
print("Either the entry or blog doesn't exist.")
  • create(**kwargs):创建对象并保存
# 以下操作等效
p = Person.objects.create(first_name="Bruce", last_name="Springsteen")

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

# 手动指定主键时,要处理好同主键的异常
  • get_or_create(default=None,**kwargs):根据筛选条件查询对象,若不存在就创建一个
# 以下代码效果相同,知识第一种过于臃肿
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()

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

# defaults 只能在创建时对对象赋值,而不能进行查询
Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'})
  • update_or_create(defaults=None,**kwargs):与 get_or_create() 类似
try:
obj = Person.objects.get(first_name='John', last_name='Lennon')
for key, value in updated_values.iteritems():
setattr(obj, key, value)
obj.save()
except Person.DoesNotExist:
updated_values.update({'first_name': 'John', 'last_name': 'Lennon'})
obj = Person(**updated_values)
obj.save()

# 可以简化为

obj, created = Person.objects.update_or_create(
first_name='John', last_name='Lennon', defaults=updated_values)
  • bulk_create(objs,batch_size=None):批量创建
>>> Entry.objects.bulk_create([
... Entry(headline="Django 1.0 Released"),
... Entry(headline="Django 1.1 Announced"),
... Entry(headline="Breaking: Django is awesome")
... ])

# 优于

Entry.objects.create(headline="Python 1.0 Released"
Entry.objects.create(headline="Python 1.1 Planned"
  • count():返回数据库中匹配查询的对象数量,不会抛出任何异常
  • in_bulk(id_list):接收一个主键值列表,然后根据每个主键值所其对应的对象,返回一个主键值与对象的映射字典
>>> 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([])
{}
  • iterator():运行查询,根据结果返回一个迭代器。分多次对数据实例化,用到时才会实例化。使用迭代器效率更高,节省内存
  • latest(field_name=None):根据时间字段 field_name 得到最新的对象
Entry.objects.latest('pub_date')
  • earliest(field_name=None):根据时间字段 field_name 得到最旧(早)的对象
  • first():排序后对第一个对象

    p = Article.objects.order_by('title', 'pub_date').first()
  • last():类似于 first()

  • aggregate(args, *kwargs):通过对 QuerySet 进行计算,返回一个聚合值的字典。 aggregate() 中每个参数都指定一个包含在字典中的返回值。
>>> from django.db.models import Count
>>> q = Blog.objects.aggregate(Count('entry'))
{'entry__count': 16}

# 指定返回对聚合名称
>>> q = Blog.objects.aggregate(number_of_entries=Count('entry'))
{'number_of_entries': 16}
  • exists():查询是否有值,返回布尔值
  • update():更新
  • delete():删除

字段筛选条件(Field Lookups)

字段筛选条件决定了你如何构造 SQL 语句中的 WHERE 从句。它们被指定为 QuerySet 中 filter(),exclude() 和 get() 方法的关键字参数。

  • exact():精确匹配,指定为 None 值会翻译为 SQL 中对 Null
Entry.objects.get(id__exact=14)
Entry.objects.get(id__exact=None)
  • iexact():忽略大小写的匹配,SQLite 对 Unicode 字符串,无法做忽略大小写的匹配。
Blog.objects.get(name__iexact='beatles blog')
Blog.objects.get(name__iexact=None)
  • contains():大小写敏感的包含匹配
Entry.objects.get(headline__contains='Lennon')
  • icontains():忽略大小写敏感的包含匹配
Entry.objects.get(headline__icontains='Lennon')
  • in:是否在给定的列表中
Entry.objects.filter(id__in=[1, 3, 4])

inner_qs = Blog.objects.filter(name__contains='Cheddar')
entries = Entry.objects.filter(blog__in=inner_qs)

inner_qs = Blog.objects.filter(name__contains='Ch').values('name')
entries = Entry.objects.filter(blog__name__in=inner_qs)
  • gt:大于
  • gte:大于等于
  • lt:小于
  • lte:小于等于
  • startswith:大小写敏感的以**开头
  • istartswith:忽略大小写的以**开头
  • endswith:大小写敏感的以**结尾
  • iendswith:忽略大小写的以**结尾
  • range:包含的范围,类似 SQL 中的 BETWEEN
import datetime
start_date = datetime.date(2005, 1, 1)
end_date = datetime.date(2005, 3, 31)
Entry.objects.filter(pub_date__range=(start_date, end_date))
  • year:对日期/时间字段精确匹配年份,年份用四位数字表示
Entry.objects.filter(pub_date__year=2005)

等价于SQL:

SELECT ... WHERE EXTRACT('year' FROM pub_date) = '2005';
  • month:对日期/时间字段精确匹配月份
  • day:对日期/时间字段精确匹配日期
  • week_day:对日期/时间字段精确匹配周数
  • hour:对日期/时间字段精确匹配小时
  • minute:对日期/时间字段精确匹配分钟
  • second:对日期/时间字段精确匹配秒
  • isnull:根据字段是否为空筛选数据
Entry.objects.filter(pub_date__isnull=True)
SELECT ... WHERE pub_date IS NULL;
  • search:利用全文索引做全文搜索,与 contains 类似,但使用全文索引会更快
Entry.objects.filter(headline__search="+Django -jazz Python")
  • regex:大小写敏感的正则表达式匹配
Entry.objects.get(title__regex=r'^(An?|The) +')
  • iregex:忽略大小写的正则表达式匹配

聚合函式

  • avg:__avg ,返回所给字段的平均值
  • count:__count ,返回所给关联字段的 model 数量
  • max:__max ,返回所给字段数据的最大值
  • min:__min , 返回所给字段数据的最小值
  • strdev:__stddev ,返回所给字段的标准差,sample=True 返回一个样本偏差值
  • sum:__sum ,计算所给字段的和
  • variance:__variance ,计算所给字段的标准方差,sample=True 返回样本方差