GIS QuerySet APIリファレンス—Djangoドキュメント

提供:Dev Guides
< DjangoDjango/docs/3.2.x/ref/contrib/gis/geoquerysets
移動先:案内検索

GIS QuerySetAPIリファレンス

空間ルックアップ

このセクションの空間ルックアップは、 GeometryField および RasterField で使用できます。

概要については、空間ルックアップの概要を参照してください。 特定の空間バックエンドと互換性のあるルックアップの概要については、空間ルックアップ互換性テーブルを参照してください。

ラスターを使用したルックアップ

以下のリファレンスのすべての例は、ジオメトリフィールドと入力について示されていますが、ルックアップは両側のラスターで同じように使用できます。 ルックアップがラスター入力をサポートしていない場合は常に、 ST_Polygon 関数を使用して、必要に応じて入力がジオメトリに自動的に変換されます。 ラスタールックアップの概要も参照してください。

ルックアップで使用されるデータベース演算子は、次の3つのカテゴリに分類できます。

  • ネイティブラスターサポート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)
オラクル 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)
オラクル 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、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)
オラクル 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)
オラクル SDO_EQUAL(poly, geom)
MariaDB 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)
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)
オラクル SDO_OVERLAPBDYINTERSECT(poly, geom)
MariaDB ST_Intersects(poly, geom)
MySQL ST_Intersects(poly, geom)
SpatiaLite Intersects(poly, geom)


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と同等
PostGIS ST_Overlaps(poly, geom)
オラクル 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

これらの空間バックエンドでは、交差パターンは9文字で構成される文字列であり、ジオメトリフィールドの内部、境界、外部とルックアップジオメトリの間の交差を定義します。 交差パターンマトリックスは、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とMariaDBSQLの同等物:

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サポートが追加されました。


オラクル

ここで、関係パターンは、TOUCHOVERLAPBDYDISJOINTOVERLAPBDYINTERSECTEQUALINSIDEの9つの関係文字列の少なくとも1つで構成されます。 、COVEREDBYCONTAINSCOVERSON、およびANYINTERACT'inside+touch'のように、複数の文字列を論理ブール演算子ORと組み合わせることができます。 2 リレーション文字列では大文字と小文字は区別されません。

例:

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

同等のOracleSQL:

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)
オラクル 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)
オラクル SDO_INSIDE(poly, geom)
SpatiaLite Within(poly, geom)


left

可用性PostGIS 、PGRaster(変換)

ジオメトリフィールドのバウンディングボックスがルックアップジオメトリのバウンディングボックスの左側にあるかどうかをテストします。

例:

Zipcode.objects.filter(poly__left=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'])

距離ルックアップに渡される値はタプルです。 最初の2つの値は必須であり、距離を計算するためのジオメトリと距離の値(フィールド単位の数値、 Distance オブジェクト、またはクエリ式のいずれか)です。 )。 バンドインデックスをルックアップに渡すには、2番目のエントリがバンドインデックスである3タプルを使用します。

:lookup: `dwithin` を除くすべての距離ルックアップに、オプションの要素'spheroid'を含めて、測地座標系のフィールドでより正確な回転楕円体距離計算関数を使用できます。

PostgreSQLでは、'spheroid'オプションは ST_DistanceSphere の代わりに ST_DistanceSpheroid を使用します。 より単純な 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
オラクル 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
オラクル 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
オラクル 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
オラクル 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固有の集計関数を提供します。 これらの集計関数の使用方法の詳細については、集計に関するトピックガイドを参照してください。

キーワード引数 説明
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の範囲を、左下の座標と右上の座標で構成される4つのタプルとして返します。

例:

>>> 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座標)で構成される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)

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.
312
このルーチンの説明については、Martin Davis(PostGIS開発者)による Quirks of the“ Contains” Spatial Predicate をお読みください。