The classes documented below provide a way for users to use functions provided\nby the underlying database as annotations, aggregations, or filters in Django.\nFunctions are also expressions, so they can be used and\ncombined with other expressions like aggregate functions.
\nWe’ll be using the following model in examples of each function:
\nclass Author(models.Model):\n name = models.CharField(max_length=50)\n age = models.PositiveIntegerField(null=True, blank=True)\n alias = models.CharField(max_length=50, null=True, blank=True)\n goes_by = models.CharField(max_length=50, null=True, blank=True)\nWe don’t usually recommend allowing null=True for CharField since this\nallows the field to have two “empty values”, but it’s important for the\nCoalesce example below.
Accepts a list of at least two field names or expressions and returns the\nfirst non-null value (note that an empty string is not considered a null\nvalue). Each argument must be of a similar type, so mixing text and numbers\nwill result in a database error.
\nUsage examples:
\n>>> # Get a screen name from least to most public\n>>> from django.db.models import Sum, Value as V\n>>> from django.db.models.functions import Coalesce\n>>> Author.objects.create(name='Margaret Smith', goes_by='Maggie')\n>>> author = Author.objects.annotate(\n... screen_name=Coalesce('alias', 'goes_by', 'name')).get()\n>>> print(author.screen_name)\nMaggie\n\n>>> # Prevent an aggregate Sum() from returning None\n>>> aggregated = Author.objects.aggregate(\n... combined_age=Coalesce(Sum('age'), V(0)),\n... combined_age_default=Sum('age'))\n>>> print(aggregated['combined_age'])\n0\n>>> print(aggregated['combined_age_default'])\nNone\nAccepts a list of at least two text fields or expressions and returns the\nconcatenated text. Each argument must be of a text or char type. If you want\nto concatenate a TextField() with a CharField(), then be sure to tell\nDjango that the output_field should be a TextField(). This is also\nrequired when concatenating a Value as in the example below.
This function will never have a null result. On backends where a null argument\nresults in the entire expression being null, Django will ensure that each null\npart is converted to an empty string first.
\nUsage example:
\n>>> # Get the display name as "name (goes_by)"\n>>> from django.db.models import CharField, Value as V\n>>> from django.db.models.functions import Concat\n>>> Author.objects.create(name='Margaret Smith', goes_by='Maggie')\n>>> author = Author.objects.annotate(\n... screen_name=Concat('name', V(' ('), 'goes_by', V(')'),\n... output_field=CharField())).get()\n>>> print(author.screen_name)\nMargaret Smith (Maggie)\nAccepts a single text field or expression and returns the number of characters\nthe value has. If the expression is null, then the length will also be null.
\nUsage example:
\n>>> # Get the length of the name and goes_by fields\n>>> from django.db.models.functions import Length\n>>> Author.objects.create(name='Margaret Smith')\n>>> author = Author.objects.annotate(\n... name_length=Length('name'),\n... goes_by_length=Length('goes_by')).get()\n>>> print(author.name_length, author.goes_by_length)\n(14, None)\nAccepts a single text field or expression and returns the lowercase\nrepresentation.
\nUsage example:
\n>>> from django.db.models.functions import Lower\n>>> Author.objects.create(name='Margaret Smith')\n>>> author = Author.objects.annotate(name_lower=Lower('name')).get()\n>>> print(author.name_lower)\nmargaret smith\nReturns a substring of length length from the field or expression starting\nat position pos. The position is 1-indexed, so the position must be greater\nthan 0. If length is None, then the rest of the string will be returned.
Usage example:
\n>>> # Set the alias to the first 5 characters of the name as lowercase\n>>> from django.db.models.functions import Substr, Lower\n>>> Author.objects.create(name='Margaret Smith')\n>>> Author.objects.update(alias=Lower(Substr('name', 1, 5)))\n1\n>>> print(Author.objects.get(name='Margaret Smith').alias)\nmarga\nAccepts a single text field or expression and returns the uppercase\nrepresentation.
\nUsage example:
\n>>> from django.db.models.functions import Upper\n>>> Author.objects.create(name='Margaret Smith')\n>>> author = Author.objects.annotate(name_upper=Upper('name')).get()\n>>> print(author.name_upper)\nMARGARET SMITH\n