条件表达式

在后续的例子中，我们将使用以下模型：

class When(condition=None, then=None, \*lookups*)

When() 对象用于封装一个条件及其结果，以便在条件表达式中使用。使用 When() 对象类似于使用 filter() 方法。可以使用 、 Q 对象或 对象来指定条件，这些对象的 output_field 是 BooleanField。结果是用 then 关键字提供的。

Changed in Django 4.0:

Support for lookup expressions was added.

一些例子：

>>> from django.db.models import F, Q, When
>>> # String arguments refer to fields; the following two examples are equivalent:
>>> When(account_type=Client.GOLD, then='name')
>>> When(account_type=Client.GOLD, then=F('name'))
>>> # You can use field lookups in the condition
>>> from datetime import date
>>> When(registered_on__gt=date(2014, 1, 1),
...      registered_on__lt=date(2015, 1, 1),
...      then='account_type')
>>> # Complex conditions can be created using Q objects
>>> When(Q(name__startswith="John") | Q(name__startswith="Paul"),
...      then='name')
>>> # Condition can be created using boolean expressions.
>>> from django.db.models import Exists, OuterRef
>>> non_unique_account_type = Client.objects.filter(
...     account_type=OuterRef('account_type'),
... ).exclude(pk=OuterRef('pk')).values('pk')
>>> When(Exists(non_unique_account_type), then=Value('non unique'))
>>> # Condition can be created using lookup expressions.
>>> from django.db.models.lookups import GreaterThan, LessThan
>>> When(
...     GreaterThan(F('registered_on'), date(2014, 1, 1)) &
...     LessThan(F('registered_on'), date(2015, 1, 1)),
...     then='account_type',
... )

请记住，每个值都可以是一个表达式。

注解

>>> When(then__exact=0, then=1)
>>> When(Q(then=0), then=1)

Changed in Django 3.2:

增加了对在 lookups 中使用 condition 参数的支持。

class Case(\cases, **extra*)

Case() 表达式就像 Python 中的 … elif… 语句。在提供的 When() 对象中的每个 condition 按顺序执行，直到执行出一个对的值。从匹配的 When() 对象中返回 result 表达式。

一个例子：

>>>
>>> from datetime import date, timedelta
>>> Client.objects.create(
...     account_type=Client.REGULAR,
...     registered_on=date.today() - timedelta(days=36))
>>> Client.objects.create(
...     name='James Smith',
...     account_type=Client.GOLD,
...     registered_on=date.today() - timedelta(days=5))
>>> Client.objects.create(
...     name='Jack Black',
...     account_type=Client.PLATINUM,
...     registered_on=date.today() - timedelta(days=10 * 365))
>>> # Get the discount for each Client based on the account type
>>> Client.objects.annotate(
...     discount=Case(
...         When(account_type=Client.GOLD, then=Value('5%')),
...         When(account_type=Client.PLATINUM, then=Value('10%')),
...         default=Value('0%'),
...     ),
... ).values_list('name', 'discount')
<QuerySet [('Jane Doe', '0%'), ('James Smith', '5%'), ('Jack Black', '10%')]>

Case() 接受任意数量的 When() 对象作为单个参数。其他选项是通过关键字参数提供的。如果没有一个条件的值是 TRUE，那么将返回用 default 关键字参数给出的表达式。如果没有提供 default 参数，则使用 None。

如果我们想改变之前的查询，根据 Client 与我们合作的时间长短来获取折扣，我们可以使用查找：

注解

Case() 也可以在 filter() 子句中使用。例如，要查找一个月前注册的黄金客户和一年前注册的白金客户：

>>> a_month_ago = date.today() - timedelta(days=30)
>>> a_year_ago = date.today() - timedelta(days=365)
>>> Client.objects.filter(
...     registered_on__lte=Case(
...         When(account_type=Client.GOLD, then=a_month_ago),
...         When(account_type=Client.PLATINUM, then=a_year_ago),
...     ),
... ).values_list('name', 'account_type')
<QuerySet [('Jack Black', 'P')]>

高级查询

条件表达式可用于注解、聚合、过滤器、查找和更新中。它们还可以与其他表达式组合和嵌套。这使你可以进行强大的条件查询。

比方说，我们想改变客户的 account_type 以匹配他们的注册日期。我们可以使用一个条件表达式和 方法来实现这个目标：

>>> a_month_ago = date.today() - timedelta(days=30)
>>> a_year_ago = date.today() - timedelta(days=365)
>>> # Update the account_type for each Client from the registration date
>>> Client.objects.update(
...     account_type=Case(
...         When(registered_on__lte=a_year_ago,
...              then=Value(Client.PLATINUM)),
...              then=Value(Client.GOLD)),
...         default=Value(Client.REGULAR)
... )
>>> Client.objects.values_list('name', 'account_type')
<QuerySet [('Jane Doe', 'G'), ('James Smith', 'R'), ('Jack Black', 'P')]>

如果我们想知道每个 account_type 有多少个客户？我们可以使用 聚合函数 的 filter 参数来实现：

>>> # Create some more Clients first so we can have something to count
>>> Client.objects.create(
...     name='Jean Grey',
...     account_type=Client.REGULAR,
...     registered_on=date.today())
>>> Client.objects.create(
...     name='James Bond',
...     account_type=Client.PLATINUM,
...     registered_on=date.today())
>>> Client.objects.create(
...     name='Jane Porter',
...     account_type=Client.PLATINUM,
...     registered_on=date.today())
>>> # Get counts for each value of account_type
>>> from django.db.models import Count
>>> Client.objects.aggregate(
...     regular=Count('pk', filter=Q(account_type=Client.REGULAR)),
...     gold=Count('pk', filter=Q(account_type=Client.GOLD)),
...     platinum=Count('pk', filter=Q(account_type=Client.PLATINUM)),
... )
{'regular': 2, 'gold': 1, 'platinum': 3}

在支持 SQL 2003 FILTER WHERE 语法的数据库上，这个聚合产生一个查询。

在其他数据库中，这是用 CASE 语句模拟的：

SELECT count(CASE WHEN account_type=1 THEN id ELSE null) as regular,
       count(CASE WHEN account_type=2 THEN id ELSE null) as gold,
       count(CASE WHEN account_type=3 THEN id ELSE null) as platinum
FROM clients;

这两条 SQL 语句在功能上是等同的，但更明确的 FILTER 可能表现得更好。

当条件表达式返回一个布尔值时，可以直接在过滤器中使用它。这意味着它不会被添加到 SELECT 列中，但你仍然可以使用它来过滤结果：

>>> non_unique_account_type = Client.objects.filter(
...     account_type=OuterRef('account_type'),
... ).exclude(pk=OuterRef('pk')).values('pk')
>>> Client.objects.filter(~Exists(non_unique_account_type))

SELECT ...
FROM client c0
WHERE NOT EXISTS (
  SELECT c1.id
  FROM client c1
  WHERE c1.account_type = c0.account_type AND NOT c1.id = c0.id