---
title: "Databasfunktioner"
version: 5.2
locale: sv
source: https://docs.djangoproject.com/sv/5.2/ref/models/database-functions/
canonical: https://djangodocs.dev/sv/5.2/ref/models/database-functions/
---
# 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](/sv/5.2/ref/models/expressions/), så de kan användas och kombineras med andra uttryck som [aggregate functions](/sv/5.2/ref/models/querysets/#aggregation-functions).

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

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

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

## Jämförelse- och omvandlingsfunktioner

### `Sändning`

#### `class Cast(expression, output_field)`

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

Exempel på användning:

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

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

> **Warning**
>
> 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:
>
> ```pycon
> >>> from django.db.models import DateTimeField
> >>> from django.db.models.functions import Cast, Coalesce
> >>> from django.utils import timezone
> >>> now = timezone.now()
> >>> Coalesce("updated", Cast(now, DateTimeField()))
> ```

### ”Samarbeta

#### `class Collate(expression, collation)`

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:

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

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

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

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

> **Warning**
>
> Hur `Greatest` fungerar när ett eller flera uttryck kan vara `null` varierar mellan olika databaser:
>
> - PostgreSQL: `Greatest` returnerar det största icke-null-uttrycket, eller `null` om alla uttryck är `null`.
> - SQLite, Oracle och MySQL: Om något uttryck är `null` kommer `Greatest` att returnera `null`.
>
> PostgreSQL-beteendet kan emuleras med hjälp av `Coalesce` om du känner till ett förnuftigt minimivärde att tillhandahålla som standard.

### `Minsta`

#### `class Least(*expressions, **extra)`

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.

> **Warning**
>
> Hur `Least` fungerar när ett eller flera uttryck kan vara `null` varierar mellan olika databaser:
>
> - PostgreSQL: `Least` returnerar det minsta icke-null-uttrycket, eller `null` om alla uttryck är `null`.
> - SQLite, Oracle och MySQL: Om något uttryck är `null` kommer `Least` att returnera `null`.
>
> PostgreSQL-beteendet kan emuleras med hjälp av `Coalesce` om du känner till ett förnuftigt maximalt värde att tillhandahålla som standard.

### `NullIf`

#### `class NullIf(expression1, expression2)`

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](/sv/5.2/ref/databases/#oracle-null-empty-strings), returnerar denna funktion den tomma strängen istället för `None` när uttrycken är av typen [`CharField`](/sv/5.2/ref/models/fields/#django.db.models.CharField).
>
> Att skicka `Value(None)` till `expression1` är förbjudet på Oracle eftersom Oracle inte accepterar `NULL` som första argument.

## Datumfunktioner

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

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

### `Extract`

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

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`](https://docs.python.org/3/library/zoneinfo.html#module-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:
>
> ```pycon
> >>> 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](https://en.wikipedia.org/wiki/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:

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

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

#### `DateTimeField` utdrag

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

#### `class ExtractHour(expression, tzinfo=None, **extra)`

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

```pycon
>>> 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`](/sv/5.2/ref/settings/#std-setting-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:

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

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

```pycon
>>> 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`](/sv/5.2/ref/contrib/postgres/functions/#django.contrib.postgres.functions.TransactionNow).

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

### `Trunc`

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

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`](https://docs.python.org/3/library/zoneinfo.html#module-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:

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

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

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

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

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

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

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

## JSON-funktioner

### `JSONArray`

> **New in Django 5.2**

#### `class JSONArray(*expressions)`

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

Exempel på användning:

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

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

## Matematiska funktioner

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

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

### `Abs`

#### `class Abs(expression, **extra)`

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

Exempel på användning:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```pycon
>>> 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()`](https://docs.python.org/3/library/functions.html#chr).

Precis som [`Length`](#django.db.models.functions.Length) kan den registreras som en transform på `IntegerField`. Standarduppslagsnamnet är `chr`.

Exempel på användning:

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

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

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

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

```pycon
>>> 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`](#django.db.models.functions.Length).

Exempel på användning:

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

```pycon
>>> 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`](#django.db.models.functions.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`](#django.db.models.functions.Length).

Exempel på användning:

```pycon
>>> 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()`](https://docs.python.org/3/library/functions.html#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`](#django.db.models.functions.Length). Standardnamnet på uppslagsordet är `ord`.

Exempel på användning:

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

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

```pycon
>>> 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`](#django.db.models.functions.Length). Standarduppslagsnamnet är `reverse`.

Exempel på användning:

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

### `Höger`

#### `class Right(expression, length, **extra)`

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

Exempel på användning:

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

### `RPad`

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

Liknar [`LPad`](#django.db.models.functions.LPad), men är på höger sida.

### `RTrim`

#### `class RTrim(expression, **extra)`

Liknar [`Trim`](#django.db.models.functions.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`](#django.db.models.functions.Length).

Exempel på användning:

```pycon
>>> 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](https://www.postgresql.org/docs/current/pgcrypto.html) måste installeras. Du kan använda migreringsoperationen [`CryptoExtension`](/sv/5.2/ref/contrib/postgres/operations/#django.contrib.postgres.operations.CryptoExtension) för att installera det.

> **Oracle**
>
> Oracle har inte stöd för funktionen `SHA224`.

### `StrIndex`

#### `class StrIndex(string, substring, **extra)`

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:

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

> **Warning**
>
> I MySQL avgör en databastabells [collation](/sv/5.2/ref/databases/#mysql-collation) om strängjämförelser (som `uttryck` och `substräng` i den här funktionen) är skiftlägeskänsliga. Jämförelser är som standard okänsliga för skiftlägesskillnader.

### `Substr`

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

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:

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

```pycon
>>> 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`](#django.db.models.functions.Length).

Exempel på användning:

```pycon
>>> 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`](/sv/5.2/ref/models/expressions/#django.db.models.expressions.Window)-uttryck för att beräkna rangordningen av element eller [`Ntile`](#django.db.models.functions.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`](#django.db.models.functions.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.

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

### `Sista Värde`

#### `class LastValue(expression, **extra)`

Jämförbart med [`FirstValue`](#django.db.models.functions.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](/sv/5.2/ref/models/expressions/#window-frames). Både `offset` och `default` utvärderas med avseende på den aktuella raden.

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

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

### `NthValue`

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

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`](#django.db.models.functions.RowNumber) och rangordnar raderna i fönstret. Den beräknade rankningen innehåller luckor. Använd [`DenseRank`](#django.db.models.functions.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](/sv/5.2/ref/models/expressions/#window-frames).