djangodocs

Django 6.0
Svenska
Documentation contents

PostgreSQL-specifika modellfält

Alla dessa fält är tillgängliga från modulen django.contrib.postgres.fields.

Indexering av dessa fält

Index och Field.db_index skapar båda ett B-tree-index, vilket inte är särskilt användbart vid frågor om komplexa datatyper. Index som GinIndex och GistIndex är bättre lämpade, även om indexvalet beror på de frågor som du använder. Generellt kan GiST vara ett bra val för range fields och HStoreField, och GIN kan vara till hjälp för ArrayField.

ArrayField

class ArrayField(base_field, size=None, **options)

Ett fält för lagring av listor med data. De flesta fälttyper kan användas, och du skickar en annan fältinstans som base_field. Du kan också ange en size. ArrayField kan nästlas för att lagra flerdimensionella matriser.

Om du ger fältet en default, se till att det är en callable som list (för en tom standard) eller en callable som returnerar en lista (t.ex. en funktion). Felaktig användning av default=[] skapar en föränderlig standard som delas mellan alla instanser av ArrayField.

base_field

Detta är ett nödvändigt argument.

Anger den underliggande datatypen och beteendet för arrayen. Det bör vara en instans av en underklass av Field. Det kan t.ex. vara en IntegerField eller en CharField. De flesta fälttyper är tillåtna, med undantag för de som hanterar relationsdata (ForeignKey, OneToOneField och ManyToManyField) och filfält (FileField och ImageField).

Det är möjligt att nesta array-fält - du kan ange en instans av ArrayField som base_field. Till exempel:

Code
from django.contrib.postgres.fields import ArrayField
from django.db import models


class ChessBoard(models.Model):
    board = ArrayField(
        ArrayField(
            models.CharField(max_length=10, blank=True),
            size=8,
        ),
        size=8,
    )

Omvandling av värden mellan databasen och modellen, validering av data och konfiguration samt serialisering delegeras till det underliggande basfältet.

size

Detta är ett valfritt argument.

Om den godkänns kommer matrisen att ha en maximal storlek enligt specifikationen. Detta kommer att skickas till databasen, även om PostgreSQL för närvarande inte verkställer begränsningen.

Fråga om ArrayField

Det finns ett antal anpassade lookups och transformationer för ArrayField. Vi kommer att använda följande exempelmodell:

Code
from django.contrib.postgres.fields import ArrayField
from django.db import models


class Post(models.Model):
    name = models.CharField(max_length=200)
    tags = ArrayField(models.CharField(max_length=200), blank=True)

    def __str__(self):
        return self.name

innehåller

Uppslaget contains är åsidosatt på ArrayField. De returnerade objekten kommer att vara de där de värden som skickas är en delmängd av data. Den använder SQL-operatorn @>. Till exempel:

Python console
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])

>>> Post.objects.filter(tags__contains=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>

>>> Post.objects.filter(tags__contains=["django"])
<QuerySet [<Post: First post>, <Post: Third post>]>

>>> Post.objects.filter(tags__contains=["django", "thoughts"])
<QuerySet [<Post: First post>]>

innehålls_av

Detta är motsatsen till contains - de objekt som returneras är de där data är en delmängd av de värden som skickats. Den använder SQL-operatorn <@. Till exempel:

Python console
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])

>>> Post.objects.filter(tags__contained_by=["thoughts", "django"])
<QuerySet [<Post: First post>, <Post: Second post>]>

>>> Post.objects.filter(tags__contained_by=["thoughts", "django", "tutorial"])
<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>

överlappning

Returnerar objekt där data delar eventuella resultat med de värden som skickats. Använder SQL-operatorn &&. Till exempel:

Python console
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts", "tutorial"])
>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])

>>> Post.objects.filter(tags__overlap=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>

>>> Post.objects.filter(tags__overlap=["thoughts", "tutorial"])
<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>

>>> Post.objects.filter(tags__overlap=Post.objects.values_list("tags"))
<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>

len

Returnerar längden på arrayen. De uppslagningar som är tillgängliga efteråt är de som är tillgängliga för IntegerField. Till exempel:

Python console
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])

>>> Post.objects.filter(tags__len=1)
<QuerySet [<Post: Second post>]>

Index omvandlas

