DatabasfunktionerLink to this heading

Klasserna som dokumenteras nedan ger ett sätt för användare att använda funktioner som tillhandahålls av den underliggande databasen som anteckningar, aggregeringar eller filter i Django. Funktioner är också expressions, så de kan användas och kombineras med andra uttryck som aggregate functions.

Vi kommer att använda följande modell i exempel på varje funktion:

Code

class Author(models.Model):
    name = models.CharField(max_length=50)
    age = models.PositiveIntegerField(null=True, blank=True)
    alias = models.CharField(max_length=50, null=True, blank=True)
    goes_by = models.CharField(max_length=50, null=True, blank=True)

Vi rekommenderar vanligtvis inte att tillåta null=True för CharField eftersom detta gör att fältet kan ha två ”tomma värden”, men det är viktigt för Coalesce-exemplet nedan.

Jämförelse- och omvandlingsfunktionerLink to this heading

`Sändning`Link to this heading

class Cast(expression, output_field)Link to this definition

Tvingar resultattypen för expression att vara den från output_field.

Exempel på användning:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Cast
>>> Author.objects.create(age=25, name="Margaret Smith")
>>> author = Author.objects.annotate(
...     age_as_float=Cast("age", output_field=FloatField()),
... ).get()
>>> print(author.age_as_float)
25.0

`Koalesera`Link to this heading

class Coalesce(*expressions, **extra)Link to this definition

Accepterar en lista med minst två fältnamn eller uttryck och returnerar det första värdet som inte är null (observera att en tom sträng inte betraktas som ett null-värde). Varje argument måste vara av samma typ, så om du blandar text och siffror kommer det att resultera i ett databasfel.

Exempel på användning:

Python console

>>> # Get a screen name from least to most public
>>> from django.db.models import Sum
>>> from django.db.models.functions import Coalesce
>>> Author.objects.create(name="Margaret Smith", goes_by="Maggie")
>>> author = Author.objects.annotate(screen_name=Coalesce("alias", "goes_by", "name")).get()
>>> print(author.screen_name)
Maggie

>>> # Prevent an aggregate Sum() from returning None
>>> # The aggregate default argument uses Coalesce() under the hood.
>>> aggregated = Author.objects.aggregate(
...     combined_age=Sum("age"),
...     combined_age_default=Sum("age", default=0),
...     combined_age_coalesce=Coalesce(Sum("age"), 0),
... )
>>> print(aggregated["combined_age"])
None
>>> print(aggregated["combined_age_default"])
0
>>> print(aggregated["combined_age_coalesce"])
0

Varning

Ett Python-värde som skickas till Coalesce på MySQL kan konverteras till en felaktig typ om det inte uttryckligen kastas till rätt databastyp:

Python console

>>> from django.db.models import DateTimeField
>>> from django.db.models.functions import Cast, Coalesce
>>> from django.utils import timezone
>>> now = timezone.now()
>>> Coalesce("updated", Cast(now, DateTimeField()))

”SamarbetaLink to this heading

class Collate(expression, collation)Link to this definition

Tar emot ett uttryck och ett kollationsnamn att göra en sökning mot.

Till exempel: för att filtrera utan hänsyn till skiftfall i SQLite:

Python console

>>> Author.objects.filter(name=Collate(Value("john"), "nocase"))
<QuerySet [<Author: John>, <Author: john>]>

Det kan också användas vid beställning, till exempel med PostgreSQL:

Python console

>>> Author.objects.order_by(Collate("name", "et-x-icu"))
<QuerySet [<Author: Ursula>, <Author: Veronika>, <Author: Ülle>]>

`Greatest`Link to this heading

class Greatest(*expressions, **extra)Link to this definition

Accepterar en lista med minst två fältnamn eller uttryck och returnerar det största värdet. Varje argument måste vara av samma typ, så om man blandar text och siffror blir det ett databasfel.

Exempel på användning:

Code

class Blog(models.Model):
    body = models.TextField()
    modified = models.DateTimeField(auto_now=True)


class Comment(models.Model):
    body = models.TextField()
    modified = models.DateTimeField(auto_now=True)
    blog = models.ForeignKey(Blog, on_delete=models.CASCADE)

Python console

>>> from django.db.models.functions import Greatest
>>> blog = Blog.objects.create(body="Greatest is the best.")
>>> comment = Comment.objects.create(body="No, Least is better.", blog=blog)
>>> comments = Comment.objects.annotate(last_updated=Greatest("modified", "blog__modified"))
>>> annotated_comment = comments.get()

annotated_comment.last_updated kommer att vara den senaste av blog.modified och comment.modified.

`Minsta`Link to this heading

class Least(*expressions, **extra)Link to this definition

Accepterar en lista med minst två fältnamn eller uttryck och returnerar det minsta värdet. Varje argument måste vara av samma typ, så att blanda text och siffror kommer att resultera i ett databasfel.

`NullIf`Link to this heading

class NullIf(expression1, expression2)Link to this definition

Accepterar två uttryck och returnerar None om de är lika, annars returneras expression1.

DatumfunktionerLink to this heading

Vi kommer att använda följande modell i exempel på varje funktion:

Code

class Experiment(models.Model):
    start_datetime = models.DateTimeField()
    start_date = models.DateField(null=True, blank=True)
    start_time = models.TimeField(null=True, blank=True)
    end_datetime = models.DateTimeField(null=True, blank=True)
    end_date = models.DateField(null=True, blank=True)
    end_time = models.TimeField(null=True, blank=True)

`Extract`Link to this heading

class Extract(expression, lookup_name=None, tzinfo=None, **extra)Link to this definition

Extraherar en del av ett datum som ett tal.

Tar ett uttryck som representerar en DateField, DateTimeField, TimeField eller DurationField och ett lookup_name och returnerar den del av datumet som refereras av lookup_name som en IntegerField. Django använder vanligtvis databasernas extraheringsfunktion, så du kan använda vilket lookup_name som helst som din databas stöder. En underklass av tzinfo, som vanligtvis tillhandahålls av zoneinfo, kan skickas för att extrahera ett värde i en specifik tidszon.

Givet datatiden 2015-06-15 23:30:01.000321+00:00, returnerar den inbyggda lookup_name:

”år”: 2015
”iso_year”: 2015
”kvartal”: 2
”månad”: 6
”dag”: 15
”vecka”: 25
”veckodag”: 2
”iso_week_day”: 1
”timme”: 23
”minut”: 30
”andra”: 1

Om en annan tidszon som Australia/Melbourne är aktiv i Django, konverteras datatiden till tidszonen innan värdet extraheras. Tidszonsförskjutningen för Melbourne i exempeldatumet ovan är +10:00. De värden som returneras när denna tidszon är aktiv kommer att vara desamma som ovan med undantag för:

”dag”: 16
”veckodag”: 3
”iso_week_day”: 2
”timme”: 9

week_day värden

week_day lookup_type beräknas på ett annat sätt än i de flesta databaser och i Pythons standardfunktioner. Denna funktion returnerar 1 för söndag, 2 för måndag, till 7 för lördag.

Motsvarande beräkning i Python är:

Python console

>>> from datetime import datetime
>>> dt = datetime(2015, 6, 15)
>>> (dt.isoweekday() % 7) + 1
2

Varje lookup_name ovan har en motsvarande Extract subklass (listad nedan) som vanligtvis bör användas istället för den mer verbala motsvarigheten, t.ex. använd ExtractYear(...) istället för Extract(..., lookup_name='year').

