Django 1.8.2 文档

QuerySet API参考

本文档描述了QuerySet API的详细信息。它建立在模型数据库查询指南的基础上,所以在阅读本文档之前,你也许需要首先阅读这两部分的文档。

本文档将通篇使用在数据库查询指南中用到的Weblog 模型的例子

何时对查询集求值

本质上,可以创建、过滤、切片和传递查询集而不用真实操作数据库。在你对查询集做求值之前,不会发生任何实际的数据库操作。

你可以使用下列方法对查询集求值:

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

    for e in Entry.objects.all():
        print(e.headline)
    

    注意:不要使用上面的语句来验证在数据库中是否至少存在一条记录。使用 exists()方法更高效。

  • 切片。 正如在限制查询集中解释的那样, 可以使用Python 的序列切片语法对一个查询集进行分片。一个未求值的查询集进行切片通常返回另一个未求值的QuerySet,但是如果你使用切片的”step“参数,Django 将执行数据库查询并返回一个列表。对一个已经求值的查询集进行切片将返回一个列表。

    还要注意,虽然对未求值的查询集进行切片返回另一个未求值的查询集,但是却不可以进一步修改它了(例如,添加更多的Filter,或者修改排序的方式),因为这将不太好翻译成SQL而且含义也不清晰。

  • 序列化/缓存。 序列化查询集的细节参见下面一节。本节提到它的目的是强调序列化将读取数据库。

  • repr()。 当对查询集调用repr() 时,将对它求值。这是为了在Python 交互式解释器中使用的方便,这样你可以在交互式使用这个API 时立即看到结果。

  • len()。 当你对查询集调用len() 时, 将对它求值。正如你期望的那样,返回一个查询结果集的长度。

    Note: If you only need to determine the number of records in the set (and don’t need the actual objects), it’s much more efficient to handle a count at the database level using SQL’s SELECT COUNT(*).为此,Django 提供了 一个count() 方法.

  • list()。 查询集调用list() 将强制对它求值。例如:

    entry_list = list(Entry.objects.all())
    
  • bool()。 测试一个查询集的布尔值,例如使用bool()orand 或者if 语句将导致查询集的执行。如果至少有一个记录,则查询集True,否则为False例如:

    if Entry.objects.filter(headline="Test"):
       print("There is at least one Entry with the headline Test")
    

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

Pickle 查询集

如果你Pickle一个查询集,它将在Pickle 之前强制将所有的结果加载到内存中。Pickle 通常用于缓存之前,并且当缓存的查询集重新加载时,你希望结果已经存在随时准备使用(从数据库读取耗费时间,就失去了缓存的目的)。这意味着当你Unpickle查询集时,它包含Pickle 时的结果,而不是当前数据库中的结果。

如果此后你只想Pickle 必要的信息来从数据库重新创建查询集,可以Pickle查询集query 属性。然后你可以使用类似下面的代码重新创建原始的查询集(不用加载任何结果):

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

query 是一个不透明的对象。它表示查询的内部构造,不属于公开的API。然而,这里讲到的Pickle 和Unpickle 这个属性的内容是安全的(和完全支持的)。

不可以在不同版本之间共享Pickle 的结果

查询集的Pickle 只能用于生成它们的Django 版本中。如果你使用Django 的版本N 生成一个Pickle,不保证这个Pickle 在Django 的版本N+1 中可以读取。Pickle 不可用于归档的长期策略。

New in Django 1.8.

因为Pickle 兼容性的错误很难诊断例如产生损坏的对象,当你试图Unpickle 的查询集与Pickle 时的Django 版本不同,将引发一个RuntimeWarning

查询集 API

下面是对于查询集的正式定义:

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

通常你在使用QuerySet时会以链式的filter 来使用。为了让这个能工作,大部分QuerySet 方法返回新的QuerySet。这些方法在本节将详细讲述。

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

ordered[source]

如果QuerySet 是排好序的则为True —— 例如有一个order_by() 子句或者模型有默认的排序。否则为False .

db[source]

如果现在执行,则返回将使用的数据库。

QuerySet 存在query 参数是为了让具有特殊查询用途的子类如GeoQuerySet 可以重新构造内部的查询状态。这个参数的值是查询状态的不透明的表示,不是一个公开的API。简而言之:如果你有疑问,那么你实际上不需要使用它。

返回新的QuerySets的方法

Django 提供了一系列 的QuerySet筛选方法,用于改变 QuerySet 返回的结果类型或者SQL查询执行的方式。

filter

filter(**kwargs)

返回一个新的QuerySet,包含与给定的查询参数匹配的对象。

查找的参数(**kwargs)应该满足下文字段查找中的格式。在底层的SQL 语句中,多个参数通过AND 连接。

如果你需要执行更复杂的查询(例如,使用OR 语句查询),你可以使用Q 对象

exclude