Index transformerar index till matrisen. Alla icke-negativa heltal kan användas. Det blir inga fel om det överskrider size för matrisen. De uppslag som är tillgängliga efter transformationen är de från base_field. Till exempel:

Python console
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])

>>> Post.objects.filter(tags__0="thoughts")
<QuerySet [<Post: First post>, <Post: Second post>]>

>>> Post.objects.filter(tags__1__iexact="Django")
<QuerySet [<Post: First post>]>

>>> Post.objects.filter(tags__276="javascript")
<QuerySet []>

Skivtransformationer

Slice-transformationer tar en slice av matrisen. Två icke-negativa heltal kan användas, åtskilda av ett enda understreck. De uppslagsord som är tillgängliga efter transformationen ändras inte. Till exempel:

Python console
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.create(name="Third post", tags=["django", "python", "thoughts"])

>>> Post.objects.filter(tags__0_1=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>

>>> Post.objects.filter(tags__0_2__contains=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>

HStoreField

class HStoreField(**options)

Ett fält för lagring av nyckel-värde-par. Python-datatypen som används är en dict. Nycklar måste vara strängar och värden kan vara antingen strängar eller nollor (None i Python).

För att använda detta fält måste du:

  1. Lägg till 'django.contrib.postgres' i din INSTALLED_APPS.

  2. Sätta upp hstore-tillägget i PostgreSQL.

Du kommer att se ett fel som kan inte anpassa typen 'dict' om du hoppar över det första steget, eller typen "hstore" finns inte om du hoppar över det andra.

Förfrågan på HStoreField

Förutom möjligheten att ställa frågor efter nyckel finns det ett antal anpassade uppslagningar tillgängliga för HStoreField.

Vi kommer att använda följande exempelmodell:

Code
from django.contrib.postgres.fields import HStoreField
from django.db import models


class Dog(models.Model):
    name = models.CharField(max_length=200)
    data = HStoreField()

    def __str__(self):
        return self.name

Nyckeluppslagningar

Om du vill göra en sökning baserad på en viss nyckel kan du använda den nyckeln som uppslagsnamn:

Python console
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie"})

>>> Dog.objects.filter(data__breed="collie")
<QuerySet [<Dog: Meg>]>

Du kan kedja andra uppslagningar efter nyckeluppslagningar:

Python console
>>> Dog.objects.filter(data__breed__contains="l")
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

eller använda F()-uttryck för att kommentera ett nyckelvärde. Till exempel:

Python console
>>> from django.db.models import F
>>> rufus = Dog.objects.annotate(breed=F("data__breed"))[0]
>>> rufus.breed
'labrador'

Om den nyckel som du vill söka på krockar med namnet på en annan uppslagning måste du använda hstorefield.contains istället.

innehåller

Uppslaget contains är åsidosatt på HStoreField. De returnerade objekten är de där den givna dict av nyckel-värdepar alla finns i fältet. Den använder SQL-operatorn @>. Till exempel:

Python console
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
>>> Dog.objects.create(name="Fred", data={})

>>> Dog.objects.filter(data__contains={"owner": "Bob"})
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

>>> Dog.objects.filter(data__contains={"breed": "collie"})
<QuerySet [<Dog: Meg>]>

innehålls_av

Detta är inversen av contains - de objekt som returneras är de där nyckel-värdeparen på objektet är en delmängd av dem i det värde som skickas. SQL-operatorn <@ används. Till exempel:

Python console
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
>>> Dog.objects.create(name="Fred", data={})

>>> Dog.objects.filter(data__contained_by={"breed": "collie", "owner": "Bob"})
<QuerySet [<Dog: Meg>, <Dog: Fred>]>

>>> Dog.objects.filter(data__contained_by={"breed": "collie"})
<QuerySet [<Dog: Fred>]>

har_nyckel

Returnerar objekt där den angivna nyckeln finns i data. Använder SQL-operatorn ?. Till exempel:

Python console
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})

>>> Dog.objects.filter(data__has_key="owner")
<QuerySet [<Dog: Meg>]>

har_några_nycklar

Returnerar objekt där någon av de angivna nycklarna finns i data. Använder SQL-operatorn ?|. Till exempel:

Python console
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
>>> Dog.objects.create(name="Meg", data={"owner": "Bob"})
>>> Dog.objects.create(name="Fred", data={})

>>> Dog.objects.filter(data__has_any_keys=["owner", "breed"])
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

