# Django 5.2.8 documentation

# Geografiska databasfunktioner

De funktioner som dokumenteras på den här sidan ger användare tillgång till geografiska databasfunktioner som kan användas i anteckningar, aggregeringar eller filter i Django.

Exempel:

    >>> from django.contrib.gis.db.models.functions import Length
    >>> Track.objects.annotate(length=Length("line")).filter(length__gt=100)

Alla backends stöder inte alla funktioner, så läs dokumentationen för varje funktion för att se om din databasbackend stöder den funktion du vill använda. Om du anropar en geografisk funktion på en backend som inte stöder den, får du ett `NotImplementedError` undantag.

## Mått

### `Area`

class Area(expression, **extra)

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar fältets area som ett `Area`-mått.

MySQL och SpatiaLite utan LWGEOM/RTTOPO stöder inte områdesberäkningar på geografiska SRS:er.

### `Avstånd`

class Distance(expr1, expr2, spheroid=None, **extra)

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar två geografiska fält eller uttryck och returnerar avståndet mellan dem, som ett `Distance`-objekt. På MySQL returneras ett rått floatvärde när koordinaterna är geodetiska.

På backends som stöder avståndsberäkning på geodetiska koordinater väljs automatiskt rätt backend-funktion beroende på geometriernas SRID-värde (t.ex. ST_DistanceSphere på PostGIS).

När avstånd beräknas med geodetiska (vinkel-) koordinater, vilket är fallet med standard SRID:en WGS84 (4326), kan du ange nyckelordsargumentet `spheroid` för att bestämma om beräkningen ska baseras på en enkel sfär (mindre noggrann, mindre resurskrävande) eller på en sfäroid (mer noggrann, mer resurskrävande).

I följande exempel beräknas avståndet från staden Hobart till alla andra `PointField` i frågeuppsättningen `AustraliaCity`:

    >>> from django.contrib.gis.db.models.functions import Distance
    >>> pnt = AustraliaCity.objects.get(name="Hobart").point
    >>> for city in AustraliaCity.objects.annotate(distance=Distance("point", pnt)):
    ...     print(city.name, city.distance)
    ...
    Wollongong 990071.220408 m
    Shellharbour 972804.613941 m
    Thirroul 1002334.36351 m
    ...

Observera

Because the `distance` attribute is a `Distance` object, you can easily express the value in the units of your choice. For example, `city.distance.mi` is the distance value in miles and `city.distance.km` is the distance value in kilometers. See Mätobjekt for usage details and the list of Stödda enheter.

### `GeometryDistance`

class GeometryDistance(expr1, expr2, **extra)

Tillgänglighet: PostGIS

Accepterar två geografiska fält eller uttryck och returnerar avståndet mellan dem. När den används i en `order_by()`-klausul ger den indexassisterade resultatuppsättningar för närmaste granne.

### `Längd`

class Length(expression, spheroid=True, **extra)

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Tar emot ett geografiskt fält eller uttryck med en eller flera strängar och returnerar dess längd som ett `Distance`-mått.

I PostGIS och SpatiaLite, när koordinaterna är geodetiska (vinkel), kan du ange om beräkningen ska baseras på en enkel sfär (mindre exakt, mindre resurskrävande) eller på en sfäroid (mer exakt, mer resurskrävande) med nyckelordsargumentet ”sfäroid”.

MySQL stöder inte längdberäkningar på geografiska SRS:er.

### `Perimeter`

class Perimeter(expression, **extra)

Tillgänglighet: PostGIS, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar geometriområdets omkrets som ett `Distance`-objekt.

## Relationer

### ”Azimut

class Azimuth(point_a, point_b, **extra)

Tillgänglighet: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Returnerar azimut i radianer för det segment som definieras av de givna punktgeometrierna, eller `None` om de två punkterna sammanfaller. Azimuten är vinkelrefererad från norr och är positiv medurs: norr = `0`; öster = `π/2`; söder = `π`; väster = `3π/2`.

### `BoundingCircle`

class BoundingCircle(expression, num_seg=48, **extra)

Tillgänglighet: PostGIS, Oracle, SpatiaLite 5.1+

Accepterar ett enda geografiskt fält eller uttryck och returnerar den minsta cirkelpolygon som helt kan innehålla geometrin.

Parametern `num_seg` används endast på PostGIS.

### `Centroid`

class Centroid(expression, **extra)

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar geometrins `centroid`-värde.

### `Närmaste punkt`

class ClosestPoint(expr1, expr2, **extra)

Tillgänglighet: PostGIS, SpatiaLite

Accepterar två geografiska fält eller uttryck och returnerar den 2-dimensionella punkt på geometri A som ligger närmast geometri B.

### `Kuvert`

class Envelope(expression, **extra)

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar den geometri som representerar geometrins begränsningsbox.

### `LineLocatePoint`

class LineLocatePoint(linestring, point, **extra)

Tillgänglighet: PostGIS, SpatiaLite

Returnerar en flottör mellan 0 och 1 som representerar platsen för den närmaste punkten på `linjestring` till den angivna `punkten`, som en bråkdel av 2D-linjens längd.

