djangodocs

Django 6.1
Svenska
Documentation contents

Databasfunktioner

The classes documented below provide a way for users to use functions provided by the underlying database as annotations, aggregations, or filters in Django. Functions are also expressions, so they can be used and combined with other expressions like aggregate functions. See the Func documentation for security considerations.

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

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

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

Jämförelse- och omvandlingsfunktioner

Sändning

class Cast(expression, output_field)

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

Exempel på användning:

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

Koalesera

class Coalesce(*expressions, **extra)

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

Exempel på användning:

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

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

”Samarbeta

class Collate(expression, collation)

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

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

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

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

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

Greatest

class Greatest(*expressions, **extra)

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

Exempel på användning:

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


class Comment(models.Model):
    body = models.TextField()
    modified = models.DateTimeField(auto_now=True)
    blog = models.ForeignKey(Blog, on_delete=models.CASCADE)
Python console
>>> from django.db.models.functions import Greatest
>>> blog = Blog.objects.create(body="Greatest is the best.")
>>> comment = Comment.objects.create(body="No, Least is better.", blog=blog)
>>> comments = Comment.objects.annotate(last_updated=Greatest("modified", "blog__modified"))
>>> annotated_comment = comments.get()

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

Minsta

class Least(*expressions, **extra)

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

NullIf

class NullIf(expression1, expression2)

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

Datumfunktioner

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

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

Extract

class Extract(expression, lookup_name=None, tzinfo=None, **extra)

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

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

Exempel på användning:

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

DateField utdrag

class ExtractYear(expression, tzinfo=None, **extra)
lookup_name = 'year'
class ExtractIsoYear(expression, tzinfo=None, **extra)

Returnerar det ISO-8601 veckonumrerade året.

lookup_name = 'iso_year'
class ExtractMonth(expression, tzinfo=None, **extra)
lookup_name = 'month'
class ExtractDay(expression, tzinfo=None, **extra)
lookup_name = 'day'
class ExtractWeekDay(expression, tzinfo=None, **extra)
lookup_name = 'week_day'
class ExtractIsoWeekDay(expression, tzinfo=None, **extra)

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)
lookup_name = 'week'
class ExtractQuarter(expression, tzinfo=None, **extra)
lookup_name = 'quarter'

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

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

Python console
>>> from datetime import UTC, datetime
>>> from django.db.models.functions import (
...     ExtractDay,
...     ExtractMonth,
...     ExtractQuarter,
...     ExtractWeek,
...     ExtractIsoWeekDay,
...     ExtractWeekDay,
...     ExtractIsoYear,
...     ExtractYear,
... )
>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=UTC)
>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=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)
lookup_name = 'hour'
class ExtractMinute(expression, tzinfo=None, **extra)
lookup_name = 'minute'
class ExtractSecond(expression, tzinfo=None, **extra)
lookup_name = 'second'

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

exempel på DateTimeField:

Python console
>>> from datetime import UTC, datetime
>>> 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=UTC)
>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=UTC)
>>> Experiment.objects.create(
...     start_datetime=start_2015,
...     start_date=start_2015.date(),
...     end_datetime=end_2015,
...     end_date=end_2015.date(),
... )
>>> Experiment.objects.annotate(
...     year=ExtractYear("start_datetime"),
...     isoyear=ExtractIsoYear("start_datetime"),
...     quarter=ExtractQuarter("start_datetime"),
...     month=ExtractMonth("start_datetime"),
...     week=ExtractWeek("start_datetime"),
...     day=ExtractDay("start_datetime"),
...     weekday=ExtractWeekDay("start_datetime"),
...     isoweekday=ExtractIsoWeekDay("start_datetime"),
...     hour=ExtractHour("start_datetime"),
...     minute=ExtractMinute("start_datetime"),
...     second=ExtractSecond("start_datetime"),
... ).values(
...     "year",
...     "isoyear",
...     "month",
...     "week",
...     "day",
...     "weekday",
...     "isoweekday",
...     "hour",
...     "minute",
...     "second",
... ).get(
...     end_datetime__year=ExtractYear("start_datetime")
... )
{'year': 2015, 'isoyear': 2015, 'quarter': 2, 'month': 6, 'week': 25,
 'day': 15, 'weekday': 2, 'isoweekday': 1, 'hour': 23, 'minute': 30,
 'second': 1}

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

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

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

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

