地理数据库函数¶

本页所描述的函数允许用户访问地理数据库函数，以便在 Django 中使用注释、聚合或过滤器。

Example:

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

并非所有的后端都支持所有的函数，所以请参考每个函数的文档，看看你的数据库后端是否支持你要使用的函数。如果你在一个不支持地理函数的后台调用该函数，你会得到一个 NotImplementedError 异常。

函数的摘要：

测量	关系映射	操作	编辑器	Input format	输出格式	杂项
`Area`	`Azimuth`	`Difference`	`ForcePolygonCW`		`AsGeoJSON`	`IsEmpty`
`Distance`	`BoundingCircle`	`Intersection`	`MakeValid`		`AsGML`	`IsValid`
`GeometryDistance`	`Centroid`	`SymDifference`	`Reverse`		`AsKML`	`MemSize`
`Length`	`ClosestPoint`	`Union`	`Scale`		`AsSVG`	`NumGeometries`
`Perimeter`	`Envelope` `LineLocatePoint` `PointOnSurface`		`SnapToGrid` `Transform` `Translate`	`FromWKB` `FromWKT`	`AsWKB` `AsWKT` `GeoHash`	`NumPoints`

`Area`¶

class Area(expression, **extra)¶

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns the area of the field as an Area measure.

MySQL and SpatiaLite without LWGEOM/RTTOPO don't support area calculations on geographic SRSes.

`AsGeoJSON`¶

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

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a GeoJSON representation of the geometry. Note that the result is not a complete GeoJSON structure but only the geometry key content of a GeoJSON structure. See also GeoJSON Serializer.

Example:

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

关键字参数	描述
`bbox`	Set this to `True` if you want the bounding box to be included in the returned GeoJSON. Ignored on Oracle.
`crs`	Set this to `True` if you want the coordinate reference system to be included in the returned GeoJSON. Ignored on MySQL and Oracle.
`precision`	It may be used to specify the number of significant digits for the coordinates in the GeoJSON representation -- the default value is 8. Ignored on Oracle.

`AsGML`¶

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

Availability: Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Geographic Markup Language (GML) representation of the geometry.

Example:

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

关键字参数	描述
`precision`	Specifies the number of significant digits for the coordinates in the GML representation -- the default value is 8. Ignored on Oracle.
`version`	Specifies the GML version to use: 2 (default) or 3.

`AsKML`¶

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

Availability: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Keyhole Markup Language (KML) representation of the geometry.

Example:

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

关键字参数	描述
`precision`	This keyword may be used to specify the number of significant digits for the coordinates in the KML representation -- the default value is 8.

`AsSVG`¶

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

Availability: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Scalable Vector Graphics (SVG) representation of the geometry.

关键字参数	描述
`relative`	If set to `True`, the path data will be implemented in terms of relative moves. Defaults to `False`, meaning that absolute moves are used instead.
`precision`	This keyword may be used to specify the number of significant digits for the coordinates in the SVG representation -- the default value is 8.

`AsWKB`¶

class AsWKB(expression, **extra)¶

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Well-known binary (WKB) representation of the geometry.

Example:

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

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a Well-known text (WKT) representation of the geometry.

Example:

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

`Azimuth`¶

class Azimuth(point_a, point_b, **extra)¶

Availability: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Returns the azimuth in radians of the segment defined by the given point geometries, or None if the two points are coincident. The azimuth is angle referenced from north and is positive clockwise: north = 0; east = π/2; south = π; west = 3π/2.

`BoundingCircle`¶

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

Availability: PostGIS, Oracle

Accepts a single geographic field or expression and returns the smallest circle polygon that can fully contain the geometry.

The num_seg parameter is used only on PostGIS.

`Centroid`¶

class Centroid(expression, **extra)¶

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns the centroid value of the geometry.

`ClosestPoint`¶

New in Django 5.0.

class ClosestPoint(expr1, expr2, **extra)¶

