GIS QuerySet API リファレンス¶
空間のルックアップ (Spatial Lookup)¶
このセクションの空間ルックアップは GeometryField
と RasterField
用です。
導入については、 空間ルックアップの概要 を参照してください。特定の空間バックエンドと互換性のあるルックアップの概要については、 空間ルックアップの互換表 を参照してください。
ラスターのルックアップ¶
以下のリファレンスにあるすべての例は地理情報フィールドおよび入力に対して提供されていますが、ルックアップはラスタの両側で同じように使用できます。ルックアップがラスター入力をサポートしていない場合、入力は ST_Polygon 関数を使用して必要に応じて自動的にジオメトリに変換されます。 ラスタルックアップの概要 も参照してください。
ルックアップで使用されるデータベース演算子は、以下の 3 つのカテゴリに分類できます:
ネイティブラスターサポート (
N
): この演算子は、参照先としてラスターをネイティブに受け入れ、ラスター入力をジオメトリ入力と混在させることができます。双方向ラスターサポート
B
: このオペレータは、ルックアップの両側がラスター入力を受け取る場合のみ、ラスターをサポートします。異なるルックアップの場合は、ラスターデータは自動的にジオメトリに変換されます。ジオメトリ変換サポート
C
。ルックアップはネイティブのラスターをサポートしていないため、すべてのラスターデータは自動的にジオメトリに変換されます。
以下の例は、さまざまなタイプのラスターサポートにおけるルックアップに相当する SQL を示しています。同じパターンがすべての空間ルックアップに適用されます。
ケース |
ルックアップ |
等価なSQL |
---|---|---|
N, B |
|
|
N, B |
|
|
B, C |
|
|
B, C |
|
|
B, C |
|
|
B, C |
|
|
C |
|
|
C |
|
|
C |
|
|
C |
|
|
ラスターを使った空間ルックアップは、PostGISバックエンド (この節ではPGRasterと表記) のみでサポートされています。
bbcontains
¶
利用可能なDB: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Native)
ジオメトリまたはラスタフィールドのバウンディングボックスが、ルックアップジオメトリのバウンディングボックスを完全に含むかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__bbcontains=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
bboverlaps
¶
利用可能なDB: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Native)
ジオメトリフィールドのバウンディングボックスが、ルックアップジオメトリのバウンディングボックスと重なるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__bboverlaps=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
contained
¶
利用可能なDB: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Native)
ジオメトリフィールドのバウンディングボックスがルックアップジオメトリのバウンディングボックスに完全に含まれるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__contained=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
contains
¶
利用可能なDB: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
ジオメトリフィールドにルックアップ ジオメトリが含まれているかどうかを調べます。
実装例:
Zipcode.objects.filter(poly__contains=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
contains_properly
¶
利用可能なDB: PostGIS, PGRaster (Bilateral)
ルックアップ ジオメトリがジオメトリ フィールドの内部と交差し、境界 (または外部) と交差しない場合に true を返します。
実装例:
Zipcode.objects.filter(poly__contains_properly=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
coveredby
¶
利用可能なDB: PostGIS, Oracle, PGRaster (Bilateral), SpatiaLite
ジオメトリフィールドのどのポイントもルックアップジオメトリの外側にないかどうかをテストします。 [3]
実装例:
Zipcode.objects.filter(poly__coveredby=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
Oracle |
|
SpatiaLite |
|
covers
¶
利用可能なDB: PostGIS, Oracle, PGRaster (Bilateral), SpatiaLite
ルックアップされたジオメトリ内のどのポイントも、ジオメトリフィールドの外にないかどうかテストします。 [3]
実装例:
Zipcode.objects.filter(poly__covers=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
Oracle |
|
SpatiaLite |
|
crosses
¶
利用可能なDB: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Conversion)
ジオメトリフィールドがルックアップジオメトリと空間的に交差しているかをテストします。
実装例:
Zipcode.objects.filter(poly__crosses=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
disjoint
¶
利用可能なDB: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
ジオメトリフィールドがルックアップジオメトリから空間的に分離しているかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__disjoint=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
equals
¶
利用可能なDB: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Conversion)
ジオメトリフィールドがルックアップジオメトリと空間的に等しいかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__equals=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
exact
, same_as
¶
利用可能なDB: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
ジオメトリフィールドがルックアップジオメトリと "等しい" かどうかをテストします。Oracle、MySQL、SpatiaLite では空間的な等しさをテストし、PostGIS ではバウンディングボックスの等しさをテストします。
実装例:
Zipcode.objects.filter(poly=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
intersects
¶
利用可能なDB: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
ジオメトリフィールドがルックアップジオメトリと空間的に交差しているかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__intersects=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
isempty
¶
利用可能なDB: PostGIS
ジオメトリが空かどうかをテストします。
実装例:
Zipcode.objects.filter(poly__isempty=True)
isvalid
¶
利用可能なDB: MySQL, PostGIS, Oracle, SpatiaLite
ジオメトリが有効かどうかをテストします。
実装例:
Zipcode.objects.filter(poly__isvalid=True)
バックエンド |
等価なSQL |
---|---|
MySQL, PostGIS, SpatiaLite |
|
Oracle |
|
overlaps
¶
利用可能なDB: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
ジオメトリフィールドがルックアップ ジオメトリと空間的に重なっているかどうかをテストします。
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
Oracle |
|
MariaDB |
|
MySQL |
|
SpatiaLite |
|
relate
¶
利用可能なDB: PostGIS, MariaDB, Oracle, SpatiaLite, PGRaster (Conversion)
ジオメトリフィールドが指定されたパターンの値によって空間的に関連しているかをテストします。このルックアップには (geom, pattern)
というタプルパラメータが必要であり、pattern
の形式は空間バックエンドによって異なります。
MariaDB, PostGIS, SpatiaLite¶
これらの空間バックエンドでは、交差パターンは9文字からなる文字列で、ジオメトリフィールドとルックアップジオメトリの内部、境界、外部の交差を定義します。交差パターン行列では、次の文字のみを使用できます: 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¶
ここで、リレーションパターンは9つのリレーション文字列のうち少なくとも1つで構成されます: TOUCH
, OVERLAPBDYDISJOINT
, OVERLAPBDYINTERSECT
, EQUAL
, INSIDE
, COVEREDBY
, CONTAINS
, COVERS
, ON
, ANYINTERACT
。複数の文字列を論理論理演算子 OR で結合することもできます。 [2] リレーション文字列は大文字小文字を区別しません。
実装例:
Zipcode.objects.filter(poly__relate=(geom, "anyinteract"))
Oracle では下記の SQL と同等です:
SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')
touches
¶
利用可能なDB: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite
ジオメトリ フィールドがルックアップ ジオメトリに空間的に接しているかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__touches=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
Oracle |
|
SpatiaLite |
|
within
¶
利用可能なDB: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Bilateral)
ジオメトリフィールドが空間的にルックアップジオメトリ内にあるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__within=geom)
バックエンド |
等価なSQL |
---|---|
PostGIS |
|
MariaDB |
|
MySQL |
|
Oracle |
|
SpatiaLite |
|
left
¶
利用可能なDB: PostGIS, PGRaster (Conversion)
ジオメトリフィールドのバウンディングボックスが、ルックアップ ジオメトリのバウンディングボックスよりも厳密に左側にあるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__left=geom)
PostGIS では下記の SQL と同等です:
SELECT ... WHERE poly << geom
right
¶
利用可能なDB: PostGIS, PGRaster (Conversion)
ジオメトリフィールドのバウンディングボックスが、ルックアップ ジオメトリのバウンディングボックスの厳密に右側にあるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__right=geom)
PostGIS では下記の SQL と同等です:
SELECT ... WHERE poly >> geom
overlaps_left
¶
利用可能なDB: PostGIS, PGRaster (Bilateral)
ジオメトリフィールドのバウンディングボックスが、ルックアップ ジオメトリのバウンディングボックスと重なるか、または左にあるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__overlaps_left=geom)
PostGIS では下記の SQL と同等です:
SELECT ... WHERE poly &< geom
overlaps_right
¶
利用可能なDB: PostGIS, PGRaster (Bilateral)
ジオメトリフィールドのバウンディングボックスが、ルックアップ ジオメトリのバウンディングボックスと重なっているか、または右側にあるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__overlaps_right=geom)
PostGIS では下記の SQL と同等です:
SELECT ... WHERE poly &> geom
overlaps_above
¶
利用可能なDB: PostGIS, PGRaster (Conversion)
ジオメトリフィールドのバウンディングボックスがルックアップジオメトリのバウンディングボックスと重なっているか、または上にあるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__overlaps_above=geom)
PostGIS では下記の SQL と同等です:
SELECT ... WHERE poly |&> geom
overlaps_below
¶
利用可能なDB: PostGIS, PGRaster (Conversion)
ジオメトリフィールドのバウンディングボックスがルックアップジオメトリのバウンディングボックスと重なっているか、または下にあるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__overlaps_below=geom)
PostGIS では下記の SQL と同等です:
SELECT ... WHERE poly &<| geom
strictly_above
¶
利用可能なDB: PostGIS, PGRaster (Conversion)
ジオメトリフィールドのバウンディングボックスが、ルックアップジオメトリのバウンディングボックスの厳密に上にあるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__strictly_above=geom)
PostGIS では下記の SQL と同等です:
SELECT ... WHERE poly |>> geom
strictly_below
¶
利用可能なDB: PostGIS, PGRaster (Conversion)
ジオメトリフィールドのバウンディングボックスが、ルックアップジオメトリのバウンディングボックスの厳密に下にあるかどうかをテストします。
実装例:
Zipcode.objects.filter(poly__strictly_below=geom)
PostGIS では下記の SQL と同等です:
SELECT ... WHERE poly <<| geom
距離ルックアップ¶
利用可能なDB: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Native)
距離クエリの概要については 距離クエリの概要 を参照してください。
距離ルックアップは次の形式を取ります:
<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"])
距離ルックアップに渡される値はタプルであり、最初の2つの値は必須で、それぞれ、距離の計算対象のジオメトリと距離値 (フィールドの単位での数値、 Distance
オブジェクト、または クエリ式) です。ルックアップにバンドインデックスを渡すには、2番目のエントリがバンドインデックスである3値タプルを使用します。
dwithin
を除くすべての距離ルックアップには、オプションの要素として 'spheroid'
を含めることができます。これにより、測地座標系を持つフィールドにおいてより精度の高い回転楕円体距離計算関数を使用できます。
PostgreSQLでは、 'spheroid'
オプションは ST_DistanceSphere の代わりに ST_DistanceSpheroid を使用します。投影座標系では、より単純な 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
¶
Availability: PostGIS, MySQL, SpatiaLite
ジオメトリ列から GEOMETRYCOLLECTION
または MULTI
ジオメトリオブジェクトを返します。これは Union
集計の簡略版に似ていますが、ジオメトリをコレクションまたはマルチオブジェクトにまとめ、境界の解消を気にしないため、ユニオンを実行するよりも数桁高速です。
filter
引数のサポートが追加されました。
MySQL 8.0.24+ support was added.
Extent
¶
利用可能なDB: 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
¶
利用可能なDB: 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
¶
利用可能なDB: 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
¶
利用可能なDB: 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
引数のサポートが追加されました。
脚注