Databasfunktioner¶

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:

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 omvandlingsfunktioner¶

`Sändning`¶

class Cast(expression, output_field)[source]¶

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

Exempel på användning:

>>> 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`¶

class Coalesce(*expressions, **extra)[source]¶

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:

>>> # 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:

>>> 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()))

”Samarbeta¶

class Collate(expression, collation)[source]¶

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:

>>> 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:

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

`Greatest`¶

class Greatest(*expressions, **extra)[source]¶

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:

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)

>>> 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.

Varning

Hur Greatest fungerar när ett eller flera uttryck kan vara null varierar mellan olika databaser:

PostgreSQL: Greatest returnerar det största icke-null-uttrycket, eller null om alla uttryck är null.
SQLite, Oracle och MySQL: Om något uttryck är null kommer Greatest att returnera null.

PostgreSQL-beteendet kan emuleras med hjälp av Coalesce om du känner till ett förnuftigt minimivärde att tillhandahålla som standard.

`Minsta`¶

class Least(*expressions, **extra)[source]¶

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.

Varning

Hur Least fungerar när ett eller flera uttryck kan vara null varierar mellan olika databaser:

PostgreSQL: Least returnerar det minsta icke-null-uttrycket, eller null om alla uttryck är null.
SQLite, Oracle och MySQL: Om något uttryck är null kommer Least att returnera null.

PostgreSQL-beteendet kan emuleras med hjälp av Coalesce om du känner till ett förnuftigt maximalt värde att tillhandahålla som standard.

`NullIf`¶

class NullIf(expression1, expression2)[source]¶

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

Förbehåll för Oracle

På grund av en Oracle-konvention, returnerar denna funktion den tomma strängen istället för None när uttrycken är av typen CharField.

Att skicka Value(None) till expression1 är förbjudet på Oracle eftersom Oracle inte accepterar NULL som första argument.

Datumfunktioner¶

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

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`¶

class Extract(expression, lookup_name=None, tzinfo=None, **extra)[source]¶

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:

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

vecka värden

lookup_type week beräknas enligt ISO-8601, dvs. en vecka börjar på en måndag. Den första veckan i ett år är den som innehåller årets första torsdag, dvs. den första veckan har majoriteten (fyra eller fler) av sina dagar under året. Det returnerade värdet ligger i intervallet 1 till 52 eller 53.

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:

>>> 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` utdrag¶

class ExtractYear(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'year'

class ExtractIsoYear(expression, tzinfo=None, **extra)[source]¶

Returnerar det ISO-8601 veckonumrerade året.

lookup_name = 'iso_year'

class ExtractMonth(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'month'

class ExtractDay(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'day'

class ExtractWeekDay(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'week_day'

class ExtractIsoWeekDay(expression, tzinfo=None, **extra)[source]¶

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)[source]¶

lookup_name = 'week'

class ExtractQuarter(expression, tzinfo=None, **extra)[source]¶

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:

>>> 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` utdrag¶

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