har_nycklar

Returnerar objekt där alla de angivna nycklarna finns i data. Använder SQL-operatorn ?&. Till exempel:

Python console
>>> Dog.objects.create(name="Rufus", data={})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})

>>> Dog.objects.filter(data__has_keys=["breed", "owner"])
<QuerySet [<Dog: Meg>]>

nycklar

Returnerar objekt där matrisen med nycklar är det angivna värdet. Observera att ordningen inte garanteras vara tillförlitlig, så denna transform är främst användbar för att använda i samband med uppslagningar på ArrayField. Använder SQL-funktionen akeys(). Till exempel:

Python console
>>> Dog.objects.create(name="Rufus", data={"toy": "bone"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})

>>> Dog.objects.filter(data__keys__overlap=["breed", "toy"])
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

värden

Returnerar objekt där matrisen av värden är det givna värdet. Observera att ordningen inte garanteras vara tillförlitlig, så denna transform är främst användbar för att använda i samband med uppslagningar på ArrayField. Använder SQL-funktionen avals(). Till exempel: avals():

Python console
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})

>>> Dog.objects.filter(data__values__contains=["collie"])
<QuerySet [<Dog: Meg>]>

Område Fält

Det finns fem fältfältstyper som motsvarar de inbyggda intervalltyperna i PostgreSQL. Dessa fält används för att lagra ett intervall av värden; till exempel start- och sluttidsstämplarna för en händelse eller åldersintervallet som en aktivitet är lämplig för.

Alla intervallfält översätts till psycopg Range objects i Python, men accepterar också tuples som inmatning om ingen gränsinformation är nödvändig. Standardvärdet är nedre gräns inkluderad, övre gräns utesluten, det vill säga [) (se PostgreSQL-dokumentationen för detaljer om olika gränser). Standardgränserna kan ändras för icke-diskreta intervallfält (DateTimeRangeField och DecimalRangeField) med hjälp av argumentet default_bounds.

IntegerRangeField

class IntegerRangeField(**options)

Lagrar ett intervall av heltal. Baserat på en IntegerField. Representeras av en int4range i databasen och en django.db.backends.postgresql.psycopg_any.NumericRange i Python.

Oavsett de gränser som anges när du sparar data returnerar PostgreSQL alltid ett intervall i en kanonisk form som inkluderar den nedre gränsen och utesluter den övre gränsen, det vill säga [).

BigIntegerRangeField

class BigIntegerRangeField(**options)

Lagrar ett intervall av stora heltal. Baserat på en BigIntegerField. Representeras av en int8range i databasen och en django.db.backends.postgresql.psycopg_any.NumericRange i Python.

Oavsett de gränser som anges när du sparar data returnerar PostgreSQL alltid ett intervall i en kanonisk form som inkluderar den nedre gränsen och utesluter den övre gränsen, det vill säga [).

DecimalRangeField

class DecimalRangeField(default_bounds='[)', **options)

Lagrar ett intervall av värden med flytande kommatecken. Baserat på en DecimalField. Representeras av en numrange i databasen och en django.db.backends.postgresql.psycopg_any.NumericRange i Python.

default_bounds

Valfritt. Värdet på bounds för list- och tupelingångar. Standardvärdet är nedre gränsen inkluderad, övre gränsen utesluten, det vill säga [) (se PostgreSQL-dokumentationen för detaljer om olika gränser). default_bounds används inte för django.db.backends.postgresql.psycopg_any.NumericRange inmatningar.

DatumTimeRangeField

class DateTimeRangeField(default_bounds='[)', **options)

Lagrar ett intervall av tidsstämplar. Baserat på en DateTimeField. Representeras av en tstzrange i databasen och en django.db.backends.postgresql.psycopg_any.DateTimeTZRange i Python.

default_bounds

Valfritt. Värdet på bounds för list- och tupelingångar. Standardvärdet är nedre gränsen inkluderad, övre gränsen utesluten, det vill säga [) (se PostgreSQL-dokumentationen för detaljer om olika gränser). default_bounds används inte för django.db.backends.postgresql.psycopg_any.DateTimeTZRange inmatningar.

Datumintervallfält

class DateRangeField(**options)

Lagrar ett intervall av datum. Baserat på en DateField. Representeras av en daterange i databasen och en django.db.backends.postgresql.psycopg_any.DateRange i Python.