Exempel på användning:

Python console

>>> from datetime import datetime
>>> from django.db.models.functions import Extract
>>> start = datetime(2015, 6, 15)
>>> end = datetime(2015, 7, 2)
>>> Experiment.objects.create(
...     start_datetime=start, start_date=start.date(), end_datetime=end, end_date=end.date()
... )
>>> # Add the experiment start year as a field in the QuerySet.
>>> experiment = Experiment.objects.annotate(
...     start_year=Extract("start_datetime", "year")
... ).get()
>>> experiment.start_year
2015
>>> # How many experiments completed in the same year in which they started?
>>> Experiment.objects.filter(start_datetime__year=Extract("end_datetime", "year")).count()
1

`DateField` utdragLink to this heading

class ExtractYear(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'year'

class ExtractIsoYear(expression, tzinfo=None, **extra)Link to this definition

Returnerar det ISO-8601 veckonumrerade året.

lookup_name = 'iso_year'

class ExtractMonth(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'month'

class ExtractDay(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'day'

class ExtractWeekDay(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'week_day'

class ExtractIsoWeekDay(expression, tzinfo=None, **extra)Link to this definition

Returnerar ISO-8601-veckodagen där dag 1 är måndag och dag 7 är söndag.

lookup_name = 'iso_week_day'

class ExtractWeek(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'week'

class ExtractQuarter(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'quarter'

Dessa är logiskt likvärdiga med Extract('date_field', lookup_name). Varje klass är också en Transform registrerad på DateField och DateTimeField som __(lookup_name), t.ex. __year.

Eftersom DateField inte har någon tidskomponent, kan endast Extract subklasser som hanterar datumdelar användas med DateField:

Python console

>>> from datetime import datetime, timezone
>>> from django.db.models.functions import (
...     ExtractDay,
...     ExtractMonth,
...     ExtractQuarter,
...     ExtractWeek,
...     ExtractIsoWeekDay,
...     ExtractWeekDay,
...     ExtractIsoYear,
...     ExtractYear,
... )
>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=timezone.utc)
>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.utc)
>>> Experiment.objects.create(
...     start_datetime=start_2015,
...     start_date=start_2015.date(),
...     end_datetime=end_2015,
...     end_date=end_2015.date(),
... )
>>> Experiment.objects.annotate(
...     year=ExtractYear("start_date"),
...     isoyear=ExtractIsoYear("start_date"),
...     quarter=ExtractQuarter("start_date"),
...     month=ExtractMonth("start_date"),
...     week=ExtractWeek("start_date"),
...     day=ExtractDay("start_date"),
...     weekday=ExtractWeekDay("start_date"),
...     isoweekday=ExtractIsoWeekDay("start_date"),
... ).values(
...     "year",
...     "isoyear",
...     "quarter",
...     "month",
...     "week",
...     "day",
...     "weekday",
...     "isoweekday",
... ).get(
...     end_date__year=ExtractYear("start_date")
... )
{'year': 2015, 'isoyear': 2015, 'quarter': 2, 'month': 6, 'week': 25,
 'day': 15, 'weekday': 2, 'isoweekday': 1}

`DateTimeField` utdragLink to this heading

Förutom följande kan alla utdrag för DateField som anges ovan också användas på DateTimeField .

class ExtractHour(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'hour'

class ExtractMinute(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'minute'

class ExtractSecond(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'second'

Dessa är logiskt likvärdiga med Extract('datetime_field', lookup_name). Varje klass är också en Transform registrerad på DateTimeField som __(lookup_name), t.ex. __minute.

exempel på DateTimeField:

Python console

>>> from datetime import datetime, timezone
>>> from django.db.models.functions import (
...     ExtractDay,
...     ExtractHour,
...     ExtractMinute,
...     ExtractMonth,
...     ExtractQuarter,
...     ExtractSecond,
...     ExtractWeek,
...     ExtractIsoWeekDay,
...     ExtractWeekDay,
...     ExtractIsoYear,
...     ExtractYear,
... )
>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=timezone.utc)
>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.utc)
>>> Experiment.objects.create(
...     start_datetime=start_2015,
...     start_date=start_2015.date(),
...     end_datetime=end_2015,
...     end_date=end_2015.date(),
... )
>>> Experiment.objects.annotate(
...     year=ExtractYear("start_datetime"),
...     isoyear=ExtractIsoYear("start_datetime"),
...     quarter=ExtractQuarter("start_datetime"),
...     month=ExtractMonth("start_datetime"),
...     week=ExtractWeek("start_datetime"),
...     day=ExtractDay("start_datetime"),
...     weekday=ExtractWeekDay("start_datetime"),
...     isoweekday=ExtractIsoWeekDay("start_datetime"),
...     hour=ExtractHour("start_datetime"),
...     minute=ExtractMinute("start_datetime"),
...     second=ExtractSecond("start_datetime"),
... ).values(
...     "year",
...     "isoyear",
...     "month",
...     "week",
...     "day",
...     "weekday",
...     "isoweekday",
...     "hour",
...     "minute",
...     "second",
... ).get(
...     end_datetime__year=ExtractYear("start_datetime")
... )
{'year': 2015, 'isoyear': 2015, 'quarter': 2, 'month': 6, 'week': 25,
 'day': 15, 'weekday': 2, 'isoweekday': 1, 'hour': 23, 'minute': 30,
 'second': 1}

När USE_TZ är True så lagras datatider i databasen i UTC. Om en annan tidszon är aktiv i Django konverteras datatiden till den tidszonen innan värdet extraheras. I exemplet nedan konverteras till tidszonen Melbourne (UTC +10:00), vilket ändrar värdena för dag, veckodag och timme som returneras:

Python console

>>> from django.utils import timezone
>>> import zoneinfo
>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")  # UTC+10:00
>>> with timezone.override(melb):
...     Experiment.objects.annotate(
...         day=ExtractDay("start_datetime"),
...         weekday=ExtractWeekDay("start_datetime"),
...         isoweekday=ExtractIsoWeekDay("start_datetime"),
...         hour=ExtractHour("start_datetime"),
...     ).values("day", "weekday", "isoweekday", "hour").get(
...         end_datetime__year=ExtractYear("start_datetime"),
...     )
...
{'day': 16, 'weekday': 3, 'isoweekday': 2, 'hour': 9}

Om du uttryckligen skickar tidszonen till funktionen Extract fungerar den på samma sätt och prioriteras framför en aktiv tidszon:

Python console

>>> import zoneinfo
>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")
>>> Experiment.objects.annotate(
...     day=ExtractDay("start_datetime", tzinfo=melb),
...     weekday=ExtractWeekDay("start_datetime", tzinfo=melb),
...     isoweekday=ExtractIsoWeekDay("start_datetime", tzinfo=melb),
...     hour=ExtractHour("start_datetime", tzinfo=melb),
... ).values("day", "weekday", "isoweekday", "hour").get(
...     end_datetime__year=ExtractYear("start_datetime"),
... )
{'day': 16, 'weekday': 3, 'isoweekday': 2, 'hour': 9}

`Nu`Link to this heading

class NowLink to this definition

Returnerar databasserverns aktuella datum och tid när frågan körs, vanligtvis med hjälp av SQL CURRENT_TIMESTAMP.

Exempel på användning:

Python console

>>> from django.db.models.functions import Now
>>> Article.objects.filter(published__lte=Now())
<QuerySet [<Article: How to Django>]>

`Trunc`Link to this heading

class Trunc(expression, kind, output_field=None, tzinfo=None, **extra)Link to this definition

Avkortar ett datum upp till en betydande del.

När du bara bryr dig om att något hände under ett visst år, en viss timme eller dag, men inte den exakta sekunden, kan Trunc (och dess underklasser) vara användbara för att filtrera eller aggregera dina data. Du kan t.ex. använda Trunc för att beräkna antalet försäljningar per dag.

Trunc tar ett enda uttryck, som representerar en DateField, TimeField eller DateTimeField, en kind som representerar en datum- eller tidsdel och ett output_field som är antingen DateTimeField(), TimeField() eller DateField(). Den returnerar en datetime, ett datum eller en tid beroende på output_field, med fält upp till kind inställda på sitt lägsta värde. Om output_field utelämnas kommer den att använda output_field från expression som standard. En underklass till tzinfo, som vanligtvis tillhandahålls av zoneinfo, kan skickas för att trunkera ett värde i en specifik tidszon.

Givet datatiden 2015-06-15 14:30:50.000321+00:00, returnerar den inbyggda kind:

”år”: 2015-01-01 00:00:00+00:00
”kvartal”: 2015-04-01 00:00:00+00:00
”månad”: 2015-06-01 00:00:00+00:00
”vecka”: 2015-06-15 00:00:00+00:00
”dag”: 2015-06-15 00:00:00+00:00
”timme”: 2015-06-15 14:00:00+00:00
”minut”: 2015-06-15 14:30:00+00:00
”andra”: 2015-06-15 14:30:50+00:00

Om en annan tidszon som Australia/Melbourne är aktiv i Django, konverteras datumen till den nya tidszonen innan värdet trunkeras. Tidszonförskjutningen för Melbourne i exempeldatumet ovan är +10:00. De värden som returneras när denna tidszon är aktiv kommer att vara:

”år”: 2015-01-01 00:00:00+11:00
”kvartal”: 2015-04-01 00:00:00+10:00
”månad”: 2015-06-01 00:00:00+10:00
”vecka”: 2015-06-16 00:00:00+10:00
”dag”: 2015-06-16 00:00:00+10:00
”timme”: 2015-06-16 00:00:00+10:00
”minut”: 2015-06-16 00:30:00+10:00
”andra”: 2015-06-16 00:30:50+10:00

Året har en förskjutning på +11:00 eftersom resultatet övergick till sommartid.

Varje kind ovan har en motsvarande Trunc underklass (listad nedan) som typiskt bör användas istället för den mer ordrika motsvarigheten, t.ex. använd TruncYear(...) istället för Trunc(..., kind='year').

Underklasserna är alla definierade som transformationer, men de är inte registrerade med några fält, eftersom uppslagsnamnen redan är reserverade av underklasserna Extract.

Exempel på användning:

Python console

>>> from datetime import datetime
>>> from django.db.models import Count, DateTimeField
>>> from django.db.models.functions import Trunc
>>> Experiment.objects.create(start_datetime=datetime(2015, 6, 15, 14, 30, 50, 321))
>>> Experiment.objects.create(start_datetime=datetime(2015, 6, 15, 14, 40, 2, 123))
>>> Experiment.objects.create(start_datetime=datetime(2015, 12, 25, 10, 5, 27, 999))
>>> experiments_per_day = (
...     Experiment.objects.annotate(
...         start_day=Trunc("start_datetime", "day", output_field=DateTimeField())
...     )
...     .values("start_day")
...     .annotate(experiments=Count("id"))
... )
>>> for exp in experiments_per_day:
...     print(exp["start_day"], exp["experiments"])
...
2015-06-15 00:00:00 2
2015-12-25 00:00:00 1
>>> experiments = Experiment.objects.annotate(
...     start_day=Trunc("start_datetime", "day", output_field=DateTimeField())
... ).filter(start_day=datetime(2015, 6, 15))
>>> for exp in experiments:
...     print(exp.start_datetime)
...
2015-06-15 14:30:50.000321
2015-06-15 14:40:02.000123

trunkering av `DateField`Link to this heading

class TruncYear(expression, output_field=None, tzinfo=None, **extra)Link to this definition

kind = 'year'

class TruncMonth(expression, output_field=None, tzinfo=None, **extra)Link to this definition

kind = 'month'

class TruncWeek(expression, output_field=None, tzinfo=None, **extra)Link to this definition

Trunkeras till midnatt på måndagen i veckan.

kind = 'week'

class TruncQuarter(expression, output_field=None, tzinfo=None, **extra)Link to this definition

kind = 'quarter'

Dessa är logiskt likvärdiga med Trunc('date_field', kind). De trunkerar alla delar av datumet upp till kind vilket gör det möjligt att gruppera eller filtrera datum med mindre precision. expression kan ha ett output_field av antingen DateField eller DateTimeField.

Eftersom DateField inte har någon tidskomponent, kan endast Trunc subklasser som hanterar date-parts användas med DateField:

Python console

>>> from datetime import datetime, timezone
>>> from django.db.models import Count
>>> from django.db.models.functions import TruncMonth, TruncYear
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)
>>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)
>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.utc)
>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())
>>> Experiment.objects.create(start_datetime=start2, start_date=start2.date())
>>> Experiment.objects.create(start_datetime=start3, start_date=start3.date())
>>> experiments_per_year = (
...     Experiment.objects.annotate(year=TruncYear("start_date"))
...     .values("year")
...     .annotate(experiments=Count("id"))
... )
>>> for exp in experiments_per_year:
...     print(exp["year"], exp["experiments"])
...
2014-01-01 1
2015-01-01 2

>>> import zoneinfo
>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")
>>> experiments_per_month = (
...     Experiment.objects.annotate(month=TruncMonth("start_datetime", tzinfo=melb))
...     .values("month")
...     .annotate(experiments=Count("id"))
... )
>>> for exp in experiments_per_month:
...     print(exp["month"], exp["experiments"])
...
2015-06-01 00:00:00+10:00 1
2016-01-01 00:00:00+11:00 1
2014-06-01 00:00:00+10:00 1

trunkering av `DateTimeField`Link to this heading

class TruncDate(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'date'

output_field = DateField()

TruncDate kastar uttryck till ett datum istället för att använda den inbyggda SQL truncate-funktionen. Den är också registrerad som en transform på DateTimeField som __date.

class TruncTime(expression, tzinfo=None, **extra)Link to this definition

lookup_name = 'time'

output_field = TimeField()

TruncTime kastar uttryck till en tid istället för att använda den inbyggda SQL truncate-funktionen. Den är också registrerad som en transform på DateTimeField som __time.

class TruncDay(expression, output_field=None, tzinfo=None, **extra)Link to this definition

kind = 'day'

class TruncHour(expression, output_field=None, tzinfo=None, **extra)Link to this definition

kind = 'hour'

class TruncMinute(expression, output_field=None, tzinfo=None, **extra)Link to this definition

kind = 'minute'

class TruncSecond(expression, output_field=None, tzinfo=None, **extra)Link to this definition

kind = 'second'

Dessa är logiskt likvärdiga med Trunc('datetime_field', kind). De trunkerar alla delar av datumet upp till kind och tillåter gruppering eller filtrering av datumtider med mindre precision. expression måste ha ett output_field av DateTimeField.

Exempel på användning:

Python console

>>> from datetime import date, datetime, timezone
>>> from django.db.models import Count
>>> from django.db.models.functions import (
...     TruncDate,
...     TruncDay,
...     TruncHour,
...     TruncMinute,
...     TruncSecond,
... )
>>> import zoneinfo
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)
>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())
>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")
>>> Experiment.objects.annotate(
...     date=TruncDate("start_datetime"),
...     day=TruncDay("start_datetime", tzinfo=melb),
...     hour=TruncHour("start_datetime", tzinfo=melb),
...     minute=TruncMinute("start_datetime"),
...     second=TruncSecond("start_datetime"),
... ).values("date", "day", "hour", "minute", "second").get()
{'date': datetime.date(2014, 6, 15),
 'day': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=zoneinfo.ZoneInfo('Australia/Melbourne')),
 'hour': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=zoneinfo.ZoneInfo('Australia/Melbourne')),
 'minute': 'minute': datetime.datetime(2014, 6, 15, 14, 30, tzinfo=timezone.utc),
 'second': datetime.datetime(2014, 6, 15, 14, 30, 50, tzinfo=timezone.utc)
}

