GIS QuerySet API 参考

空间查找

本节中的空间查找可用于 GeometryField 和 RasterField。

有关介绍，请参阅空间查找介绍。有关哪些查找与特定空间后端兼容的概述，请参阅空间查找兼容性表。

使用栅格查找

下面参考中的所有示例都是针对几何字段和输入给出的，但查找可以以相同的方式用于两侧的栅格。每当查找不支持栅格输入时，输入会在必要时使用 ST_Polygon 函数自动转换为几何图形。另请参阅对栅格查找的介绍。

查找使用的数据库运算符可以分为三类：

原生栅格支持 N：运算符在查找的两侧原生接受栅格，并且栅格输入可以与几何输入混合。
双边栅格支持 B：仅当查找的两侧都接收栅格输入时，运算符才支持栅格。栅格数据会自动转换为几何图形以进行混合查找。
几何转换支持 C。查找没有原生栅格支持，所有栅格数据都会自动转换为几何图形。

下面的示例显示了在不同类型的栅格支持中查找的 SQL 等效项。相同的模式适用于所有空间查找。

案例	查找	SQL 等价物
否，乙	`rast__contains=rst`	`ST_Contains(rast, rst)`
否，乙	`rast__1__contains=(rst, 2)`	`ST_Contains(rast, 1, rst, 2)`
乙、丙	`rast__contains=geom`	`ST_Contains(ST_Polygon(rast), geom)`
乙、丙	`rast__1__contains=geom`	`ST_Contains(ST_Polygon(rast, 1), geom)`
乙、丙	`poly__contains=rst`	`ST_Contains(poly, ST_Polygon(rst))`
乙、丙	`poly__contains=(rst, 1)`	`ST_Contains(poly, ST_Polygon(rst, 1))`
C	`rast__crosses=rst`	`ST_Crosses(ST_Polygon(rast), ST_Polygon(rst))`
C	`rast__1__crosses=(rst, 2)`	`ST_Crosses(ST_Polygon(rast, 1), ST_Polygon(rst, 2))`
C	`rast__crosses=geom`	`ST_Crosses(ST_Polygon(rast), geom)`
C	`poly__crosses=rst`	`ST_Crosses(poly, ST_Polygon(rst))`

仅 PostGIS 后端（在本节中称为 PGRaster）支持使用栅格进行空间查找。

bbcontains

可用性：PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster（原生）

测试几何或栅格字段的边界框是否完全包含查找几何的边界框。

例子：

Zipcode.objects.filter(poly__bbcontains=geom)

后端	SQL 等价物
地理信息系统	`poly ~ geom`
玛丽亚数据库	`MBRContains(poly, geom)`
MySQL	`MBRContains(poly, geom)`
SpatiaLite	`MbrContains(poly, geom)`

bboverlaps

可用性：PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster（原生）

测试几何字段的边界框是否与查找几何的边界框重叠。

例子：

Zipcode.objects.filter(poly__bboverlaps=geom)

后端	SQL 等价物
地理信息系统	`poly && geom`
玛丽亚数据库	`MBROverlaps(poly, geom)`
MySQL	`MBROverlaps(poly, geom)`
SpatiaLite	`MbrOverlaps(poly, geom)`

contained

可用性：PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster（原生）

测试几何字段的边界框是否完全包含在查找几何的边界框内。

例子：

Zipcode.objects.filter(poly__contained=geom)

后端	SQL 等价物
地理信息系统	`poly @ geom`
玛丽亚数据库	`MBRWithin(poly, geom)`
MySQL	`MBRWithin(poly, geom)`
SpatiaLite	`MbrWithin(poly, geom)`

contains

可用性：PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster（双边）

测试几何字段在空间上是否包含查找几何。

例子：

Zipcode.objects.filter(poly__contains=geom)

后端	SQL 等价物
地理信息系统	`ST_Contains(poly, geom)`
甲骨文	`SDO_CONTAINS(poly, geom)`
玛丽亚数据库	`ST_Contains(poly, geom)`
MySQL	`ST_Contains(poly, geom)`
SpatiaLite	`Contains(poly, geom)`

3.0 版本变化：在旧版本中，MySQL 使用 MBRContains 并且仅对边界框进行操作。

contains_properly

可用性：PostGIS，PGRaster（双边）

如果查找几何与几何字段的内部相交，但不与边界（或外部）相交，则返回 true。

例子：

Zipcode.objects.filter(poly__contains_properly=geom)