class ExtractHour(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'hour'

class ExtractMinute(expression, tzinfo=None, **extra)[source]¶

lookup_name = 'minute'

class ExtractSecond(expression, tzinfo=None, **extra)[source]¶

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:

>>> 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:

>>> 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:

>>> 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`¶

class Now[source]¶

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

Exempel på användning:

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

PostgreSQL överväganden

På PostgreSQL returnerar SQL CURRENT_TIMESTAMP den tid då den aktuella transaktionen startade. För kompatibilitet mellan databaser använder därför Now() STATEMENT_TIMESTAMP istället. Om du behöver transaktionens tidsstämpel, använd django.contrib.postgres.functions.TransactionNow.

Oracle

I Oracle används SQL LOCALTIMESTAMP för att undvika problem med casting av CURRENT_TIMESTAMP till DateTimeField.

`Trunc`¶

class Trunc(expression, kind, output_field=None, tzinfo=None, **extra)[source]¶

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:

>>> 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`¶

class TruncYear(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'year'

class TruncMonth(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'month'

class TruncWeek(expression, output_field=None, tzinfo=None, **extra)[source]¶

Trunkeras till midnatt på måndagen i veckan.

kind = 'week'

class TruncQuarter(expression, output_field=None, tzinfo=None, **extra)[source]¶

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:

>>> 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`¶

class TruncDate(expression, tzinfo=None, **extra)[source]¶

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)[source]¶

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)[source]¶

kind = 'day'

class TruncHour(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'hour'

class TruncMinute(expression, output_field=None, tzinfo=None, **extra)[source]¶

kind = 'minute'

class TruncSecond(expression, output_field=None, tzinfo=None, **extra)[source]¶

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:

>>> 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`¶

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

kind = 'hour'

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

kind = 'minute'

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

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:

>>> 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-funktioner¶

`JSONArray`¶

New in Django 5.2.

class JSONArray(*expressions)[source]¶

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

Exempel på användning:

>>> 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`¶

class JSONObject(**fields)[source]¶

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

Exempel på användning:

>>> 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 funktioner¶

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

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

`Abs`¶

class Abs(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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)

”ACos¶

class ACos(expression, **extra)[source]¶

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:

>>> 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:

>>> 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`¶

class ASin(expression, **extra)[source]¶

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:

>>> 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:

>>> 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`¶

class ATan(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class ATan2(expression1, expression2, **extra)[source]¶

Returnerar arctangenten av uttryck1 / uttryck2.

Exempel på användning:

>>> 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`¶

class Ceil(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class Cos(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class Cot(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class Degrees(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class Exp(expression, **extra)[source]¶

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:

>>> 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:

>>> 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`¶

class Floor(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class Ln(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class Log(expression1, expression2, **extra)[source]¶

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

Exempel på användning:

>>> 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`¶

class Mod(expression1, expression2, **extra)[source]¶

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

Exempel på användning:

>>> 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`¶

class Pi(**extra)[source]¶

Returnerar värdet av den matematiska konstanten π.

`Kraft`¶

class Power(expression1, expression2, **extra)[source]¶

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:

>>> 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`¶

class Radians(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class Random(**extra)[source]¶

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

`Rund`¶

class Round(expression, precision=0, **extra)[source]¶

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:

>>> 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:

>>> 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`¶

class Sign(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class Sin(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class Sqrt(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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`¶

class Tan(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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:

>>> 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)

Textfunktioner¶

`Chr`¶

class Chr(expression, **extra)[source]¶

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:

>>> 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`¶

class Concat(*expressions, **extra)[source]¶

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:

>>> # 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`¶

class Left(expression, length, **extra)[source]¶

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

Exempel på användning:

>>> 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`¶

class Length(expression, **extra)[source]¶

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:

>>> # 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:

>>> 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`¶

class Lower(expression, **extra)[source]¶

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:

>>> 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`¶

class LPad(expression, length, fill_text=Value(' '), **extra)[source]¶

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:

>>> 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`¶

class LTrim(expression, **extra)[source]¶

Liknar Trim, men tar bara bort inledande mellanslag.

`MD5`¶

class MD5(expression, **extra)[source]¶

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:

>>> 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`¶

class Ord(expression, **extra)[source]¶

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:

>>> 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`¶

class Repeat(expression, number, **extra)[source]¶

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

Exempel på användning:

>>> 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`¶

class Replace(expression, text, replacement=Value(''), **extra)[source]¶

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:

>>> 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`¶

class Reverse(expression, **extra)[source]¶

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:

>>> 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`¶

class Right(expression, length, **extra)[source]¶

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

Exempel på användning:

>>> 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`¶

class RPad(expression, length, fill_text=Value(' '), **extra)[source]¶

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

`RTrim`¶

class RTrim(expression, **extra)[source]¶

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

`SHA1`, `SHA224`, `SHA256`, `SHA384` och `SHA512`¶

class SHA1(expression, **extra)[source]¶

class SHA224(expression, **extra)[source]¶

class SHA256(expression, **extra)[source]¶

class SHA384(expression, **extra)[source]¶

class SHA512(expression, **extra)[source]¶

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:

>>> 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

PostgreSQL

Tillägget pgcrypto måste installeras. Du kan använda migreringsoperationen CryptoExtension för att installera det.

Oracle

Oracle har inte stöd för funktionen SHA224.

`StrIndex`¶

class StrIndex(string, substring, **extra)[source]¶

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:

>>> 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>]>

Varning

I MySQL avgör en databastabells collation om strängjämförelser (som uttryck och substräng i den här funktionen) är skiftlägeskänsliga. Jämförelser är som standard okänsliga för skiftlägesskillnader.

`Substr`¶

class Substr(expression, pos, length=None, **extra)[source]¶

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:

>>> # 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`¶

class Trim(expression, **extra)[source]¶

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

Exempel på användning:

>>> 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`¶

class Upper(expression, **extra)[source]¶

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:

>>> 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önsterfunktioner¶

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`¶

class CumeDist(*expressions, **extra)[source]¶

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`¶

class DenseRank(*expressions, **extra)[source]¶

Motsvarar Rank men har inte luckor.

`Första Värde`¶

class FirstValue(expression, **extra)[source]¶

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`¶

class Lag(expression, offset=1, default=None, **extra)[source]¶

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.

MariaDB och default

MariaDB stödjer inte <https://jira.mariadb.org/browse/MDEV-12981> parametern default.

`Sista Värde`¶

class LastValue(expression, **extra)[source]¶

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

`Ledare`¶

class Lead(expression, offset=1, default=None, **extra)[source]¶

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.

MariaDB och default

MariaDB stödjer inte <https://jira.mariadb.org/browse/MDEV-12981> parametern default.

`NthValue`¶

class NthValue(expression, nth=1, **extra)[source]¶

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`¶

class Ntile(num_buckets=1, **extra)[source]¶

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`¶

class PercentRank(*expressions, **extra)[source]¶

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

(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`¶

class Rank(*expressions, **extra)[source]¶

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`¶

class RowNumber(*expressions, **extra)[source]¶

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.

Databasfunktioner¶

Jämförelse- och omvandlingsfunktioner¶

Sändning¶

Koalesera¶

”Samarbeta¶

Greatest¶

Minsta¶

NullIf¶

Datumfunktioner¶

Extract¶

DateField utdrag¶

DateTimeField utdrag¶

Nu¶

Trunc¶

trunkering av DateField¶

trunkering av DateTimeField¶

trunkering av TimeField¶

JSON-funktioner¶

JSONArray¶

JSONObject¶

Matematiska funktioner¶

Abs¶

”ACos¶

ASin¶

ATan¶

ATan2¶

Tak¶

Cos¶

Cot¶

Degrees¶

Exp¶

Golv¶

Ln¶

Log¶

Mod¶

Pi¶

Kraft¶

Radianer¶

Random¶

Rund¶

Sign¶

Sin¶

Sqrt¶

Tan¶

Textfunktioner¶

Chr¶

Concat¶

Vänster¶

Längd¶

Lägre¶

LPad¶

LTrim¶

MD5¶

Ord¶

Upprepa¶

Replace¶

Reverse¶

Höger¶

RPad¶

RTrim¶

SHA1, SHA224, SHA256, SHA384 och SHA512¶

StrIndex¶

Substr¶

Trim¶

Övre¶

Fönsterfunktioner¶

CumeDist¶

DenseRank¶

Första Värde¶

Lag¶

Sista Värde¶

Ledare¶

NthValue¶

Ntile¶

PercentRank¶

Rank¶

RowNumber¶

Ytterligare information

Stöd Django!

Innehåll

`Sändning`¶

`Koalesera`¶

`Greatest`¶

`Minsta`¶

`NullIf`¶

`Extract`¶

`DateField` utdrag¶

`DateTimeField` utdrag¶

`Nu`¶

`Trunc`¶

trunkering av `DateField`¶

trunkering av `DateTimeField`¶

trunkering av `TimeField`¶

`JSONArray`¶

`JSONObject`¶

`Abs`¶

`ASin`¶

`ATan`¶

`ATan2`¶

`Tak`¶

`Cos`¶

`Cot`¶

`Degrees`¶

`Exp`¶

`Golv`¶

`Ln`¶

`Log`¶

`Mod`¶

`Pi`¶

`Kraft`¶

`Radianer`¶

`Random`¶

`Rund`¶

`Sign`¶

`Sin`¶

`Sqrt`¶

`Tan`¶

`Chr`¶

`Concat`¶

`Vänster`¶

`Längd`¶

`Lägre`¶

`LPad`¶

`LTrim`¶

`MD5`¶

`Ord`¶

`Upprepa`¶

`Replace`¶

`Reverse`¶

`Höger`¶

`RPad`¶

`RTrim`¶

`SHA1`, `SHA224`, `SHA256`, `SHA384` och `SHA512`¶

`StrIndex`¶

`Substr`¶

`Trim`¶

`Övre`¶

`CumeDist`¶

`DenseRank`¶

`Första Värde`¶

`Lag`¶

`Sista Värde`¶

`Ledare`¶

`NthValue`¶

`Ntile`¶

`PercentRank`¶

`Rank`¶

`RowNumber`¶