trunkering av `TimeField`Link to this heading

class TruncHour(expression, output_field=None, tzinfo=None, **extra)

kind = 'hour'

class TruncMinute(expression, output_field=None, tzinfo=None, **extra)

kind = 'minute'

class TruncSecond(expression, output_field=None, tzinfo=None, **extra)

kind = 'second'

Dessa är logiskt likvärdiga med Trunc('time_field', kind). De trunkerar alla delar av tiden upp till kind vilket gör det möjligt att gruppera eller filtrera tider med mindre precision. uttryck kan ha ett utgångsfält av antingen TimeField eller DateTimeField.

Eftersom TimeField inte har någon datumkomponent, kan endast Trunc subklasser som hanterar tidsdelar användas med TimeField:

Python console

>>> from datetime import datetime, timezone
>>> from django.db.models import Count, TimeField
>>> from django.db.models.functions import TruncHour
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)
>>> start2 = datetime(2014, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)
>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.utc)
>>> Experiment.objects.create(start_datetime=start1, start_time=start1.time())
>>> Experiment.objects.create(start_datetime=start2, start_time=start2.time())
>>> Experiment.objects.create(start_datetime=start3, start_time=start3.time())
>>> experiments_per_hour = (
...     Experiment.objects.annotate(
...         hour=TruncHour("start_datetime", output_field=TimeField()),
...     )
...     .values("hour")
...     .annotate(experiments=Count("id"))
... )
>>> for exp in experiments_per_hour:
...     print(exp["hour"], exp["experiments"])
...
14:00:00 2
17:00:00 1