exclude(**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 对象

annotate

annotate(*args, **kwargs)

使用提供的查询表达式Annotate 查询集中的每个对象。查询表达式可以是一个简单的值、模型(或关联模型)字段的一个引用或对查询集中的对象一个聚合函数(平均值、和等)。

New in Django 1.8:

之前版本的Django 值允许聚合函数用作Annotation。现在可以使用各种表达式annotate 一个模型。

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

Django 提供的聚合函数在下文的聚合函数文档中讲述。

关键字参数指定的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

聚合的深入讨论,参见 聚合主题的指南

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'],那么第一个QuerySet 将等同于:

Entry.objects.order_by('blog__name')

通过关联字段排序QuerySet 还能够不用带来JOIN 产生的花费,方法是引用关联字段的_id

# No Join
Entry.objects.order_by('blog_id')

# Join
Entry.objects.order_by('blog__id')
New in Django 1.7:

QuerySet 通过关联字段进行排序不用带来JOIN 产生的开销。

你还可以通过调用表达式的asc() 或者desc(),根据查询表达式排序:

Entry.objects.order_by(Coalesce('summary', 'headline').desc())
New in Django 1.8:

增加根据查询表达式排序。

如果你还用到distinct(),在根据关联模型中的字段排序时要小心。distinct() 中有一个备注讲述关联模型的排序如何对结果产生影响。

指定一个多值字段来排序结果(例如,一个ManyToManyField 字段或者ForeignKey 字段的反向关联)。

考虑下面的情况:

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

Event.objects.order_by('children__date')

这里,每个Event 可能有多个潜在的排序数据;each Event with multiple children will be returned multiple times into the new QuerySet that order_by() creates. 换句话说, 用 order_by()方法对 QuerySet对象进行操作会返回一个扩大版的新QuerySet对象——新增的条目也许并没有什么卵用,你也用不着它们。

因此,当你使用多值字段对结果进行排序时要格外小心。If you can be sure that there will only be one ordering piece of data for each of the items you’re ordering, this approach should not present problems. 如果不确定,请确保结果是你期望的。

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

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

Entry.objects.order_by(Lower('headline').desc())
New in Django 1.8:

新增根据表达式如Lower 来排序。

如果你不想对查询做任何排序,即使是默认的排序,可以不带参数调用order_by()

你可以通过检查QuerySet.ordered 属性来知道查询是否是排序的,如果QuerySet 有任何方式的排序它将为True

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

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

警告

排序不是没有开销的操作。添加到排序中的每个字段都将带来数据库的开销。添加的每个外键也都将隐式包含进它的默认排序。

reverse

reverse()

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

如要获取QuerySet 中最后五个元素,你可以这样做:

my_queryset.reverse()[:5]

注意,这与Python 中从一个序列的末尾进行切片有点不一样。上面的例子将首先返回最后一个元素,然后是倒数第二个元素,以此类推。如果我们有一个Python 序列,当我们查看seq[-5:] 时,我们将一下子得到倒数五个元素。Django 不支持这种访问模型(从末尾进行切片),因为它不可能利用SQL 高效地实现。

同时还要注意,reverse() 应该只在一个已经定义排序的QuerySet 上调用(例如,在一个定义了默认排序的模型上,或者使用order_by() 的时候)。如果QuerySet 没有定义排序,调用reverse() 将不会有任何效果(在调用reverse() 之前没有定义排序,那么调用之后仍保持没有定义)。

distinct

distinct([*fields])

返回一个在SQL 查询中使用SELECT DISTINCT 的新QuerySet它将去除查询结果中重复的行。

默认情况下,QuerySet 不会去除重复的行。在实际应用中,这一般不是个问题,因为像Blog.objects.all() 这样的简单查询不会引入重复的行。但是,如果查询跨越多张表,当对QuerySet 求值时就可能得到重复的结果。这时候你应该使用distinct()

order_by() 调用中的任何字段都将包含在SQL 的 SELECT 列中。distinct() 一起使用时可能导致预计不到的结果。如果你根据关联模型的字段排序,这些fields将添加到查询的字段中,它们可能产生本应该是唯一的重复的行。因为多余的列没有出现在返回的结果中(它们只是为了支持排序),有时候看上去像是返回了不明确的结果。

类似地,如果您使用values()查询来限制所选择的列,则仍然会涉及任何order_by()(或默认模型排序)影响结果的唯一性。

这里的约束是,如果你使用的是distinct(),请注意相关模型的排序。类似地,当一起使用distinct()values()时,请注意字段在不在values()

在PostgreSQL上,您可以传递位置参数(* fields),以便指定DISTINCT应该应用的字段的名称。这转换为SELECT DISTINCT ON SQL查询。这里有区别。对于正常的distinct()调用,数据库在确定哪些行不同时比较每行中的每个字段。对于具有指定字段名称的distinct()调用,数据库将仅比较指定的字段名称。

注意

当你指定字段名称时,必须QuerySet中提供order_by(),而且order_by()中的字段必须以distinct()中的字段相同开始并且顺序相同。

例如,SELECT DISTINCT ON (a)a中的每个值。如果你没有指定一个顺序,你会得到一个任意的行。

示例(除第一个示例外,其他示例都只能在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')
[...]

注释

请记住,order_by()使用已定义的任何默认相关模型排序。您可能需要通过关系_id或引用字段显式排序,以确保DISTINCT ONORDER BY子句的开头。例如,如果Blog模型通过name定义排序

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

...无法工作,因为查询将按blog__name排序,从而使DISTINCT ON表达式不匹配。你必须按照关系_id字段(在这种情况下为blog_id)或引用的(blog__pk)显式排序来确保两个表达式都匹配。

values

values(*fields)

返回一个ValuesQuerySet —— QuerySet 的一个子类,迭代时返回字典而不是模型实例对象。

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

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

# 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.'}]

values() 接收可选的位置参数*fields,它指定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'}]

值得注意的几点:

  • 如果你有一个字段foo 是一个ForeignKey,默认的values() 调用返回的字典将有一个叫做foo_id 的键,因为这是保存实际的值的那个隐藏的模型属性的名称(foo 属性引用关联的模型)。当你调用values() 并传递字段的名称,传递foofoo_id 都可以,得到的结果是相同的(字典的键会与你传递的字段名匹配)。

    例如:

    >>> Entry.objects.values()
    [{'blog_id': 1, 'headline': 'First Entry', ...}, ...]
    
    >>> Entry.objects.values('blog')
    [{'blog': 1}, ...]
    
    >>> Entry.objects.values('blog_id')
    [{'blog_id': 1}, ...]
    
  • values()distinct() 一起使用时,注意排序可能影响最终的结果。详细信息参见distinct() 中的备注。

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

  • values() 之后调用only()defer() 不太合理,所以将引发一个NotImplementedError

New in Django 1.7:

新增最后一点。以前,在values() 之后调用only()defer() 是允许的,但是它要么会崩溃要么返回错误的结果。

ValuesQuerySet 用于你知道你只需要字段的一小部分,而不需要用到模型实例对象的函数。只选择用到的字段当然更高效。

最后,要注意ValuesQuerySetQuerySet 的子类,它实现了大部分相同的方法。你可以对它调用filter()order_by() 等等。这表示下面的两个调用完全相同:

Blog.objects.values().order_by('id')
Blog.objects.order_by('id').values()

Django 的作者喜欢将影响SQL 的方法放在前面,然后放置影响输出的方法(例如values()),但是实际上无所谓。这是卖弄你个性的好机会。

你可以通过OneToOneFieldForeignKeyManyToManyField 属性反向引用关联的模型的字段:

Blog.objects.values('name', 'entry__headline')
[{'name': 'My blog', 'entry__headline': 'An entry'},
     {'name': 'My blog', 'entry__headline': 'Another entry'}, ...]

警告

因为ManyToManyField 字段和反向关联可能有多个关联的行,包含它们可能导致结果集的倍数放大。如果你在values() 查询中包含多个这样的字段将更加明显,这种情况下将返回所有可能的组合。

values_list

values_list(*fields, flat=False)

values() 类似,只是在迭代时返回的是元组而不是字典。每个元组包含传递给values_list() 调用的字段的值 —— 所以第一个元素为第一个字段,以此类推。例如:

>>> Entry.objects.values_list('id', 'headline')
[(1, '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, ...]

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

如果你不传递任何值给values_list(),它将按照字段在模型中定义的顺序, 返回模型中的所有字段。

注意,这个方法返回ValuesListQuerySet这个类的行为类似列表。大部分时候它足够用了,但是如果你需要一个真实的Python 列表对象,可以对它调用list(),这将会对查询集求值。

dates

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

返回DateQuerySet - QuerySet,其计算结果为datetime.date对象列表,表示特定种类的所有可用日期QuerySet

field应为模型的DateField的名称。 kind应为"year""month""day"隐式的是升序排序。若要随机排序,请使用"?",像这样:

  • "year" 返回对应该field的所有不同年份值的list。
  • “month”返回字段的所有不同年/月值的列表。
  • “day”返回字段的所有不同年/月/日值的列表。

order(默认为“ASC”)应为'ASC''DESC'它t指定如何排序结果。

例子:

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

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

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

field_name应为模型的DateTimeField的名称。

kind应为“year”“month”“day”“hour”“minute”“second”结果列表中的每个datetime.datetime对象被“截断”到给定的类型

order, 默认为'ASC', 可选项为'ASC' 或者 'DESC'. 这个选项指定了返回结果的排序方式。

tzinfo定义在截断之前将数据时间转换到的时区。实际上,给定的datetime具有不同的表示,这取决于使用的时区。此参数必须是datetime.tzinfo对象。如果它,Django使用当前时区USE_TZFalse时,它不起作用。

Note

This function performs time zone conversions directly in the database. As a consequence, your database must be able to interpret the value of tzinfo.tzname(None). This translates into the following requirements:

none

none()

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

Examples:

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

all

all()

返回当前QuerySet(或QuerySet 子类) 的副本它可以用于在你希望传递一个模型管理器或QuerySet 并对结果做进一步过滤的情况。不管对哪一种对象调用all(),你都将获得一个可以工作的QuerySet

当对QuerySet进行求值时,它通常会缓存其结果。如果数据库中的数据在QuerySet求值之后可能已经改变,你可以通过在以前求值过的QuerySet上调用相同的all() 查询以获得更新后的结果。

extra

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

有些情况下,Django的查询语法难以简单的表达复杂的 WHERE 子句,对于这种情况, Django 提供了 extra() QuerySet 修改机制 — 它能在 QuerySet生成的SQL从句中注入新子句

Warning

无论何时你都需要非常小心的使用extra(). Every time you use it, you should escape any parameters that the user can control by using params in order to protect against SQL injection attacks . Please read more about SQL injection protection.

由于产品差异的原因,这些自定义的查询难以保障在不同的数据库之间兼容(因为你手写 SQL 代码的原因),而且违背了 DRY 原则,所以如非必要,还是尽量避免写 extra。

extra可以指定一个或多个 参数,例如 select, where or tables. 这些参数都不是必须的,但是你至少要使用一个

  • select

    The select 参数可以让你在 SELECT 从句中添加其他字段信息,它应该是一个字典,存放着属性名到 SQL 从句的映射。

    Example:

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

    结果集中每个 Entry 对象都有一个额外的属性is_recent, 它是一个布尔值,表示 Entry对象的pub_date 是否晚于 Jan. 1, 2006.

    Django 会直接在 SELECT 中加入对应的 SQL 片断,所以转换后的 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'
        },
    )
    

    在上面这个特例中,我们要了解这个事实,就是 blog_blog 表已经存在于FROM从句中

    The resulting SQL of the above example would be:

    SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count
    FROM blog_blog;
    

    要注意的是,大多数数据库需要在子句两端添加括号,而在 Django 的select从句中却无须这样。 另请注意,某些数据库后端(如某些MySQL版本)不支持子查询。

    在少数情况下,您可能希望将参数传递到extra(select = ...)中的SQL片段。For this purpose, use the select_params parameter. Since select_params is a sequence and the select attribute is a dictionary, some care is required so that the parameters are matched up correctly with the extra select pieces. In this situation, you should use a collections.OrderedDict for the select value, not just a normal Python dictionary.

    This will work, for example:

    Blog.objects.extra(
        select=OrderedDict([('a', '%s'), ('b', '%s')]),
        select_params=('one', 'two'))
    

    If you need to use a literal %s inside your select string, use the sequence %%s.

    Changed in Django 1.8:

    Prior to 1.8, you were unable to escape a literal %s.

  • where / tables

    您可以使用where定义显式SQL WHERE子句 - 也许执行非显式连接。您可以使用tables手动将表添加到SQL FROM子句。

    wheretables都接受字符串列表。所有where参数均为“与”任何其他搜索条件。

    Example:

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

    ...translates (roughly) into the following SQL:

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

    Be careful when using the tables parameter if you’re specifying tables that are already used in the query. When you add extra tables via the tables parameter, Django assumes you want that table included an extra time, if it is already included. That creates a problem, since the table name will then be given an alias. If a table appears multiple times in an SQL statement, the second and subsequent occurrences must use aliases so the database can tell them apart. If you’re referring to the extra table you added in the extra where parameter this is going to cause errors.

    Normally you’ll only be adding extra tables that don’t already appear in the query. However, if the case outlined above does occur, there are a few solutions. First, see if you can get by without including the extra table and use the one already in the query. If that isn’t possible, put your extra() call at the front of the queryset construction so that your table is the first use of that table. Finally, if all else fails, look at the query produced and rewrite your where addition to use the alias given to your extra table. The alias will be the same each time you construct the queryset in the same way, so you can rely upon the alias name to not change.

  • order_by

    如果您需要使用通过extra()包含的一些新字段或表来对结果查询进行排序,请使用order_by参数extra()并传入一个字符串序列。这些字符串应该是模型字段(如查询集上的正常order_by()方法),形式为table_name.column_name或您在select参数到extra()

    For example:

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

    This would sort all the items for which is_recent is true to the front of the result set (True sorts before False in a descending ordering).

    This shows, by the way, that you can make multiple calls to extra() and it will behave as you expect (adding new constraints each time).

  • params

    The where parameter described above may use standard Python database string placeholders — '%s' to indicate parameters the database engine should automatically quote. The params argument is a list of any extra parameters to be substituted.

    Example:

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

    Always use params instead of embedding values directly into where because params will ensure values are quoted correctly according to your particular backend. For example, quotes will be escaped correctly.

    Bad:

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

    Good:

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

Warning

If you are performing queries on MySQL, note that MySQL’s silent type coercion may cause unexpected results when mixing types. If you query on a string type column, but with an integer value, MySQL will coerce the types of all values in the table to an integer before performing the comparison.For example, if your table contains the values 'abc', 'def' and you query for WHERE mycolumn=0, both rows will match. To prevent this, perform the correct typecasting before using the value in a query.

defer

defer(*fields)

在一些复杂的数据建模情况下,您的模型可能包含大量字段,其中一些可能包含大量数据(例如,文本字段),或者需要昂贵的处理来将它们转换为Python对象。如果您在某些情况下使用查询集的结果,当您最初获取数据时不知道是否需要这些特定字段,可以告诉Django不要从数据库中检索它们。

这是通过传递字段名称不加载到defer()

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

具有延迟字段的查询集仍将返回模型实例。如果您访问该字段(一次一个,而不是一次所有的延迟字段),将从数据库中检索每个延迟字段。

您可以多次调用defer()每个调用都向延迟集添加新字段:

# Defers both the body and headline fields.
Entry.objects.defer("body").filter(rating=5).defer("headline")

The order in which fields are added to the deferred set does not matter. Calling defer() with a field name that has already been deferred is harmless (the field will still be deferred).

You can defer loading of fields in related models (if the related models are loading via select_related()) by using the standard double-underscore notation to separate related fields:

Blog.objects.select_related().defer("entry__headline", "entry__body")

If you want to clear the set of deferred fields, pass None as a parameter to defer():

# Load all fields immediately.
my_queryset.defer(None)

Some fields in a model won’t be deferred, even if you ask for them. You can never defer the loading of the primary key. If you are using select_related() to retrieve related models, you shouldn’t defer the loading of the field that connects from the primary model to the related one, doing so will result in an error.

Note

The defer() method (and its cousin, only(), below) are only for advanced use-cases. They provide an optimization for when you have analyzed your queries closely and understand exactly what information you need and have measured that the difference between returning the fields you need and the full set of fields for the model will be significant.

即使你认为你是在高级用例的情况下,当你不能在查询集加载时确定是否需要额外的字段,只使用defer()If you are frequently loading and using a particular subset of your data, the best choice you can make is to normalize your models and put the non-loaded data into a separate model (and database table). 如果列必须由于某种原因保留在一个表中,请创建一个具有Meta.managed = false(请参阅managed attribute文档)的模型,只包含您通常需要加载和使用的字段否则调用defer()This makes your code more explicit to the reader, is slightly faster and consumes a little less memory in the Python process.

For example, both of these models use the same underlying database table:

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.all().defer('f2')

If many fields need to be duplicated in the unmanaged model, it may be best to create an abstract model with the shared fields and then have the unmanaged and managed models inherit from the abstract model.

Note

When calling save() for instances with deferred fields, only the loaded fields will be saved. See save() for more details.

only

only(*fields)

only()方法或多或少与defer()相反。您调用它时,应该在检索模型时延迟的字段。如果你有一个模型几乎所有的字段需要延迟,使用only()指定补充的字段集可以导致更简单的代码。

假设您有一个包含字段name, agebiography的模型。以下两个查询集是相同的,就延迟字段而言:

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

Since defer() acts incrementally (adding fields to the deferred list), you can combine calls to only() and defer() and things will behave logically:

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

All of the cautions in the note for the defer() documentation apply to only() as well. Use it cautiously and only after exhausting your other options.

Using only() and omitting a field requested using select_related() is an error as well.

Note

When calling save() for instances with deferred fields, only the loaded fields will be saved. See save() for more details.

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)

返回一个 queryset  ,会锁定相关行直到事务结束。在支持的数据库上面产生一个SELECT ... FOR UPDATE 语句

例如:

entries = Entry.objects.select_for_update().filter(author=request.user)

所有匹配的行将被锁定,直到事务结束。这意味着可以通过锁防止数据被其它事务修改。

一般情况下如果其他事务锁定了相关行,那么本查询将被阻塞,直到锁被释放。如果这不是你想要的行为,请使用select_for_update(nowait=True). 这将使查询不阻塞。如果其它事务持有冲突的锁, 那么查询将引发 DatabaseError 异常.

目前,postgresql_psycopg2, oraclemysql 数据库后端支持 select_for_update().但是 MySQL 不支持 nowait 参数。显然,用户应该检查后端的支持情况。

当在不支持nowait功能的数据库后端(例如 MySql) 使用nowait=True 参数调用 select_for_update()  时将引发 DatabaseError 异常. 这是防止意外造成代码被阻塞。

在自动提交模式下使用 select_for_update() 将引发 TransactionManagementError 异常,原因是自动提交模式下不支持锁定行。如果允许这个调用,那么可能造成数据损坏,而且这个功能很容易在事务外被调用。

对于不支持 SELECT ... FOR UPDATE 的后端 (例如SQLite)  select_for_update() 将没有效果。

Changed in Django 1.6.3:

It is now an error to execute a query with select_for_update() in autocommit mode. With earlier releases in the 1.6 series it was a no-op.

Warning

Although select_for_update() normally fails in autocommit mode, since TestCase automatically wraps each test in a transaction, calling select_for_update() in a TestCase even outside an atomic() block will (perhaps unexpectedly) pass without raising a TransactionManagementError. To properly test select_for_update() you should use TransactionTestCase.

raw

raw(raw_query, params=None, translations=None)
Changed in Django 1.7:

raw 移动到QuerySet 类中。以前,它只位于Manager 中。

接收一个原始的SQL 查询,执行它并返回一个django.db.models.query.RawQuerySet 实例。这个RawQuerySet 实例可以迭代以提供实例对象,就像普通的QuerySet 一样。

更多信息参见执行原始的SQL 查询

警告

raw() 永远触发一个新的查询,而与之前的filter 无关。因此,它通常应该从Manager 或一个全新的QuerySet 实例调用。

不会返回QuerySets的方法

以下QuerySet方法评估QuerySet并返回而不是 一个 QuerySet

These methods do not use a cache (see Caching and QuerySets). 这些方法每次被调用的时候都会查询数据库。

get

get(**kwargs)

返回按照查询参数匹配到的对象,参数的格式应该符合 Field lookups的要求.

如果匹配到的对象个数不只一个的话,get() 将会触发MultipleObjectsReturned 异常. MultipleObjectsReturned 异常是模型类的属性.

如果根据给出的参数匹配不到对象的话,get() 将触发DoesNotExist 异常. 这个异常是模型类的属性. Example:

Entry.objects.get(id='foo') # raises Entry.DoesNotExist

The DoesNotExist exception inherits from django.core.exceptions.ObjectDoesNotExist, so you can target multiple DoesNotExist exceptions. Example:

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

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)