后端	SQL 等价物
地理信息系统	`ST_ContainsProperly(poly, geom)`

coveredby

可用性：PostGIS、Oracle、PGRaster（双边）、SpatiaLite

测试几何字段中是否没有点位于查找几何之外。 3

例子：

Zipcode.objects.filter(poly__coveredby=geom)

后端	SQL 等价物
地理信息系统	`ST_CoveredBy(poly, geom)`
甲骨文	`SDO_COVEREDBY(poly, geom)`
SpatiaLite	`CoveredBy(poly, geom)`

covers

可用性：PostGIS、Oracle、PGRaster（双边）、SpatiaLite

测试查找几何中是否没有点位于几何字段之外。 3

例子：

Zipcode.objects.filter(poly__covers=geom)

后端	SQL 等价物
地理信息系统	`ST_Covers(poly, geom)`
甲骨文	`SDO_COVERS(poly, geom)`
SpatiaLite	`Covers(poly, geom)`

crosses

可用性：PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster（转换）

测试几何字段是否与查找几何在空间上交叉。

例子：

Zipcode.objects.filter(poly__crosses=geom)

后端	SQL 等价物
地理信息系统	`ST_Crosses(poly, geom)`
玛丽亚数据库	`ST_Crosses(poly, geom)`
MySQL	`ST_Crosses(poly, geom)`
SpatiaLite	`Crosses(poly, geom)`

3.0 版更改：增加了 MySQL 支持。

disjoint

可用性：PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster（双边）

测试几何字段是否与查找几何在空间上不相交。

例子：

Zipcode.objects.filter(poly__disjoint=geom)

后端	SQL 等价物
地理信息系统	`ST_Disjoint(poly, geom)`
甲骨文	`SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)`
玛丽亚数据库	`ST_Disjoint(poly, geom)`
MySQL	`ST_Disjoint(poly, geom)`
SpatiaLite	`Disjoint(poly, geom)`

3.0 版本变化：在旧版本中，MySQL 使用 MBRDisjoint 并且仅对边界框进行操作。

equals

可用性：PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster（转换）

测试几何字段在空间上是否等于查找几何。

例子：

Zipcode.objects.filter(poly__equals=geom)

后端	SQL 等价物
地理信息系统	`ST_Equals(poly, geom)`
甲骨文	`SDO_EQUAL(poly, geom)`
玛丽亚数据库	`ST_Equals(poly, geom)`
MySQL	`ST_Equals(poly, geom)`
SpatiaLite	`Equals(poly, geom)`

3.0 版本变化：在旧版本中，MySQL 使用 MBREquals 并且仅对边界框进行操作。

exact、same_as

可用性：PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster（双边）

测试几何字段是否“等于”查找几何。在 Oracle、MySQL 和 SpatiaLite 上，它测试空间相等性，而在 PostGIS 上，它测试边界框的相等性。

例子：

Zipcode.objects.filter(poly=geom)

后端	SQL 等价物
地理信息系统	`poly ~= geom`
甲骨文	`SDO_EQUAL(poly, geom)`
玛丽亚数据库	`ST_Equals(poly, geom)`
MySQL	`ST_Equals(poly, geom)`
SpatiaLite	`Equals(poly, geom)`

3.0 版本变化：在旧版本中，MySQL 使用 MBREquals 并且仅对边界框进行操作。

intersects

可用性：PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster（双边）

测试几何字段是否与查找几何在空间上相交。

例子：

Zipcode.objects.filter(poly__intersects=geom)

后端	SQL 等价物
地理信息系统	`ST_Intersects(poly, geom)`
甲骨文	`SDO_OVERLAPBDYINTERSECT(poly, geom)`
玛丽亚数据库	`ST_Intersects(poly, geom)`
MySQL	`ST_Intersects(poly, geom)`
SpatiaLite	`Intersects(poly, geom)`

3.0 版本变化：在旧版本中，MySQL 使用 MBRIntersects 并且仅对边界框进行操作。

isvalid

可用性：MySQL (≥ 5.7.5)、PostGIS、Oracle、SpatiaLite

测试几何图形是否有效。

例子：

Zipcode.objects.filter(poly__isvalid=True)

后端	SQL 等价物
MySQL、PostGIS、SpatiaLite	`ST_IsValid(poly)`
甲骨文	`SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(poly, 0.05) = 'TRUE'`

overlaps

可用性：PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster（双边）