>>> import zoneinfo
>>> melb = zoneinfo.ZoneInfo("Australia/Melbourne")
>>> experiments_per_hour = (
...     Experiment.objects.annotate(
...         hour=TruncHour("start_datetime", tzinfo=melb),
...     )
...     .values("hour")
...     .annotate(experiments=Count("id"))
... )
>>> for exp in experiments_per_hour:
...     print(exp["hour"], exp["experiments"])
...
2014-06-16 00:00:00+10:00 2
2016-01-01 04:00:00+11:00 1

JSON-funktionerLink to this heading

`JSONArray`Link to this heading

class JSONArray(*expressions)Link to this definition

Accepterar en lista med fältnamn eller uttryck och returnerar en JSON-array som innehåller dessa värden.

Exempel på användning:

Python console

>>> from django.db.models import F
>>> from django.db.models.functions import JSONArray, Lower
>>> Author.objects.create(name="Margaret Smith", alias="msmith", age=25)
>>> author = Author.objects.annotate(
...     json_array=JSONArray(
...         Lower("name"),
...         "alias",
...         F("age") * 2,
...     )
... ).get()
>>> author.json_array
['margaret smith', 'msmith', 50]

`JSONObject`Link to this heading

class JSONObject(**fields)Link to this definition

Tar emot en lista med nyckel-värde-par och returnerar ett JSON-objekt som innehåller dessa par.

Exempel på användning:

Python console

>>> from django.db.models import F
>>> from django.db.models.functions import JSONObject, Lower
>>> Author.objects.create(name="Margaret Smith", alias="msmith", age=25)
>>> author = Author.objects.annotate(
...     json_object=JSONObject(
...         name=Lower("name"),
...         alias="alias",
...         age=F("age") * 2,
...     )
... ).get()
>>> author.json_object
{'name': 'margaret smith', 'alias': 'msmith', 'age': 50}

Matematiska funktionerLink to this heading

Vi kommer att använda följande modell i exempel på matematiska funktioner:

Code

class Vector(models.Model):
    x = models.FloatField()
    y = models.FloatField()

`Abs`Link to this heading

class Abs(expression, **extra)Link to this definition

Returnerar det absoluta värdet av ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Abs
>>> Vector.objects.create(x=-0.5, y=1.1)
>>> vector = Vector.objects.annotate(x_abs=Abs("x"), y_abs=Abs("y")).get()
>>> vector.x_abs, vector.y_abs
(0.5, 1.1)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Abs
>>> FloatField.register_lookup(Abs)
>>> # Get vectors inside the unit cube
>>> vectors = Vector.objects.filter(x__abs__lt=1, y__abs__lt=1)

”ACosLink to this heading

class ACos(expression, **extra)Link to this definition

Returnerar arccosinus för ett numeriskt fält eller uttryck. Uttryckets värde måste ligga inom intervallet -1 till 1.

Exempel på användning:

Python console

>>> from django.db.models.functions import ACos
>>> Vector.objects.create(x=0.5, y=-0.9)
>>> vector = Vector.objects.annotate(x_acos=ACos("x"), y_acos=ACos("y")).get()
>>> vector.x_acos, vector.y_acos
(1.0471975511965979, 2.6905658417935308)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import ACos
>>> FloatField.register_lookup(ACos)
>>> # Get vectors whose arccosine is less than 1
>>> vectors = Vector.objects.filter(x__acos__lt=1, y__acos__lt=1)

`ASin`Link to this heading

class ASin(expression, **extra)Link to this definition

Returnerar arcsinus för ett numeriskt fält eller uttryck. Uttryckets värde måste ligga inom intervallet -1 till 1.

Exempel på användning:

Python console

>>> from django.db.models.functions import ASin
>>> Vector.objects.create(x=0, y=1)
>>> vector = Vector.objects.annotate(x_asin=ASin("x"), y_asin=ASin("y")).get()
>>> vector.x_asin, vector.y_asin
(0.0, 1.5707963267948966)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import ASin
>>> FloatField.register_lookup(ASin)
>>> # Get vectors whose arcsine is less than 1
>>> vectors = Vector.objects.filter(x__asin__lt=1, y__asin__lt=1)

`ATan`Link to this heading

class ATan(expression, **extra)Link to this definition

Returnerar arctangenten för ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import ATan
>>> Vector.objects.create(x=3.12, y=6.987)
>>> vector = Vector.objects.annotate(x_atan=ATan("x"), y_atan=ATan("y")).get()
>>> vector.x_atan, vector.y_atan
(1.2606282660069106, 1.428638798133829)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import ATan
>>> FloatField.register_lookup(ATan)
>>> # Get vectors whose arctangent is less than 2
>>> vectors = Vector.objects.filter(x__atan__lt=2, y__atan__lt=2)

`ATan2`Link to this heading

