{"title":"Conditional Expressions","version":"6.0","locale":"el","docname":"ref/models/conditional-expressions","url":"/el/6.0/ref/models/conditional-expressions/","canonical":"https://djangodocs.dev/el/6.0/ref/models/conditional-expressions/","summary":"Conditional expressions let you use if … elif … else logic within filters, annotations, aggregations, and updates. A conditional expression evaluates a series of…","html":"

Conditional ExpressionsLink to this heading#

\n

Conditional expressions let you use if … elif …\nelse logic within filters, annotations, aggregations, and updates. A\nconditional expression evaluates a series of conditions for each row of a table\nand returns the matching result expression. Conditional expressions can also be\ncombined and nested like other expressions.

\n
\n

The conditional expression classesLink to this heading#

\n

We’ll be using the following model in the subsequent examples:

\n
Code
from django.db import models\n\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

A When() object is used to encapsulate a condition and its result for use\nin the conditional expression. Using a When() object is similar to using\nthe filter() method. The condition can\nbe specified using field lookups,\nQ objects, or Expression\nobjects that have an output_field that is a\nBooleanField. The result is provided using the\nthen keyword.

\n

Some examples:

\n
Python console
>>> 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(\n...     registered_on__gt=date(2014, 1, 1),\n...     registered_on__lt=date(2015, 1, 1),\n...     then="account_type",\n... )\n>>> # Complex conditions can be created using Q objects\n>>> When(Q(name__startswith="John") | Q(name__startswith="Paul"), then="name")\n>>> # Condition can be created using boolean expressions.\n>>> from django.db.models import Exists, OuterRef\n>>> non_unique_account_type = (\n...     Client.objects.filter(\n...         account_type=OuterRef("account_type"),\n...     )\n...     .exclude(pk=OuterRef("pk"))\n...     .values("pk")\n... )\n>>> When(Exists(non_unique_account_type), then=Value("non unique"))\n>>> # Condition can be created using lookup expressions.\n>>> from django.db.models.lookups import GreaterThan, LessThan\n>>> When(\n...     GreaterThan(F("registered_on"), date(2014, 1, 1))\n...     & LessThan(F("registered_on"), date(2015, 1, 1)),\n...     then="account_type",\n... )\n
\n

Keep in mind that each of these values can be an expression.

\n\n
\n
\n

CaseLink to this heading#

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

A Case() expression is like the if … elif …\nelse statement in Python. Each condition in the provided\nWhen() objects is evaluated in order, until one evaluates to a\ntruthful value. The result expression from the matching When() object\nis returned.

\n

An example:

\n
Python console
>>>\n>>> from datetime import date, timedelta\n>>> from django.db.models import Case, Value, When\n>>> Client.objects.create(\n...     name="Jane Doe",\n...     account_type=Client.REGULAR,\n...     registered_on=date.today() - timedelta(days=36),\n... )\n>>> Client.objects.create(\n...     name="James Smith",\n...     account_type=Client.GOLD,\n...     registered_on=date.today() - timedelta(days=5),\n... )\n>>> Client.objects.create(\n...     name="Jack Black",\n...     account_type=Client.PLATINUM,\n...     registered_on=date.today() - timedelta(days=10 * 365),\n... )\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...     ),\n... ).values_list("name", "discount")\n<QuerySet [('Jane Doe', '0%'), ('James Smith', '5%'), ('Jack Black', '10%')]>\n
\n

Case() accepts any number of When() objects as individual arguments.\nOther options are provided using keyword arguments. If none of the conditions\nevaluate to TRUE, then the expression given with the default keyword\nargument is returned. If a default argument isn’t provided, None is\nused.

\n

If we wanted to change our previous query to get the discount based on how long\nthe Client has been with us, we could do so using lookups:

\n
Python console
>>> 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...     )\n... ).values_list("name", "discount")\n<QuerySet [('Jane Doe', '5%'), ('James Smith', '0%'), ('Jack Black', '10%')]>\n
\n\n

Case() also works in a filter() clause. For example, to find gold\nclients that registered more than a month ago and platinum clients that\nregistered more than a year ago:

\n
Python console
>>> 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

Advanced queriesLink to this heading#

\n

Conditional expressions can be used in annotations, aggregations, filters,\nlookups, and updates. They can also be combined and nested with other\nexpressions. This allows you to make powerful conditional queries.

\n
\n

Conditional updateLink to this heading#

\n

Let’s say we want to change the account_type for our clients to match\ntheir registration dates. We can do this using a conditional expression and the\nupdate() method:

\n
Python console
>>> 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, then=Value(Client.PLATINUM)),\n...         When(registered_on__lte=a_month_ago, 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

Conditional aggregationLink to this heading#

\n

What if we want to find out how many clients there are for each\naccount_type? We can use the filter argument of aggregate\nfunctions to achieve this:

\n
Python console
>>> # Create some more Clients first so we can have something to count\n>>> Client.objects.create(\n...     name="Jean Grey", account_type=Client.REGULAR, registered_on=date.today()\n... )\n>>> Client.objects.create(\n...     name="James Bond", account_type=Client.PLATINUM, registered_on=date.today()\n... )\n>>> Client.objects.create(\n...     name="Jane Porter", account_type=Client.PLATINUM, registered_on=date.today()\n... )\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

This aggregate produces a query with the SQL 2003 FILTER WHERE syntax\non databases that support it:

\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

On other databases, this is emulated using a CASE statement:

\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

The two SQL statements are functionally equivalent but the more explicit\nFILTER may perform better.

\n
\n
\n

Conditional filterLink to this heading#

\n

When a conditional expression returns a boolean value, it is possible to use it\ndirectly in filters. This means that it will not be added to the SELECT\ncolumns, but you can still use it to filter results:

\n
Python console
>>> non_unique_account_type = (\n...     Client.objects.filter(\n...         account_type=OuterRef("account_type"),\n...     )\n...     .exclude(pk=OuterRef("pk"))\n...     .values("pk")\n... )\n>>> Client.objects.filter(~Exists(non_unique_account_type))\n
\n

In SQL terms, that evaluates to:

\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":"The conditional expression classes","anchor":"the-conditional-expression-classes","children":[{"title":"When","anchor":"when","children":[]},{"title":"Case","anchor":"case","children":[]}]},{"title":"Advanced queries","anchor":"advanced-queries","children":[{"title":"Conditional update","anchor":"conditional-update","children":[]},{"title":"Conditional aggregation","anchor":"conditional-aggregation","children":[]},{"title":"Conditional filter","anchor":"conditional-filter","children":[]}]}],"breadcrumbs":[{"docname":"ref/index","title":"API Reference","url":"/el/6.0/ref/"},{"docname":"ref/models/index","title":"Models","url":"/el/6.0/ref/models/"}],"prev":{"docname":"ref/models/expressions","title":"Query Expressions","url":"/el/6.0/ref/models/expressions/"},"next":{"docname":"ref/models/database-functions","title":"Database Functions","url":"/el/6.0/ref/models/database-functions/"},"formats":{"html":"/el/6.0/ref/models/conditional-expressions/","markdown":"/el/6.0/ref/models/conditional-expressions.md","json":"/el/6.0/ref/models/conditional-expressions.json"},"source":"https://github.com/django/django/blob/stable/6.0.x/docs/ref/models/conditional-expressions.txt","official":"https://docs.djangoproject.com/el/6.0/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","1.11","1.10"],"inLocales":["en","sv","zh-hans","ga","fr","ja","id","it","pt-br","ko","es","el","pl"]}