测试几何字段是否与查找几何在空间上重叠。

后端	SQL 等价物
地理信息系统	`ST_Overlaps(poly, geom)`
甲骨文	`SDO_OVERLAPS(poly, geom)`
玛丽亚数据库	`ST_Overlaps(poly, geom)`
MySQL	`ST_Overlaps(poly, geom)`
SpatiaLite	`Overlaps(poly, geom)`

3.0 版本变化：在旧版本中，MySQL 使用 MBROverlaps 并且仅对边界框进行操作。

relate

可用性：PostGIS、MariaDB、Oracle、SpatiaLite、PGRaster（转换）

通过给定模式中给定的值测试几何字段是否与查找几何在空间上相关。这个查找需要一个元组参数，(geom, pattern)； pattern 的形式将取决于空间后端：

MariaDB、PostGIS 和 SpatiaLite

在这些空间后端上，相交模式是一个由九个字符组成的字符串，用于定义几何字段与查找几何的内部、边界和外部之间的交集。交集模式矩阵只能使用以下字符：1、2、T、F或*。这种查找类型允许用户“微调”与 DE-9IM 模型一致的特定几何关系。 1

几何示例：

# A tuple lookup parameter is used to specify the geometry and
# the intersection pattern (the pattern here is for 'contains').
Zipcode.objects.filter(poly__relate=(geom, 'T*T***FF*'))

PostGIS 和 MariaDB SQL 等价物：

SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')

SpatiaLite SQL 等效项：

SELECT ... WHERE Relate(poly, geom, 'T*T***FF*')

光栅示例：

Zipcode.objects.filter(poly__relate=(rast, 1, 'T*T***FF*'))
Zipcode.objects.filter(rast__2__relate=(rast, 1, 'T*T***FF*'))

PostGIS SQL 等效项：

SELECT ... WHERE ST_Relate(poly, ST_Polygon(rast, 1), 'T*T***FF*')
SELECT ... WHERE ST_Relate(ST_Polygon(rast, 2), ST_Polygon(rast, 1), 'T*T***FF*')

3.1 版更改：添加了 MariaDB 支持。

甲骨文

这里的关系模式由以下九个关系串中的至少一个组成：TOUCH、OVERLAPBDYDISJOINT、OVERLAPBDYINTERSECT、EQUAL、INSIDE 、COVEREDBY、CONTAINS、COVERS、ON 和 ANYINTERACT。多个字符串可以用逻辑布尔运算符 OR 组合，例如，'inside+touch'。 2 关系字符串不区分大小写。

例子：

Zipcode.objects.filter(poly__relate=(geom, 'anyinteract'))

Oracle SQL 等效项：

SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')

touches

可用性：PostGIS、Oracle、MariaDB、MySQL、SpatiaLite

测试几何字段是否在空间上接触查找几何。

例子：

Zipcode.objects.filter(poly__touches=geom)

后端	SQL 等价物
地理信息系统	`ST_Touches(poly, geom)`
玛丽亚数据库	`ST_Touches(poly, geom)`
MySQL	`ST_Touches(poly, geom)`
甲骨文	`SDO_TOUCH(poly, geom)`
SpatiaLite	`Touches(poly, geom)`

3.0 版本变化：在旧版本中，MySQL 使用 MBRTouches 并且仅对边界框进行操作。

within

可用性：PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster（双边）

测试几何字段是否在空间上查找几何。

例子：

Zipcode.objects.filter(poly__within=geom)

后端	SQL 等价物
地理信息系统	`ST_Within(poly, geom)`
玛丽亚数据库	`ST_Within(poly, geom)`
MySQL	`ST_Within(poly, geom)`
甲骨文	`SDO_INSIDE(poly, geom)`
SpatiaLite	`Within(poly, geom)`

3.0 版本变化：在旧版本中，MySQL 使用 MBRWithin 并且仅对边界框进行操作。

left

可用性：PostGIS，PGRaster（转换）

测试几何字段的边界框是否严格位于查找几何的边界框的左侧。

例子：

Zipcode.objects.filter(poly__left=geom)

PostGIS 等效项：

SELECT ... WHERE poly << geom

right

可用性：PostGIS，PGRaster（转换）

测试几何字段的边界框是否严格位于查找几何的边界框的右侧。

例子：

Zipcode.objects.filter(poly__right=geom)

PostGIS 等效项：

SELECT ... WHERE poly >> geom

overlaps_left

