Справочник по API GIS QuerySet¶
Пространственные запросы¶
Пространственные запросы в этом разделе доступны для GeometryField и RasterField.
Для введения см. Введение в пространственный поиск. Для обзора того, какие поисковые запросы совместимы с конкретным пространственным сервером, обратитесь к таблице совместимости пространственного поиска.
Поиск с помощью растров¶
Все примеры в ссылке ниже даны для геометрических полей и входных данных, но поиск можно использовать таким же образом с растрами с обеих сторон. Всякий раз, когда поиск не поддерживает растровый ввод, входные данные автоматически преобразуются в геометрию, где это необходимо, с помощью функции ST_Polygon. См. также введение в поиск растра.
Операторы базы данных, используемые при поиске, можно разделить на три категории:
Встроенная поддержка растров «N»: оператор изначально принимает растры с обеих сторон поиска, а входные растровые данные можно смешивать с входными геометрическими данными.
Поддержка двусторонних растров
B: оператор поддерживает растры, только если обе стороны поиска получают растровые входные данные. Растровые данные автоматически преобразуются в геометрию для смешанного поиска.Поддержка преобразования геометрии
C. Поиск не имеет встроенной поддержки растров, все растровые данные автоматически преобразуются в геометрию.
В примерах ниже показан эквивалент SQL для поиска в различных типах поддержки растров. Тот же шаблон применим ко всем пространственным поискам.
Случай |
Искать |
SQL-эквивалент |
|---|---|---|
Н, Б |
|
|
Н, Б |
|
|
Б, С |
|
|
Б, С |
|
|
Б, С |
|
|
Б, С |
|
|
С |
|
|
С |
|
|
С |
|
|
С |
|
|
Пространственный поиск с помощью растров поддерживается только для серверов PostGIS (в этом разделе обозначен как PGRaster).
bbcontains¶
Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (родной)
Проверяет, полностью ли ограничивающая рамка геометрического или растрового поля содержит ограничивающую рамку искомой геометрии.
Например:
Zipcode.objects.filter(poly__bbcontains=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
МарияДБ |
|
MySQL |
|
SpatiaLite |
|
bboverlaps¶
Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (родной)
Проверяет, перекрывает ли ограничивающая рамка поля геометрии ограничивающую рамку искомой геометрии.
Например:
Zipcode.objects.filter(poly__bboverlaps=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
МарияДБ |
|
MySQL |
|
SpatiaLite |
|
содержится¶
Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (родной)
Проверяет, полностью ли ограничивающая рамка геометрического поля содержится в ограничивающей рамке искомой геометрии.
Например:
Zipcode.objects.filter(poly__contained=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
МарияДБ |
|
MySQL |
|
SpatiaLite |
|
contains¶
Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (двусторонний)
Проверяет, содержит ли поле геометрии пространственно искомую геометрию.
Например:
Zipcode.objects.filter(poly__contains=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
Оракул |
|
МарияДБ |
|
MySQL |
|
SpatiaLite |
|
содержит_правильно¶
Доступность: PostGIS, PGRaster (двусторонний)
Возвращает true, если искомая геометрия пересекает внутреннюю часть поля геометрии, но не границу (или внешнюю часть).
Например:
Zipcode.objects.filter(poly__contains_properly=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
покрытый¶
Доступность: PostGIS, Oracle, PGRaster (двусторонний), SpatiaLite
Проверяет, находится ли ни одна точка в поле геометрии за пределами геометрии поиска. [3]
Например:
Zipcode.objects.filter(poly__coveredby=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
Оракул |
|
SpatiaLite |
|
обложки¶
Доступность: PostGIS, Oracle, PGRaster (двусторонний), SpatiaLite
Проверяет, находится ли ни одна точка в геометрии поиска за пределами поля геометрии. [3]
Например:
Zipcode.objects.filter(poly__covers=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
Оракул |
|
SpatiaLite |
|
кресты¶
Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (конвертация)
Проверяет, пересекает ли поле геометрии пространственно искомую геометрию.
Например:
Zipcode.objects.filter(poly__crosses=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
МарияДБ |
|
MySQL |
|
SpatiaLite |
|
непересекающийся¶
Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (двусторонний)
Проверяет, не пересекается ли поле геометрии пространственно с геометрией поиска.
Например:
Zipcode.objects.filter(poly__disjoint=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
Оракул |
|
МарияДБ |
|
MySQL |
|
SpatiaLite |
|
равно¶
Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (конвертация)
Проверяет, соответствует ли поле геометрии в пространстве искомой геометрии.
Например:
Zipcode.objects.filter(poly__equals=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
Оракул |
|
МарияДБ |
|
MySQL |
|
SpatiaLite |
|
точный, такой же_как¶
Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (двусторонний)
Проверяет, соответствует ли поле геометрии искомой геометрии. В Oracle, MySQL и SpatiaLite он проверяет пространственное равенство, а в PostGIS — равенство ограничивающих рамок.
Например:
Zipcode.objects.filter(poly=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
Оракул |
|
МарияДБ |
|
MySQL |
|
SpatiaLite |
|
пересекается¶
Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (двусторонний)
Проверяет, пересекает ли поле геометрии пространственно искомую геометрию.
Например:
Zipcode.objects.filter(poly__intersects=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
Оракул |
|
МарияДБ |
|
MySQL |
|
SpatiaLite |
|
недействительно¶
Availability: MySQL (≥ 5.7.5), PostGIS, Oracle, SpatiaLite
Проверяет, является ли геометрия допустимой.
Например:
Zipcode.objects.filter(poly__isvalid=True)
Бэкэнд |
SQL-эквивалент |
|---|---|
MySQL, PostGIS, SpatiaLite |
|
Оракул |
|
перекрывается¶
Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (двусторонний)
Проверяет, перекрывает ли поле геометрии пространственно искомую геометрию.
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
Оракул |
|
МарияДБ |
|
MySQL |
|
SpatiaLite |
|
относить¶
Доступность: PostGIS, MariaDB, Oracle, SpatiaLite, PGRaster (конверсия)
Проверяет, связано ли поле геометрии пространственно с геометрией поиска значениями, заданными в заданном шаблоне. Для этого поиска требуется параметр кортежа (geom, 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*')
SQL-эквивалент SpatiaLite:
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 support was added.
Оракул¶
Здесь шаблон отношения состоит как минимум из одной из девяти строк отношений: 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')
касается¶
Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite
Проверяет, касается ли пространственно поле геометрии искомой геометрии.
Например:
Zipcode.objects.filter(poly__touches=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
МарияДБ |
|
MySQL |
|
Оракул |
|
SpatiaLite |
|
внутри¶
Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (двусторонний)
Проверяет, находится ли поле геометрии пространственно в пределах геометрии поиска.
Например:
Zipcode.objects.filter(poly__within=geom)
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
МарияДБ |
|
MySQL |
|
Оракул |
|
SpatiaLite |
|
левый¶
Доступность: PostGIS, PGRaster (конверсия)
Проверяет, находится ли ограничивающая рамка геометрического поля строго слева от ограничивающей рамки искомой геометрии.
Например:
Zipcode.objects.filter(poly__left=geom)
Эквивалент PostGIS:
SELECT ... WHERE poly << geom
правильно¶
Доступность: 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, PGRaster (конверсия)
Проверяет, находится ли ограничивающая рамка поля геометрии строго над ограничивающей рамкой искомой геометрии.
Например:
Zipcode.objects.filter(poly__strictly_above=geom)
Эквивалент PostGIS:
SELECT ... WHERE poly |>> geom
строго_ниже¶
Доступность: PostGIS, PGRaster (конверсия)
Проверяет, находится ли ограничивающая рамка поля геометрии строго ниже ограничивающей рамки искомой геометрии.
Например:
Zipcode.objects.filter(poly__strictly_below=geom)
Эквивалент PostGIS:
SELECT ... WHERE poly <<| geom
Дистанционные поиски¶
Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (родной)
Обзор выполнения дистанционных запросов см. в разделе Введение в дистанционные запросы.
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'])
Значение, передаваемое при удаленном поиске, представляет собой кортеж; первые два значения являются обязательными и представляют собой геометрию для расчета расстояний и значение расстояния (либо число в единицах поля, либо объект Distance, либо выражение запроса). Чтобы передать индекс канала в поиск, используйте кортеж из трех элементов, где вторая запись — это индекс канала.
При каждом поиске расстояния, кроме dwithin, может быть включен дополнительный элемент ``сфероид“`, чтобы использовать более точные функции расчета сфероидного расстояния на полях с геодезической системой координат.
В PostgreSQL опция spheroid использует ST_DistanceSpheroid <https://postgis.net/docs/ST_Distance_Spheroid.html>`__ вместо ST_DistanceSphere <https://postgis.net/docs/ST_DistanceSphere.html>`__. Более простая функция ST_Distance используется с системами координат проекции. Растры преобразуются в геометрию для поиска на основе сфероидов.
distance_gt¶
Возвращает модели, в которых расстояние до поля геометрии из искомой геометрии больше заданного значения расстояния.
Например:
Zipcode.objects.filter(poly__distance_gt=(geom, D(m=5)))
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
МарияДБ |
|
MySQL |
|
Оракул |
|
SpatiaLite |
|
distance_gte¶
Возвращает модели, в которых расстояние до поля геометрии из искомой геометрии больше или равно заданному значению расстояния.
Например:
Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
МарияДБ |
|
MySQL |
|
Оракул |
|
SpatiaLite |
|
distance_lt¶
Возвращает модели, в которых расстояние до поля геометрии из искомой геометрии меньше заданного значения расстояния.
Например:
Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
МарияДБ |
|
MySQL |
|
Оракул |
|
SpatiaLite |
|
distance_lte¶
Возвращает модели, в которых расстояние до поля геометрии из искомой геометрии меньше или равно заданному значению расстояния.
Например:
Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
МарияДБ |
|
MySQL |
|
Оракул |
|
SpatiaLite |
|
в пределах¶
Возвращает модели, в которых расстояния до поля геометрии из искомой геометрии находятся в пределах заданного расстояния друг от друга. Обратите внимание, что вы можете предоставлять объекты Distance только в том случае, если целевые геометрии находятся в проецируемой системе. Для географической геометрии следует использовать единицы измерения поля геометрии (например, градусы для WGS84).
Например:
Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))
Бэкэнд |
SQL-эквивалент |
|---|---|
ПостГИС |
|
Оракул |
|
SpatiaLite |
|
Агрегатные функции¶
Django предоставляет некоторые агрегатные функции, специфичные для ГИС. Подробную информацию о том, как использовать эти агрегатные функции, см. в тематическом руководстве по агрегации.
Ключевое слово Аргумент |
Описание |
|---|---|
|
Это ключевое слово предназначено только для Oracle. Это значение допуска, используемое процедурой SDOAGGRTYPE; документация Oracle содержит более подробную информацию. |
Например:
>>> from django.contrib.gis.db.models import Extent, Union
>>> WorldBorder.objects.aggregate(Extent('mpoly'), Union('mpoly'))
Собрать¶
- class Collect(geo_field)¶
Availability: PostGIS, SpatiaLite
Возвращает объект геометрии GEOMETRYCOLLECTION или MULTI из столбца геометрии. Это аналогично упрощенной версии агрегата Union, за исключением того, что он может выполняться на несколько порядков быстрее, чем выполнение объединения, поскольку свертывает геометрии в коллекцию или несколько объектов, не заботясь о растворении границ.
Протяженность¶
- class Extent(geo_field)¶
Доступность: PostGIS, Oracle, SpatiaLite
Returns the extent of all geo_field in the QuerySet as a four-tuple,
comprising the lower left coordinate and the upper right coordinate.
Например:
>>> qs = City.objects.filter(name__in=('Houston', 'Dallas')).aggregate(Extent('poly'))
>>> print(qs['poly__extent'])
(-96.8016128540039, 29.7633724212646, -95.3631439208984, 32.782058715820)
Экстент3D¶
- class Extent3D(geo_field)¶
Доступность: PostGIS
Returns the 3D extent of all geo_field in the QuerySet as a six-tuple,
comprising the lower left coordinate and upper right coordinate (each with x, y,
and z coordinates).
Например:
>>> 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
Возвращает 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)
Союз¶
- 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.
Сноски