Nu

class Now

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

Exempel på användning:

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

Trunc

class Trunc(expression, kind, output_field=None, tzinfo=None, **extra)

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

  • ”quarter”: 2015-04-01 00:00:00+11:00

  • ”månad”: 2015-06-01 00:00:00+10:00

  • ”week”: 2015-06-15 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

The year and quarter have an offset of +11:00 because each result falls before the daylight saving time transition.

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

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

Exempel på användning:

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

trunkering av DateField

class TruncYear(expression, output_field=None, tzinfo=None, **extra)
kind = 'year'
class TruncMonth(expression, output_field=None, tzinfo=None, **extra)
kind = 'month'
class TruncWeek(expression, output_field=None, tzinfo=None, **extra)

Trunkeras till midnatt på måndagen i veckan.

kind = 'week'
class TruncQuarter(expression, output_field=None, tzinfo=None, **extra)
kind = 'quarter'

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

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

Python console
>>> from datetime import UTC, datetime
>>> from django.db.models import Count
>>> from django.db.models.functions import TruncMonth, TruncYear
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=UTC)
>>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=UTC)
>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=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)
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)
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)
kind = 'day'
class TruncHour(expression, output_field=None, tzinfo=None, **extra)
kind = 'hour'
class TruncMinute(expression, output_field=None, tzinfo=None, **extra)
kind = 'minute'
class TruncSecond(expression, output_field=None, tzinfo=None, **extra)
kind = 'second'

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

Exempel på användning:

Python console
>>> from datetime import UTC, date, datetime
>>> 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=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=UTC),
 'second': datetime.datetime(2014, 6, 15, 14, 30, 50, tzinfo=UTC)
}

trunkering av TimeField

class TruncHour(expression, output_field=None, tzinfo=None, **extra)
kind = 'hour'
class TruncMinute(expression, output_field=None, tzinfo=None, **extra)
kind = 'minute'
class TruncSecond(expression, output_field=None, tzinfo=None, **extra)
kind = 'second'

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

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

Python console
>>> from datetime import UTC, datetime
>>> from django.db.models import Count, TimeField
>>> from django.db.models.functions import TruncHour
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=UTC)
>>> start2 = datetime(2014, 6, 15, 14, 40, 2, 123, tzinfo=UTC)
>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=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

class JSONArray(*expressions)

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

Exempel på användning:

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

JSONObject

class JSONObject(**fields)

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

Exempel på användning:

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

Matematiska funktioner

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

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

Abs

class Abs(expression, **extra)

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

Exempel på användning:

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

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

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

”ACos

class ACos(expression, **extra)

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

Exempel på användning:

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

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

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

ASin

class ASin(expression, **extra)

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

Exempel på användning:

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

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

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

ATan

class ATan(expression, **extra)

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

Exempel på användning:

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

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

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

ATan2

class ATan2(expression1, expression2, **extra)

Returnerar arctangenten av uttryck1 / uttryck2.

Exempel på användning:

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

Tak

class Ceil(expression, **extra)

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

Exempel på användning:

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

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

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

Cos

class Cos(expression, **extra)

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

Exempel på användning:

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

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

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

Cot

class Cot(expression, **extra)

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

Exempel på användning:

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

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

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

Degrees

class Degrees(expression, **extra)

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

Exempel på användning:

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

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

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

Exp

class Exp(expression, **extra)

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

Exempel på användning:

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

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

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

Golv

class Floor(expression, **extra)

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

Exempel på användning:

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

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

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

Ln

class Ln(expression, **extra)

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

Exempel på användning:

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

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

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

Log