可用性：PostGIS，PGRaster（双边）

测试几何字段的边界框是否与查找几何的边界框重叠或位于其左侧。

例子：

Zipcode.objects.filter(poly__overlaps_left=geom)

PostGIS 等效项：

SELECT ... WHERE poly &< geom

overlaps_right

可用性：PostGIS，PGRaster（双边）

测试几何字段的边界框是否与查找几何的边界框重叠或位于其右侧。

例子：

Zipcode.objects.filter(poly__overlaps_right=geom)

PostGIS 等效项：

SELECT ... WHERE poly &> geom

overlaps_above

可用性：PostGIS，PGRaster（转换）

测试几何字段的边界框是否与查找几何的边界框重叠或位于其上方。

例子：

Zipcode.objects.filter(poly__overlaps_above=geom)

PostGIS 等效项：

SELECT ... WHERE poly |&> geom

overlaps_below

可用性：PostGIS，PGRaster（转换）

测试几何字段的边界框是否重叠或低于查找几何的边界框。

例子：

Zipcode.objects.filter(poly__overlaps_below=geom)

PostGIS 等效项：

SELECT ... WHERE poly &<| geom

strictly_above

可用性：PostGIS，PGRaster（转换）

测试几何字段的边界框是否严格高于查找几何的边界框。

例子：

Zipcode.objects.filter(poly__strictly_above=geom)

PostGIS 等效项：

SELECT ... WHERE poly |>> geom

strictly_below

可用性：PostGIS，PGRaster（转换）

测试几何字段的边界框是否严格低于查找几何的边界框。

例子：

Zipcode.objects.filter(poly__strictly_below=geom)

PostGIS 等效项：

SELECT ... WHERE poly <<| geom

距离查找

可用性：PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster（原生）

有关执行距离查询的概述，请参阅距离查询介绍。

距离查找采用以下形式：

<field>__<distance lookup>=(<geometry/raster>, <distance value>[, 'spheroid'])
<field>__<distance lookup>=(<raster>, <band_index>, <distance value>[, 'spheroid'])
<field>__<band_index>__<distance lookup>=(<raster>, <band_index>, <distance value>[, 'spheroid'])

传递给距离查找的值是一个元组；前两个值是强制性的，并且是计算到的距离的几何图形和一个距离值（以字段为单位的数字、Distance 对象或查询表达式）。要将波段索引传递给查找，请使用 3 元组，其中第二个条目是波段索引。

在除 :lookup:`dwithin` 之外的每个距离查找中，可以包含一个可选元素 'spheroid'，以便在具有大地坐标系的字段上使用更准确的球体距离计算函数。

在 PostgreSQL 上，'spheroid' 选项使用 ST_DistanceSpheroid 而不是 ST_DistanceSphere。更简单的 ST_Distance 函数用于投影坐标系。栅格被转换为几何图形以进行基于球体的查找。

distance_gt

返回从查找几何到几何字段的距离大于给定距离值的模型。

例子：

Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))

后端	SQL 等价物
地理信息系统	`ST_Distance/ST_Distance_Sphere(poly, geom) > 5`
玛丽亚数据库	`ST_Distance(poly, geom) > 5`
MySQL	`ST_Distance(poly, geom) > 5`
甲骨文	`SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) > 5`
SpatiaLite	`Distance(poly, geom) > 5`

distance_gte

返回从查找几何到几何字段的距离大于或等于给定距离值的模型。

例子：

Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))

后端	SQL 等价物
地理信息系统	`ST_Distance/ST_Distance_Sphere(poly, geom) >= 5`
玛丽亚数据库	`ST_Distance(poly, geom) >= 5`
MySQL	`ST_Distance(poly, geom) >= 5`
甲骨文	`SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) >= 5`
SpatiaLite	`Distance(poly, geom) >= 5`

distance_lt

返回从查找几何到几何字段的距离小于给定距离值的模型。

例子：

Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))

后端	SQL 等价物
地理信息系统	`ST_Distance/ST_Distance_Sphere(poly, geom) < 5`
玛丽亚数据库	`ST_Distance(poly, geom) < 5`
MySQL	`ST_Distance(poly, geom) < 5`
甲骨文	`SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) < 5`
SpatiaLite	`Distance(poly, geom) < 5`

distance_lte

返回从查找几何到几何字段的距离小于或等于给定距离值的模型。

例子：

Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))