是等同的.

参数 force_insert 在其他的文档中有介绍, 它意味着一个新的对象一定会被创建. 正常情况中,你不必要担心这点. 然而, 如果你的model中有一个你手动设置主键, 并且这个值已经存在于数据库中, 调用 create()将会失败并且触发 IntegrityError 因为主键必须是唯一的. 如果你手动设置了主键,做好异常处理的准备.

get_or_create

get_or_create(defaults=None, **kwargs)

一个通过给出的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()

如果模型的字段数量较大的话,这种模式就变的非常不易用了。上面的示例可以用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 将引发MultipleObjectsReturned如果查找不到对象get_or_create() 将会实例化并保存一个新的对象,返回一个由新的对象以及True 组成的元组。新的对象将会大概按照以下的逻辑创建:

params = {k: v for k, v in kwargs.items() if '__' not in k}
params.update(defaults)
obj = self.model(**params)
obj.save()

它表示从非'defaults' 且不包含双下划线的关键字参数开始(暗示这是一个不精确的查询)。然后将defaults 的内容添加进来,覆盖必要的键,并使用结果作为关键字参数传递给模型类。这是对用到的算法的简单描述,但它包含了所有的相关的细节。内部的实现有更多的错误检查并处理一些边缘条件;如果感兴趣,请阅读代码。