class ATan2(expression1, expression2, **extra)Link to this definition

Returnerar arctangenten av uttryck1 / uttryck2.

Exempel på användning:

Python console

>>> from django.db.models.functions import ATan2
>>> Vector.objects.create(x=2.5, y=1.9)
>>> vector = Vector.objects.annotate(atan2=ATan2("x", "y")).get()
>>> vector.atan2
0.9209258773829491

`Tak`Link to this heading

class Ceil(expression, **extra)Link to this definition

Returnerar det minsta heltalet som är större än eller lika med ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Ceil
>>> Vector.objects.create(x=3.12, y=7.0)
>>> vector = Vector.objects.annotate(x_ceil=Ceil("x"), y_ceil=Ceil("y")).get()
>>> vector.x_ceil, vector.y_ceil
(4.0, 7.0)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Ceil
>>> FloatField.register_lookup(Ceil)
>>> # Get vectors whose ceil is less than 10
>>> vectors = Vector.objects.filter(x__ceil__lt=10, y__ceil__lt=10)

`Cos`Link to this heading

class Cos(expression, **extra)Link to this definition

Returnerar cosinus för ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Cos
>>> Vector.objects.create(x=-8.0, y=3.1415926)
>>> vector = Vector.objects.annotate(x_cos=Cos("x"), y_cos=Cos("y")).get()
>>> vector.x_cos, vector.y_cos
(-0.14550003380861354, -0.9999999999999986)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Cos
>>> FloatField.register_lookup(Cos)
>>> # Get vectors whose cosine is less than 0.5
>>> vectors = Vector.objects.filter(x__cos__lt=0.5, y__cos__lt=0.5)

`Cot`Link to this heading

class Cot(expression, **extra)Link to this definition

Returnerar cotangenten för ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Cot
>>> Vector.objects.create(x=12.0, y=1.0)
>>> vector = Vector.objects.annotate(x_cot=Cot("x"), y_cot=Cot("y")).get()
>>> vector.x_cot, vector.y_cot
(-1.5726734063976826, 0.642092615934331)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Cot
>>> FloatField.register_lookup(Cot)
>>> # Get vectors whose cotangent is less than 1
>>> vectors = Vector.objects.filter(x__cot__lt=1, y__cot__lt=1)

`Degrees`Link to this heading

class Degrees(expression, **extra)Link to this definition

Konverterar ett numeriskt fält eller uttryck från radianer till grader.

Exempel på användning:

Python console

>>> from django.db.models.functions import Degrees
>>> Vector.objects.create(x=-1.57, y=3.14)
>>> vector = Vector.objects.annotate(x_d=Degrees("x"), y_d=Degrees("y")).get()
>>> vector.x_d, vector.y_d
(-89.95437383553924, 179.9087476710785)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Degrees
>>> FloatField.register_lookup(Degrees)
>>> # Get vectors whose degrees are less than 360
>>> vectors = Vector.objects.filter(x__degrees__lt=360, y__degrees__lt=360)

`Exp`Link to this heading

class Exp(expression, **extra)Link to this definition

Returnerar värdet av e (den naturliga logaritmens bas) upphöjt till en potens i ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Exp
>>> Vector.objects.create(x=5.4, y=-2.0)
>>> vector = Vector.objects.annotate(x_exp=Exp("x"), y_exp=Exp("y")).get()
>>> vector.x_exp, vector.y_exp
(221.40641620418717, 0.1353352832366127)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Exp
>>> FloatField.register_lookup(Exp)
>>> # Get vectors whose exp() is greater than 10
>>> vectors = Vector.objects.filter(x__exp__gt=10, y__exp__gt=10)

`Golv`Link to this heading

class Floor(expression, **extra)Link to this definition

Returnerar det största heltalsvärdet som inte är större än ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Floor
>>> Vector.objects.create(x=5.4, y=-2.3)
>>> vector = Vector.objects.annotate(x_floor=Floor("x"), y_floor=Floor("y")).get()
>>> vector.x_floor, vector.y_floor
(5.0, -3.0)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Floor
>>> FloatField.register_lookup(Floor)
>>> # Get vectors whose floor() is greater than 10
>>> vectors = Vector.objects.filter(x__floor__gt=10, y__floor__gt=10)

`Ln`Link to this heading

class Ln(expression, **extra)Link to this definition

Returnerar den naturliga logaritmen för ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Ln
>>> Vector.objects.create(x=5.4, y=233.0)
>>> vector = Vector.objects.annotate(x_ln=Ln("x"), y_ln=Ln("y")).get()
>>> vector.x_ln, vector.y_ln
(1.6863989535702288, 5.4510384535657)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Ln
>>> FloatField.register_lookup(Ln)
>>> # Get vectors whose value greater than e
>>> vectors = Vector.objects.filter(x__ln__gt=1, y__ln__gt=1)

`Log`Link to this heading

class Log(expression1, expression2, **extra)Link to this definition

Accepterar två numeriska fält eller uttryck och returnerar logaritmen av det andra till basen av det första.

Exempel på användning:

Python console

>>> from django.db.models.functions import Log
>>> Vector.objects.create(x=2.0, y=4.0)
>>> vector = Vector.objects.annotate(log=Log("x", "y")).get()
>>> vector.log
2.0

`Mod`Link to this heading

class Mod(expression1, expression2, **extra)Link to this definition

Accepterar två numeriska fält eller uttryck och returnerar resten av det första dividerat med det andra (modulooperation).

Exempel på användning:

Python console

>>> from django.db.models.functions import Mod
>>> Vector.objects.create(x=5.4, y=2.3)
>>> vector = Vector.objects.annotate(mod=Mod("x", "y")).get()
>>> vector.mod
0.8

`Pi`Link to this heading

class Pi(**extra)Link to this definition

Returnerar värdet av den matematiska konstanten π.

`Kraft`Link to this heading

class Power(expression1, expression2, **extra)Link to this definition

Accepterar två numeriska fält eller uttryck och returnerar värdet av det första upphöjt till potensen av det andra.

Exempel på användning:

Python console

>>> from django.db.models.functions import Power
>>> Vector.objects.create(x=2, y=-2)
>>> vector = Vector.objects.annotate(power=Power("x", "y")).get()
>>> vector.power
0.25

`Radianer`Link to this heading

class Radians(expression, **extra)Link to this definition

Konverterar ett numeriskt fält eller uttryck från grader till radianer.

Exempel på användning:

Python console

>>> from django.db.models.functions import Radians
>>> Vector.objects.create(x=-90, y=180)
>>> vector = Vector.objects.annotate(x_r=Radians("x"), y_r=Radians("y")).get()
>>> vector.x_r, vector.y_r
(-1.5707963267948966, 3.141592653589793)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Radians
>>> FloatField.register_lookup(Radians)
>>> # Get vectors whose radians are less than 1
>>> vectors = Vector.objects.filter(x__radians__lt=1, y__radians__lt=1)

`Random`Link to this heading

class Random(**extra)Link to this definition

Returnerar ett slumpmässigt värde i intervallet 0,0 ≤ x < 1,0.

`Rund`Link to this heading

class Round(expression, precision=0, **extra)Link to this definition

Avrundar ett numeriskt fält eller uttryck till precision (måste vara ett heltal) decimaler. Som standard avrundas till närmaste heltal. Huruvida halva värden avrundas uppåt eller nedåt beror på databasen.

Exempel på användning:

Python console

