{"title":"条件表达式","version":"3.1","locale":"zh-hans","docname":"ref/models/conditional-expressions","url":"/zh-hans/3.1/ref/models/conditional-expressions/","canonical":"https://djangodocs.dev/zh-hans/3.1/ref/models/conditional-expressions/","summary":"条件表达式让你可以在过滤器、注解、聚合和更新中使用 if... elif... else 逻辑。条件表达式对表的每条记录执行一系列条件，并返回匹配的结果表达式。","html":"

条件表达式Link to this heading#

\n

条件表达式让你可以在过滤器、注解、聚合和更新中使用 if ... elif ... else 逻辑。条件表达式对表的每条记录执行一系列条件，并返回匹配的结果表达式。条件表达式也可以像其他 表达式 一样进行组合和嵌套。

\n
\n

条件表达式类Link to this heading#

\n

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

\n
Code
from django.db import models\n\nclass Client(models.Model):\n    REGULAR = 'R'\n    GOLD = 'G'\n    PLATINUM = 'P'\n    ACCOUNT_TYPE_CHOICES = [\n        (REGULAR, 'Regular'),\n        (GOLD, 'Gold'),\n        (PLATINUM, 'Platinum'),\n    ]\n    name = models.CharField(max_length=50)\n    registered_on = models.DateField()\n    account_type = models.CharField(\n        max_length=1,\n        choices=ACCOUNT_TYPE_CHOICES,\n        default=REGULAR,\n    )\n
\n
\n

WhenLink to this heading#

\n
\n
\nclass When(condition=None, then=None, **lookups)Link to this definition#
\n
\n\n

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

\n\n

一些例子：

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

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

\n\n
\n
\n

CaseLink to this heading#

\n
\n
\nclass Case(*cases, **extra)Link to this definition#
\n
\n\n

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

\n

一个例子：

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

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

\n

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

\n
Code
>>> a_month_ago = date.today() - timedelta(days=30)\n>>> a_year_ago = date.today() - timedelta(days=365)\n>>> # Get the discount for each Client based on the registration date\n>>> Client.objects.annotate(\n...     discount=Case(\n...         When(registered_on__lte=a_year_ago, then=Value('10%')),\n...         When(registered_on__lte=a_month_ago, then=Value('5%')),\n...         default=Value('0%'),\n...         output_field=CharField(),\n...     )\n... ).values_list('name', 'discount')\n<QuerySet [('Jane Doe', '5%'), ('James Smith', '0%'), ('Jack Black', '10%')]>\n
\n\n

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

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

高级查询Link to this heading#

\n

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

\n
\n

条件更新Link to this heading#

\n

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

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

条件聚合Link to this heading#

\n

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

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

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

\n
SQL
SELECT count('id') FILTER (WHERE account_type=1) as regular,\n       count('id') FILTER (WHERE account_type=2) as gold,\n       count('id') FILTER (WHERE account_type=3) as platinum\nFROM clients;\n
\n

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

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

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

\n
\n
\n

条件过滤Link to this heading#

\n\n

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

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

用 SQL 术语来说，它的值是：

\n
SQL
SELECT ...\nFROM client c0\nWHERE NOT EXISTS (\n  SELECT c1.id\n  FROM client c1\n  WHERE c1.account_type = c0.account_type AND NOT c1.id = c0.id\n)\n
\n
\n
","rootId":"conditional-expressions","toc":[{"title":"条件表达式类","anchor":"the-conditional-expression-classes","children":[{"title":"When","anchor":"when","children":[]},{"title":"Case","anchor":"case","children":[]}]},{"title":"高级查询","anchor":"advanced-queries","children":[{"title":"条件更新","anchor":"conditional-update","children":[]},{"title":"条件聚合","anchor":"conditional-aggregation","children":[]},{"title":"条件过滤","anchor":"conditional-filter","children":[]}]}],"breadcrumbs":[{"docname":"ref/index","title":"API 参考","url":"/zh-hans/3.1/ref/"},{"docname":"ref/models/index","title":"模型","url":"/zh-hans/3.1/ref/models/"}],"prev":{"docname":"ref/models/expressions","title":"查询表达式","url":"/zh-hans/3.1/ref/models/expressions/"},"next":{"docname":"ref/models/database-functions","title":"数据库函数","url":"/zh-hans/3.1/ref/models/database-functions/"},"formats":{"html":"/zh-hans/3.1/ref/models/conditional-expressions/","markdown":"/zh-hans/3.1/ref/models/conditional-expressions.md","json":"/zh-hans/3.1/ref/models/conditional-expressions.json"},"source":"https://github.com/django/django/blob/stable/3.1.x/docs/ref/models/conditional-expressions.txt","official":"https://docs.djangoproject.com/zh-hans/3.1/ref/models/conditional-expressions/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0"],"inLocales":["en","zh-hans","fr","ja","id","pt-br","ko","es","el","pl"]}