如果你有一个名为defaults的字段,并且想在get_or_create() 是用它作为精确查询,只需要使用'defaults__exact',像这样:

Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'})

当你使用手动指定的主键时,get_or_create() 方法与create()方法有相似的错误行为 。如果需要创建一个对象而该对象的主键早已存在于数据库中,IntegrityError 异常将会被触发。

这个方法假设正确使用原子操作,正确的数据库配置和底层数据库的正确行为。然而,如果数据库级别没有对get_or_create 中用到的kwargs 强制要求唯一性(参见uniqueunique_together),这个方法容易导致竞态条件可能会仍具有相同参数的多行同时插入。

如果你正在使用MySQL,请确保使用READ COMMITTED 隔离级别而不是默认的REPEATABLE READ,否则你将会遇到get_or_create 引发IntegrityError 但对象在接下来的get() 调用中并不存在的情况。

最后讲一句get_or_create() 在Django 视图中的使用。请确保只在POST 请求中使用,除非你有充分的理由。GET 请求不应该对数据有任何影响。POST 则用于对数据产生影响的请求。更多信息,参见HTTP 细则中的安全的方法

警告

你可以通过ManyToManyField 属性和反向关联使用get_or_create()在这种情况下,你应该限制查询在关联的上下文内部。如果你不一致地使用它,将可能导致完整性问题。