>>> from django.db.models.functions import Round
>>> Vector.objects.create(x=5.4, y=-2.37)
>>> vector = Vector.objects.annotate(x_r=Round("x"), y_r=Round("y", precision=1)).get()
>>> vector.x_r, vector.y_r
(5.0, -2.4)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Round
>>> FloatField.register_lookup(Round)
>>> # Get vectors whose round() is less than 20
>>> vectors = Vector.objects.filter(x__round__lt=20, y__round__lt=20)

`Sign`Link to this heading

class Sign(expression, **extra)Link to this definition

Returnerar tecknet (-1, 0, 1) för ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Sign
>>> Vector.objects.create(x=5.4, y=-2.3)
>>> vector = Vector.objects.annotate(x_sign=Sign("x"), y_sign=Sign("y")).get()
>>> vector.x_sign, vector.y_sign
(1, -1)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Sign
>>> FloatField.register_lookup(Sign)
>>> # Get vectors whose signs of components are less than 0.
>>> vectors = Vector.objects.filter(x__sign__lt=0, y__sign__lt=0)

`Sin`Link to this heading

class Sin(expression, **extra)Link to this definition

Returnerar sinus för ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Sin
>>> Vector.objects.create(x=5.4, y=-2.3)
>>> vector = Vector.objects.annotate(x_sin=Sin("x"), y_sin=Sin("y")).get()
>>> vector.x_sin, vector.y_sin
(-0.7727644875559871, -0.7457052121767203)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Sin
>>> FloatField.register_lookup(Sin)
>>> # Get vectors whose sin() is less than 0
>>> vectors = Vector.objects.filter(x__sin__lt=0, y__sin__lt=0)

`Sqrt`Link to this heading

class Sqrt(expression, **extra)Link to this definition

Returnerar kvadratroten av ett icke-negativt numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Sqrt
>>> Vector.objects.create(x=4.0, y=12.0)
>>> vector = Vector.objects.annotate(x_sqrt=Sqrt("x"), y_sqrt=Sqrt("y")).get()
>>> vector.x_sqrt, vector.y_sqrt
(2.0, 3.46410)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Sqrt
>>> FloatField.register_lookup(Sqrt)
>>> # Get vectors whose sqrt() is less than 5
>>> vectors = Vector.objects.filter(x__sqrt__lt=5, y__sqrt__lt=5)

`Tan`Link to this heading

class Tan(expression, **extra)Link to this definition

Returnerar tangenten för ett numeriskt fält eller uttryck.

Exempel på användning:

Python console

>>> from django.db.models.functions import Tan
>>> Vector.objects.create(x=0, y=12)
>>> vector = Vector.objects.annotate(x_tan=Tan("x"), y_tan=Tan("y")).get()
>>> vector.x_tan, vector.y_tan
(0.0, -0.6358599286615808)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Tan
>>> FloatField.register_lookup(Tan)
>>> # Get vectors whose tangent is less than 0
>>> vectors = Vector.objects.filter(x__tan__lt=0, y__tan__lt=0)

TextfunktionerLink to this heading

`Chr`Link to this heading

class Chr(expression, **extra)Link to this definition

Accepterar ett numeriskt fält eller uttryck och returnerar textrepresentationen av uttrycket som ett enda tecken. Den fungerar på samma sätt som Pythons funktion chr().

Precis som Length kan den registreras som en transform på IntegerField. Standarduppslagsnamnet är chr.

Exempel på användning:

Python console

>>> from django.db.models.functions import Chr
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.filter(name__startswith=Chr(ord("M"))).get()
>>> print(author.name)
Margaret Smith

`Concat`Link to this heading

class Concat(*expressions, **extra)Link to this definition

Accepterar en lista med minst två textfält eller uttryck och returnerar den sammanlänkade texten. Varje argument måste vara av typen text eller char. Om du vill konkatenera ett TextField() med ett CharField(), se då till att tala om för Django att output_field ska vara ett TextField(). Att ange ett output_field krävs också när man sammanfogar ett Value som i exemplet nedan.

Denna funktion kommer aldrig att ha ett null-resultat. På backends där ett null-argument resulterar i att hela uttrycket blir null, kommer Django att se till att varje null-del konverteras till en tom sträng först.

Exempel på användning:

Python console

>>> # Get the display name as "name (goes_by)"
>>> from django.db.models import CharField, Value as V
>>> from django.db.models.functions import Concat
>>> Author.objects.create(name="Margaret Smith", goes_by="Maggie")
>>> author = Author.objects.annotate(
...     screen_name=Concat("name", V(" ("), "goes_by", V(")"), output_field=CharField())
... ).get()
>>> print(author.screen_name)
Margaret Smith (Maggie)

`Vänster`Link to this heading

class Left(expression, length, **extra)Link to this definition

Returnerar de första tecknen i length i det angivna textfältet eller uttrycket.

Exempel på användning:

Python console

>>> from django.db.models.functions import Left
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(first_initial=Left("name", 1)).get()
>>> print(author.first_initial)
M

`Längd`Link to this heading

class Length(expression, **extra)Link to this definition

Accepterar ett enda textfält eller uttryck och returnerar antalet tecken som värdet har. Om uttrycket är null blir längden också null.

Exempel på användning:

Python console

>>> # Get the length of the name and goes_by fields
>>> from django.db.models.functions import Length
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(
...     name_length=Length("name"), goes_by_length=Length("goes_by")
... ).get()
>>> print(author.name_length, author.goes_by_length)
(14, None)

Den kan också registreras som en transform. Till exempel:

Python console

>>> from django.db.models import CharField
>>> from django.db.models.functions import Length
>>> CharField.register_lookup(Length)
>>> # Get authors whose name is longer than 7 characters
>>> authors = Author.objects.filter(name__length__gt=7)

`Lägre`Link to this heading

class Lower(expression, **extra)Link to this definition

Accepterar ett enda textfält eller uttryck och returnerar representationen med små bokstäver.

Den kan också registreras som en transform enligt beskrivningen i Length.

Exempel på användning:

Python console

>>> from django.db.models.functions import Lower
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(name_lower=Lower("name")).get()
>>> print(author.name_lower)
margaret smith

`LPad`Link to this heading

class LPad(expression, length, fill_text=Value(' '), **extra)Link to this definition

Returnerar värdet i det angivna textfältet eller uttrycket, utfyllt på vänster sida med fill_text så att det resulterande värdet är length tecken långt. Standardvärdet för fill_text är ett mellanslag.

Exempel på användning:

Python console

>>> from django.db.models import Value
>>> from django.db.models.functions import LPad
>>> Author.objects.create(name="John", alias="j")
>>> Author.objects.update(name=LPad("name", 8, Value("abc")))
1
>>> print(Author.objects.get(alias="j").name)
abcaJohn

`LTrim`Link to this heading

class LTrim(expression, **extra)Link to this definition

Liknar Trim, men tar bara bort inledande mellanslag.

`MD5`Link to this heading

class MD5(expression, **extra)Link to this definition

Accepterar ett enda textfält eller uttryck och returnerar MD5-hashvärdet för strängen.

Den kan också registreras som en transform enligt beskrivningen i Length.

Exempel på användning:

Python console

>>> from django.db.models.functions import MD5
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(name_md5=MD5("name")).get()
>>> print(author.name_md5)
749fb689816b2db85f5b169c2055b247

`Ord`Link to this heading

class Ord(expression, **extra)Link to this definition

