Django 5.1.dev 文档

Home | Table of contents | Index | Modules

« previous | up | next »

GIS查询集API参考¶

空间查找¶

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

有关介绍，请参见 spatial lookups introduction . 有关与特定空间后端兼容的查找的概述，请参阅 spatial lookup compatibility table .

用粗锉查找¶

以下参考中的所有示例都是为几何字段和输入提供的，但是查找可以以同样的方式使用两边的栅格。当查找不支持栅格输入时，输入将在必要时自动转换为几何图形，使用 ST_Polygon 功能。也见 introduction to raster lookups .

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

本地栅格支持 N ：操作员在查找的两侧本机接受栅格，栅格输入可以与几何输入混合。
双边栅格支持 B ：只有当查找的两侧都接收到栅格输入时，操作员才支持栅格。栅格数据自动转换为几何图形以进行混合查找。
几何转换支持 C . 查找没有本机栅格支持，所有栅格数据都将自动转换为几何图形。

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

案例	查找	SQL等价物
N，B	`rast__contains=rst`	`ST_Contains(rast, rst)`
N，B	`rast__1__contains=(rst, 2)`	`ST_Contains(rast, 1, rst, 2)`
B	`rast__contains=geom`	`ST_Contains(ST_Polygon(rast), geom)`
B	`rast__1__contains=geom`	`ST_Contains(ST_Polygon(rast, 1), geom)`
B	`poly__contains=rst`	`ST_Contains(poly, ST_Polygon(rst))`
B	`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，spacealite，PGRaster（本机）

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

例子：：

Zipcode.objects.filter(poly__bbcontains=geom)

后端	SQL等价物
PostGIS	`poly ~ geom`
玛丽亚德	`MBRContains(poly, geom)`
MySQL	`MBRContains(poly, geom)`
SpatiaLite	`MbrContains(poly, geom)`

`bboverlaps`¶

可利用性 ： PostGIS ，MariaDB，MySQL，spacealite，PGRaster（本机）

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

例子：：

Zipcode.objects.filter(poly__bboverlaps=geom)

后端	SQL等价物
PostGIS	`poly && geom`
玛丽亚德	`MBROverlaps(poly, geom)`
MySQL	`MBROverlaps(poly, geom)`
SpatiaLite	`MbrOverlaps(poly, geom)`

`contained`¶

可利用性 ： PostGIS ，MariaDB，MySQL，spacealite，PGRaster（本机）

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

例子：：

Zipcode.objects.filter(poly__contained=geom)

后端	SQL等价物
PostGIS	`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等价物
PostGIS	`ST_Contains(poly, geom)`
甲骨文公司	`SDO_CONTAINS(poly, geom)`
玛丽亚德	`ST_Contains(poly, geom)`
MySQL	`ST_Contains(poly, geom)`
SpatiaLite	`Contains(poly, geom)`

`contains_properly`¶

可用性 ： PostGIS ，PGRASTER（双边）

如果查找几何图形与几何图形字段的内部相交，而不是与边界（或外部）相交，则返回“真”。

例子：：

Zipcode.objects.filter(poly__contains_properly=geom)

后端	SQL等价物
PostGIS	`ST_ContainsProperly(poly, geom)`

`coveredby`¶

可用性 ： PostGIS ，Oracle，PGRASTER（双边），Spatialite

测试几何图形字段中的任何点是否在查找几何图形之外。 [3]

例子：：

Zipcode.objects.filter(poly__coveredby=geom)

后端	SQL等价物
PostGIS	`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等价物
PostGIS	`ST_Covers(poly, geom)`
甲骨文公司	`SDO_COVERS(poly, geom)`
SpatiaLite	`Covers(poly, geom)`

`crosses`¶

可利用性 ： PostGIS ，MariaDB，MySQL，spacealite，PGRaster（转换）

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

例子：：

Zipcode.objects.filter(poly__crosses=geom)

后端	SQL等价物
PostGIS	`ST_Crosses(poly, geom)`
玛丽亚德	`ST_Crosses(poly, geom)`
MySQL	`ST_Crosses(poly, geom)`
SpatiaLite	`Crosses(poly, geom)`

`disjoint`¶

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

测试几何图形字段是否与查找几何图形在空间上分离。

例子：：

Zipcode.objects.filter(poly__disjoint=geom)

后端	SQL等价物
PostGIS	`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)`

`equals`¶

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

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

例子：：

Zipcode.objects.filter(poly__equals=geom)

后端	SQL等价物
PostGIS	`ST_Equals(poly, geom)`
甲骨文公司	`SDO_EQUAL(poly, geom)`
玛丽亚德	`ST_Equals(poly, geom)`
MySQL	`ST_Equals(poly, geom)`
SpatiaLite	`Equals(poly, geom)`

`exact`, `same_as`¶

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

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

例子：：

Zipcode.objects.filter(poly=geom)

后端	SQL等价物
PostGIS	`poly ~= geom`
甲骨文公司	`SDO_EQUAL(poly, geom)`
玛丽亚德	`ST_Equals(poly, geom)`
MySQL	`ST_Equals(poly, geom)`
SpatiaLite	`Equals(poly, geom)`

`intersects`¶

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

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

例子：：

Zipcode.objects.filter(poly__intersects=geom)

后端	SQL等价物
PostGIS	`ST_Intersects(poly, geom)`
甲骨文公司	`SDO_OVERLAPBDYINTERSECT(poly, geom)`
玛丽亚德	`ST_Intersects(poly, geom)`
MySQL	`ST_Intersects(poly, geom)`
SpatiaLite	`Intersects(poly, geom)`

`isempty`¶

Availability ： PostGIS

测试几何图形是否为空。

例子：：

Zipcode.objects.filter(poly__isempty=True)

`isvalid`¶

Availability ：MySQL， PostGIS 、Oracle、SpatiaLite

测试几何图形是否有效。

例子：：

Zipcode.objects.filter(poly__isvalid=True)

后端	SQL等价物
mysql、postgis、spaceialite	`ST_IsValid(poly)`
甲骨文公司	`SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(poly, 0.05) = 'TRUE'`

`overlaps`¶

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

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

后端	SQL等价物
PostGIS	`ST_Overlaps(poly, geom)`
甲骨文公司	`SDO_OVERLAPS(poly, geom)`
玛丽亚德	`ST_Overlaps(poly, geom)`
MySQL	`ST_Overlaps(poly, geom)`
SpatiaLite	`Overlaps(poly, geom)`

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

甲骨文公司¶

这里的关系模式由九个关系字符串中的至少一个组成： TOUCH ， OVERLAPBDYDISJOINT ， OVERLAPBDYINTERSECT ， EQUAL ， INSIDE ， COVEREDBY ， CONTAINS ， COVERS ， ON 和 ANYINTERACT . 多个字符串可以与逻辑布尔运算符组合，例如， '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等价物
PostGIS	`ST_Touches(poly, geom)`
玛丽亚德	`ST_Touches(poly, geom)`
MySQL	`ST_Touches(poly, geom)`
甲骨文公司	`SDO_TOUCH(poly, geom)`
SpatiaLite	`Touches(poly, geom)`

`within`¶

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

测试几何图形字段是否在查找几何图形的空间内。

例子：：

Zipcode.objects.filter(poly__within=geom)

后端	SQL等价物
PostGIS	`ST_Within(poly, geom)`
玛丽亚德	`ST_Within(poly, geom)`
MySQL	`ST_Within(poly, geom)`
甲骨文公司	`SDO_INSIDE(poly, geom)`
SpatiaLite	`Within(poly, geom)`

`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（本机）

