GIS QuerySet API 參考

空間查詢

本節中的空間查詢適用於 GeometryFieldRasterField

如需簡介,請參閱空間查詢簡介。如需了解特定空間後端支援哪些查詢,請參考空間查詢相容性表格

使用柵格的查詢

以下參考中的所有範例都針對幾何欄位和輸入,但查詢可以使用相同的方式,在兩側使用柵格。每當查詢不支援柵格輸入時,輸入會在使用ST_Polygon函數時,在必要時自動轉換為幾何圖形。另請參閱柵格查詢簡介

查詢所使用的資料庫運算子可以分為三種類別

  • 原生柵格支援 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, C

rast__contains=geom

ST_Contains(ST_Polygon(rast), geom)

B, C

rast__1__contains=geom

ST_Contains(ST_Polygon(rast, 1), geom)

B, C

poly__contains=rst

ST_Contains(poly, ST_Polygon(rst))

B, C

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 對應項

PostGIS

poly ~ geom

MariaDB

MBRContains(poly, geom)

MySQL

MBRContains(poly, geom)

SpatiaLite

MbrContains(poly, geom)

bboverlaps

可用性PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster (原生)

測試幾何欄位的邊界框是否與查詢幾何的邊界框重疊。

範例

Zipcode.objects.filter(poly__bboverlaps=geom)

後端

SQL 對應項

PostGIS

poly && geom

MariaDB

MBROverlaps(poly, geom)

MySQL

MBROverlaps(poly, geom)

SpatiaLite

MbrOverlaps(poly, geom)

contained

可用性PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster (原生)

測試幾何欄位的邊界框是否完全包含在查詢幾何的邊界框內。

範例

Zipcode.objects.filter(poly__contained=geom)

後端

SQL 對應項

PostGIS

poly @ geom

MariaDB

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)

Oracle

SDO_CONTAINS(poly, geom)

MariaDB

ST_Contains(poly, geom)

MySQL

ST_Contains(poly, geom)

SpatiaLite

Contains(poly, geom)

contains_properly

可用性PostGIS、PGRaster (雙邊)

如果查詢幾何與幾何欄位的內部相交,但不與邊界(或外部)相交,則傳回 true。

範例

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)

Oracle

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)

Oracle

SDO_COVERS(poly, geom)

SpatiaLite

Covers(poly, geom)

crosses

可用性PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster (轉換)

測試幾何欄位是否在空間上與查詢幾何相交。

範例

Zipcode.objects.filter(poly__crosses=geom)

後端

SQL 對應項

PostGIS

ST_Crosses(poly, geom)

MariaDB

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)

Oracle

SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)

MariaDB

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)

Oracle

SDO_EQUAL(poly, geom)

MariaDB

ST_Equals(poly, geom)

MySQL

ST_Equals(poly, geom)

SpatiaLite

Equals(poly, geom)

exactsame_as

可用性PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster (雙邊)

測試幾何欄位是否「等於」查詢幾何。在 Oracle、MySQL 和 SpatiaLite 上,它測試空間相等性,而在 PostGIS 上,它測試邊界框的相等性。

範例

Zipcode.objects.filter(poly=geom)

後端

SQL 對應項

PostGIS

poly ~= geom

Oracle

SDO_EQUAL(poly, geom)

MariaDB

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)

Oracle

SDO_OVERLAPBDYINTERSECT(poly, geom)

MariaDB

ST_Intersects(poly, geom)

MySQL

ST_Intersects(poly, geom)

SpatiaLite

Intersects(poly, geom)

isempty

可用性PostGIS

測試幾何是否為空。

範例

Zipcode.objects.filter(poly__isempty=True)

isvalid

可用性:MySQL、PostGIS、Oracle、SpatiaLite

測試幾何是否有效。

範例

Zipcode.objects.filter(poly__isvalid=True)

後端

SQL 對應項

MySQL、PostGIS、SpatiaLite

ST_IsValid(poly)

Oracle

SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(poly, 0.05) = 'TRUE'

overlaps

可用性PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster (雙邊)

測試幾何欄位是否在空間上與查詢幾何重疊。

後端

SQL 對應項

PostGIS

ST_Overlaps(poly, geom)

Oracle

SDO_OVERLAPS(poly, geom)

MariaDB

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

在這些空間後端上,交集模式是一個包含九個字元的字串,定義幾何欄位與查詢幾何的內部、邊界和外部之間的交集。交集模式矩陣只能使用以下字元: 12TF*。此查詢類型允許使用者「微調」符合 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*')

Oracle

此處的關係模式包含至少一個以下九個關係字串: TOUCHOVERLAPBDYDISJOINTOVERLAPBDYINTERSECTEQUALINSIDECOVEREDBYCONTAINSCOVERSONANYINTERACT。可以使用邏輯布林運算子 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 對應項

PostGIS

ST_Touches(poly, geom)

MariaDB

ST_Touches(poly, geom)

MySQL

ST_Touches(poly, geom)

Oracle

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)

MariaDB

ST_Within(poly, geom)

MySQL

ST_Within(poly, geom)

Oracle

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 (原生)

如需執行距離查詢的概述,請參閱距離查詢介紹

距離查詢採用以下形式

<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 元組,其中第二個項目是頻帶索引。

在除了dwithin之外的每個距離查詢中,都可以包含一個可選元素'spheroid',以在具有大地坐標系的欄位上使用更精確的球面距離計算函數。

在 PostgreSQL 上,'spheroid' 選項使用 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

MariaDB

ST_Distance(poly, geom) > 5

MySQL

ST_Distance(poly, geom) > 5

Oracle

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

MariaDB

ST_Distance(poly, geom) >= 5

MySQL

ST_Distance(poly, geom) >= 5

Oracle

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

MariaDB

ST_Distance(poly, geom) < 5

MySQL

ST_Distance(poly, geom) < 5

Oracle

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

MariaDB

ST_Distance(poly, geom) <= 5

MySQL

ST_Distance(poly, geom) <= 5

Oracle

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)

Oracle

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, filter=None)[原始碼]

可用性: PostGIS, MySQL, SpatiaLite

從幾何欄位回傳一個 GEOMETRYCOLLECTION 或一個 MULTI 幾何物件。這類似於簡化版本的 Union 聚合函數,但由於它將幾何圖形彙整到集合或多重物件中,而不在意邊界的消解,因此速度可能比執行聯集快幾個數量級。

在 Django 5.0 中變更

新增了使用 filter 引數的支援。

在 Django 5.1 中變更

新增了對 MySQL 8.0.24+ 的支援。

Extent

class Extent(geo_field, filter=None)[原始碼]

可用性: PostGIS, Oracle, SpatiaLite

QuerySet 中所有 geo_field 的範圍回傳為一個包含左下角座標和右上角座標的 4 元組。

範例

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

新增了使用 filter 引數的支援。

Extent3D

class Extent3D(geo_field, filter=None)[原始碼]

可用性: PostGIS

QuerySet 中所有 geo_field 的 3D 範圍回傳為一個包含左下角座標和右上角座標(每個座標都有 x、y 和 z 座標)的 6 元組。

範例

>>> 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)
在 Django 5.0 中變更

新增了使用 filter 引數的支援。

MakeLine

class MakeLine(geo_field, filter=None)[原始碼]

可用性: 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)
在 Django 5.0 中變更

新增了使用 filter 引數的支援。

Union

class Union(geo_field, filter=None)[原始碼]

可用性: 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.
在 Django 5.0 中變更

新增了使用 filter 引數的支援。

註腳

返回頂部