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\nused and combined with other expressions like aggregate functions. See the Func documentation\nfor security considerations.
We’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 para este cabeçalho#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>>> Author.objects.create(age=25, name="Margaret Smith")\n>>> author = Author.objects.annotate(\n... age_as_float=Cast("age", output_field=FloatField()),\n... ).get()\n>>> print(author.age_as_float)\n25.0\nCoalesceLink para este cabeçalho#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\n>>> from django.db.models.functions import Coalesce\n>>> Author.objects.create(name="Margaret Smith", goes_by="Maggie")\n>>> author = Author.objects.annotate(screen_name=Coalesce("alias", "goes_by", "name")).get()\n>>> print(author.screen_name)\nMaggie\n\n>>> # Prevent an aggregate Sum() from returning None\n>>> # The aggregate default argument uses Coalesce() under the hood.\n>>> aggregated = Author.objects.aggregate(\n... combined_age=Sum("age"),\n... combined_age_default=Sum("age", default=0),\n... combined_age_coalesce=Coalesce(Sum("age"), 0),\n... )\n>>> print(aggregated["combined_age"])\nNone\n>>> print(aggregated["combined_age_default"])\n0\n>>> print(aggregated["combined_age_coalesce"])\n0\nCollateLink para este cabeçalho#Takes an expression and a collation name to query against.
\nFor example, to filter case-insensitively in SQLite:
\n>>> Author.objects.filter(name=Collate(Value("john"), "nocase"))\n<QuerySet [<Author: John>, <Author: john>]>\nIt can also be used when ordering, for example with PostgreSQL:
\n>>> Author.objects.order_by(Collate("name", "et-x-icu"))\n<QuerySet [<Author: Ursula>, <Author: Veronika>, <Author: Ülle>]>\nGreatestLink para este cabeçalho#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\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>>> 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 para este cabeçalho#Accepts a list of at least two field names or expressions and returns the least\nvalue. Each argument must be of a similar type, so mixing text and numbers will\nresult in a database error.
\n\nNullIfLink para este cabeçalho#Accepts two expressions and returns None if they are equal, otherwise\nreturns expression1.
We’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 start_time = models.TimeField(null=True, blank=True)\n end_datetime = models.DateTimeField(null=True, blank=True)\n end_date = models.DateField(null=True, blank=True)\n end_time = models.TimeField(null=True, blank=True)\nExtractLink para este cabeçalho#Extracts a component of a date as a number.
\nTakes an expression representing a DateField, DateTimeField,\nTimeField, or DurationField and a lookup_name, and returns the part\nof the date referenced by lookup_name as an IntegerField.\nDjango usually uses the databases’ extract function, so you may use any\nlookup_name that your database supports. A tzinfo subclass, usually\nprovided by zoneinfo, can be passed to extract a value in a specific\ntimezone.
Given the datetime 2015-06-15 23:30:01.000321+00:00, the built-in\nlookup_names return:
“year”: 2015
“iso_year”: 2015
“quarter”: 2
“month”: 6
“day”: 15
“week”: 25
“week_day”: 2
“iso_week_day”: 1
“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
“iso_week_day”: 2
“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(), end_datetime=end, end_date=end.date()\n... )\n>>> # Add the experiment start year as a field in the QuerySet.\n>>> experiment = Experiment.objects.annotate(\n... start_year=Extract("start_datetime", "year")\n... ).get()\n>>> experiment.start_year\n2015\n>>> # How many experiments completed in the same year in which they started?\n>>> Experiment.objects.filter(start_datetime__year=Extract("end_datetime", "year")).count()\n1\nDateField extractsLink para este cabeçalho#Returns the ISO-8601 week-numbering year.
\nReturns the ISO-8601 week day with day 1 being Monday and day 7 being\nSunday.
\nThese 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 UTC, datetime\n>>> from django.db.models.functions import (\n... ExtractDay,\n... ExtractMonth,\n... ExtractQuarter,\n... ExtractWeek,\n... ExtractIsoWeekDay,\n... ExtractWeekDay,\n... ExtractIsoYear,\n... ExtractYear,\n... )\n>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=UTC)\n>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=UTC)\n>>> Experiment.objects.create(\n... start_datetime=start_2015,\n... start_date=start_2015.date(),\n... end_datetime=end_2015,\n... end_date=end_2015.date(),\n... )\n>>> Experiment.objects.annotate(\n... year=ExtractYear("start_date"),\n... isoyear=ExtractIsoYear("start_date"),\n... quarter=ExtractQuarter("start_date"),\n... month=ExtractMonth("start_date"),\n... week=ExtractWeek("start_date"),\n... day=ExtractDay("start_date"),\n... weekday=ExtractWeekDay("start_date"),\n... isoweekday=ExtractIsoWeekDay("start_date"),\n... ).values(\n... "year",\n... "isoyear",\n... "quarter",\n... "month",\n... "week",\n... "day",\n... "weekday",\n... "isoweekday",\n... ).get(\n... end_date__year=ExtractYear("start_date")\n... )\n{'year': 2015, 'isoyear': 2015, 'quarter': 2, 'month': 6, 'week': 25,\n 'day': 15, 'weekday': 2, 'isoweekday': 1}\nDateTimeField extractsLink para este cabeçalho#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 UTC, datetime\n>>> from django.db.models.functions import (\n... ExtractDay,\n... ExtractHour,\n... ExtractMinute,\n... ExtractMonth,\n... ExtractQuarter,\n... ExtractSecond,\n... ExtractWeek,\n... ExtractIsoWeekDay,\n... ExtractWeekDay,\n... ExtractIsoYear,\n... ExtractYear,\n... )\n>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=UTC)\n>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=UTC)\n>>> Experiment.objects.create(\n... start_datetime=start_2015,\n... start_date=start_2015.date(),\n... end_datetime=end_2015,\n... end_date=end_2015.date(),\n... )\n>>> Experiment.objects.annotate(\n... year=ExtractYear("start_datetime"),\n... isoyear=ExtractIsoYear("start_datetime"),\n... quarter=ExtractQuarter("start_datetime"),\n... month=ExtractMonth("start_datetime"),\n... week=ExtractWeek("start_datetime"),\n... day=ExtractDay("start_datetime"),\n... weekday=ExtractWeekDay("start_datetime"),\n... isoweekday=ExtractIsoWeekDay("start_datetime"),\n... hour=ExtractHour("start_datetime"),\n... minute=ExtractMinute("start_datetime"),\n... second=ExtractSecond("start_datetime"),\n... ).values(\n... "year",\n... "isoyear",\n... "month",\n... "week",\n... "day",\n... "weekday",\n... "isoweekday",\n... "hour",\n... "minute",\n... "second",\n... ).get(\n... end_datetime__year=ExtractYear("start_datetime")\n... )\n{'year': 2015, 'isoyear': 2015, 'quarter': 2, 'month': 6, 'week': 25,\n 'day': 15, 'weekday': 2, 'isoweekday': 1, 'hour': 23, 'minute': 30,\n '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:
>>> from django.utils import timezone\n>>> import zoneinfo\n>>> melb = zoneinfo.ZoneInfo("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... isoweekday=ExtractIsoWeekDay("start_datetime"),\n... hour=ExtractHour("start_datetime"),\n... ).values("day", "weekday", "isoweekday", "hour").get(\n... end_datetime__year=ExtractYear("start_datetime"),\n... )\n...\n{'day': 16, 'weekday': 3, 'isoweekday': 2, 'hour': 9}\nExplicitly passing the timezone to the Extract function behaves in the same\nway, and takes priority over an active timezone:
>>> import zoneinfo\n>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")\n>>> Experiment.objects.annotate(\n... day=ExtractDay("start_datetime", tzinfo=melb),\n... weekday=ExtractWeekDay("start_datetime", tzinfo=melb),\n... isoweekday=ExtractIsoWeekDay("start_datetime", tzinfo=melb),\n... hour=ExtractHour("start_datetime", tzinfo=melb),\n... ).values("day", "weekday", "isoweekday", "hour").get(\n... end_datetime__year=ExtractYear("start_datetime"),\n... )\n{'day': 16, 'weekday': 3, 'isoweekday': 2, 'hour': 9}\nNowLink para este cabeçalho#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>]>\nTruncLink para este cabeçalho#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,\nTimeField, or DateTimeField, a kind representing a date or time\npart, and an output_field that’s either DateTimeField(),\nTimeField(), or DateField(). It returns a datetime, date, or time\ndepending on output_field, with fields up to kind set to their minimum\nvalue. If output_field is omitted, it will default to the output_field\nof expression. A tzinfo subclass, usually provided by zoneinfo,\ncan 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\nkinds return:
“year”: 2015-01-01 00:00:00+00:00
“quarter”: 2015-04-01 00:00:00+00:00
“month”: 2015-06-01 00:00:00+00:00
“week”: 2015-06-15 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
“quarter”: 2015-04-01 00:00:00+10:00
“month”: 2015-06-01 00:00:00+10:00
“week”: 2015-06-16 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 lookup names are already reserved by the Extract\nsubclasses.
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 = (\n... Experiment.objects.annotate(\n... start_day=Trunc("start_datetime", "day", output_field=DateTimeField())\n... )\n... .values("start_day")\n... .annotate(experiments=Count("id"))\n... )\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 para este cabeçalho#Truncates to midnight on the Monday of the week.
\nThese 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 UTC, datetime\n>>> from django.db.models import Count\n>>> from django.db.models.functions import TruncMonth, TruncYear\n>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=UTC)\n>>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=UTC)\n>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=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 = (\n... Experiment.objects.annotate(year=TruncYear("start_date"))\n... .values("year")\n... .annotate(experiments=Count("id"))\n... )\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 zoneinfo\n>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")\n>>> experiments_per_month = (\n... Experiment.objects.annotate(month=TruncMonth("start_datetime", tzinfo=melb))\n... .values("month")\n... .annotate(experiments=Count("id"))\n... )\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 para este cabeçalho#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.
TruncTime casts expression to a time rather than using the built-in SQL\ntruncate function. It’s also registered as a transform on DateTimeField as\n__time.
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 UTC, date, datetime\n>>> from django.db.models import Count\n>>> from django.db.models.functions import (\n... TruncDate,\n... TruncDay,\n... TruncHour,\n... TruncMinute,\n... TruncSecond,\n... )\n>>> import zoneinfo\n>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=UTC)\n>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())\n>>> melb = zoneinfo.ZoneInfo("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=zoneinfo.ZoneInfo('Australia/Melbourne')),\n 'hour': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=zoneinfo.ZoneInfo('Australia/Melbourne')),\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}\nTimeField truncationLink para este cabeçalho#These are logically equivalent to Trunc('time_field', kind). They truncate\nall parts of the time up to kind which allows grouping or filtering times\nwith less precision. expression can have an output_field of either\nTimeField or DateTimeField.
Since TimeFields don’t have a date component, only Trunc subclasses\nthat deal with time-parts can be used with TimeField:
>>> from datetime import UTC, datetime\n>>> from django.db.models import Count, TimeField\n>>> from django.db.models.functions import TruncHour\n>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=UTC)\n>>> start2 = datetime(2014, 6, 15, 14, 40, 2, 123, tzinfo=UTC)\n>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=UTC)\n>>> Experiment.objects.create(start_datetime=start1, start_time=start1.time())\n>>> Experiment.objects.create(start_datetime=start2, start_time=start2.time())\n>>> Experiment.objects.create(start_datetime=start3, start_time=start3.time())\n>>> experiments_per_hour = (\n... Experiment.objects.annotate(\n... hour=TruncHour("start_datetime", output_field=TimeField()),\n... )\n... .values("hour")\n... .annotate(experiments=Count("id"))\n... )\n>>> for exp in experiments_per_hour:\n... print(exp["hour"], exp["experiments"])\n...\n14:00:00 2\n17:00:00 1\n\n>>> import zoneinfo\n>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")\n>>> experiments_per_hour = (\n... Experiment.objects.annotate(\n... hour=TruncHour("start_datetime", tzinfo=melb),\n... )\n... .values("hour")\n... .annotate(experiments=Count("id"))\n... )\n>>> for exp in experiments_per_hour:\n... print(exp["hour"], exp["experiments"])\n...\n2014-06-16 00:00:00+10:00 2\n2016-01-01 04:00:00+11:00 1\nJSONArrayLink para este cabeçalho#Accepts a list of field names or expressions and returns a JSON array\ncontaining those values.
\nUsage example:
\n>>> from django.db.models import F\n>>> from django.db.models.functions import JSONArray, Lower\n>>> Author.objects.create(name="Margaret Smith", alias="msmith", age=25)\n>>> author = Author.objects.annotate(\n... json_array=JSONArray(\n... Lower("name"),\n... "alias",\n... F("age") * 2,\n... )\n... ).get()\n>>> author.json_array\n['margaret smith', 'msmith', 50]\nJSONObjectLink para este cabeçalho#Takes a list of key-value pairs and returns a JSON object containing those\npairs.
\nUsage example:
\n>>> from django.db.models import F\n>>> from django.db.models.functions import JSONObject, Lower\n>>> Author.objects.create(name="Margaret Smith", alias="msmith", age=25)\n>>> author = Author.objects.annotate(\n... json_object=JSONObject(\n... name=Lower("name"),\n... alias="alias",\n... age=F("age") * 2,\n... )\n... ).get()\n>>> author.json_object\n{'name': 'margaret smith', 'alias': 'msmith', 'age': 50}\nWe’ll be using the following model in math function examples:
\nclass Vector(models.Model):\n x = models.FloatField()\n y = models.FloatField()\nAbsLink para este cabeçalho#Returns the absolute value of a numeric field or expression.
\nUsage example:
\n>>> from django.db.models.functions import Abs\n>>> Vector.objects.create(x=-0.5, y=1.1)\n>>> vector = Vector.objects.annotate(x_abs=Abs("x"), y_abs=Abs("y")).get()\n>>> vector.x_abs, vector.y_abs\n(0.5, 1.1)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Abs\n>>> FloatField.register_lookup(Abs)\n>>> # Get vectors inside the unit cube\n>>> vectors = Vector.objects.filter(x__abs__lt=1, y__abs__lt=1)\nACosLink para este cabeçalho#Returns the arccosine of a numeric field or expression. The expression value\nmust be within the range -1 to 1.
\nUsage example:
\n>>> from django.db.models.functions import ACos\n>>> Vector.objects.create(x=0.5, y=-0.9)\n>>> vector = Vector.objects.annotate(x_acos=ACos("x"), y_acos=ACos("y")).get()\n>>> vector.x_acos, vector.y_acos\n(1.0471975511965979, 2.6905658417935308)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import ACos\n>>> FloatField.register_lookup(ACos)\n>>> # Get vectors whose arccosine is less than 1\n>>> vectors = Vector.objects.filter(x__acos__lt=1, y__acos__lt=1)\nASinLink para este cabeçalho#Returns the arcsine of a numeric field or expression. The expression value must\nbe in the range -1 to 1.
\nUsage example:
\n>>> from django.db.models.functions import ASin\n>>> Vector.objects.create(x=0, y=1)\n>>> vector = Vector.objects.annotate(x_asin=ASin("x"), y_asin=ASin("y")).get()\n>>> vector.x_asin, vector.y_asin\n(0.0, 1.5707963267948966)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import ASin\n>>> FloatField.register_lookup(ASin)\n>>> # Get vectors whose arcsine is less than 1\n>>> vectors = Vector.objects.filter(x__asin__lt=1, y__asin__lt=1)\nATanLink para este cabeçalho#Returns the arctangent of a numeric field or expression.
\nUsage example:
\n>>> from django.db.models.functions import ATan\n>>> Vector.objects.create(x=3.12, y=6.987)\n>>> vector = Vector.objects.annotate(x_atan=ATan("x"), y_atan=ATan("y")).get()\n>>> vector.x_atan, vector.y_atan\n(1.2606282660069106, 1.428638798133829)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import ATan\n>>> FloatField.register_lookup(ATan)\n>>> # Get vectors whose arctangent is less than 2\n>>> vectors = Vector.objects.filter(x__atan__lt=2, y__atan__lt=2)\nATan2Link para este cabeçalho#Returns the arctangent of expression1 / expression2.
Usage example:
\n>>> from django.db.models.functions import ATan2\n>>> Vector.objects.create(x=2.5, y=1.9)\n>>> vector = Vector.objects.annotate(atan2=ATan2("x", "y")).get()\n>>> vector.atan2\n0.9209258773829491\nCeilLink para este cabeçalho#Returns the smallest integer greater than or equal to a numeric field or\nexpression.
\nUsage example:
\n>>> from django.db.models.functions import Ceil\n>>> Vector.objects.create(x=3.12, y=7.0)\n>>> vector = Vector.objects.annotate(x_ceil=Ceil("x"), y_ceil=Ceil("y")).get()\n>>> vector.x_ceil, vector.y_ceil\n(4.0, 7.0)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Ceil\n>>> FloatField.register_lookup(Ceil)\n>>> # Get vectors whose ceil is less than 10\n>>> vectors = Vector.objects.filter(x__ceil__lt=10, y__ceil__lt=10)\nCosLink para este cabeçalho#Returns the cosine of a numeric field or expression.
\nUsage example:
\n>>> from django.db.models.functions import Cos\n>>> Vector.objects.create(x=-8.0, y=3.1415926)\n>>> vector = Vector.objects.annotate(x_cos=Cos("x"), y_cos=Cos("y")).get()\n>>> vector.x_cos, vector.y_cos\n(-0.14550003380861354, -0.9999999999999986)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Cos\n>>> FloatField.register_lookup(Cos)\n>>> # Get vectors whose cosine is less than 0.5\n>>> vectors = Vector.objects.filter(x__cos__lt=0.5, y__cos__lt=0.5)\nCotLink para este cabeçalho#Returns the cotangent of a numeric field or expression.
\nUsage example:
\n>>> from django.db.models.functions import Cot\n>>> Vector.objects.create(x=12.0, y=1.0)\n>>> vector = Vector.objects.annotate(x_cot=Cot("x"), y_cot=Cot("y")).get()\n>>> vector.x_cot, vector.y_cot\n(-1.5726734063976826, 0.642092615934331)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Cot\n>>> FloatField.register_lookup(Cot)\n>>> # Get vectors whose cotangent is less than 1\n>>> vectors = Vector.objects.filter(x__cot__lt=1, y__cot__lt=1)\nDegreesLink para este cabeçalho#Converts a numeric field or expression from radians to degrees.
\nUsage example:
\n>>> from django.db.models.functions import Degrees\n>>> Vector.objects.create(x=-1.57, y=3.14)\n>>> vector = Vector.objects.annotate(x_d=Degrees("x"), y_d=Degrees("y")).get()\n>>> vector.x_d, vector.y_d\n(-89.95437383553924, 179.9087476710785)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Degrees\n>>> FloatField.register_lookup(Degrees)\n>>> # Get vectors whose degrees are less than 360\n>>> vectors = Vector.objects.filter(x__degrees__lt=360, y__degrees__lt=360)\nExpLink para este cabeçalho#Returns the value of e (the natural logarithm base) raised to the power of\na numeric field or expression.
Usage example:
\n>>> from django.db.models.functions import Exp\n>>> Vector.objects.create(x=5.4, y=-2.0)\n>>> vector = Vector.objects.annotate(x_exp=Exp("x"), y_exp=Exp("y")).get()\n>>> vector.x_exp, vector.y_exp\n(221.40641620418717, 0.1353352832366127)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Exp\n>>> FloatField.register_lookup(Exp)\n>>> # Get vectors whose exp() is greater than 10\n>>> vectors = Vector.objects.filter(x__exp__gt=10, y__exp__gt=10)\nFloorLink para este cabeçalho#Returns the largest integer value not greater than a numeric field or\nexpression.
\nUsage example:
\n>>> from django.db.models.functions import Floor\n>>> Vector.objects.create(x=5.4, y=-2.3)\n>>> vector = Vector.objects.annotate(x_floor=Floor("x"), y_floor=Floor("y")).get()\n>>> vector.x_floor, vector.y_floor\n(5.0, -3.0)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Floor\n>>> FloatField.register_lookup(Floor)\n>>> # Get vectors whose floor() is greater than 10\n>>> vectors = Vector.objects.filter(x__floor__gt=10, y__floor__gt=10)\nLnLink para este cabeçalho#Returns the natural logarithm a numeric field or expression.
\nUsage example:
\n>>> from django.db.models.functions import Ln\n>>> Vector.objects.create(x=5.4, y=233.0)\n>>> vector = Vector.objects.annotate(x_ln=Ln("x"), y_ln=Ln("y")).get()\n>>> vector.x_ln, vector.y_ln\n(1.6863989535702288, 5.4510384535657)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Ln\n>>> FloatField.register_lookup(Ln)\n>>> # Get vectors whose value greater than e\n>>> vectors = Vector.objects.filter(x__ln__gt=1, y__ln__gt=1)\nLogLink para este cabeçalho#Accepts two numeric fields or expressions and returns the logarithm of\nthe second to base of the first.
\nUsage example:
\n>>> from django.db.models.functions import Log\n>>> Vector.objects.create(x=2.0, y=4.0)\n>>> vector = Vector.objects.annotate(log=Log("x", "y")).get()\n>>> vector.log\n2.0\nModLink para este cabeçalho#Accepts two numeric fields or expressions and returns the remainder of\nthe first divided by the second (modulo operation).
\nUsage example:
\n>>> from django.db.models.functions import Mod\n>>> Vector.objects.create(x=5.4, y=2.3)\n>>> vector = Vector.objects.annotate(mod=Mod("x", "y")).get()\n>>> vector.mod\n0.8\nPiLink para este cabeçalho#Returns the value of the mathematical constant π.
PowerLink para este cabeçalho#Accepts two numeric fields or expressions and returns the value of the first\nraised to the power of the second.
\nUsage example:
\n>>> from django.db.models.functions import Power\n>>> Vector.objects.create(x=2, y=-2)\n>>> vector = Vector.objects.annotate(power=Power("x", "y")).get()\n>>> vector.power\n0.25\nRadiansLink para este cabeçalho#Converts a numeric field or expression from degrees to radians.
\nUsage example:
\n>>> from django.db.models.functions import Radians\n>>> Vector.objects.create(x=-90, y=180)\n>>> vector = Vector.objects.annotate(x_r=Radians("x"), y_r=Radians("y")).get()\n>>> vector.x_r, vector.y_r\n(-1.5707963267948966, 3.141592653589793)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Radians\n>>> FloatField.register_lookup(Radians)\n>>> # Get vectors whose radians are less than 1\n>>> vectors = Vector.objects.filter(x__radians__lt=1, y__radians__lt=1)\nRandomLink para este cabeçalho#Returns a random value in the range 0.0 ≤ x < 1.0.
RoundLink para este cabeçalho#Rounds a numeric field or expression to precision (must be an integer)\ndecimal places. By default, it rounds to the nearest integer. Whether half\nvalues are rounded up or down depends on the database.
Usage example:
\n>>> from django.db.models.functions import Round\n>>> Vector.objects.create(x=5.4, y=-2.37)\n>>> vector = Vector.objects.annotate(x_r=Round("x"), y_r=Round("y", precision=1)).get()\n>>> vector.x_r, vector.y_r\n(5.0, -2.4)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Round\n>>> FloatField.register_lookup(Round)\n>>> # Get vectors whose round() is less than 20\n>>> vectors = Vector.objects.filter(x__round__lt=20, y__round__lt=20)\nSignLink para este cabeçalho#Returns the sign (-1, 0, 1) of a numeric field or expression.
\nUsage example:
\n>>> from django.db.models.functions import Sign\n>>> Vector.objects.create(x=5.4, y=-2.3)\n>>> vector = Vector.objects.annotate(x_sign=Sign("x"), y_sign=Sign("y")).get()\n>>> vector.x_sign, vector.y_sign\n(1, -1)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Sign\n>>> FloatField.register_lookup(Sign)\n>>> # Get vectors whose signs of components are less than 0.\n>>> vectors = Vector.objects.filter(x__sign__lt=0, y__sign__lt=0)\nSinLink para este cabeçalho#Returns the sine of a numeric field or expression.
\nUsage example:
\n>>> from django.db.models.functions import Sin\n>>> Vector.objects.create(x=5.4, y=-2.3)\n>>> vector = Vector.objects.annotate(x_sin=Sin("x"), y_sin=Sin("y")).get()\n>>> vector.x_sin, vector.y_sin\n(-0.7727644875559871, -0.7457052121767203)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Sin\n>>> FloatField.register_lookup(Sin)\n>>> # Get vectors whose sin() is less than 0\n>>> vectors = Vector.objects.filter(x__sin__lt=0, y__sin__lt=0)\nSqrtLink para este cabeçalho#Returns the square root of a nonnegative numeric field or expression.
\nUsage example:
\n>>> from django.db.models.functions import Sqrt\n>>> Vector.objects.create(x=4.0, y=12.0)\n>>> vector = Vector.objects.annotate(x_sqrt=Sqrt("x"), y_sqrt=Sqrt("y")).get()\n>>> vector.x_sqrt, vector.y_sqrt\n(2.0, 3.46410)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Sqrt\n>>> FloatField.register_lookup(Sqrt)\n>>> # Get vectors whose sqrt() is less than 5\n>>> vectors = Vector.objects.filter(x__sqrt__lt=5, y__sqrt__lt=5)\nTanLink para este cabeçalho#Returns the tangent of a numeric field or expression.
\nUsage example:
\n>>> from django.db.models.functions import Tan\n>>> Vector.objects.create(x=0, y=12)\n>>> vector = Vector.objects.annotate(x_tan=Tan("x"), y_tan=Tan("y")).get()\n>>> vector.x_tan, vector.y_tan\n(0.0, -0.6358599286615808)\nIt can also be registered as a transform. For example:
\n>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Tan\n>>> FloatField.register_lookup(Tan)\n>>> # Get vectors whose tangent is less than 0\n>>> vectors = Vector.objects.filter(x__tan__lt=0, y__tan__lt=0)\nChrLink para este cabeçalho#Accepts a numeric field or expression and returns the text representation of\nthe expression as a single character. It works the same as Python’s chr()\nfunction.
Like Length, it can be registered as a transform on IntegerField.\nThe default lookup name is chr.
Usage example:
\n>>> from django.db.models.functions import Chr\n>>> Author.objects.create(name="Margaret Smith")\n>>> author = Author.objects.filter(name__startswith=Chr(ord("M"))).get()\n>>> print(author.name)\nMargaret Smith\nConcatLink para este cabeçalho#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(). Specifying an\noutput_field is also required when concatenating a Value as in the\nexample 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(")"), output_field=CharField())\n... ).get()\n>>> print(author.screen_name)\nMargaret Smith (Maggie)\nLeftLink para este cabeçalho#Returns the first length characters of the given text field or expression.
Usage example:
\n>>> from django.db.models.functions import Left\n>>> Author.objects.create(name="Margaret Smith")\n>>> author = Author.objects.annotate(first_initial=Left("name", 1)).get()\n>>> print(author.first_initial)\nM\nLengthLink para este cabeçalho#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"), goes_by_length=Length("goes_by")\n... ).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)\n>>> # Get authors whose name is longer than 7 characters\n>>> authors = Author.objects.filter(name__length__gt=7)\nLowerLink para este cabeçalho#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\nLPadLink para este cabeçalho#Returns the value of the given text field or expression padded on the left side\nwith fill_text so that the resulting value is length characters long.\nThe default fill_text is a space.
Usage example:
\n>>> from django.db.models import Value\n>>> from django.db.models.functions import LPad\n>>> Author.objects.create(name="John", alias="j")\n>>> Author.objects.update(name=LPad("name", 8, Value("abc")))\n1\n>>> print(Author.objects.get(alias="j").name)\nabcaJohn\nLTrimLink para este cabeçalho#Similar to Trim, but removes only leading\nspaces.
MD5Link para este cabeçalho#Accepts a single text field or expression and returns the MD5 hash of the\nstring.
\nIt can also be registered as a transform as described in Length.
Usage example:
\n>>> from django.db.models.functions import MD5\n>>> Author.objects.create(name="Margaret Smith")\n>>> author = Author.objects.annotate(name_md5=MD5("name")).get()\n>>> print(author.name_md5)\n749fb689816b2db85f5b169c2055b247\nOrdLink para este cabeçalho#Accepts a single text field or expression and returns the Unicode code point\nvalue for the first character of that expression. It works similar to Python’s\nord() function, but an exception isn’t raised if the expression is more\nthan one character long.
It can also be registered as a transform as described in Length.\nThe default lookup name is ord.
Usage example:
\n>>> from django.db.models.functions import Ord\n>>> Author.objects.create(name="Margaret Smith")\n>>> author = Author.objects.annotate(name_code_point=Ord("name")).get()\n>>> print(author.name_code_point)\n77\nRepeatLink para este cabeçalho#Returns the value of the given text field or expression repeated number\ntimes.
Usage example:
\n>>> from django.db.models.functions import Repeat\n>>> Author.objects.create(name="John", alias="j")\n>>> Author.objects.update(name=Repeat("name", 3))\n1\n>>> print(Author.objects.get(alias="j").name)\nJohnJohnJohn\nReplaceLink para este cabeçalho#Replaces all occurrences of text with replacement in expression.\nThe default replacement text is the empty string. The arguments to the function\nare case-sensitive.
Usage example:
\n>>> from django.db.models import Value\n>>> from django.db.models.functions import Replace\n>>> Author.objects.create(name="Margaret Johnson")\n>>> Author.objects.create(name="Margaret Smith")\n>>> Author.objects.update(name=Replace("name", Value("Margaret"), Value("Margareth")))\n2\n>>> Author.objects.values("name")\n<QuerySet [{'name': 'Margareth Johnson'}, {'name': 'Margareth Smith'}]>\nReverseLink para este cabeçalho#Accepts a single text field or expression and returns the characters of that\nexpression in reverse order.
\nIt can also be registered as a transform as described in Length. The\ndefault lookup name is reverse.
Usage example:
\n>>> from django.db.models.functions import Reverse\n>>> Author.objects.create(name="Margaret Smith")\n>>> author = Author.objects.annotate(backward=Reverse("name")).get()\n>>> print(author.backward)\nhtimS teragraM\nRightLink para este cabeçalho#Returns the last length characters of the given text field or expression.
Usage example:
\n>>> from django.db.models.functions import Right\n>>> Author.objects.create(name="Margaret Smith")\n>>> author = Author.objects.annotate(last_letter=Right("name", 1)).get()\n>>> print(author.last_letter)\nh\nRPadLink para este cabeçalho#Similar to LPad, but pads on the right\nside.
RTrimLink para este cabeçalho#Similar to Trim, but removes only trailing\nspaces.
SHA1, SHA224, SHA256, SHA384, and SHA512Link para este cabeçalho#Accepts a single text field or expression and returns the particular hash of\nthe string.
\nThey can also be registered as transforms as described in Length.
Usage example:
\n>>> from django.db.models.functions import SHA1\n>>> Author.objects.create(name="Margaret Smith")\n>>> author = Author.objects.annotate(name_sha1=SHA1("name")).get()\n>>> print(author.name_sha1)\nb87efd8a6c991c390be5a68e8a7945a7851c7e5c\nStrIndexLink para este cabeçalho#Returns a positive integer corresponding to the 1-indexed position of the first\noccurrence of substring inside expression, or 0 if substring is not\nfound.
Usage example:
\n>>> from django.db.models import Value as V\n>>> from django.db.models.functions import StrIndex\n>>> Author.objects.create(name="Margaret Smith")\n>>> Author.objects.create(name="Smith, Margaret")\n>>> Author.objects.create(name="Margaret Jackson")\n>>> Author.objects.filter(name="Margaret Jackson").annotate(\n... smith_index=StrIndex("name", V("Smith"))\n... ).get().smith_index\n0\n>>> authors = Author.objects.annotate(smith_index=StrIndex("name", V("Smith"))).filter(\n... smith_index__gt=0\n... )\n<QuerySet [<Author: Margaret Smith>, <Author: Smith, Margaret>]>\nSubstrLink para este cabeçalho#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\nreturned.
Usage example:
\n>>> # Set the alias to the first 5 characters of the name as lowercase\n>>> from django.db.models.functions import Lower, Substr\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\nTrimLink para este cabeçalho#Returns the value of the given text field or expression with leading and\ntrailing spaces removed.
\nUsage example:
\n>>> from django.db.models.functions import Trim\n>>> Author.objects.create(name=" John ", alias="j")\n>>> Author.objects.update(name=Trim("name"))\n1\n>>> print(Author.objects.get(alias="j").name)\nJohn\nUpperLink para este cabeçalho#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\nThere are a number of functions to use in a\nWindow expression for computing the rank\nof elements or the Ntile of some rows.
CumeDistLink para este cabeçalho#Calculates the cumulative distribution of a value within a window or partition.\nThe cumulative distribution is defined as the number of rows preceding or\npeered with the current row divided by the total number of rows in the frame.
\nDenseRankLink para este cabeçalho#Equivalent to Rank but does not have gaps.
FirstValueLink para este cabeçalho#Returns the value evaluated at the row that’s the first row of the window\nframe, or None if no such value exists.
LagLink para este cabeçalho#Calculates the value offset by offset, and if no row exists there, returns\ndefault.
default must have the same type as the expression, however, this is\nonly validated by the database and not in Python.
LastValueLink para este cabeçalho#Comparable to FirstValue, it calculates the last value in a given\nframe clause.
LeadLink para este cabeçalho#Calculates the leading value in a given frame. Both\noffset and default are evaluated with respect to the current row.
default must have the same type as the expression, however, this is\nonly validated by the database and not in Python.
NthValueLink para este cabeçalho#Computes the row relative to the offset nth (must be a positive value)\nwithin the window. Returns None if no row exists.
Some databases may handle a nonexistent nth-value differently. For example,\nOracle returns an empty string rather than None for character-based\nexpressions. Django doesn’t do any conversions in these cases.
NtileLink para este cabeçalho#Calculates a partition for each of the rows in the frame clause, distributing\nnumbers as evenly as possible between 1 and num_buckets. If the rows don’t\ndivide evenly into a number of buckets, one or more buckets will be represented\nmore frequently.
PercentRankLink para este cabeçalho#Computes the relative rank of the rows in the frame clause. This computation is\nequivalent to evaluating:
\n(rank - 1) / (total rows - 1)\nThe following table explains the calculation for the relative rank of a row:
\nRow # | \nValue | \nRank | \nCalculation | \nRelative Rank | \n
|---|---|---|---|---|
1 | \n15 | \n1 | \n(1-1)/(7-1) | \n0.0000 | \n
2 | \n20 | \n2 | \n(2-1)/(7-1) | \n0.1666 | \n
3 | \n20 | \n2 | \n(2-1)/(7-1) | \n0.1666 | \n
4 | \n20 | \n2 | \n(2-1)/(7-1) | \n0.1666 | \n
5 | \n30 | \n5 | \n(5-1)/(7-1) | \n0.6666 | \n
6 | \n30 | \n5 | \n(5-1)/(7-1) | \n0.6666 | \n
7 | \n40 | \n7 | \n(7-1)/(7-1) | \n1.0000 | \n
RankLink para este cabeçalho#Comparable to RowNumber, this function ranks rows in the window. The\ncomputed rank contains gaps. Use DenseRank to compute rank without\ngaps.
RowNumberLink para este cabeçalho#Computes the row number according to the ordering of either the frame clause\nor the ordering of the whole query if there is no partitioning of the\nwindow frame.
\n