根据下面的模型:

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 的chapters 字段使用get_or_create(),但是它只会获取该Book 内部的上下文:

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

发生这个错误时因为它尝试通过Book “Ulysses” 获取或者创建“Chapter 1”,但是它不能:关联关系不能获取这个chapter 因为它与这个book 不关联,但因为title 字段是唯一的它仍然不能创建。

update_or_create

update_or_create(defaults=None, **kwargs)
New in Django 1.7.

一个通过给出的kwargs 来更新对象的便捷方法, 如果需要的话创建一个新的对象。defaults 是一个由 (field, value) 对组成的字典,用于更新对象。

返回一个由 (object, created)组成的元组,元组中的object 是一个创建的或者是被更新的对象, created 是一个标示是否创建了新的对象的布尔值。

update_or_create 方法尝试通过给出的kwargs 去从数据库中获取匹配的对象。如果找到匹配的对象,它将会依据defaults 字典给出的值更新字段。

这用作样板代码的一种快捷方式。例如:

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

如果模型的字段数量较大的话,这种模式就变的非常不易用。上面的示例可以用 update_or_create() 重写:

obj, created = Person.objects.update_or_create(
    first_name='John', last_name='Lennon', defaults=updated_values)

kwargs 中的名称如何解析的详细描述可以参见get_or_create()

和上文描述的get_or_create() 一样,这个方式容易导致竞态条件,如果数据库层级没有前置唯一性它会让多行同时插入。

bulk_create

bulk_create(objs, batch_size=None)

此方法以有效的方式(通常只有1个查询,无论有多少对象)将提供的对象列表插入到数据库中:

>>> Entry.objects.bulk_create([
...     Entry(headline="Django 1.0 Released"),
...     Entry(headline="Django 1.1 Announced"),
...     Entry(headline="Breaking: Django is awesome")
... ])

这有一些注意事项:

  • 将不会调用模型的save()方法,并且不会发送pre_savepost_save信号。
  • 它不适用于多表继承场景中的子模型。
  • 如果模型的主键是AutoField,它不会像save()那样检索和设置主键属性。
  • 它不适用于多对多关系。

batch_size参数控制在单个查询中创建的对象数。默认值是在一个批处理中创建所有对象,除了SQLite,其中默认值为每个查询最多使用999个变量。

count

count()

返回在数据库中对应的 QuerySet.对象的个数。 count() 永远不会引发异常。

Example:

# Returns the total number of entries in the database.
Entry.objects.count()

# Returns the number of entries whose headline contains 'Lennon'
Entry.objects.filter(headline__contains='Lennon').count()

count()在后台执行SELECT COUNT(*) count(),而不是将所有的记录加载到Python对象中并在结果上调用len()(除非你需要将对象加载到内存中, len()会更快)。

根据您使用的数据库(例如PostgreSQL vs. MySQL),count()可能返回一个长整型而不是普通的Python整数。这是一个潜在的实现方案,不应该引起任何真实世界的问题。

请注意,如果您想要QuerySet中的项目数量,并且还要从中检索模型实例(例如,通过迭代它),使用len(查询集)更有效,这不会像count()一样导致额外的数据库查询。

