Acuan API QuerySet GIS

Pencarian Spasial

Pencarian spasial dalam bagian ini tersedia untuk GeometryField dan RasterField.

Untuk pengenalan, lihat the spatial lookups introduction. Untuk sebuah tinjauan dari apa pencarian cocok dengan backend spasial tertentu, mengacu pada spatial lookup compatibility table.

Pencarian dengan raster

Semua contoh dalam acuan dibawah diberikan untuk bidang-bidang dan masukan geometri, tetapi pencarian dapat menggunakan cara sama dengan raster pada kedua sisi. Kapanpun pencarian tidak mendukung amsukan raster, masukan otomatis dirubah ke geometri dimana dibutuhkan menggunakan fungsi ST_Polygon. Lihat juga introduction to raster lookups.

Penghubung basisdata digunakan oleh pencarian dapat dibagi menjadi tiga kategori:

  • Raster asli mendukung N: penghubung menerima raster secara asli pada kedua sisi dari pencarian, dan masukan raster dapat dicampur dengan masukan geometri.
  • Dukungan raster timbal balik B: penghubung mendukung hanya raster jika kedua sisi dari pencarian menerima masukan raster. Data raster otomatis dirubah menjadi geometri untuk pencarian campuran.
  • Dukungan perubahan geometri C. Pencarian tidak memiliku dukungan raster asli, semua data raster otomatis dirubah ke geometri.

Contoh-contoh dibawah menunjukkan SQL setara untuk pencarian dalam jenis berbeda dari dukungan raster. Pola sama berlaku pada semua pencarian spasial.

Kasus Cari Setara 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))

Pencarian spasial dengan raster hanya didukung untuk backend PostGIS (dinamai sebagai PGRaster dalam bagian ini).

bbcontains

Ketersediaan: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Asli)

Coba jika geometri atau kotak pembatas bidang raster sepenuhnya mengandung pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__bbcontains=geom)
Backend Setara SQL
PostGIS poly ~ geom
MariaDB MBRContains(poly, geom)
MySQL MBRContains(poly, geom)
SpatiaLite MbrContains(poly, geom)

bboverlaps

Ketersediaan: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Asli)

Coba jika kotak pembatas bidang geometri tumpang tindih pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__bboverlaps=geom)
Backend Setara SQL
PostGIS poly && geom
MariaDB MBROverlaps(poly, geom)
MySQL MBROverlaps(poly, geom)
SpatiaLite MbrOverlaps(poly, geom)

contained

Ketersediaan: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Asli)

Coba jika kotak pembatas bidang geometri sepenuhnya terkandung oleh pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__contained=geom)
Backend Setara SQL
PostGIS poly @ geom
MariaDB MBRWithin(poly, geom)
MySQL MBRWithin(poly, geom)
SpatiaLite MbrWithin(poly, geom)

contains

Ketersediaan: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Timbal balik)

Dicoba jika bidang geometri secara spasial mengandung pencarian geometri.

Contoh:

Zipcode.objects.filter(poly__contains=geom)
Backend Setara 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

Tersedia: PostGIS, PGRaster (Timbal balik)

Mengembalikan true jika pencarian geometri memotong interior dari bidang geometri, tetapi bukan batas (atau eksterior).

Contoh:

Zipcode.objects.filter(poly__contains_properly=geom)
Backend Setara SQL
PostGIS ST_ContainsProperly(poly, geom)

coveredby

Tersedia: PostGIS, Oracle, PGRaster (Bilateral), SpatiaLite

Uji jika tidak ada titik dalam bidang geometri diluar pencarian geometri. [3]

Contoh:

Zipcode.objects.filter(poly__coveredby=geom)
Backend Setara SQL
PostGIS ST_CoveredBy(poly, geom)
Oracle SDO_COVEREDBY(poly, geom)
SpatiaLite CoveredBy(poly, geom)

covers

Tersedia: PostGIS, Oracle, PGRaster (Bilateral), SpatiaLite

Uji jika tidak ada titik dalam pencarian geometri diluar bidang geometri. [3]

Contoh:

