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.
CastLink to this heading#Forces the result type of expression to be the one from output_field.
Usage example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Cast\n>>> Value.objects.create(integer=4)\n>>> value = Value.objects.annotate(as_float=Cast('integer', FloatField())).get()\n>>> print(value.as_float)\n4.0\nCoalesceLink to this heading#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\nConcatLink to this heading#Accepts 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)\nGreatestLink to this heading#Accepts a list of at least two field names or expressions and returns the\ngreatest value. Each argument must be of a similar type, so mixing text and\nnumbers will result in a database error.
\nUsage example:
\nclass Blog(models.Model):\n body = models.TextField()\n modified = models.DateTimeField(auto_now=True)\n\nclass Comment(models.Model):\n body = models.TextField()\n modified = models.DateTimeField(auto_now=True)\n blog = models.ForeignKey(Blog, on_delete=models.CASCADE)\n\n>>> from django.db.models.functions import Greatest\n>>> blog = Blog.objects.create(body='Greatest is the best.')\n>>> comment = Comment.objects.create(body='No, Least is better.', blog=blog)\n>>> comments = Comment.objects.annotate(last_updated=Greatest('modified', 'blog__modified'))\n>>> annotated_comment = comments.get()\nannotated_comment.last_updated will be the most recent of blog.modified\nand comment.modified.
LeastLink to this heading#Accepts a list of at least two field names or expressions and returns the\nleast value. Each argument must be of a similar type, so mixing text and numbers\nwill result in a database error.
\n\nLengthLink to this heading#Accepts 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)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import CharField\n>>> from django.db.models.functions import Length\n>>> CharField.register_lookup(Length, 'length')\n>>> # Get authors whose name is longer than 7 characters\n>>> authors = Author.objects.filter(name__length__gt=7)\nLowerLink to this heading#Accepts a single text field or expression and returns the lowercase\nrepresentation.
\nIt can also be registered as a transform as described in Length.
Usage 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\nNowLink to this heading#Returns the database server's current date and time when the query is executed,\ntypically using the SQL CURRENT_TIMESTAMP.
Usage example:
\n>>> from django.db.models.functions import Now\n>>> Article.objects.filter(published__lte=Now())\n<QuerySet [<Article: How to Django>]>\nSubstrLink to this heading#Returns 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\nUpperLink to this heading#Accepts a single text field or expression and returns the uppercase\nrepresentation.
\nIt can also be registered as a transform as described in Length.
Usage 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\nWe'll be using the following model in examples of each function:
\nclass Experiment(models.Model):\n start_datetime = models.DateTimeField()\n start_date = models.DateField(null=True, blank=True)\n end_datetime = models.DateTimeField(null=True, blank=True)\n end_date = models.DateField(null=True, blank=True)\nExtractLink to this heading#Extracts a component of a date as a number.
\nTakes an expression representing a DateField or DateTimeField and a\nlookup_name, and returns the part of the date referenced by lookup_name\nas an IntegerField. Django usually uses the databases' extract function, so\nyou may use any lookup_name that your database supports. A tzinfo\nsubclass, usually provided by pytz, can be passed to extract a value in a\nspecific timezone.
Given the datetime 2015-06-15 23:30:01.000321+00:00, the built-in\nlookup_names return:
"year": 2015
"month": 6
"day": 15
"week_day": 2
"hour": 23
"minute": 30
"second": 1
If a different timezone like Australia/Melbourne is active in Django, then\nthe datetime is converted to the timezone before the value is extracted. The\ntimezone offset for Melbourne in the example date above is +10:00. The values\nreturned when this timezone is active will be the same as above except for:
"day": 16
"week_day": 3
"hour": 9
Each lookup_name above has a corresponding Extract subclass (listed\nbelow) that should typically be used instead of the more verbose equivalent,\ne.g. use ExtractYear(...) rather than Extract(..., lookup_name='year').
Usage example:
\n>>> from datetime import datetime\n>>> from django.db.models.functions import Extract\n>>> start = datetime(2015, 6, 15)\n>>> end = datetime(2015, 7, 2)\n>>> Experiment.objects.create(\n... start_datetime=start, start_date=start.date(),\n... end_datetime=end, end_date=end.date())\n>>> # Add the experiment start year as a field in the QuerySet.\n>>> experiment = Experiment.objects.annotate(\n... start_year=Extract('start_datetime', 'year')).get()\n>>> experiment.start_year\n2015\n>>> # How many experiments completed in the same year in which they started?\n>>> Experiment.objects.filter(\n... start_datetime__year=Extract('end_datetime', 'year')).count()\n1\nDateField extractsLink to this heading#These are logically equivalent to Extract('date_field', lookup_name). Each\nclass is also a Transform registered on DateField and DateTimeField\nas __(lookup_name), e.g. __year.
Since DateFields don't have a time component, only Extract subclasses\nthat deal with date-parts can be used with DateField:
>>> from datetime import datetime\n>>> from django.utils import timezone\n>>> from django.db.models.functions import (\n... ExtractYear, ExtractMonth, ExtractDay, ExtractWeekDay\n... )\n>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=timezone.utc)\n>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.utc)\n>>> Experiment.objects.create(\n... start_datetime=start_2015, start_date=start_2015.date(),\n... end_datetime=end_2015, end_date=end_2015.date())\n>>> Experiment.objects.annotate(\n... year=ExtractYear('start_date'),\n... month=ExtractMonth('start_date'),\n... day=ExtractDay('start_date'),\n... weekday=ExtractWeekDay('start_date'),\n... ).values('year', 'month', 'day', 'weekday').get(\n... end_date__year=ExtractYear('start_date'),\n... )\n{'year': 2015, 'month': 6, 'day': 15, 'weekday': 2}\nDateTimeField extractsLink to this heading#In addition to the following, all extracts for DateField listed above may\nalso be used on DateTimeFields .
These are logically equivalent to Extract('datetime_field', lookup_name).\nEach class is also a Transform registered on DateTimeField as\n__(lookup_name), e.g. __minute.
DateTimeField examples:
>>> from datetime import datetime\n>>> from django.utils import timezone\n>>> from django.db.models.functions import (\n... ExtractYear, ExtractMonth, ExtractDay, ExtractWeekDay,\n... ExtractHour, ExtractMinute, ExtractSecond,\n... )\n>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=timezone.utc)\n>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.utc)\n>>> Experiment.objects.create(\n... start_datetime=start_2015, start_date=start_2015.date(),\n... end_datetime=end_2015, end_date=end_2015.date())\n>>> Experiment.objects.annotate(\n... year=ExtractYear('start_datetime'),\n... month=ExtractMonth('start_datetime'),\n... day=ExtractDay('start_datetime'),\n... weekday=ExtractWeekDay('start_datetime'),\n... hour=ExtractHour('start_datetime'),\n... minute=ExtractMinute('start_datetime'),\n... second=ExtractSecond('start_datetime'),\n... ).values(\n... 'year', 'month', 'day', 'weekday', 'hour', 'minute', 'second',\n... ).get(end_datetime__year=ExtractYear('start_datetime'))\n{'year': 2015, 'month': 6, 'day': 15, 'weekday': 2, 'hour': 23, 'minute': 30, 'second': 1}\nWhen USE_TZ is True then datetimes are stored in the database\nin UTC. If a different timezone is active in Django, the datetime is converted\nto that timezone before the value is extracted. The example below converts to\nthe Melbourne timezone (UTC +10:00), which changes the day, weekday, and hour\nvalues that are returned:
>>> import pytz\n>>> melb = pytz.timezone('Australia/Melbourne') # UTC+10:00\n>>> with timezone.override(melb):\n... Experiment.objects.annotate(\n... day=ExtractDay('start_datetime'),\n... weekday=ExtractWeekDay('start_datetime'),\n... hour=ExtractHour('start_datetime'),\n... ).values('day', 'weekday', 'hour').get(\n... end_datetime__year=ExtractYear('start_datetime'),\n... )\n{'day': 16, 'weekday': 3, 'hour': 9}\nExplicitly passing the timezone to the Extract function behaves in the same\nway, and takes priority over an active timezone:
>>> import pytz\n>>> melb = pytz.timezone('Australia/Melbourne')\n>>> Experiment.objects.annotate(\n... day=ExtractDay('start_datetime', tzinfo=melb),\n... weekday=ExtractWeekDay('start_datetime', tzinfo=melb),\n... hour=ExtractHour('start_datetime', tzinfo=melb),\n... ).values('day', 'weekday', 'hour').get(\n... end_datetime__year=ExtractYear('start_datetime'),\n... )\n{'day': 16, 'weekday': 3, 'hour': 9}\nTruncLink to this heading#Truncates a date up to a significant component.
\nWhen you only care if something happened in a particular year, hour, or day,\nbut not the exact second, then Trunc (and its subclasses) can be useful to\nfilter or aggregate your data. For example, you can use Trunc to calculate\nthe number of sales per day.
Trunc takes a single expression, representing a DateField or\nDateTimeField, a kind representing a date part, and an output_field\nthat's either DateTimeField() or DateField(). It returns a datetime or\ndate, depending on output_field, with fields up to kind set to their\nminimum value. If output_field is omitted, it will default to the\noutput_field of expression. A tzinfo subclass, usually provided by\npytz, can be passed to truncate a value in a specific timezone.
Given the datetime 2015-06-15 14:30:50.000321+00:00, the built-in kinds\nreturn:
"year": 2015-01-01 00:00:00+00:00
"month": 2015-06-01 00:00:00+00:00
"day": 2015-06-15 00:00:00+00:00
"hour": 2015-06-15 14:00:00+00:00
"minute": 2015-06-15 14:30:00+00:00
"second": 2015-06-15 14:30:50+00:00
If a different timezone like Australia/Melbourne is active in Django, then\nthe datetime is converted to the new timezone before the value is truncated.\nThe timezone offset for Melbourne in the example date above is +10:00. The\nvalues returned when this timezone is active will be:
"year": 2015-01-01 00:00:00+11:00
"month": 2015-06-01 00:00:00+10:00
"day": 2015-06-16 00:00:00+10:00
"hour": 2015-06-16 00:00:00+10:00
"minute": 2015-06-16 00:30:00+10:00
"second": 2015-06-16 00:30:50+10:00
The year has an offset of +11:00 because the result transitioned into daylight\nsaving time.
\nEach kind above has a corresponding Trunc subclass (listed below) that\nshould typically be used instead of the more verbose equivalent,\ne.g. use TruncYear(...) rather than Trunc(..., kind='year').
The subclasses are all defined as transforms, but they aren't registered with\nany fields, because the obvious lookup names are already reserved by the\nExtract subclasses.
Usage example:
\n>>> from datetime import datetime\n>>> from django.db.models import Count, DateTimeField\n>>> from django.db.models.functions import Trunc\n>>> Experiment.objects.create(start_datetime=datetime(2015, 6, 15, 14, 30, 50, 321))\n>>> Experiment.objects.create(start_datetime=datetime(2015, 6, 15, 14, 40, 2, 123))\n>>> Experiment.objects.create(start_datetime=datetime(2015, 12, 25, 10, 5, 27, 999))\n>>> experiments_per_day = Experiment.objects.annotate(\n... start_day=Trunc('start_datetime', 'day', output_field=DateTimeField())\n... ).values('start_day').annotate(experiments=Count('id'))\n>>> for exp in experiments_per_day:\n... print(exp['start_day'], exp['experiments'])\n...\n2015-06-15 00:00:00 2\n2015-12-25 00:00:00 1\n>>> experiments = Experiment.objects.annotate(\n... start_day=Trunc('start_datetime', 'day', output_field=DateTimeField())\n... ).filter(start_day=datetime(2015, 6, 15))\n>>> for exp in experiments:\n... print(exp.start_datetime)\n...\n2015-06-15 14:30:50.000321\n2015-06-15 14:40:02.000123\nDateField truncationLink to this heading#These are logically equivalent to Trunc('date_field', kind). They truncate\nall parts of the date up to kind which allows grouping or filtering dates\nwith less precision. expression can have an output_field of either\nDateField or DateTimeField.
Since DateFields don't have a time component, only Trunc subclasses\nthat deal with date-parts can be used with DateField:
>>> from datetime import datetime\n>>> from django.db.models import Count\n>>> from django.db.models.functions import TruncMonth, TruncYear\n>>> from django.utils import timezone\n>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)\n>>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)\n>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.utc)\n>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())\n>>> Experiment.objects.create(start_datetime=start2, start_date=start2.date())\n>>> Experiment.objects.create(start_datetime=start3, start_date=start3.date())\n>>> experiments_per_year = Experiment.objects.annotate(\n... year=TruncYear('start_date')).values('year').annotate(\n... experiments=Count('id'))\n>>> for exp in experiments_per_year:\n... print(exp['year'], exp['experiments'])\n...\n2014-01-01 1\n2015-01-01 2\n\n>>> import pytz\n>>> melb = pytz.timezone('Australia/Melbourne')\n>>> experiments_per_month = Experiment.objects.annotate(\n... month=TruncMonth('start_datetime', tzinfo=melb)).values('month').annotate(\n... experiments=Count('id'))\n>>> for exp in experiments_per_month:\n... print(exp['month'], exp['experiments'])\n...\n2015-06-01 00:00:00+10:00 1\n2016-01-01 00:00:00+11:00 1\n2014-06-01 00:00:00+10:00 1\nDateTimeField truncationLink to this heading#TruncDate casts expression to a date rather than using the built-in SQL\ntruncate function. It's also registered as a transform on DateTimeField as\n__date.
These are logically equivalent to Trunc('datetime_field', kind). They\ntruncate all parts of the date up to kind and allow grouping or filtering\ndatetimes with less precision. expression must have an output_field of\nDateTimeField.
Usage example:
\n>>> from datetime import date, datetime\n>>> from django.db.models import Count\n>>> from django.db.models.functions import (\n... TruncDate, TruncDay, TruncHour, TruncMinute, TruncSecond,\n... )\n>>> from django.utils import timezone\n>>> import pytz\n>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)\n>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())\n>>> melb = pytz.timezone('Australia/Melbourne')\n>>> Experiment.objects.annotate(\n... date=TruncDate('start_datetime'),\n... day=TruncDay('start_datetime', tzinfo=melb),\n... hour=TruncHour('start_datetime', tzinfo=melb),\n... minute=TruncMinute('start_datetime'),\n... second=TruncSecond('start_datetime'),\n... ).values('date', 'day', 'hour', 'minute', 'second').get()\n{'date': datetime.date(2014, 6, 15),\n 'day': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=<DstTzInfo 'Australia/Melbourne' AEST+10:00:00 STD>),\n 'hour': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=<DstTzInfo 'Australia/Melbourne' AEST+10:00:00 STD>),\n 'minute': 'minute': datetime.datetime(2014, 6, 15, 14, 30, tzinfo=<UTC>),\n 'second': datetime.datetime(2014, 6, 15, 14, 30, 50, tzinfo=<UTC>)\n}\n