in_bulk

in_bulk(id_list)

获取主键值的列表,并返回将每个主键值映射到具有给定ID的对象的实例的字典。

Example:

>>> 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([])
{}

如果你传递in_bulk()一个空列表,你会得到一个空的字典。

iterator

iterator()

评估QuerySet(通过执行查询),并返回一个迭代器(参见 PEP 234)。QuerySet通常在内部缓存其结果,以便在重复计算是不会导致额外的查询。相反,iterator()将直接读取结果,而不在QuerySet级别执行任何缓存(内部,默认迭代器调用iterator()并高速缓存返回值)。对于返回大量只需要访问一次的对象的QuerySet,这可以带来更好的性能和显着减少内存。

请注意,在已经求值了的QuerySet上使用iterator()会强制它再次计算,重复查询。

此外,使用iterator()会导致先前的prefetch_related()调用被忽略,因为这两个优化一起没有意义。

警告

一些Python数据库驱动程序如psycopg2如果使用客户端游标(使用connection.cursor()实例化和Django的ORM使用)执行缓存。使用iterator()不会影响数据库驱动程序级别的缓存。要禁用此缓存,请查看服务器端游标

latest

latest(field_name=None)

使用作为日期字段提供的field_name,按日期返回表中的最新对象。

此示例根据pub_date字段返回表中的最新条目

Entry.objects.latest('pub_date')

如果模型的Meta指定get_latest_by,则可以将field_name参数留给earliest()或者 latest()默认情况下,Django将使用get_latest_by中指定的字段。

get()earliest()latest() raise DoesNotExist参数。

请注意,earliest()latest()仅仅是为了方便和可读性。

earliest

earliest(field_name=None)

除非方向更改,否则像latest()

first

first()

返回结果集的第一个对象, 当没有找到时返回None.如果 QuerySet 没有设置排序,则将会自动按主键进行排序

Example:

p = Article.objects.order_by('title', 'pub_date').first()

笔记:first() 是一个简便方法 下面这个例子和上面的代码效果是一样

try:
    p = Article.objects.order_by('title', 'pub_date')[0]
except IndexError:
    p = None

last

last()

工作方式类似first(),只是返回的是查询集中最后一个对象。

aggregate(聚合查询)

aggregate(*args, **kwargs)

返回一个字典,包含根据QuerySet 计算得到的聚合值(平均数、和等等)。aggregate() 的每个参数指定返回的字典中将要包含的值。

Django 提供的聚合函数在下文的聚合函数中讲述。因为聚合也是查询表达式,你可以组合多个聚合以及值来创建复杂的聚合。

使用关键字参数指定的聚合将使用关键字参数的名称作为Annotation 的名称。匿名的参数的名称将基于聚合函数的名称和模型字段生成。复杂的聚合不可以使用匿名参数,它们必须指定一个关键字参数作为别名。

例如,当你使用Blog Entry 时,你可能想知道对Author 贡献的Blog Entry 的数目:

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

exists()

如果QuerySet 包含任何结果,则返回True,否则返回False它会试图用最简单和最快的方法完成查询,但它执行的方法与普通的QuerySet 查询确实几乎相同。

exists() 用于搜寻对象是否在QuerySet 中以及QuerySet 是否存在任何对象,特别是QuerySet 比较大的时候。

查找具有唯一性字段(例如primary_key)的模型是否在一个QuerySet 中的最高效的方法是:

entry = Entry.objects.get(pk=123)
if some_queryset.filter(pk=entry.pk).exists():
    print("Entry contained in queryset")

它将比下面的方法快很多,这个方法要求对QuerySet 求值并迭代整个QuerySet:

if entry in some_queryset:
   print("Entry contained in QuerySet")

若要查找一个QuerySet 是否包含任何元素:

if some_queryset.exists():
    print("There is at least one object in some_queryset")

将快于:

if some_queryset:
    print("There is at least one object in some_queryset")

... 但不会快很多(因为这需要很大的QuerySet 以获得效率的提升)。

另外,如果some_queryset 还没有求值,但你知道它将在某个时刻求值,那么使用some_queryset.exists() 将比简单地使用bool(some_queryset) 完成更多的工作(一个查询用于存在性检查,另外一个是后面的求值),后者将求值并检查是否有结果返回。

update

update(**kwargs)

对指定的字段执行SQL更新查询,并返回匹配的行数(如果某些行已具有新值,则可能不等于已更新的行数)。

例如,要对2010年发布的所有博客条目启用评论,您可以执行以下操作:

>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)

(假设您的输入模型具有字段pub_datecomments_on。)

您可以更新多个字段 - 没有多少字段的限制。例如,在这里我们更新comments_on标题字段:

>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False, headline='This is old')

update()方法立即应用,对更新的QuerySet的唯一限制是它只能更新模型主表中的列,而不是相关模型。你不能这样做,例如:

>>> Entry.objects.update(blog__name='foo') # Won't work!

仍然可以根据相关字段进行过滤:

>>> Entry.objects.filter(blog__id=1).update(comments_on=True)

您不能在QuerySet上调用update(),该查询已截取一个切片,或者无法再进行过滤。

update()方法返回受影响的行数:

>>> Entry.objects.filter(id=64).update(comments_on=True)
1

>>> Entry.objects.filter(slug='nonexistent-slug').update(comments_on=True)
0

>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)
132

如果你只是更新一个记录,不需要对模型对象做任何事情,最有效的方法是调用update(),而不是将模型对象加载到内存中。例如,而不是这样做:

e = Entry.objects.get(id=10)
e.comments_on = False
e.save()

...do this:

Entry.objects.filter(id=10).update(comments_on=False)

使用update()还可以防止在加载对象和调用save()之间的短时间内数据库中某些内容可能发生更改的竞争条件。

Finally, realize that update() does an update at the SQL level and, thus, does not call any save() methods on your models, nor does it emit the pre_save or post_save signals (which are a consequence of calling Model.save()). 如果你想更新一个具有自定义save()方法的模型的记录,请循环遍历它们并调用save(),如下所示:

for e in Entry.objects.filter(pub_date__year=2010):
    e.comments_on = False
    e.save()

delete

delete()

QuerySet中的所有行执行SQL删除查询。立即应用delete()您不能在QuerySet上调用delete(),该查询已采取切片或以其他方式无法过滤。