Oavsett de gränser som anges när du sparar data returnerar PostgreSQL alltid ett intervall i en kanonisk form som inkluderar den nedre gränsen och utesluter den övre gränsen, det vill säga [).

Fråga efter intervallfält

Det finns ett antal anpassade uppslagningar och transformationer för intervallfält. De är tillgängliga för alla ovanstående fält, men vi kommer att använda följande exempelmodell:

Code
from django.contrib.postgres.fields import IntegerRangeField
from django.db import models


class Event(models.Model):
    name = models.CharField(max_length=200)
    ages = IntegerRangeField()
    start = models.DateTimeField()

    def __str__(self):
        return self.name

Vi kommer också att använda följande exempelobjekt:

Python console
>>> import datetime
>>> from django.utils import timezone
>>> now = timezone.now()
>>> Event.objects.create(name="Soft play", ages=(0, 10), start=now)
>>> Event.objects.create(
...     name="Pub trip", ages=(21, None), start=now - datetime.timedelta(days=1)
... )

och NumericRange:

Code
>>> from django.db.backends.postgresql.psycopg_any import NumericRange

Inneslutningsfunktioner

Som med andra PostgreSQL-fält finns det tre standardinhållningsoperatörer: contains, contained_by och overlap, med hjälp av SQL-operatörerna @>, <@ och && respektive.

innehåller
Code
>>> Event.objects.filter(ages__contains=NumericRange(4, 5))
<QuerySet [<Event: Soft play>]>
innehålls_av
Code
>>> Event.objects.filter(ages__contained_by=NumericRange(0, 15))
<QuerySet [<Event: Soft play>]>