Availability: PostGIS, SpatiaLite

Accepts two geographic fields or expressions and returns the 2-dimensional point on geometry A that is closest to geometry B.

`Difference`¶

class Difference(expr1, expr2, **extra)¶

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the geometric difference, that is the part of geometry A that does not intersect with geometry B.

`Distance`¶

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

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the distance between them, as a Distance object. On MySQL, a raw float value is returned when the coordinates are geodetic.

On backends that support distance calculation on geodetic coordinates, the proper backend function is automatically chosen depending on the SRID value of the geometries (e.g. ST_DistanceSphere on PostGIS).

When distances are calculated with geodetic (angular) coordinates, as is the case with the default WGS84 (4326) SRID, you can set the spheroid keyword argument to decide if the calculation should be based on a simple sphere (less accurate, less resource-intensive) or on a spheroid (more accurate, more resource-intensive).

In the following example, the distance from the city of Hobart to every other PointField in the AustraliaCity queryset is calculated:

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

备注

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 Measurement Objects for usage details and the list of Supported units.

`Envelope`¶

class Envelope(expression, **extra)¶

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns the geometry representing the bounding box of the geometry.

`ForcePolygonCW`¶

class ForcePolygonCW(expression, **extra)¶

Availability: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a modified version of the polygon/multipolygon in which all exterior rings are oriented clockwise and all interior rings are oriented counterclockwise. Non-polygonal geometries are returned unchanged.

`FromWKB`¶

New in Django 4.2.

class FromWKB(expression, **extra)¶

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Creates geometry from Well-known binary (WKB) representation.

`FromWKT`¶

New in Django 4.2.

class FromWKT(expression, **extra)¶

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Creates geometry from Well-known text (WKT) representation.

`GeoHash`¶

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

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

Accepts a single geographic field or expression and returns a GeoHash representation of the geometry.

The precision keyword argument controls the number of characters in the result.

`GeometryDistance`¶

class GeometryDistance(expr1, expr2, **extra)¶

Availability: PostGIS

Accepts two geographic fields or expressions and returns the distance between them. When used in an order_by() clause, it provides index-assisted nearest-neighbor result sets.

`Intersection`¶

class Intersection(expr1, expr2, **extra)¶

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the geometric intersection between them.

`IsEmpty`¶

New in Django 4.2.

class IsEmpty(expr)¶

Availability: PostGIS

Accepts a geographic field or expression and tests if the value is an empty geometry. Returns True if its value is empty and False otherwise.

`IsValid`¶

class IsValid(expr)¶

Availability: MySQL, PostGIS, Oracle, SpatiaLite

Accepts a geographic field or expression and tests if the value is well formed. Returns True if its value is a valid geometry and False otherwise.

`Length`¶

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

Availability: MariaDB, MySQL, Oracle, PostGIS, SpatiaLite

Accepts a single geographic linestring or multilinestring field or expression and returns its length as a Distance measure.

On PostGIS and SpatiaLite, when the coordinates are geodetic (angular), you can specify if the calculation should be based on a simple sphere (less accurate, less resource-intensive) or on a spheroid (more accurate, more resource-intensive) with the spheroid keyword argument.

MySQL doesn't support length calculations on geographic SRSes.

`LineLocatePoint`¶

class LineLocatePoint(linestring, point, **extra)¶

Availability: PostGIS, SpatiaLite

Returns a float between 0 and 1 representing the location of the closest point on linestring to the given point, as a fraction of the 2D line length.

`MakeValid`¶

class MakeValid(expr)¶

Availability: PostGIS, SpatiaLite (LWGEOM/RTTOPO)

Accepts a geographic field or expression and attempts to convert the value into a valid geometry without losing any of the input vertices. Geometries that are already valid are returned without changes. Simple polygons might become a multipolygon and the result might be of lower dimension than the input.

`MemSize`¶

class MemSize(expression, **extra)¶

Availability: PostGIS