Accepterar ett enda textfält eller uttryck och returnerar Unicode-kodpunktsvärdet för det första tecknet i uttrycket. Den fungerar på samma sätt som Pythons funktion ord(), men ett undantag görs inte om uttrycket är mer än ett tecken långt.

Den kan också registreras som en transform enligt beskrivningen i Length. Standardnamnet på uppslagsordet är ord.

Exempel på användning:

Python console

>>> from django.db.models.functions import Ord
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(name_code_point=Ord("name")).get()
>>> print(author.name_code_point)
77

`Upprepa`Link to this heading

class Repeat(expression, number, **extra)Link to this definition

Returnerar värdet av det angivna textfältet eller uttrycket som upprepats antal gånger.

Exempel på användning:

Python console

>>> from django.db.models.functions import Repeat
>>> Author.objects.create(name="John", alias="j")
>>> Author.objects.update(name=Repeat("name", 3))
1
>>> print(Author.objects.get(alias="j").name)
JohnJohnJohn

`Replace`Link to this heading

class Replace(expression, text, replacement=Value(''), **extra)Link to this definition

Ersätter alla förekomster av text med replacement i expression. Standardvärdet för ersättningstexten är den tomma strängen. Argumenten till funktionen är skiftlägeskänsliga.

Exempel på användning:

Python console

>>> from django.db.models import Value
>>> from django.db.models.functions import Replace
>>> Author.objects.create(name="Margaret Johnson")
>>> Author.objects.create(name="Margaret Smith")
>>> Author.objects.update(name=Replace("name", Value("Margaret"), Value("Margareth")))
2
>>> Author.objects.values("name")
<QuerySet [{'name': 'Margareth Johnson'}, {'name': 'Margareth Smith'}]>

`Reverse`Link to this heading

class Reverse(expression, **extra)Link to this definition

Accepterar ett enda textfält eller uttryck och returnerar tecknen i uttrycket i omvänd ordning.

Den kan också registreras som en transform enligt beskrivningen i Length. Standarduppslagsnamnet är reverse.

Exempel på användning:

Python console

>>> from django.db.models.functions import Reverse
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(backward=Reverse("name")).get()
>>> print(author.backward)
htimS teragraM

`Höger`Link to this heading

class Right(expression, length, **extra)Link to this definition

Returnerar de sista tecknen i length i det angivna textfältet eller uttrycket.

Exempel på användning:

Python console

>>> from django.db.models.functions import Right
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(last_letter=Right("name", 1)).get()
>>> print(author.last_letter)
h

`RPad`Link to this heading

class RPad(expression, length, fill_text=Value(' '), **extra)Link to this definition

Liknar LPad, men är på höger sida.

`RTrim`Link to this heading

class RTrim(expression, **extra)Link to this definition

Liknar Trim, men tar bara bort efterföljande mellanslag.

`SHA1`, `SHA224`, `SHA256`, `SHA384` och `SHA512`Link to this heading

class SHA1(expression, **extra)Link to this definition

class SHA224(expression, **extra)Link to this definition

class SHA256(expression, **extra)Link to this definition

class SHA384(expression, **extra)Link to this definition

class SHA512(expression, **extra)Link to this definition

Accepterar ett enda textfält eller uttryck och returnerar den specifika hashen för strängen.

De kan också registreras som transformationer enligt beskrivningen i Length.

Exempel på användning:

Python console

>>> from django.db.models.functions import SHA1
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(name_sha1=SHA1("name")).get()
>>> print(author.name_sha1)
b87efd8a6c991c390be5a68e8a7945a7851c7e5c

`StrIndex`Link to this heading

class StrIndex(string, substring, **extra)Link to this definition

Returnerar ett positivt heltal som motsvarar den 1-indexerade positionen för den första förekomsten av understräng i sträng, eller 0 om understräng inte hittas.

Exempel på användning:

Python console

>>> from django.db.models import Value as V
>>> from django.db.models.functions import StrIndex
>>> Author.objects.create(name="Margaret Smith")
>>> Author.objects.create(name="Smith, Margaret")
>>> Author.objects.create(name="Margaret Jackson")
>>> Author.objects.filter(name="Margaret Jackson").annotate(
...     smith_index=StrIndex("name", V("Smith"))
... ).get().smith_index
0
>>> authors = Author.objects.annotate(smith_index=StrIndex("name", V("Smith"))).filter(
...     smith_index__gt=0
... )
<QuerySet [<Author: Margaret Smith>, <Author: Smith, Margaret>]>

`Substr`Link to this heading

class Substr(expression, pos, length=None, **extra)Link to this definition

Returnerar en delsträng med längden length från fältet eller uttrycket som börjar vid positionen pos. Positionen är 1-indexerad, så positionen måste vara större än 0. Om length är None returneras resten av strängen.

Exempel på användning:

Python console

>>> # Set the alias to the first 5 characters of the name as lowercase
>>> from django.db.models.functions import Lower, Substr
>>> Author.objects.create(name="Margaret Smith")
>>> Author.objects.update(alias=Lower(Substr("name", 1, 5)))
1
>>> print(Author.objects.get(name="Margaret Smith").alias)
marga

`Trim`Link to this heading

class Trim(expression, **extra)Link to this definition

Returnerar värdet för det angivna textfältet eller uttrycket med inledande och avslutande mellanslag borttagna.

Exempel på användning:

Python console

>>> from django.db.models.functions import Trim
>>> Author.objects.create(name="  John  ", alias="j")
>>> Author.objects.update(name=Trim("name"))
1
>>> print(Author.objects.get(alias="j").name)
John

`Övre`Link to this heading

class Upper(expression, **extra)Link to this definition

Accepterar ett enda textfält eller uttryck och returnerar representationen med versaler.

Den kan också registreras som en transform enligt beskrivningen i Length.

Exempel på användning:

Python console

>>> from django.db.models.functions import Upper
>>> Author.objects.create(name="Margaret Smith")
>>> author = Author.objects.annotate(name_upper=Upper("name")).get()
>>> print(author.name_upper)
MARGARET SMITH

FönsterfunktionerLink to this heading

Det finns ett antal funktioner som kan användas i ett Window-uttryck för att beräkna rangordningen av element eller Ntile för vissa rader.

`CumeDist`Link to this heading

class CumeDist(*expressions, **extra)Link to this definition

Beräknar den kumulativa fördelningen av ett värde inom ett fönster eller en partition. Den kumulativa fördelningen definieras som antalet rader som föregår eller är jämförda med den aktuella raden dividerat med det totala antalet rader i ramen.

`DenseRank`Link to this heading

class DenseRank(*expressions, **extra)Link to this definition

Motsvarar Rank men har inte luckor.

`Första Värde`Link to this heading

class FirstValue(expression, **extra)Link to this definition

Returnerar det värde som utvärderas på den rad som är den första raden i fönsterramen, eller None om inget sådant värde finns.

`Lag`Link to this heading

class Lag(expression, offset=1, default=None, **extra)Link to this definition

Beräknar värdet som förskjuts med offset, och om ingen rad finns där returneras default.

default måste ha samma typ som expression, men detta valideras endast av databasen och inte i Python.

`Sista Värde`Link to this heading

class LastValue(expression, **extra)Link to this definition

Jämförbart med FirstValue, beräknar det det sista värdet i en given ramklausul.

`Ledare`Link to this heading

class Lead(expression, offset=1, default=None, **extra)Link to this definition

