Django模型层之字段查询参数及聚合函数

该系列教程系个人原创，并完整发布在个人官网刘江的博客和教程

所有转载本文者，需在顶部显著位置注明原作者及www.liujiangblog.com官网地址。

---

字段查询是指如何指定SQL WHERE子句的内容。它们用作QuerySet的filter(), exclude()和get()方法的关键字参数。

默认查找类型为exact。

---

下表列出了所有的字段查询参数：

字段名	说明
exact	精确匹配
iexact	不区分大小写的精确匹配
contains	包含匹配
icontains	不区分大小写的包含匹配
in	在..之内的匹配
gt	大于
gte	大于等于
lt	小于
lte	小于等于
startswith	从开头匹配
istartswith	不区分大小写从开头匹配
endswith	从结尾处匹配
iendswith	不区分大小写从结尾处匹配
range	范围匹配
date	日期匹配
year	年份
month	月份
day	日期
week	第几周
week_day	周几
time	时间
hour	小时
minute	分钟
second	秒
isnull	判断是否为空
search	1.10中被废弃
regex	区分大小写的正则匹配
iregex	不区分大小写的正则匹配

1. exact

精确匹配。 默认的查找类型！

Entry.objects.get(id__exact=14)
Entry.objects.get(id__exact=None)

2. iexact

不区分大小写的精确匹配。

Blog.objects.get(name__iexact='beatles blog')
Blog.objects.get(name__iexact=None)

第一个查询将匹配 'Beatles Blog', 'beatles blog', 'BeAtLes BLoG'等等。

3. contains

大小写敏感的包含关系匹配。

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

这将匹配标题'Lennon honored today'，但不匹配'lennon honored today'。

4. icontains

不区分大小写的包含关系匹配。

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

5. 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)

或者从values()或values_list()中获取的QuerySet作为比对的对象：

inner_qs = Blog.objects.filter(name__contains='Ch').values('name')
entries = Entry.objects.filter(blog__name__in=inner_qs)

下面的例子将产生一个异常，因为试图提取两个字段的值，但是查询语句只需要一个字段的值：

# 错误的实例，将弹出异常。
inner_qs = Blog.objects.filter(name__contains='Ch').values('name', 'id')
entries = Entry.objects.filter(blog__name__in=inner_qs)

6. gt

大于

Entry.objects.filter(id__gt=4)

7. gte

大于或等于

8. lt

小于

9. lte

小于或等于

10. startswith

区分大小写，从开始位置匹配。

Entry.objects.filter(headline__startswith='Lennon')

11. istartswith

不区分大小写，从开始位置匹配。

Entry.objects.filter(headline__istartswith='Lennon')

12. endswith

区分大小写，从结束未知开始匹配。

Entry.objects.filter(headline__endswith='Lennon')

13. iendswith

不区分大小写，从结束未知开始匹配。

Entry.objects.filter(headline__iendswith='Lennon')

14. range

范围测试（包含于之中）。

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

警告:过滤具有日期的DateTimeField不会包含最后一天，因为边界被解释为“给定日期的0am”。

15. date

进行日期对比。

Entry.objects.filter(pub_date__date=datetime.date(2005, 1, 1))
Entry.objects.filter(pub_date__date__gt=datetime.date(2005, 1, 1))

当USE_TZ为True时，字段将转换为当前时区，然后进行过滤。

16. year

对年份进行匹配。

Entry.objects.filter(pub_date__year=2005)
Entry.objects.filter(pub_date__year__gte=2005)

当USE_TZ为True时，在过滤之前，datetime字段将转换为当前时区。

17. month

对月份进行匹配。取整数1（1月）至12（12月）。

Entry.objects.filter(pub_date__month=12)
Entry.objects.filter(pub_date__month__gte=6)

当USE_TZ为True时，在过滤之前，datetime字段将转换为当前时区。

18. day

对具体到某一天的匹配。

Entry.objects.filter(pub_date__day=3)
Entry.objects.filter(pub_date__day__gte=3)

当USE_TZ为True时，在过滤之前，datetime字段将转换为当前时区。

19. week

Django1.11中的新功能。根据ISO-8601返回周号（1-52或53），即星期一开始的星期，星期四或之前的第一周。