例如,要删除特定博客中的所有条目:

>>> b = Blog.objects.get(pk=1)

# Delete all the entries belonging to this Blog.
>>> Entry.objects.filter(blog=b).delete()

默认情况下,Django的ForeignKey模拟SQL约束ON DELETE CASCADE字,任何具有指向要删除的对象的外键的对象将与它们一起被删除。例如:

blogs = Blog.objects.all()
# This will delete all Blogs and all of their Entry objects.
blogs.delete()

此级联行为可通过ForeignKeyon_delete参数自定义。

delete()方法执行批量删除,并且不会在模型上调用任何delete()方法。但它会为所有已删除的对象(包括级联删除)发出pre_deletepost_delete信号。

Django需要获取对象到内存中以发送信号和处理级联。然而,如果没有级联和没有信号,那么Django可以采取快速路径并删除对象而不提取到内存中。对于大型删除,这可以显着减少内存使用。执行的查询量也可以减少。

设置为on_delete DO_NOTHING的外键不会阻止删除快速路径。

请注意,在对象删除中生成的查询是实施详细信息,可能会更改。

as_manager

classmethod as_manager()
New in Django 1.7.

Class method that returns an instance of Manager with a copy of the QuerySet’s methods. See Creating Manager with QuerySet methods for more details.

字段查找

字段查询是指如何指定SQL WHERE子句的内容. 它们通过查询集filter(), exclude() and get()的关键字参数指定.

查阅简介, 请参考 模型与数据库查询.

Django’s inbuilt lookups are listed below. It is also possible to write custom lookups for model fields.

As a convenience when no lookup type is provided (like in Entry.objects.get(id=14)) the lookup type is assumed to be exact.

exact

精确匹配。If the value provided for comparison is None, it will be interpreted as an SQL NULL (see isnull for more details).

Examples:

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

SQL equivalents:

SELECT ... WHERE id = 14;
SELECT ... WHERE id IS NULL;

MySQL comparisons

In MySQL, a database table’s “collation” setting determines whether exact comparisons are case-sensitive. This is a database setting, not a Django setting. It’s possible to configure your MySQL tables to use case-sensitive comparisons, but some trade-offs are involved. For more information about this, see the collation section in the databases documentation.

iexact

不区分大小写的精确匹配

Changed in Django 1.7:

If the value provided for comparison is None, it will be interpreted as an SQL NULL (see isnull for more details).

Example:

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

SQL equivalents:

SELECT ... WHERE name ILIKE 'beatles blog';
SELECT ... WHERE name IS NULL;

请注意,第一个查询将匹配 'Beatles Blog', 'beatles blog', 'BeAtLes BLoG', etc.

SQLite用户

当使用SQLite后端和Unicode(非ASCII)字符串时,请记住关于字符串比较的数据库注释SQLite不对Unicode字符串进行不区分大小写的匹配。

contains

区分大小写的包含例子。

Example:

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

SQL equivalent:

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

请注意,这将匹配标题'Lennon honored today',但不符合'lennon honored today'.

SQLite users

SQLite不支持区分大小写的LIKE语句;contains 用于SQLite的icontains有关详细信息,请参阅数据库注释

icontains

不区分大小写的遏制试验。

Example:

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

SQL equivalent:

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

SQLite users

当使用SQLite后端和Unicode(非ASCII)字符串时,请记住关于字符串比较的数据库注释

in

在给定的列表。

Example:

Entry.objects.filter(id__in=[1, 3, 4])

SQL equivalent:

SELECT ... WHERE id IN (1, 3, 4);

您还可以使用查询集动态评估值列表,而不是提供文字值列表:

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

此查询集将作为subselect语句求值:

SELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')

如果您传入ValuesQuerySetValuesListQuerySet(调用values()values_list()查询集)作为__在查找的值,您需要确保您只提取结果中的一个字段。例如,这将工作(过滤博客名称):

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

这个例子将产生一个异常,由于内查询试图提取两个字段的值,但是查询语句只期望提取一个字段的值:

# Bad code! Will raise a TypeError.
inner_qs = Blog.objects.filter(name__contains='Ch').values('name', 'id')
entries = Entry.objects.filter(blog__name__in=inner_qs)

性能注意事项

对于使用嵌套查询和了解数据库服务器的性能特征(如果有疑问,去做基准测试)要谨慎。一些数据库后端,最着名的是MySQL,不能很好地优化嵌套查询。在这些情况下,提取值列表然后将其传递到第二个查询中更有效。也就是说,执行两个查询,而不是一个:

values = Blog.objects.filter(
        name__contains='Cheddar').values_list('pk', flat=True)
entries = Entry.objects.filter(blog__in=list(values))

请注意list()调用Blog QuerySet以强制执行第一个查询。没有它,将执行嵌套查询,因为QuerySet是惰性的

gt

大于

例子:

Entry.objects.filter(id__gt=4)

SQL语句相当于:

SELECT ... WHERE id > 4;

gte

大于或等于

lt

小于

lte

小于或等于

startswith

区分大小写,开始位置匹配

Example:

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

SQL equivalent:

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

SQLite 不支持区分大小写 LIKE 语句; Sqlite 下startswith 等于 istartswith .

istartswith

不区分大小写,开始位置匹配

Example:

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

SQL equivalent:

SELECT ... WHERE headline ILIKE 'Will%';

SQLite users

当使用SQLite后端和Unicode(非ASCII)字符串时,请记住关于字符串比较的数据库注释

endswith

区分大小写。

例:

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

SQL等效:

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

SQLite users

SQLite不支持区分大小写的LIKE语句;endswith用作SQLite的iendswith有关更多信息,请参阅数据库注释文档。

iendswith

不区分大小写。

Example:

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

SQL equivalent:

SELECT ... WHERE headline ILIKE '%will'

SQLite users

当使用SQLite后端和Unicode(非ASCII)字符串时,请记住关于字符串比较的数据库注释

range

范围测试(包含于之中)。

Example:

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

SQL equivalent:

SELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31';

您可以在任何可以使用BETWEEN的SQL中使用范围(对于日期,数字和偶数字符)。

Warning

过滤具有日期的DateTimeField不会包含最后一天的项目,因为边界被解释为“给定日期的0am”。如果pub_dateDateTimeField,上面的表达式将变成这个SQL:

SELECT ... WHERE pub_date BETWEEN '2005-01-01 00:00:00' and '2005-03-31 00:00:00';