Zipcode.objects.filter(poly__covers=geom)
Backend Setara SQL
PostGIS ST_Covers(poly, geom)
Oracle SDO_COVERS(poly, geom)
SpatiaLite Covers(poly, geom)

crosses

Ketersediaan: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Perubahan)

Uji jika bidang geometri secara spasial menyebrangi pencarian geometri.

Contoh:

Zipcode.objects.filter(poly__crosses=geom)
Backend Setara SQL
PostGIS ST_Crosses(poly, geom)
MariaDB ST_Crosses(poly, geom)
MySQL ST_Crosses(poly, geom)
SpatiaLite Crosses(poly, geom)

disjoint

Ketersediaan: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Timbal balik)

Coba jika bidang geometri secara spasial diuraikan dari pencarian geometri.

Contoh:

Zipcode.objects.filter(poly__disjoint=geom)
Backend Setara 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

Ketersediaan: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Perubahan)

Coba jika bidang geometri secara spasial setara pada pencarian geometri.

Contoh:

Zipcode.objects.filter(poly__equals=geom)
Backend Setara 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)

exact, same_as

Ketersediaan: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Timbal balik)

Tests if the geometry field is "equal" to the lookup geometry. On Oracle, MySQL, and SpatiaLite, it tests spatial equality, while on PostGIS it tests equality of bounding boxes.

Contoh:

Zipcode.objects.filter(poly=geom)
Backend Setara SQL
PostGIS poly ~= geom
Oracle SDO_EQUAL(poly, geom)
MariaDB ST_Equals(poly, geom)
MySQL ST_Equals(poly, geom)
SpatiaLite Equals(poly, geom)

intersects

Ketersediaan: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Timbal balik)

Coba jika bidang geometri secara spasial memotong pencarian geometri.

Contoh:

Zipcode.objects.filter(poly__intersects=geom)
Backend Setara 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

New in Django 4.2.

Availability: PostGIS

Tests if the geometry is empty.

Contoh:

Zipcode.objects.filter(poly__isempty=True)

isvalid

Availability: MySQL, PostGIS, Oracle, SpatiaLite

Coba jika geometri adalah sah.

Contoh:

Zipcode.objects.filter(poly__isvalid=True)
Backend Setara SQL
MySQL, PostGIS, SpatiaLite ST_IsValid(poly)
Oracle SDO_GEOM.VALIDATE_GEOMETRY_WITH_CONTEXT(poly, 0.05) = 'TRUE'

overlaps

Ketersediaan: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Timbal balik)

Coba jika bidang geometri spasial tumpang tindih pencarian geometri.

Backend Setara 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

Availability: PostGIS, MariaDB, Oracle, SpatiaLite, PGRaster (Conversion)

Coba jika bidang geometri secara spasial terkait pada pencarian geometri dengan nilai-nilai diberikan dalam pola yang diberikan. Pencarian ini membutuhkan sebuah parameter tuple. (geom, pattern); bentuk dari pattern akan bergantung pada backend spasial:

MariaDB, PostGIS, and SpatiaLite

Pada backend spasial ini pola persimpangan adalah sebuah string terdiri dari sembilan karakter, yang menentukan persimpangan diantara interior, batasan, dan eksterior dari bidang geometri dan pencarian geometri. Matriks pola persimpangan mungkin hanya menggunakan karakter: 1, 2, T, F, atau *. Jenis pencarian ini mengizinkan pengguna untuk "fine tune" sebuah hubungan geometrik khusus sesuai dengan model DE-9IM. [1]

Contoh geometri:

# 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 and MariaDB SQL equivalent:

SELECT ... WHERE ST_Relate(poly, geom, 'T*T***FF*')

SpatiaLite SQL setara:

SELECT ... WHERE Relate(poly, geom, 'T*T***FF*')

Contoh raster:

Zipcode.objects.filter(poly__relate=(rast, 1, "T*T***FF*"))
Zipcode.objects.filter(rast__2__relate=(rast, 1, "T*T***FF*"))

PostGIS SQL setara:

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

