---
title: "地理数据库函数"
version: 6.0
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/6.0/ref/contrib/gis/functions/
canonical: https://djangodocs.dev/zh-hans/6.0/ref/contrib/gis/functions/
---
# 地理数据库函数

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

例如：

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

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

## Measurements

### `Area`

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

*Availability*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/gis-polygon-property-functions.html#function_st-area),
Oracle, [PostGIS](https://postgis.net/docs/ST_Area.html), SpatiaLite

接受单个地理字段或表达式，并将字段的面积作为一个 [`Area`](/zh-hans/6.0/ref/contrib/gis/measure/#django.contrib.gis.measure.Area) 测量返回。

在没有 LWGEOM/RTTOPO 支持的情况下，MySQL 和 SpatiaLite 不支持对地理 SRS（空间参考系统）进行面积计算。

### `Distance`

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

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/spatial-relation-functions-object-shapes.html#function_st-distance), [PostGIS](https://postgis.net/docs/ST_Distance.html), Oracle, SpatiaLite

接受两个地理字段或表达式，并返回它们之间的距离，作为一个 [`Distance`](/zh-hans/6.0/ref/contrib/gis/measure/#django.contrib.gis.measure.Distance) 对象。在 MySQL 上，当坐标是大地测量时，会返回原始的浮点值。

在支持大地测量坐标距离计算的后端上，根据几何形状的 SRID 值，会自动选择合适的后端函数（例如，在 PostGIS 上使用 [ST\_DistanceSphere](https://postgis.net/docs/ST_DistanceSphere.html)）。

当使用大地测量（角度）坐标计算距离时，例如默认的 WGS84 (4326) SRID，您可以设置 `spheroid` 关键字参数来决定计算是基于简单球体（精度较低，资源消耗较少）还是基于椭球体（精度较高，资源消耗较多）。

在以下示例中，计算了从霍巴特市到 `AustraliaCity` 查询集中的每个其他 [`PointField`](/zh-hans/6.0/ref/contrib/gis/model-api/#django.contrib.gis.db.models.PointField) 的距离：

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

> **Note**
>
> Because the `distance` attribute is a
> [`Distance`](/zh-hans/6.0/ref/contrib/gis/measure/#django.contrib.gis.measure.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
> [测量对象](/zh-hans/6.0/ref/contrib/gis/measure/) for usage details and the list of
> [支持的单位](/zh-hans/6.0/ref/contrib/gis/measure/#supported-units).

### `GeometryDistance`

#### `class GeometryDistance(expr1, expr2, **extra)`

*可用性*: [PostGIS](https://postgis.net/docs/geometry_distance_knn.html)

接受两个地理字段或表达式，并返回它们之间的距离。当在 [`order_by()`](/zh-hans/6.0/ref/models/querysets/#django.db.models.query.QuerySet.order_by) 子句中使用时，它提供了辅助索引的最近邻结果集。

### `Length`

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

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/gis-linestring-property-functions.html#function_st-length), Oracle, [PostGIS](https://postgis.net/docs/ST_Length.html), SpatiaLite

接受单个地理线串或多线串字段或表达式，并将其长度返回为 [`Distance`](/zh-hans/6.0/ref/contrib/gis/measure/#django.contrib.gis.measure.Distance) 测量。

在 PostGIS 和 SpatiaLite 上，当坐标是大地测量（角度）时，您可以使用 `spheroid` 关键字参数来指定计算是基于简单球体（精度较低，资源消耗较少）还是基于椭球体（精度较高，资源消耗较多）。

MySQL 不支持在地理 SRS 上进行长度计算。

### `Perimeter`

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

*可用性*: [PostGIS](https://postgis.net/docs/ST_Perimeter.html), Oracle, SpatiaLite

接受单个地理字段或表达式，并将几何字段的周长返回为 [`Distance`](/zh-hans/6.0/ref/contrib/gis/measure/#django.contrib.gis.measure.Distance) 对象。

## 关系映射

### `Azimuth`

#### `class Azimuth(point_a, point_b, **extra)`

*可用性*：[PostGIS](https://postgis.net/docs/ST_Azimuth.html), SpatiaLite (LWGEOM/RTTOPO)

返回由给定点几何形状定义的线段的方位角（以弧度表示），如果两个点重合，则返回 `None`。方位角是以北方为参考的角度，顺时针方向为正：north = `0`; east = `π/2`; south = `π`; west = `3π/2`。

### `BoundingCircle`

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

*可用性*：[PostGIS](https://postgis.net/docs/ST_MinimumBoundingCircle.html)、[Oracle](https://docs.oracle.com/en/database/oracle/oracle-database/21/spatl/SDO_GEOM-reference.html#GUID-82A61626-BB64-4793-B53D-A0DBEC91831A)、SpatiaLite 5.1+

接受单个地理字段或表达式，并返回可以完全包含几何形状的最小圆形多边形。

`num_seg` 参数仅在 PostGIS 中使用。

### `Centroid`

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

*可用性*：MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/gis-polygon-property-functions.html#function_st-centroid), [PostGIS](https://postgis.net/docs/ST_Centroid.html), Oracle, SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 `centroid` 值。

### `ClosestPoint`

#### `class ClosestPoint(expr1, expr2, **extra)`

*可用性*: [PostGIS](https://postgis.net/docs/ST_ClosestPoint.html), SpatiaLite

接受两个地理字段或表达式，并返回在几何体 A 上最接近几何体 B 的二维点。

### `Envelope`

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

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/gis-general-property-functions.html#function_st-envelope), [Oracle](https://docs.oracle.com/en/database/oracle/oracle-database/21/spatl/spatial-operators-reference.html#GUID-ACED800F-3435-44AA-9606-D40934A23ED0), [PostGIS](https://postgis.net/docs/ST_Envelope.html), SpatiaLite

接受单个地理字段或表达式，并返回表示几何形状的边界框的几何形状。

### `LineLocatePoint`

#### `class LineLocatePoint(linestring, point, **extra)`

*可用性*: [PostGIS](https://postgis.net/docs/ST_LineLocatePoint.html), SpatiaLite

返回一个介于 0 和 1 之间的浮点数，表示最接近给定的 `point` 在 `linestring` 上的位置，作为 2D 线长度的一部分。

### `PointOnSurface`

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

*可用性*: [PostGIS](https://postgis.net/docs/ST_PointOnSurface.html), MariaDB, Oracle, SpatiaLite

接受单个地理字段或表达式，并返回一个保证位于字段表面上的 `Point` 几何形状；否则返回 `None`。

## 操作

### `Difference`

#### `class Difference(expr1, expr2, **extra)`

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/spatial-operator-functions.html#function_st-difference), [PostGIS](https://postgis.net/docs/ST_Difference.html), Oracle, SpatiaLite

接受两个地理字段或表达式，并返回几何差异，即几何 A 中与几何 B 不相交的部分。

### `Intersection`

#### `class Intersection(expr1, expr2, **extra)`

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/spatial-operator-functions.html#function_st-intersection), [PostGIS](https://postgis.net/docs/ST_Intersection.html), Oracle, SpatiaLite

接受两个地理字段或表达式，并返回它们之间的几何交集。

### `SymDifference`

#### `class SymDifference(expr1, expr2, **extra)`

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/spatial-operator-functions.html#function_st-symdifference), [PostGIS](https://postgis.net/docs/ST_SymDifference.html), Oracle, SpatiaLite

接受两个地理字段或表达式，并返回给定参数之间的几何对称差异（联合而不包括交集）。

### `Union`

#### `class Union(expr1, expr2, **extra)`

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/spatial-operator-functions.html#function_st-union), [PostGIS](https://postgis.net/docs/ST_Union.html), Oracle, SpatiaLite

接受两个地理字段或表达式，并返回两个几何形状的联合。

## 编辑器

### `ForcePolygonCW`

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

*可用性*: [PostGIS](https://postgis.net/docs/ST_ForcePolygonCW.html), SpatiaLite

接受单个地理字段或表达式，并返回多边形/多多边形的修改版本，其中所有外部环都按顺时针方向排列，所有内部环都按逆时针方向排列。非多边形几何形状保持不变。

### `MakeValid`

#### `class MakeValid(expr)`

*可用性*: [PostGIS](https://postgis.net/docs/ST_MakeValid.html), SpatiaLite (LWGEOM/RTTOPO)

接受地理字段或表达式，并尝试将值转换为有效的几何形状，同时不丢失任何输入顶点。已经有效的几何形状将保持不变。简单多边形可能会变成多重多边形，结果的维度可能比输入低。

### `Reverse`

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

*可用性*: [PostGIS](https://postgis.net/docs/ST_Reverse.html), Oracle, SpatiaLite

接受单个地理字段或表达式，并返回具有颠倒坐标的几何形状。

### `Rotate`

> **New in Django 6.0**

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

*Availability*: [PostGIS](https://postgis.net/docs/ST_Rotate.html)

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

### `Scale`

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

*可用性*: [PostGIS](https://postgis.net/docs/ST_Scale.html), SpatiaLite

接受单个地理字段或表达式，并返回通过将坐标与 `x`、`y` 和可选的 `z` 参数相乘来缩放坐标的几何形状。

### `SnapToGrid`

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

*可用性*: [PostGIS](https://postgis.net/docs/ST_SnapToGrid.html), 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.

| 参数数量： | 描述 |
| --- | --- |
| 1 | 一个单独的大小，用于捕捉 X 和 Y 网格。 |
| 2 | 捕捉网格的 X 和 Y 大小。 |
| 4 | X、Y 大小以及相应的 X、Y 起始点。 |

### `Transform`

#### `class Transform(expression, srid, **extra)`

*可用性*: [PostGIS](https://postgis.net/docs/ST_Transform.html), Oracle, SpatiaLite

接受一个地理字段或表达式以及一个 SRID 整数代码，并将几何形状转换为由 `srid` 参数指定的空间参考系统。

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

*可用性*: [PostGIS](https://postgis.net/docs/ST_Translate.html), SpatiaLite

接受单个地理字段或表达式，并返回其坐标根据 `x`、`y` 和可选的 `z` 数值参数进行偏移的几何形状。

## 输入格式：

### `FromWKB`

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

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/gis-wkb-functions.html#function_st-geomfromwkb), Oracle, [PostGIS](https://postgis.net/docs/ST_GeomFromWKB.html), SpatiaLite

从 [Well-known binary (WKB)](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary) 表示创建几何。可选的 `srid` 参数允许指定结果几何的 SRID。在 Oracle 上忽略 `srid`。

### `FromWKT`

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

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/gis-wkt-functions.html#function_st-geomfromtext), Oracle, [PostGIS](https://postgis.net/docs/ST_GeomFromText.html), SpatiaLite

从 [Well-known text (WKT)](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) 表示创建几何。可选的 `srid` 参数允许指定结果几何的 SRID。在 Oracle 上忽略 `srid`。

## 输出格式

### `AsGeoJSON`

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

*可用性*：MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/spatial-geojson-functions.html#function_st-asgeojson), Oracle, [PostGIS](https://postgis.net/docs/ST_AsGeoJSON.html), SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 [GeoJSON](https://geojson.org/) 表示。请注意，结果不是完整的 GeoJSON 结构，而只是 GeoJSON 结构中 `geometry` 键的内容。另请参阅 [GeoJSON 序列化器](/zh-hans/6.0/ref/contrib/gis/serializers/)。

例如：

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

| 关键字参数 | 描述 |
| --- | --- |
| `bbox` | 如果希望包含返回的 GeoJSON 中的边界框，请将其设置为 `True`。在 Oracle 中会被忽略。 |
| `crs` | 如果希望在返回的 GeoJSON 中包含坐标参考系统，请将其设置为 `True`。在 MySQL 和 Oracle 中会被忽略。 |
| `precision` | 可以用来指定 GeoJSON 表示中坐标的有效数字位数，其默认值为 8。在 Oracle 中会被忽略。 |

### `AsGML`

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

*可用性*：Oracle, [PostGIS](https://postgis.net/docs/ST_AsGML.html), SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 [Geographic Markup Language (GML)](https://en.wikipedia.org/wiki/Geography_Markup_Language) 表示。

例如：

```pycon
>>> 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` | 指定在 GML 表示中坐标的有效数字位数，默认值为 8。在 Oracle 中会被忽略。 |
| `version` | 指定要使用的 GML 版本：2（默认）或 3。 |

### `AsKML`

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

*可用性*：[PostGIS](https://postgis.net/docs/ST_AsKML.html), SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 [Keyhole Markup Language (KML)](https://developers.google.com/kml/documentation/) 表示。

例如：

```pycon
>>> 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` | 可以使用此关键字来指定 KML 表示中坐标的有效数字位数，其默认值为 8。 |

### `AsSVG`

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

*可用性*：[PostGIS](https://postgis.net/docs/ST_AsSVG.html), SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 [Scalable Vector Graphics (SVG)](https://www.w3.org/Graphics/SVG/) 表示。

| 关键字参数 | 描述 |
| --- | --- |
| `relative` | 如果设置为 `True`，路径数据将以相对移动的方式实现。默认为 `False`，表示使用绝对移动。 |
| `precision` | 可以使用此关键字来指定 SVG 表示中坐标的有效数字位数，其默认值为 8。 |

### `AsWKB`

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

*可用性*：MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/gis-format-conversion-functions.html#function_st-asbinary), Oracle, [PostGIS](https://postgis.net/docs/ST_AsBinary.html), SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 [Well-known binary (WKB)](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary) 表示。

例如：

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

*可用性*：MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/gis-format-conversion-functions.html#function_st-astext), Oracle, [PostGIS](https://postgis.net/docs/ST_AsText.html), SpatiaLite

接受单个地理字段或表达式，并返回几何形状的 [Well-known text (WKT)](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) 表示。

例如：

```pycon
>>> 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](https://dev.mysql.com/doc/refman/en/spatial-geohash-functions.html#function_st-geohash),
[PostGIS](https://postgis.net/docs/ST_GeoHash.html), SpatiaLite
(LWGEOM/RTTOPO)

接受单个地理字段或表达式，并返回几何形状的 [GeoHash](https://en.wikipedia.org/wiki/Geohash) 表示。

`precision` 关键字参数控制结果中的字符数。

> **Changed in Django 6.0**
>
> MariaDB 12.0.1+ support was added.

## 杂项

### `IsEmpty`

#### `class IsEmpty(expr)`

*可用性*: [PostGIS](https://postgis.net/docs/ST_IsEmpty.html)

接受地理字段或表达式，并测试其值是否为空几何形状。如果其值为空，则返回 `True`，否则返回 `False`。

### `IsValid`

#### `class IsValid(expr)`

*Availability*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/spatial-convenience-functions.html#function_st-isvalid),
[PostGIS](https://postgis.net/docs/ST_IsValid.html), Oracle, SpatiaLite

接受地理字段或表达式，并测试其值是否格式正确。如果其值是有效的几何形状，则返回 `True`，否则返回 `False`。

> **Changed in Django 6.0**
>
> MariaDB 12.0.1+ support was added.

### `GeometryType`

> **New in Django 6.0**

#### `class GeometryType(expr)`

*Availability*: [PostGIS](https://postgis.net/docs/GeometryType.html),
Oracle 23c+, MariaDB, MySQL, SpatiaLite

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

### `MemSize`

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

*可用性*: [PostGIS](https://postgis.net/docs/ST_MemSize.html)

接受单个地理字段或表达式，并返回几何字段占用的内存大小（字节数）。

### `NumGeometries`

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

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/gis-geometrycollection-property-functions.html#function_st-numgeometries), [PostGIS](https://postgis.net/docs/ST_NumGeometries.html), Oracle, SpatiaLite

接受单个地理字段或表达式，并返回如果几何字段是集合（例如 `GEOMETRYCOLLECTION` 或 `MULTI*` 字段）则包含的几何形状数量。对于单个几何形状，返回 1。

在 MySQL 上，对于单个几何形状，返回 `None`。

### `NumPoints`

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

*可用性*: MariaDB, [MySQL](https://dev.mysql.com/doc/refman/en/gis-linestring-property-functions.html#function_st-numpoints), [PostGIS](https://postgis.net/docs/ST_NPoints.html), Oracle, SpatiaLite

接受单个地理字段或表达式，并返回几何形状中点的数量。

在 MySQL 上，对于任何非 `LINESTRING` 几何形状，返回 `None`。