Entry.objects.filter(pub_date__week=52)
Entry.objects.filter(pub_date__week__gte=32, pub_date__week__lte=38)

当USE_TZ为True时，字段将转换为当前时区，然后进行过滤。

20. week_day

进行“星期几”匹配。 取整数值，星期日为1，星期一为2，星期六为7。

Entry.objects.filter(pub_date__week_day=2)
Entry.objects.filter(pub_date__week_day__gte=2)

当USE_TZ为True时，在过滤之前，datetime字段将转换为当前时区。

21. time

Django1.11中的新功能。

将字段的值转为datetime.time格式并进行对比。

Entry.objects.filter(pub_date__time=datetime.time(14, 30))
Entry.objects.filter(pub_date__time__between=(datetime.time(8), datetime.time(17)))

USE_TZ为True时，字段将转换为当前时区，然后进行过滤。

22. hour

对小时进行匹配。 取0和23之间的整数。

Event.objects.filter(timestamp__hour=23)
Event.objects.filter(time__hour=5)
Event.objects.filter(timestamp__hour__gte=12)

当USE_TZ为True时，值将过滤前转换为当前时区。

23. minute

对分钟匹配。取0和59之间的整数。

Event.objects.filter(timestamp__minute=29)
Event.objects.filter(time__minute=46)
Event.objects.filter(timestamp__minute__gte=29)

当USE_TZ为True时，值将被过滤前转换为当前时区。

24. second

对秒数进行匹配。取0和59之间的整数。

Event.objects.filter(timestamp__second=31)
Event.objects.filter(time__second=2)
Event.objects.filter(timestamp__second__gte=31)

当USE_TZ为True时，值将过滤前转换为当前时区。

25. isnull

值为False或True, 相当于SQL语句IS NULL和IS NOT NULL.

Entry.objects.filter(pub_date__isnull=True)

26. search

自1.10版以来已弃用。

27. regex

区分大小写的正则表达式匹配。

Entry.objects.get(title__regex=r'^(An?|The) +')

建议使用原始字符串（例如，r'foo'而不是'foo'）来传递正则表达式语法。

28. iregex

不区分大小写的正则表达式匹配。

Entry.objects.get(title__iregex=r'^(an?|the) +')

聚合函数

Django的django.db.models模块提供以下聚合函数。

1. expression

引用模型字段的一个字符串，或者一个query expression。

2. output_field

用来表示返回值的model field，一个可选的参数。

3. **extra

关键字参数可以给聚合函数生成的SQL提供额外的信息。

4. Avg

class Avg(expression, output_field=FloatField(), **extra)[source]

返回给定表达式的平均值，它必须是数值，除非指定不同的output_field。

默认的别名：<field>__avg
返回类型：float（或指定任何output_field的类型）

5. Count

class Count(expression, distinct=False, **extra)[source]

返回与expression相关的对象的个数。

默认的别名：<field>__count
返回类型：int
有一个可选的参数：distinct。如果distinct=True，Count 将只计算唯一的实例。默认值为False。

6. Max

class Max(expression, output_field=None, **extra)[source]

返回expression的最大值。

默认的别名：<field>__max
返回类型：与输入字段的类型相同，如果提供则为`output_field`类型

7. Min

class Min(expression, output_field=None, **extra)[source]

返回expression的最小值。

默认的别名：<field>__min
返回类型：与输入字段的类型相同，如果提供则为`output_field`类型

8. StdDev

class StdDev(expression, sample=False, **extra)[source]

返回expression的标准差。

默认的别名：<field>__stddev
返回类型：float
有一个可选的参数：sample。默认情况下，返回群体的标准差。如果sample=True，返回样本的标准差。
SQLite 没有直接提供StdDev。

9. Sum

class Sum(expression, output_field=None, **extra)[source]

计算expression的所有值的和。

默认的别名：<field>__sum
返回类型：与输入字段的类型相同，如果提供则为output_field类型

10. Variance

class Variance(expression, sample=False, **extra)[source]

返回expression的方差。

默认的别名：<field>__variance
返回类型：float
有一个可选的参数：sample。
SQLite 没有直接提供Variance。