Disini hubungan pola adalah terdiri dari setidaknya satu dari sembilan hubungan string: TOUCH, OVERLAPBDYDISJOINT, OVERLAPBDYINTERSECT, EQUAL, INSIDE, COVEREDBY, CONTAINS, COVERS, ON, dan ANYINTERACT. Banyak string mungkin dipadukan dengan penghubung Boolean logis OR, sebagai contoh, 'inside+touch'. [2] Hubungan string adalah kasus-tidak-peka.

Contoh:

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

Oracle SQL setara:

SELECT ... WHERE SDO_RELATE(poly, geom, 'anyinteract')

touches

Ketersediaan: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite

Coba jika bidang geometri secara spasial menyentuh pencarian geometri.

Contoh:

Zipcode.objects.filter(poly__touches=geom)
Backend Setara 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

Ketersediaan: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Timbal balik)

Coba jika bidang geomrtri secara spasial dalam pencarian geometri.

Contoh:

Zipcode.objects.filter(poly__within=geom)
Backend Setara 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

Tersedia: PostGIS, PGRaster (Perubahan)

Coba jika kotak pembatas bidang geometri ketat ke kiri dari pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__left=geom)

PostGIS setara:

SELECT ... WHERE poly << geom

right

Tersedia: PostGIS, PGRaster (Perubahan)

Coba jika kotak pembatas bidang geometri tegas ke kanan dari pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__right=geom)

PostGIS setara:

SELECT ... WHERE poly >> geom

overlaps_left

Tersedia: PostGIS, PGRaster (Timbal balik)

Coba jika kotak pencarian bidang geometri tumpang tindih atau ke kiri dari pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__overlaps_left=geom)

PostGIS setara:

SELECT ... WHERE poly &< geom

overlaps_right

Tersedia: PostGIS, PGRaster (Timbal balik)

Coba jika kotak pencarian bidang geometri tumpang tindih atau ke kanan dari pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__overlaps_right=geom)

PostGIS setara:

SELECT ... WHERE poly &> geom

overlaps_above

Tersedia: PostGIS, PGRaster (Perubahan)

Coba jika kotak pembatas bidang geometri tumpang tindih atau diatas pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__overlaps_above=geom)

PostGIS setara:

SELECT ... WHERE poly |&> geom

overlaps_below

Tersedia: PostGIS, PGRaster (Perubahan)

Coba jika kotak pembatas bidang geometri tumpang tindih atau dibawah pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__overlaps_below=geom)

PostGIS setara:

SELECT ... WHERE poly &<| geom

strictly_above

Tersedia: PostGIS, PGRaster (Perubahan)

Coba jika kotak pembatas bidang geometri ketat diatas pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__strictly_above=geom)

PostGIS setara:

SELECT ... WHERE poly |>> geom

strictly_below

Tersedia: PostGIS, PGRaster (Perubahan)

Coba jika kotak pembatas bidang geometri ketat dibawah pencarian kotak pembatas geometri.

Contoh:

Zipcode.objects.filter(poly__strictly_below=geom)

PostGIS setara:

SELECT ... WHERE poly <<| geom

Pencarian Jarak

Ketersediaan: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Asli)

Untuk sebuah tinjauan pada melakukan permintaan jarak, hrap mengacu pada distance queries introduction.

Distance lookups take the following form:

<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"])

The value passed into a distance lookup is a tuple; the first two values are mandatory, and are the geometry to calculate distances to, and a distance value (either a number in units of the field, a Distance object, or a query expression). To pass a band index to the lookup, use a 3-tuple where the second entry is the band index.

Pada setiap pencarian jarak kecuali dwithin, sebuah unsur pilihan, 'spheroid', mungkin disertakan untuk digunakan lebih akurat fungsi perhitungan jarak bulatan dengan sistem kordinat geodetik.

Pada PostgreSQL, pilihan 'spheroid' menggunakan ST_DistanceSpheroid daripada ST_DistanceSphere. Fungsi ST_Distance paling sederhana digunakan dengan sistem kordinat yang sudah dihitung. Raster dirubah ke geometri untuk pencarian berdasarkan spheroid.