### `PointOnSurface`

class PointOnSurface(expression, **extra)

Tillgänglighet: PostGIS, MariaDB, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en geometrisk `Point` som garanterat ligger på fältets yta; annars returneras `None`.

## Åtgärder

### ”Skillnad

class Difference(expr1, expr2, **extra)

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar två geografiska fält eller uttryck och returnerar den geometriska skillnaden, det vill säga den del av geometri A som inte skär geometri B.

### `Intersektion`

class Intersection(expr1, expr2, **extra)

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar två geografiska fält eller uttryck och returnerar den geometriska skärningspunkten mellan dem.

### `SymDifference`

class SymDifference(expr1, expr2, **extra)

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Tar emot två geografiska fält eller uttryck och returnerar den geometriskt symmetriska skillnaden (union utan intersektion) mellan de angivna parametrarna.

### `Union`

class Union(expr1, expr2, **extra)

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar två geografiska fält eller uttryck och returnerar sammanslagningen av de båda geometrierna.

## Redigerare

### `ForcePolygonCW`

class ForcePolygonCW(expression, **extra)

Tillgänglighet: PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en modifierad version av polygonen/multipolygonen där alla yttre ringar är orienterade medurs och alla inre ringar är orienterade moturs. Icke-polygonala geometrier returneras oförändrade.

### `MakeValid`

class MakeValid(expr)

Tillgänglighet: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Accepterar ett geografiskt fält eller uttryck och försöker konvertera värdet till en giltig geometri utan att förlora någon av de ingående hörnen. Geometrier som redan är giltiga returneras utan ändringar. Enkla polygoner kan bli en multipolygon och resultatet kan ha en lägre dimension än indata.

### `Reverse`

class Reverse(expression, **extra)

Tillgänglighet: PostGIS, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en geometri med omvända koordinater.

### `Rotate`

New in Django 6.0.

class Rotate(expression, angle, origin=None, **extra)

Availability: PostGIS

Rotates a geometry by a specified `angle` around the origin. Optionally, the rotation can be performed around a point, defined by the `origin` parameter.

### `Skala`

class Scale(expression, x, y, z=0.0, **extra)

Tillgänglighet: PostGIS, SpatiaLite

Tar emot ett enda geografiskt fält eller uttryck och returnerar en geometri med skalade koordinater genom att multiplicera dem med parametrarna `x`, `y` och eventuellt `z`.

### `SnapToGrid`

class SnapToGrid(expression, *args, **extra)

Tillgänglighet: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a geometry with all points snapped to the given grid. How the geometry is snapped to the grid depends on how many numeric (either float, integer, or long) arguments are given.

Antal argument | Beskrivning
--- | ---
1 | En enda storlek för att fästa både X- och Y-rutnätet till.
2 | X- och Y-storlekar för att fästa rutnätet.
4 | X- och Y-storlekar och motsvarande X- och Y-ursprung.

### `Transform`

class Transform(expression, srid, **extra)

Tillgänglighet: PostGIS, Oracle, SpatiaLite

Tar emot ett geografiskt fält eller uttryck och en SRID-heltalskod och returnerar den transformerade geometrin till det rumsliga referenssystem som anges av parametern `srid`.

Observera

What spatial reference system an integer SRID corresponds to may depend on the spatial database used. In other words, the SRID numbers used for Oracle are not necessarily the same as those used by PostGIS.

### `Translate`

class Translate(expression, x, y, z=0.0, **extra)

Tillgänglighet: PostGIS, SpatiaLite

Tar emot ett enda geografiskt fält eller uttryck och returnerar en geometri med koordinaterna förskjutna med de numeriska parametrarna `x`, `y` och eventuellt `z`.

## Inmatningsformat

### `FrånWKB`

class FromWKB(expression, srid=0, **extra)

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Skapar geometri från Well-known binary (WKB) representation. Det valfria argumentet `srid` gör det möjligt att ange SRID för den resulterande geometrin. `srid` ignoreras i Oracle.

### `FrånWKT`

class FromWKT(expression, srid=0, **extra)

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Skapar geometri från Well-known text (WKT) representation. Det valfria argumentet `srid` gör det möjligt att ange SRID för den resulterande geometrin. `srid` ignoreras i Oracle.

## Utdata format

### `AsGeoJSON`

class AsGeoJSON(expression, bbox=False, crs=False, precision=8, **extra)

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en GeoJSON representation av geometrin. Observera att resultatet inte är en komplett GeoJSON-struktur utan endast nyckelinnehållet `geometry` i en GeoJSON-struktur. Se även GeoJSON Serializer.

Exempel:

    >>> City.objects.annotate(json=AsGeoJSON("point")).get(name="Chicago").json
    {"type":"Point","coordinates":[-87.65018,41.85039]}

