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¶
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¶
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¶
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¶
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:
Greatestreturnerar det största icke-null-uttrycket, ellernullom alla uttryck Àrnull.SQLite, Oracle och MySQL: Om nÄgot uttryck Àr
nullkommerGreatestatt returneranull.
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¶
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:
Leastreturnerar det minsta icke-null-uttrycket, ellernullom alla uttryck Àrnull.SQLite, Oracle och MySQL: Om nÄgot uttryck Àr
nullkommerLeastatt returneranull.
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¶
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¶
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 ExtractIsoYear(expression, tzinfo=None, **extra)[source]¶
Returnerar det ISO-8601 veckonumrerade Äret.
- lookup_name = 'iso_year'
- 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'
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 .
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¶
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¶
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 TruncWeek(expression, output_field=None, tzinfo=None, **extra)[source]¶
Trunkeras till midnatt pÄ mÄndagen i veckan.
- kind = 'week'
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.
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
Returnerar vĂ€rdet av den matematiska konstanten Ï.
Kraft¶
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¶
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¶
Returnerar ett slumpmÀssigt vÀrde i intervallet 0,0 †x < 1,0.
Rund¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
Liknar Trim, men tar bara bort inledande mellanslag.
MD5¶
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¶
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¶
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¶
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¶
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¶
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¶
Liknar LPad, men Àr pÄ höger sida.
RTrim¶
Liknar Trim, men tar bara bort efterföljande mellanslag.
SHA1, SHA224, SHA256, SHA384 och SHA512¶
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¶
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¶
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¶
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¶
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¶
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¶
Motsvarar Rank men har inte luckor.
Första VÀrde¶
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¶
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¶
JÀmförbart med FirstValue, berÀknar det det sista vÀrdet i en given ramklausul.
Ledare¶
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¶
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¶
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¶
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¶
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¶
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.