class Log(expression1, expression2, **extra)

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

Exempel på användning:

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

Mod

class Mod(expression1, expression2, **extra)

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

Exempel på användning:

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

Pi

class Pi(**extra)

Returnerar värdet av den matematiska konstanten π.

Kraft

class Power(expression1, expression2, **extra)

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

Exempel på användning:

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

Radianer

class Radians(expression, **extra)

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

Exempel på användning:

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

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

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

Random

class Random(**extra)

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

Rund

class Round(expression, precision=0, **extra)

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

Exempel på användning:

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

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

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

Sign

class Sign(expression, **extra)

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

Exempel på användning:

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

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

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

Sin

class Sin(expression, **extra)

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

Exempel på användning:

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

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

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

Sqrt

class Sqrt(expression, **extra)

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

Exempel på användning:

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

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

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

Tan

class Tan(expression, **extra)

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

Exempel på användning:

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

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

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

Textfunktioner

Chr

class Chr(expression, **extra)

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

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

Exempel på användning:

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

Concat

class Concat(*expressions, **extra)

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

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

Exempel på användning:

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

Vänster

class Left(expression, length, **extra)

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

Exempel på användning:

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

Längd

class Length(expression, **extra)

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

Exempel på användning:

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

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

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

Lägre

class Lower(expression, **extra)

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

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

Exempel på användning:

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

LPad

class LPad(expression, length, fill_text=Value(' '), **extra)

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

Exempel på användning:

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

LTrim

class LTrim(expression, **extra)

Liknar Trim, men tar bara bort inledande mellanslag.

MD5

class MD5(expression, **extra)

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

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

Exempel på användning:

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

Ord

class Ord(expression, **extra)

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

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

Exempel på användning:

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

Upprepa

class Repeat(expression, number, **extra)

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

Exempel på användning:

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

Replace

class Replace(expression, text, replacement=Value(''), **extra)

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

Exempel på användning:

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

Reverse

class Reverse(expression, **extra)

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

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

Exempel på användning:

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

RPad

class RPad(expression, length, fill_text=Value(' '), **extra)

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

RTrim

class RTrim(expression, **extra)

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

SHA1, SHA224, SHA256, SHA384 och SHA512

class SHA1(expression, **extra)
class SHA224(expression, **extra)
class SHA256(expression, **extra)
class SHA384(expression, **extra)
class SHA512(expression, **extra)

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

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

Exempel på användning:

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

StrIndex

class StrIndex(expression, substring, **extra)

Returns a positive integer corresponding to the 1-indexed position of the first occurrence of substring inside expression, or 0 if substring is not found.

Exempel på användning:

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

Substr

class Substr(expression, pos, length=None, **extra)

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

Exempel på användning:

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

Trim

class Trim(expression, **extra)

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

Exempel på användning:

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

Övre

class Upper(expression, **extra)

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

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

Exempel på användning:

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

UUID functions

UUID4

class UUID4

Generates a version 4 UUID, which is random and is generated using a cryptographically secure method.

UUID7

class UUID7(shift=None)

Generates a version 7 UUID, which starts with a time-based component.

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)

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)

Motsvarar Rank men har inte luckor.

Första Värde

class FirstValue(expression, **extra)

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)

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

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

Sista Värde

class LastValue(expression, **extra)

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)

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

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

NthValue

class NthValue(expression, nth=1, **extra)

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)

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)

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

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

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

Rad #

Värde

Rank

Beräkning

Relativ rang

1

15

1

(1-1)/(7-1)

0.0000

2

20

2

(2-1)/(7-1)

0.1666

3

20

2

(2-1)/(7-1)

0.1666

4

20

2

(2-1)/(7-1)

0.1666

5

30

5

(5-1)/(7-1)

0.6666

6

30

5

(5-1)/(7-1)

0.6666

7

40

7

(7-1)/(7-1)

1.0000

Rank

class Rank(*expressions, **extra)

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)

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.

View as Markdown Edit this page on GitHub Official version