GIS QuerySet API 參考¶
空間查詢¶
本節中的空間查詢適用於 GeometryField
和 RasterField
。
如需簡介,請參閱空間查詢簡介。如需了解特定空間後端支援哪些查詢,請參考空間查詢相容性表格。
使用柵格的查詢¶
以下參考中的所有範例都針對幾何欄位和輸入,但查詢可以使用相同的方式,在兩側使用柵格。每當查詢不支援柵格輸入時,輸入會在使用ST_Polygon函數時,在必要時自動轉換為幾何圖形。另請參閱柵格查詢簡介。
查詢所使用的資料庫運算子可以分為三種類別
原生柵格支援
N
:運算子在查詢的兩側原生接受柵格,並且柵格輸入可以與幾何輸入混合使用。雙邊柵格支援
B
:運算子僅在查詢的兩側都接收柵格輸入時才支援柵格。柵格資料會自動轉換為混合查詢的幾何圖形。幾何轉換支援
C
。查詢不具有原生柵格支援,所有柵格資料都會自動轉換為幾何圖形。
以下範例顯示了不同類型的柵格支援中查詢的 SQL 對應項。相同的模式適用於所有空間查詢。
情況 |
查詢 |
SQL 對應項 |
---|---|---|
N, B |
|
|
N, B |
|
|
B, C |
|
|
B, C |
|
|
B, C |
|
|
B, C |
|
|
C |
|
|
C |
|
|
C |
|
|
C |
|
|
空間柵格查詢僅適用於 PostGIS 後端(在本節中稱為 PGRaster)。
bbcontains
¶
可用性:PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster (原生)
測試幾何或柵格欄位的邊界框是否完全包含查詢幾何的邊界框。
範例
Zipcode.objects.filter(poly__bbcontains=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
bboverlaps
¶
可用性:PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster (原生)
測試幾何欄位的邊界框是否與查詢幾何的邊界框重疊。
範例
Zipcode.objects.filter(poly__bboverlaps=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
contained
¶
可用性:PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster (原生)
測試幾何欄位的邊界框是否完全包含在查詢幾何的邊界框內。
範例
Zipcode.objects.filter(poly__contained=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
contains
¶
可用性:PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster (雙邊)
測試幾何欄位是否在空間上包含查詢幾何。
範例
Zipcode.objects.filter(poly__contains=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
contains_properly
¶
可用性:PostGIS、PGRaster (雙邊)
如果查詢幾何與幾何欄位的內部相交,但不與邊界(或外部)相交,則傳回 true。
範例
Zipcode.objects.filter(poly__contains_properly=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
coveredby
¶
可用性:PostGIS、Oracle、PGRaster (雙邊)、SpatiaLite
測試幾何欄位中是否沒有任何點在查詢幾何之外。[3]
範例
Zipcode.objects.filter(poly__coveredby=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
Oracle |
|
SpatiaLite |
|
covers
¶
可用性:PostGIS、Oracle、PGRaster (雙邊)、SpatiaLite
測試查詢幾何中是否沒有任何點在幾何欄位之外。[3]
範例
Zipcode.objects.filter(poly__covers=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
Oracle |
|
SpatiaLite |
|
crosses
¶
可用性:PostGIS、MariaDB、MySQL、SpatiaLite、PGRaster (轉換)
測試幾何欄位是否在空間上與查詢幾何相交。
範例
Zipcode.objects.filter(poly__crosses=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
disjoint
¶
可用性:PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster (雙邊)
測試幾何欄位是否在空間上與查詢幾何不相交。
範例
Zipcode.objects.filter(poly__disjoint=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
equals
¶
可用性:PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster (轉換)
測試幾何欄位是否在空間上等於查詢幾何。
範例
Zipcode.objects.filter(poly__equals=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
exact
、same_as
¶
可用性:PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster (雙邊)
測試幾何欄位是否「等於」查詢幾何。在 Oracle、MySQL 和 SpatiaLite 上,它測試空間相等性,而在 PostGIS 上,它測試邊界框的相等性。
範例
Zipcode.objects.filter(poly=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
intersects
¶
可用性:PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster (雙邊)
測試幾何欄位是否在空間上與查詢幾何相交。
範例
Zipcode.objects.filter(poly__intersects=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
isempty
¶
可用性:PostGIS
測試幾何是否為空。
範例
Zipcode.objects.filter(poly__isempty=True)
isvalid
¶
可用性:MySQL、PostGIS、Oracle、SpatiaLite
測試幾何是否有效。
範例
Zipcode.objects.filter(poly__isvalid=True)
後端 |
SQL 對應項 |
---|---|
MySQL、PostGIS、SpatiaLite |
|
Oracle |
|
overlaps
¶
可用性:PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster (雙邊)
測試幾何欄位是否在空間上與查詢幾何重疊。
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
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*')
Oracle¶
此處的關係模式包含至少一個以下九個關係字串: 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 對應項 |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
Oracle |
|
SpatiaLite |
|
within
¶
可用性: PostGIS、Oracle、MariaDB、MySQL、SpatiaLite、PGRaster (雙向)
測試幾何欄位是否在空間上位於查詢幾何內。
範例
Zipcode.objects.filter(poly__within=geom)
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
Oracle |
|
SpatiaLite |
|
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 |
|
MariaDB |
|
MySQL |
|
Oracle |
|
SpatiaLite |
|
distance_gte
¶
傳回模型,其中幾何欄位與查詢幾何之間的距離大於或等於給定的距離值。
範例
Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
Oracle |
|
SpatiaLite |
|
distance_lt
¶
傳回模型,其中幾何欄位與查詢幾何之間的距離小於給定的距離值。
範例
Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
Oracle |
|
SpatiaLite |
|
distance_lte
¶
傳回模型,其中幾何欄位與查詢幾何之間的距離小於或等於給定的距離值。
範例
Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
Oracle |
|
SpatiaLite |
|
dwithin
¶
傳回模型,其中幾何欄位與查詢幾何之間的距離在彼此的給定距離內。請注意,如果目標幾何圖形位於投影系統中,您只能提供 Distance
物件。對於地理幾何圖形,您應使用幾何欄位的單位 (例如 WGS84
的度數)。
範例
Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))
後端 |
SQL 對應項 |
---|---|
PostGIS |
|
Oracle |
|
SpatiaLite |
|
聚合函數¶
Django 提供一些特定於 GIS 的聚合函數。如需使用這些聚合函數的詳細資訊,請參閱關於聚合的主題指南。
關鍵字引數 |
描述 |
---|---|
|
此關鍵字僅適用於 Oracle。它用於 |
範例
>>> from django.contrib.gis.db.models import Extent, Union
>>> WorldBorder.objects.aggregate(Extent("mpoly"), Union("mpoly"))
Collect
¶
可用性: PostGIS, MySQL, SpatiaLite
從幾何欄位回傳一個 GEOMETRYCOLLECTION
或一個 MULTI
幾何物件。這類似於簡化版本的 Union
聚合函數,但由於它將幾何圖形彙整到集合或多重物件中,而不在意邊界的消解,因此速度可能比執行聯集快幾個數量級。
新增了使用 filter
引數的支援。
新增了對 MySQL 8.0.24+ 的支援。
Extent
¶
可用性: 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)
新增了使用 filter
引數的支援。
Extent3D
¶
可用性: 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)
新增了使用 filter
引數的支援。
MakeLine
¶
可用性: 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)
新增了使用 filter
引數的支援。
Union
¶
可用性: 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.
新增了使用 filter
引數的支援。
註腳