Beräknar det ledande värdet i en given frame. Både offset och default utvärderas med avseende på den aktuella raden.

default måste ha samma typ som expression, men detta valideras endast av databasen och inte i Python.

`NthValue`Link to this heading

class NthValue(expression, nth=1, **extra)Link to this definition

Beräknar raden i förhållande till offset nth (måste vara ett positivt värde) inom fönstret. Returnerar None om det inte finns någon rad.

Vissa databaser kan hantera ett icke-existerande nionde värde på ett annat sätt. Oracle returnerar t.ex. en tom sträng istället för None för teckenbaserade uttryck. Django gör inga konverteringar i dessa fall.

`Ntile`Link to this heading

class Ntile(num_buckets=1, **extra)Link to this definition

Beräknar en partition för var och en av raderna i ramklausulen och fördelar siffrorna så jämnt som möjligt mellan 1 och num_buckets. Om raderna inte delas upp jämnt i ett antal buckets kommer en eller flera buckets att representeras oftare.

`PercentRank`Link to this heading

class PercentRank(*expressions, **extra)Link to this definition

Beräknar den relativa rangordningen av raderna i ramsatsen. Denna beräkning är likvärdig med att utvärdera:

Text

(rank - 1) / (total rows - 1)

I följande tabell förklaras beräkningen av den relativa rangordningen för en rad:

Rad #	Värde	Rank	Beräkning	Relativ rang
1	15	1	(1-1)/(7-1)	0.0000
2	20	2	(2-1)/(7-1)	0.1666
3	20	2	(2-1)/(7-1)	0.1666
4	20	2	(2-1)/(7-1)	0.1666
5	30	5	(5-1)/(7-1)	0.6666
6	30	5	(5-1)/(7-1)	0.6666
7	40	7	(7-1)/(7-1)	1.0000

`Rank`Link to this heading

class Rank(*expressions, **extra)Link to this definition

Denna funktion är jämförbar med RowNumber och rangordnar raderna i fönstret. Den beräknade rankningen innehåller luckor. Använd DenseRank för att beräkna rangordning utan luckor.

`RowNumber`Link to this heading

class RowNumber(*expressions, **extra)Link to this definition

Beräknar radnumret enligt ordningsföljden för antingen ramklausulen eller ordningsföljden för hela frågan om det inte finns någon partitionering av window frame.

DatabasfunktionerLink to this heading#

Jämförelse- och omvandlingsfunktionerLink to this heading#

SändningLink to this heading#

KoaleseraLink to this heading#

”SamarbetaLink to this heading#

GreatestLink to this heading#

MinstaLink to this heading#

NullIfLink to this heading#

DatumfunktionerLink to this heading#

ExtractLink to this heading#

DateField utdragLink to this heading#

DateTimeField utdragLink to this heading#

NuLink to this heading#

TruncLink to this heading#

trunkering av DateFieldLink to this heading#

trunkering av DateTimeFieldLink to this heading#

trunkering av TimeFieldLink to this heading#

JSON-funktionerLink to this heading#

JSONArrayLink to this heading#

JSONObjectLink to this heading#

Matematiska funktionerLink to this heading#

AbsLink to this heading#

”ACosLink to this heading#

ASinLink to this heading#

ATanLink to this heading#

ATan2Link to this heading#

TakLink to this heading#

CosLink to this heading#

CotLink to this heading#

DegreesLink to this heading#

ExpLink to this heading#

GolvLink to this heading#

LnLink to this heading#

LogLink to this heading#

ModLink to this heading#

PiLink to this heading#

KraftLink to this heading#

RadianerLink to this heading#

RandomLink to this heading#

RundLink to this heading#

SignLink to this heading#

SinLink to this heading#

SqrtLink to this heading#

TanLink to this heading#

TextfunktionerLink to this heading#

ChrLink to this heading#

ConcatLink to this heading#

VänsterLink to this heading#

LängdLink to this heading#

LägreLink to this heading#

LPadLink to this heading#

LTrimLink to this heading#

MD5Link to this heading#

OrdLink to this heading#

UpprepaLink to this heading#

ReplaceLink to this heading#

ReverseLink to this heading#

HögerLink to this heading#

RPadLink to this heading#

RTrimLink to this heading#

SHA1, SHA224, SHA256, SHA384 och SHA512Link to this heading#

StrIndexLink to this heading#

SubstrLink to this heading#

TrimLink to this heading#

ÖvreLink to this heading#

FönsterfunktionerLink to this heading#

CumeDistLink to this heading#

DenseRankLink to this heading#

Första VärdeLink to this heading#

LagLink to this heading#

Sista VärdeLink to this heading#

LedareLink to this heading#

NthValueLink to this heading#

NtileLink to this heading#

PercentRankLink to this heading#

RankLink to this heading#

RowNumberLink to this heading#

DatabasfunktionerLink to this heading

Jämförelse- och omvandlingsfunktionerLink to this heading

`Sändning`Link to this heading

`Koalesera`Link to this heading

”SamarbetaLink to this heading

`Greatest`Link to this heading

`Minsta`Link to this heading

`NullIf`Link to this heading

DatumfunktionerLink to this heading

`Extract`Link to this heading

`DateField` utdragLink to this heading

`DateTimeField` utdragLink to this heading

`Nu`Link to this heading

`Trunc`Link to this heading

trunkering av `DateField`Link to this heading

trunkering av `DateTimeField`Link to this heading

trunkering av `TimeField`Link to this heading

JSON-funktionerLink to this heading

`JSONArray`Link to this heading

`JSONObject`Link to this heading

Matematiska funktionerLink to this heading

`Abs`Link to this heading

”ACosLink to this heading

`ASin`Link to this heading

`ATan`Link to this heading

`ATan2`Link to this heading

`Tak`Link to this heading

`Cos`Link to this heading

`Cot`Link to this heading

`Degrees`Link to this heading

`Exp`Link to this heading

`Golv`Link to this heading

`Ln`Link to this heading

`Log`Link to this heading

`Mod`Link to this heading

`Pi`Link to this heading

`Kraft`Link to this heading

`Radianer`Link to this heading

`Random`Link to this heading

`Rund`Link to this heading

`Sign`Link to this heading

`Sin`Link to this heading

`Sqrt`Link to this heading

`Tan`Link to this heading

TextfunktionerLink to this heading

`Chr`Link to this heading

`Concat`Link to this heading

`Vänster`Link to this heading

`Längd`Link to this heading

`Lägre`Link to this heading

`LPad`Link to this heading

`LTrim`Link to this heading

`MD5`Link to this heading

`Ord`Link to this heading

`Upprepa`Link to this heading

`Replace`Link to this heading

`Reverse`Link to this heading

`Höger`Link to this heading

`RPad`Link to this heading

`RTrim`Link to this heading

`SHA1`, `SHA224`, `SHA256`, `SHA384` och `SHA512`Link to this heading

`StrIndex`Link to this heading

`Substr`Link to this heading

`Trim`Link to this heading

`Övre`Link to this heading

FönsterfunktionerLink to this heading

`CumeDist`Link to this heading

`DenseRank`Link to this heading

`Första Värde`Link to this heading

`Lag`Link to this heading

`Sista Värde`Link to this heading

`Ledare`Link to this heading

`NthValue`Link to this heading

`Ntile`Link to this heading

`PercentRank`Link to this heading

`Rank`Link to this heading

`RowNumber`Link to this heading