Sökord Argument | Beskrivning
--- | ---
`bbox` | Ställ in detta på `True` om du vill att bounding box ska ingå i den returnerade GeoJSON. Ignoreras på Oracle.
`crs` | Sätt detta till `True` om du vill att koordinatreferenssystemet ska ingå i den returnerade GeoJSON. Ignoreras på MySQL och Oracle.
`precision` | Det kan användas för att ange antalet signifikanta siffror för koordinaterna i GeoJSON-representationen - standardvärdet är 8. Ignoreras i Oracle.

### `AsGML`

class AsGML(expression, version=2, precision=8, **extra)

Tillgänglighet: Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en `Geographic Markup Language (GML)`__-representation av geometrin.

Exempel:

    >>> qs = Zipcode.objects.annotate(gml=AsGML("poly"))
    >>> print(qs[0].gml)
    <gml:Polygon srsName="EPSG:4326"><gml:OuterBoundaryIs>-147.78711,70.245363 ...
    -147.78711,70.245363</gml:OuterBoundaryIs></gml:Polygon>

Sökord Argument | Beskrivning
--- | ---
`precision` | Anger antalet signifikanta siffror för koordinaterna i GML-representationen – standardvärdet är 8. Ignoreras i Oracle.
`version` | Anger vilken GML-version som ska användas: 2 (standard) eller 3.

### `AsKML`

class AsKML(expression, precision=8, **extra)

Tillgänglighet: PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en `Keyhole Markup Language (KML)`__-representation av geometrin.

Exempel:

    >>> qs = Zipcode.objects.annotate(kml=AsKML("poly"))
    >>> print(qs[0].kml)
    <Polygon><outerBoundaryIs><LinearRing><coordinates>-103.04135,36.217596,0 ...
    -103.04135,36.217596,0</coordinates></LinearRing></outerBoundaryIs></Polygon>

Sökord Argument | Beskrivning
--- | ---
`precision` | Detta nyckelord kan användas för att ange antalet signifikanta siffror för koordinaterna i KML-representationen - standardvärdet är 8.

### `AsSVG`

class AsSVG(expression, relative=False, precision=8, **extra)

Tillgänglighet: PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en SVG-representation (SVG = Scalable Vector Graphics) av geometrin.

Sökord Argument | Beskrivning
--- | ---
`relativ` | Om inställningen är `True` implementeras sökvägsdata i form av relativa förflyttningar. Standardvärdet är `False`, vilket innebär att absoluta förflyttningar används istället.
`precision` | Detta nyckelord kan användas för att ange antalet signifikanta siffror för koordinaterna i SVG-representationen - standardvärdet är 8.

### `AsWKB`

class AsWKB(expression, **extra)

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en Well-known binary (WKB)-representation av geometrin.

Exempel:

    >>> bytes(City.objects.annotate(wkb=AsWKB("point")).get(name="Chelyabinsk").wkb)
    b'\x01\x01\x00\x00\x00]3\xf9f\x9b\x91K@\x00X\x1d9\xd2\xb9N@'

### `AsWKT`

class AsWKT(expression, **extra)

Tillgänglighet: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar en Well-known text (WKT)-representation av geometrin.

Exempel:

    >>> City.objects.annotate(wkt=AsWKT("point")).get(name="Chelyabinsk").wkt
    'POINT (55.137555 61.451728)'

### `GeoHash`

class GeoHash(expression, precision=None, **extra)

Availability: MariaDB, MySQL, PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Accepterar ett enda geografiskt fält eller uttryck och returnerar en `GeoHash`__-representation av geometrin.

Nyckelordsargumentet `precision` styr antalet tecken i resultatet.

Changed in Django 6.0:

MariaDB 12.0.1+ support was added.

## Diverse

### `IsEmpty`

class IsEmpty(expr)

Tillgänglighet: PostGIS

Accepterar ett geografiskt fält eller uttryck och testar om värdet är en tom geometri. Returnerar `True` om dess värde är tomt och `False` annars.

### `IsValid`

class IsValid(expr)

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Tar emot ett geografiskt fält eller uttryck och testar om värdet är välformat. Returnerar `True` om dess värde är en giltig geometri och `False` annars.

Changed in Django 6.0:

MariaDB 12.0.1+ support was added.

### `GeometryType`

New in Django 6.0.

class GeometryType(expr)

Availability: PostGIS, Oracle 23c+, MariaDB, MySQL, SpatiaLite

Accepts a geographic field or expression and returns its geometry type.

### `MemSize`

class MemSize(expression, **extra)

Tillgänglighet: PostGIS

Accepterar ett enda geografiskt fält eller uttryck och returnerar den minnesstorlek (antal byte) som det geometriska fältet tar.

### `NumGeometries`

class NumGeometries(expression, **extra)

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar antalet geometrier om geometrifältet är en samling (t.ex. ett fält `GEOMETRYCOLLECTION` eller `MULTI*`). Returnerar 1 för enstaka geometrier.

På MySQL returneras `None` för enstaka geometrier.

### `NumPoints`

class NumPoints(expression, **extra)

Tillgänglighet: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepterar ett enda geografiskt fält eller uttryck och returnerar antalet punkter i en geometri.

På MySQL returneras `None` för alla geometrier som inte är `LINESTRING`.