有关执行距离查询的概述，请参阅 distance queries introduction .

距离查找采用以下形式：

<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 对象，或 query expression ）要将带区索引传递给查找，请使用三元组，其中第二个条目是带区索引。

每次远程查找时，除了 dwithin ，可选元素， 'spheroid' ，可以包括在带有大地坐标系的场上使用更精确的球体距离计算函数。

在PostgreSQL上， 'spheroid' option uses ST_DistanceSpheroid 而不是 ST_DistanceSphere . 更简单 ST_Distance 函数用于投影坐标系。对于基于球体的查找，栅格转换为几何图形。

`distance_gt`¶

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

例子：：

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

后端	SQL等价物
PostGIS	`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等价物
PostGIS	`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等价物
PostGIS	`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等价物
PostGIS	`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等价物
PostGIS	`ST_DWithin(poly, geom, 5)`
甲骨文公司	`SDO_WITHIN_DISTANCE(poly, geom, 5)`
SpatiaLite	`PtDistWithin(poly, geom, 5)`

聚合函数¶

Django提供了一些特定于GIS的聚合函数。有关如何使用这些聚合函数的详细信息，请参阅 the topic guide on aggregation .

关键字参数	描述
`tolerance`	此关键字仅用于Oracle。它用于 `SDOAGGRTYPE` 程序； `Oracle documentation`_ _有更多详细信息。

示例：

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

`Collect`¶

class Collect(geo_field, filter=None)[源代码]¶

可用性 ： PostGIS SpatiaLite

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

Changed in Django 5.0:

支持使用 filter 添加了参数。

`Extent`¶

class Extent(geo_field, filter=None)[源代码]¶

可用性 ： PostGIS ，甲骨文，太空石

返回所有 geo_field 在 QuerySet 作为一个四元组，由左下坐标和右上坐标组成。

示例：

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

Changed in Django 5.0:

支持使用 filter 添加了参数。

`Extent3D`¶

class Extent3D(geo_field, filter=None)[源代码]¶

可用性 ： PostGIS

返回所有对象的3D范围 geo_field 在 QuerySet 作为一个6元组，包括左下坐标和右上坐标(每个坐标都有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)

Changed in Django 5.0:

支持使用 filter 添加了参数。

`MakeLine`¶

class MakeLine(geo_field, filter=None)[源代码]¶

可用性 ： PostGIS SpatiaLite

返回A LineString 根据点域几何构造 QuerySet . 当前，对查询集进行排序没有任何效果。

示例：

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

Changed in Django 5.0:

支持使用 filter 添加了参数。

`Union`¶

class Union(geo_field, filter=None)[源代码]¶

可用性 ： PostGIS ，甲骨文，太空石

此方法返回 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.

Changed in Django 5.0:

支持使用 filter 添加了参数。

脚注

« previous | up | next »

Django 5.1.dev 文档

GIS查询集API参考¶

空间查找¶

用粗锉查找¶

bbcontains¶

bboverlaps¶

contained¶

contains¶

contains_properly¶

coveredby¶

covers¶

crosses¶

disjoint¶

equals¶

exact, same_as¶

intersects¶

isempty¶

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¶

Last update:

`bbcontains`¶

`bboverlaps`¶

`contained`¶

`contains`¶

`contains_properly`¶

`coveredby`¶

`covers`¶

`crosses`¶

`disjoint`¶

`equals`¶

`exact`, `same_as`¶

`intersects`¶

`isempty`¶

`isvalid`¶

`overlaps`¶

`relate`¶

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