Accepts a single geographic field or expression and returns the memory size (number of bytes) that the geometry field takes.

`NumGeometries`¶

class NumGeometries(expression, **extra)¶

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns the number of geometries if the geometry field is a collection (e.g., a GEOMETRYCOLLECTION or MULTI* field). Returns 1 for single geometries.

On MySQL, returns None for single geometries.

`NumPoints`¶

class NumPoints(expression, **extra)¶

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns the number of points in a geometry.

On MySQL, returns None for any non-LINESTRING geometry.

`Perimeter`¶

class Perimeter(expression, **extra)¶

Availability: PostGIS, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns the perimeter of the geometry field as a Distance object.

`PointOnSurface`¶

class PointOnSurface(expression, **extra)¶

Availability: PostGIS, MariaDB, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns a Point geometry guaranteed to lie on the surface of the field; otherwise returns None.

`Reverse`¶

class Reverse(expression, **extra)¶

Availability: PostGIS, Oracle, SpatiaLite

Accepts a single geographic field or expression and returns a geometry with reversed coordinates.

`Scale`¶

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

Availability: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a geometry with scaled coordinates by multiplying them with the x, y, and optionally z parameters.

`SnapToGrid`¶

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

Availability: 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.

Number of Arguments	描述
1	A single size to snap both the X and Y grids to.
2	X and Y sizes to snap the grid to.
4	X, Y sizes and the corresponding X, Y origins.

`SymDifference`¶

class SymDifference(expr1, expr2, **extra)¶

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the geometric symmetric difference (union without the intersection) between the given parameters.

`Transform`¶

class Transform(expression, srid, **extra)¶

Availability: PostGIS, Oracle, SpatiaLite

Accepts a geographic field or expression and a SRID integer code, and returns the transformed geometry to the spatial reference system specified by the srid parameter.

备注

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

Availability: PostGIS, SpatiaLite

Accepts a single geographic field or expression and returns a geometry with its coordinates offset by the x, y, and optionally z numeric parameters.

`Union`¶

class Union(expr1, expr2, **extra)¶

Availability: MariaDB, MySQL, PostGIS, Oracle, SpatiaLite

Accepts two geographic fields or expressions and returns the union of both geometries.

Django 5.0.1.dev20231205051144 文档

地理数据库函数¶

Area¶

AsGeoJSON¶

AsGML¶

AsKML¶

AsSVG¶

AsWKB¶

AsWKT¶

Azimuth¶

BoundingCircle¶

Centroid¶

ClosestPoint¶

Difference¶

Distance¶

Envelope¶

ForcePolygonCW¶

FromWKB¶

FromWKT¶

GeoHash¶

GeometryDistance¶

Intersection¶

IsEmpty¶

IsValid¶

Length¶

LineLocatePoint¶

MakeValid¶

MemSize¶

NumGeometries¶

NumPoints¶

Perimeter¶

PointOnSurface¶

Reverse¶

Scale¶

SnapToGrid¶

SymDifference¶

Transform¶

Translate¶

Union¶

Last update:

`Area`¶

`AsGeoJSON`¶

`AsGML`¶

`AsKML`¶

`AsSVG`¶

`AsWKB`¶

`AsWKT`¶

`Azimuth`¶

`BoundingCircle`¶

`Centroid`¶

`ClosestPoint`¶

`Difference`¶

`Distance`¶

`Envelope`¶

`ForcePolygonCW`¶

`FromWKB`¶

`FromWKT`¶

`GeoHash`¶

`GeometryDistance`¶

`Intersection`¶

`IsEmpty`¶

`IsValid`¶

`Length`¶

`LineLocatePoint`¶

`MakeValid`¶

`MemSize`¶

`NumGeometries`¶

`NumPoints`¶

`Perimeter`¶

`PointOnSurface`¶

`Reverse`¶

`Scale`¶

`SnapToGrid`¶

`SymDifference`¶

`Transform`¶

`Translate`¶

`Union`¶