Uppslagningen contained_by är också tillgänglig för fälttyper som inte är intervall: SmallAutoField, AutoField, BigAutoField, SmallIntegerField, IntegerField, BigIntegerField.db.models.IntegerField`, BigIntegerField, DecimalField, FloatField, DateField, och DateTimeField. Till exempel:

Python console
>>> from django.db.backends.postgresql.psycopg_any import DateTimeTZRange
>>> Event.objects.filter(
...     start__contained_by=DateTimeTZRange(
...         timezone.now() - datetime.timedelta(hours=1),
...         timezone.now() + datetime.timedelta(hours=1),
...     ),
... )
<QuerySet [<Event: Soft play>]>
överlappning
Code
>>> Event.objects.filter(ages__overlap=NumericRange(8, 12))
<QuerySet [<Event: Soft play>]>

Jämförelsefunktioner

Range-fält stöder standarduppslagningar: lt, gt, lte och gte. Dessa är inte särskilt användbara - de jämför de nedre gränserna först och sedan de övre gränserna endast om det behövs. Detta är också den strategi som används för att beställa efter ett intervallfält. Det är bättre att använda de specifika operatörerna för jämförelse av intervall.

fullständigt_lt

De returnerade intervallen är strikt mindre än det passerade intervallet. Med andra ord är alla punkter i det returnerade intervallet mindre än alla punkter i det passerade intervallet.

Code
>>> Event.objects.filter(ages__fully_lt=NumericRange(11, 15))
<QuerySet [<Event: Soft play>]>
fullständigt_gt

De returnerade intervallen är strikt större än det passerade intervallet. Med andra ord är alla punkter i det returnerade intervallet större än alla punkter i det passerade intervallet.

Code
>>> Event.objects.filter(ages__fully_gt=NumericRange(11, 15))
<QuerySet [<Event: Pub trip>]>
not_lt

De returnerade intervallen innehåller inte några punkter som är mindre än det passerade intervallet, dvs. den nedre gränsen för det returnerade intervallet är minst den nedre gränsen för det passerade intervallet.

Code
>>> Event.objects.filter(ages__not_lt=NumericRange(0, 15))
<QuerySet [<Event: Soft play>, <Event: Pub trip>]>
not_gt

De returnerade intervallen innehåller inte några punkter som är större än det passerade intervallet, dvs. den övre gränsen för det returnerade intervallet är högst den övre gränsen för det passerade intervallet.

Code
>>> Event.objects.filter(ages__not_gt=NumericRange(3, 10))
<QuerySet [<Event: Soft play>]>
”intilliggande

De returnerade intervallen delar en bindning med det passerade intervallet.

Code
>>> Event.objects.filter(ages__adjacent_to=NumericRange(10, 21))
<QuerySet [<Event: Soft play>, <Event: Pub trip>]>

Förfrågan med hjälp av gränserna

Range-fält stöder flera extra uppslagningar.

börjar med

Returnerade objekt har den angivna nedre gränsen. Kan kedjas till giltiga uppslagningar för basfältet.

Code
>>> Event.objects.filter(ages__startswith=21)
<QuerySet [<Event: Pub trip>]>
slutar med

Returnerade objekt har den angivna övre gränsen. Kan kedjas till giltiga uppslagningar för basfältet.

Code
>>> Event.objects.filter(ages__endswith=10)
<QuerySet [<Event: Soft play>]>
isempty

Returnerade objekt är tomma intervall. Kan kedjas till giltiga uppslagningar för en BooleanField.

Code
>>> Event.objects.filter(ages__isempty=True)
<QuerySet []>
lägre_inc

Returnerar objekt som har inkluderande eller exklusiva nedre gränser, beroende på det booleska värdet som skickas. Kan kedjas till giltiga uppslagningar för en BooleanField.

Code
>>> Event.objects.filter(ages__lower_inc=True)
<QuerySet [<Event: Soft play>, <Event: Pub trip>]>
lägre_inf

Returnerar objekt som har obegränsad (oändlig) eller begränsad nedre gräns, beroende på det booleska värdet som skickas. Kan kedjas till giltiga uppslagningar för en BooleanField.

Code
>>> Event.objects.filter(ages__lower_inf=True)
<QuerySet []>
övre_inc

Returnerar objekt som har inkluderande eller exklusiva övre gränser, beroende på det booleska värdet som skickas. Kan kedjas till giltiga uppslagningar för en BooleanField.

Code
>>> Event.objects.filter(ages__upper_inc=True)
<QuerySet []>
övre_inf

Returnerar objekt som har obegränsad (oändlig) eller begränsad övre gräns, beroende på det booleska värdet som skickas. Kan kedjas till giltiga uppslagningar för en BooleanField.

Code
>>> Event.objects.filter(ages__upper_inf=True)
<QuerySet [<Event: Pub trip>]>

Definiera dina egna sortimentstyper

PostgreSQL tillåter definitionen av anpassade intervalltyper. Djangos modell- och formulärfältimplementeringar använder basklasser nedan, och psycopg tillhandahåller en register_range() för att tillåta användning av anpassade intervalltyper.

class RangeField(**options)

Basklass för modellområdesfält.

base_field

Den modellfältklass som ska användas.

range_type

Den intervalltyp som ska användas.

form_field

Klassen för formulärfältet som ska användas. Bör vara en underklass av django.contrib.postgres.forms.BaseRangeField.

class django.contrib.postgres.forms.BaseRangeField

Basklass för fält i formulärintervall.

base_field

Det formulärfält som ska användas.

range_type

Den intervalltyp som ska användas.

Operatörer inom området

class RangeOperators

PostgreSQL tillhandahåller en uppsättning SQL-operatörer som kan användas tillsammans med intervalldatatyperna (se PostgreSQL-dokumentationen för fullständig information om intervalloperatörer). Denna klass är tänkt som en bekväm metod för att undvika skrivfel. Operatörsnamnen överlappar namnen på motsvarande uppslagningar.

Python
class RangeOperators:
    EQUAL = "="
    NOT_EQUAL = "<>"
    CONTAINS = "@>"
    CONTAINED_BY = "<@"
    OVERLAPS = "&&"
    FULLY_LT = "<<"
    FULLY_GT = ">>"
    NOT_LT = "&>"
    NOT_GT = "&<"
    ADJACENT_TO = "-|-"

RangeBoundary() uttryck

class RangeBoundary(inclusive_lower=True, inclusive_upper=False)
inclusive_lower

Om True (standard), är den nedre gränsen inkluderande '[', annars är den exklusiv '('.

inclusive_upper

Om False (standard), är den övre gränsen exklusiv ')', annars är den inkluderande ']'.

Ett RangeBoundary()-uttryck representerar intervallgränserna. Det kan användas med anpassade intervallfunktioner som förväntade gränser, till exempel för att definiera ExclusionConstraint. Se PostgreSQL-dokumentationen för fullständiga detaljer.

View as Markdown Edit this page on GitHub Official version