一般来说,不能混合使用日期和数据时间。

year

对于日期和日期时间字段,确切的年匹配。整数年。

Example:

Entry.objects.filter(pub_date__year=2005)

SQL equivalent:

SELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31';

(确切的SQL语法因每个数据库引擎而异)。

USE_TZTrue时,在过滤之前,datetime字段将转换为当前时区。

month

对于日期和日期时间字段,确切的月份匹配。取整数1(1月)至12(12月)。

Example:

Entry.objects.filter(pub_date__month=12)

SQL equivalent:

SELECT ... WHERE EXTRACT('month' FROM pub_date) = '12';

(The exact SQL syntax varies for each database engine.)

USE_TZTrue时,在过滤之前,datetime字段将转换为当前时区。这需要数据库中的时区定义

day

对于日期和日期时间字段,具体到某一天的匹配。取一个整数的天数。

Example:

Entry.objects.filter(pub_date__day=3)

SQL equivalent:

SELECT ... WHERE EXTRACT('day' FROM pub_date) = '3';

(确切的SQL语法因每个数据库引擎而异)。

请注意,这将匹配每月第三天(例如1月3日,7月3日等)的任何包含pub_date的记录。

USE_TZTrue时,在过滤之前,datetime字段将转换为当前时区。This requires time zone definitions in the database.

week_day

对于日期和日期时间字段,“星期几”匹配。

取整数值,表示星期几从1(星期日)到7(星期六)。

Example:

Entry.objects.filter(pub_date__week_day=2)

(此查找不包括等效的SQL代码片段,因为相关查询的实现因不同数据库引擎而异)。

请注意,这将匹配落在星期一(星期二)的任何记录(pub_date),而不管其出现的月份或年份。Week days are indexed with day 1 being Sunday and day 7 being Saturday.

USE_TZTrue时,在过滤之前,datetime字段将转换为当前时区。这需要数据库中的时区定义

hour

对于日期时间字段,精确的小时匹配。取0和23之间的整数。

Example:

Event.objects.filter(timestamp__hour=23)

SQL equivalent:

SELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23';

(确切的SQL语法因每个数据库引擎而异)。

USE_TZTrue时,在过滤之前将值转换为当前时区。

minute

对于日期时间字段,精确的分钟匹配。取0和59之间的整数。

Example:

Event.objects.filter(timestamp__minute=29)

SQL equivalent:

SELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29';

(确切的SQL语法因每个数据库引擎而异)。

USE_TZTrue时,在过滤之前将值转换为当前时区。

second

对于datetime字段,精确的第二个匹配。取0和59之间的整数。

Example:

Event.objects.filter(timestamp__second=31)

等同于SQL语句:

SELECT ... WHERE EXTRACT('second' FROM timestamp) = '31';

(确切的SQL语法因每个数据库引擎而异)。

USE_TZTrue时,在过滤之前将值转换为当前时区。

isnull

值为 TrueFalse, 相当于 SQL语句IS NULLIS NOT NULL.

Example:

Entry.objects.filter(pub_date__isnull=True)

SQL equivalent:

SELECT ... WHERE pub_date IS NULL;

regex

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

正则表达式语法是正在使用的数据库后端的语法。在SQLite没有内置正则表达式支持的情况下,此功能由(Python)用户定义的REGEXP函数提供,因此正则表达式语法是Python的re模块。

Example:

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

SQL equivalents:

SELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL

SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'c'); -- Oracle

SELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL

SELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite

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

iregex

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

Example:

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

SQL equivalents:

SELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL

SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle

SELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL

SELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite

聚合函数

Django 的django.db.models 模块提供以下聚合函数。关于如何使用这些聚合函数的细节,参见聚合函数的指南关于如何创建聚合函数,参数聚合函数 的文档。

警告

SQLite 不能直接处理日期/时间字段的聚合。这是因为SQLite 中没有原生的日期/时间字段,Django 目前使用文本字段模拟它的功能。在SQLite 中对日期/时间字段使用聚合将引发NotImplementedError

QuerySet 为空时,聚合函数函数将返回None例如,如果QuerySet 中没有记录,Sum 聚合函数将返回None 而不是0Count 是一个例外,如果QuerySet 为空,它将返回0

所有聚合函数具有以下共同的参数:

expression

引用模型字段的一个字符串,或者一个查询表达式

New in Django 1.8:

现在在复杂的计算中,聚合函数可以引用多个字段。

output_field

用来表示返回值的模型字段,它是一个可选的参数。

New in Django 1.8:

添加output_field 参数。

在组合多个类型的字段时,只有在所有的字段都是相同类型的情况下,Django 才能确定output_field否则,你必须自己提供output_field 参数。

**extra

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

avg

class Avg(expression, output_field=None, **extra)

返回给定expression 的平均值,其中expression 必须为数值。

  • 默认的别名:<field>__avg
  • 返回类型:float

Count

class Count(expression, distinct=False, **extra)

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

  • 默认的别名:<field>__count
  • 返回类型:int

有一个可选的参数:

distinct

如果distinct=True,Count 将只计算唯一的实例。它等同于COUNT(DISTINCT <field>) SQL 语句。默认值为False

Max

class Max(expression, output_field=None, **extra)

返回expression 的最大值。

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

Min

class Min(expression, output_field=None, **extra)

返回expression 的最小值。

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

StdDev

class StdDev(expression, sample=False, **extra)

返回expression 的标准差。

  • 默认的别名:<field>__stddev
  • 返回类型:float

有一个可选的参数:

sample

默认情况下,StdDev 返回群体的标准差。但是,如果sample=True,返回的值将是样本的标准差。

SQLite

SQLite 没有直接提供StdDev有一个可用的实现是SQLite 的一个扩展模块。参见SQlite 的文档 中获取并安装这个扩展的指南。

Sum

class Sum(expression, output_field=None, **extra)

计算expression 的所有值的和。

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

Variance

class Variance(expression, sample=False, **extra)

返回expression 的方差。

  • 默认的别名:<field>__variance
  • 返回的类型:float

有一个可选的参数:

sample

默认情况下,Variance 返回群体的方差。但是,如果sample=True,返回的值将是样本的方差。

SQLite

SQLite 没有直接提供Variance有一个可用的实现是SQLite 的一个扩展模块。 参见SQlite 的文档 中获取并安装这个扩展的指南。