Справочник по API GIS QuerySet ¶
Пространственные поиски ¶
Пространственный поиск в этом разделе доступен для GeometryField
и RasterField
.
Для ознакомления см. Введение в пространственные поисковые запросы . Для обзора того, какие поисковые запросы совместимы с конкретным пространственным сервером, обратитесь к таблице совместимости пространственного поиска .
Поиск с растрами ¶
Все примеры в приведенной ниже ссылке приведены для геометрических полей и входных данных, но поиск можно использовать таким же образом с растрами с обеих сторон. Если поиск не поддерживает ввод растров, ввод автоматически преобразуется в геометрию, где это необходимо, с помощью функции 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) |
ДО Н.Э | rast__contains=geom |
ST_Contains(ST_Polygon(rast), geom) |
ДО Н.Э | rast__1__contains=geom |
ST_Contains(ST_Polygon(rast, 1), geom) |
ДО Н.Э | poly__contains=rst |
ST_Contains(poly, ST_Polygon(rst)) |
ДО Н.Э | 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) |
exact
, same_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) |
isvalid
¶
Доступность : MySQL (≥ 5.7.5), 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 ¶
На этих пространственных базовых модулях шаблон пересечения представляет собой строку, состоящую из девяти символов, которые определяют пересечения между внутренней, границей и внешней стороной геометрического поля и поисковой геометрией. Матрица пересечений шаблона может использовать только следующие символы:
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*'))
SQL-эквивалент PostGIS и MariaDB:
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*')
Добавлена поддержка MariaDB.
Оракул ¶
Здесь картина соотношения состоит , по меньшей мере , одной из девяти строк соотношения: TOUCH
, OVERLAPBDYDISJOINT
, OVERLAPBDYINTERSECT
,
EQUAL
, INSIDE
, COVEREDBY
, CONTAINS
, COVERS
, ON
, и
ANYINTERACT
. Несколько строк могут быть объединены с помощью логического логического оператора ИЛИ, например '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
Поиск расстояния ¶
Доступность : 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 предоставляет некоторые агрегатные функции, специфичные для ГИС. Подробные сведения об использовании этих агрегатных функций см. В тематическом руководстве по агрегированию .
Аргумент ключевого слова | Описание |
---|---|
tolerance |
Это ключевое слово предназначено только для Oracle. Это значение допуска, используемое SDOAGGRTYPE
процедурой; в документации Oracle есть более подробная информация. |
Пример:
>>> from django.contrib.gis.db.models import Extent, Union
>>> WorldBorder.objects.aggregate(Extent('mpoly'), Union('mpoly'))
Collect
¶
-
класс
Collect
( geo_field ) ¶
Доступность : PostGIS , SpatiaLite
Возвращает геометрический объект GEOMETRYCOLLECTION
или MULTI
объект из столбца геометрии. Это аналогично упрощенной версии Union
агрегата, за исключением того, что это может быть на несколько порядков быстрее, чем выполнение объединения, потому что оно сворачивает геометрии в коллекцию или несколько объектов, не заботясь о растворении границ.
Extent
¶
-
класс
Extent
( geo_field ) ¶
Доступность : PostGIS , Oracle, SpatiaLite
Возвращает экстент всего geo_field
в QuerySet
виде кортежа из четырех элементов, включающего нижнюю левую координату и верхнюю правую координату.
Пример:
>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent('poly'))
>>> print(qs['poly__extent'])
(-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)
Extent3D
¶
-
класс
Extent3D
( geo_field ) ¶
Доступность : PostGIS
Возвращает трехмерный экстент всего geo_field
в QuerySet
виде кортежа из шести элементов, включающего нижнюю левую координату и верхнюю правую координату (каждая с координатами x, y и z).
Пример:
>>> 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
¶
-
класс
MakeLine
( geo_field ) ¶
Доступность : PostGIS , SpatiaLite
Возвращает объект, LineString
построенный на основе геометрии точечного поля в
QuerySet
. В настоящее время упорядочивание набора запросов не действует.
Пример:
>>> 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
¶
-
класс
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] | См. Спецификацию простых функций OpenGIS для SQL в гл. 2.1.13.2, п. 2-13 (Размерно расширенная модель девяти пересечений). |
[2] | См. Документацию SDO_RELATE в Руководстве разработчика Oracle Spatial and Graph. |
[3] | ( 1 , 2 ) Для объяснения этой процедуры прочтите Причуды пространственного предиката «Содержит» Мартина Дэвиса (разработчика PostGIS). |