distance_gt

Mengembalikan model-model dimana jarak pada bidang geometri dari geometri pencarian lebih besar dari nilai jarak yang diberikan.

Contoh:

Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))
Backend Setara 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

Mengembalikan model-model dimana jarak pada bidang geometri dari geometri pencarian lebih besar dari atau setara pada nilai jarak diberikan.

Contoh:

Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))
Backend Setara 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

Mengembalikan model-model dimana jarak pada bidang geometri dari geometri pencarian kurang dari nilai jarak yang diberikan.

Contoh:

Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))
Backend Setara 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

Mengembalikan model-model dimana jarak pada bidang geometri dari geometri pencarian kurang dari atau setara pada nilai jarak yang diberikan.

Contoh:

Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))
Backend Setara 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

Mengembalikan model-model dimana jarak pada bidang geometri dari geometri pencarian dalam jarak yang diberikan dari satu lainnya. Catat bahwa anda hanya dapat menyediakan obyek Distance jika geometri tersasar dalam sistem diperhitungkan. Untuk geometri geografis, anda harus menggunakan satuan dari bidang geometri (misalnya tingkatan untuk WGS84) .

Contoh:

Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))
Backend Setara SQL
PostGIS ST_DWithin(poly, geom, 5)
Oracle SDO_WITHIN_DISTANCE(poly, geom, 5)
SpatiaLite PtDistWithin(poly, geom, 5)

Fungsi Kumpulan

Django menyediakan beberapa fungsi pengumpulan khusus-GIS. Untuk rincian pada bagaimana menggunakan fungsi-fungsi pengumpulan ini, lihat the topic guide on aggregation.

Argumen Katakunci Deskripsi
tolerance kata kunci ini adalah hanya untuk Oracle. Itu adalah nilai toleransi digunakan oleh prosedur ``SDOAGGRTYPE`; Oracle documentation mempunyai rincian lebih.

Example:

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

Collect

class Collect(geo_field)

Tersedia: PostGIS, SpatiaLite

Returns a GEOMETRYCOLLECTION or a MULTI geometry object from the geometry column. This is analogous to a simplified version of the Union aggregate, except it can be several orders of magnitude faster than performing a union because it rolls up geometries into a collection or multi object, not caring about dissolving boundaries.

Extent

class Extent(geo_field)

Tersedia: PostGIS, Oracle, SpatiaLite

Mengembalikan tingkatan dari semua geo_field dalam QuerySet sebagai empat-tuple, terdiri dari kordinat kiri bawah dan kordinat kanan atas.

Example:

>>> 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)

Tersedia: PostGIS

Mengembalikan tingkatan 3D dari semua geo_field dalam QuerySet sebagai enam-tuple, terdiri dari kordinat kiri bawah dan kordinat kanan atas (masing-masing dengan kordinat x,y, dan z).

Example:

>>> 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)

Tersedia: PostGIS, SpatiaLite

Mengembalikan LineString dibangun dari geometri bidang titik dalam QuerySet. Saat ini pengurutan queryset tidak mempunyai pengaruh.

Example:

>>> 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)

Tersedia: PostGIS, Oracle, SpatiaLite

Metode ini mengembalikan obyek GEOSGeometry terdiri dari gabungan dari setiap geometri dalam queryset. Harap catat bahwa penggunaan dari Union diolah secara intensif dan mungkin mengambil jumlah signifikan waktu pada queryset besar.

Catatan

Jika waktu perhitungan untuk menggunakan metode ini terlalu mahal, pertimbangkan menggunakan Collect sebagai gantinya.

Example:

>>> 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.

Catatan kaki

[1]See OpenGIS Simple Feature Specification For SQL, at Ch. 2.1.13.2, p. 2-13 (The Dimensionally Extended Nine-Intersection Model).
[2]Lihat SDO_RELATE documentation, dari Panduan Oracle Spatial and Graph Developer.
[3](1, 2) Untuk penjelasan dari rutin ini, baca Quirks of the "Contains" Spatial Predicate oleh Martin Davis (seorang pengembang PostGIS).