后端	SQL 等价物
地理信息系统	`ST_Distance/ST_Distance_Sphere(poly, geom) <= 5`
玛丽亚数据库	`ST_Distance(poly, geom) <= 5`
MySQL	`ST_Distance(poly, geom) <= 5`
甲骨文	`SDO_GEOM.SDO_DISTANCE(poly, geom, 0.05) <= 5`
SpatiaLite	`Distance(poly, geom) <= 5`

dwithin

返回从查找几何到几何字段的距离彼此在给定距离内的模型。请注意，如果目标几何图形在投影系统中，您只能提供 Distance 对象。对于地理几何，您应该使用几何字段的单位（例如 WGS84) 的度数。

例子：

Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))

后端	SQL 等价物
地理信息系统	`ST_DWithin(poly, geom, 5)`
甲骨文	`SDO_WITHIN_DISTANCE(poly, geom, 5)`
SpatiaLite	`PtDistWithin(poly, geom, 5)`

聚合函数

Django 提供了一些特定于 GIS 的聚合函数。有关如何使用这些聚合函数的详细信息，请参阅聚合主题指南。

关键字参数	说明
`tolerance`	此关键字仅适用于 Oracle。用于`SDOAGGRTYPE`程序使用的公差值； Oracle 文档有更多细节。

例子：

>>> from django.contrib.gis.db.models import Extent, Union
>>> WorldBorder.objects.aggregate(Extent('mpoly'), Union('mpoly'))

Collect

class Collect(geo_field)

可用性：PostGIS，SpatiaLite

从几何列返回 GEOMETRYCOLLECTION 或 MULTI 几何对象。这类似于 Union 聚合的简化版本，但它可以比执行联合快几个数量级，因为它将几何图形汇总到一个集合或多对象中，而不关心分解边界。

Extent

class Extent(geo_field)

可用性：PostGIS、Oracle、SpatiaLite

以四元组形式返回 QuerySet 中所有 geo_field 的范围，包括左下坐标和右上坐标。

例子：

>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent('poly'))
>>> print(qs['poly__extent'])
(-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)

Extent3D

class Extent3D(geo_field)

可用性：PostGIS

以六元组形式返回 QuerySet 中所有 geo_field 的 3D 范围，包括左下坐标和右上坐标（每个坐标都有 x、y 和 z 坐标）。

例子：

>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent3D('poly'))
>>> print(qs['poly__extent3d'])
(-96.8016128540039, 29.7633724212646, 0, -95.3631439208984, 32.782058715820, 0)

MakeLine

class MakeLine(geo_field)

可用性：PostGIS，SpatiaLite

返回从 QuerySet 中的点场几何构造的 LineString。目前，对查询集进行排序无效。

例子：

>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(MakeLine('poly'))
>>> print(qs['poly__makeline'])
LINESTRING (-95.3631510000000020 29.7633739999999989, -96.8016109999999941 32.7820570000000018)

Union

class Union(geo_field)

可用性：PostGIS、Oracle、SpatiaLite

此方法返回一个 GEOSGeometry 对象，该对象包含查询集中每个几何体的并集。请注意，使用 Union 是处理器密集型的，并且可能会在大型查询集上花费大量时间。

笔记

如果使用此方法的计算时间太昂贵，请考虑使用 Collect 代替。

例子：

>>> u = Zipcode.objects.aggregate(Union(poly))  # This may take a long time.
>>> u = Zipcode.objects.filter(poly__within=bbox).aggregate(Union(poly))  # A more sensible approach.

脚注

1: 看用于 SQL 的 OpenGIS 简单特征规范, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model).
2: 看 SDO_RELATE 文档, from the Oracle Spatial and Graph Developer’s Guide.
3(1,2): 有关此例程的解释，请阅读 Martin Davis（PostGIS 开发人员）撰写的 Quirks of the “Contains” Spatial Predicate。

GIS QuerySet API 参考 — Django 文档

GIS QuerySet API 参考

空间查找

使用栅格查找

bbcontains

bboverlaps

contained

contains

contains_properly

coveredby

covers

crosses

disjoint

equals

exact、same_as

intersects

isvalid

overlaps

relate

MariaDB、PostGIS 和 SpatiaLite

甲骨文

touches

within

left

right

overlaps_left

overlaps_right

overlaps_above

overlaps_below

strictly_above

strictly_below

距离查找

distance_gt

distance_gte

distance_lt

distance_lte

dwithin

聚合函数

Collect

Extent

Extent3D

MakeLine

Union