Справочник API набора запросов GIS

Пространственные запросы

В этом разделе доступны пространственные запросы для GeometryField и RasterField.

Для ознакомления см. введение в пространственные запросы. Чтобы узнать, какие запросы совместимы с определенным пространственным бэкендом, см. таблицу совместимости пространственных запросов.

Запросы с растровыми данными

Все примеры в данном справочнике приведены для геометрических полей и входных данных, но запросы можно использовать таким же образом с растровыми данными с обеих сторон. В тех случаях, когда запрос не поддерживает растровый ввод, входные данные автоматически преобразуются в геометрию при необходимости с помощью функции ST_Polygon. См. также введение в запросы с растровыми данными.

Операторы базы данных, используемые в запросах, можно разделить на три категории:

• Прямая поддержка растровых данных N: оператор непосредственно принимает растровые данные с обеих сторон запроса, и растровый ввод может быть смешан с геометрическим вводом.
• Двусторонняя поддержка растровых данных B: оператор поддерживает растровые данные только если с обеих сторон запроса присутствуют растровые данные. Растровые данные автоматически преобразуются в геометрию для смешанных запросов.
• Поддержка преобразования геометрии C. Запрос не имеет прямой поддержки растровых данных, все растровые данные автоматически преобразуются в геометрию.

Ниже приведены примеры эквивалента SQL для запросов в различных типах поддержки растровых данных. Такая же схема применяется ко всем пространственным запросам.

Пространственные запросы с растровыми данными поддерживаются только для бэкендов PostGIS (обозначены как PGRaster в этом разделе).

bbcontains

Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Прямая поддержка)

Проверяет, полностью ли ограничивающая рамка геометрического или растрового поля содержит ограничивающую рамку геометрического поля запроса.

Пример:

Zipcode.objects.filter(poly__bbcontains=geom)

bboverlaps

Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Прямая поддержка)

Проверяет, перекрываются ли ограничивающие рамки геометрического поля и геометрического поля запроса.

Пример:

Zipcode.objects.filter(poly__bboverlaps=geom)

contained

Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Прямая поддержка)

Проверяет, полностью ли ограничивающая рамка геометрического поля содержится в ограничивающей рамке геометрического поля запроса.

Пример:

Zipcode.objects.filter(poly__contained=geom)

contains

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Двусторонняя поддержка)

Проверяет, содержит ли геометрическое поле пространственно геометрическое поле запроса.

Пример:

Zipcode.objects.filter(poly__contains=geom)

contains_properly

Доступность: PostGIS, PGRaster (Двусторонняя поддержка)

Возвращает true, если геометрическое поле запроса пересекает внутреннюю часть геометрического поля, но не границу (или внешнюю часть).

Пример:

Zipcode.objects.filter(poly__contains_properly=geom)

coveredby

Доступность: PostGIS, Oracle, PGRaster (Двусторонняя поддержка), SpatiaLite

Проверяет, что ни одна точка в геометрическом поле не находится вне геометрического поля запроса. [3]

Пример:

Zipcode.objects.filter(poly__coveredby=geom)

covers

Доступность: PostGIS, Oracle, PGRaster (Двусторонняя поддержка), SpatiaLite

Проверяет, что ни одна точка в геометрическом поле запроса не находится вне геометрического поля. [3]

Пример:

Zipcode.objects.filter(poly__covers=geom)

crosses

Доступность: PostGIS, MariaDB, MySQL, SpatiaLite, PGRaster (Преобразование)

Проверяет, пересекает ли геометрическое поле геометрическое поле запроса.

Пример:

Zipcode.objects.filter(poly__crosses=geom)

disjoint

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Двусторонняя поддержка)

Проверяет, являются ли геометрическое поле и геометрическое поле запроса пространственно непересекающимися.

Пример:

Zipcode.objects.filter(poly__disjoint=geom)

equals

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Преобразование)

Проверяет, равны ли геометрическое поле и геометрическое поле запроса пространственно.

Пример:

Zipcode.objects.filter(poly__equals=geom)

exact, same_as

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Двусторонняя поддержка)

Проверяет, «равны» ли геометрическое поле и геометрическое поле запроса. В Oracle, MySQL и SpatiaLite проверяется пространственное равенство, а в PostGIS — равенство ограничивающих рамок.

Пример:

Zipcode.objects.filter(poly=geom)

id="std:fieldlookup-intersects">intersects

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Взаимно)

Проверяет, пересекается ли геометрическое поле с геометрией поиска.

Пример:

Zipcode.objects.filter(poly__intersects=geom)

id="std:fieldlookup-isvalid">isvalid

Доступность: MySQL (≥ 5.7.5), PostGIS, Oracle, SpatiaLite

Проверяет, является ли геометрия валидной.

Пример:

Zipcode.objects.filter(poly__isvalid=True)

id="std:fieldlookup-overlaps">overlaps

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Взаимно)

Проверяет, перекрываются ли геометрическое поле и геометрия поиска.

id="std:fieldlookup-relate">relate

Доступность: PostGIS, MariaDB, Oracle, SpatiaLite, PGRaster (Преобразование)

Проверяет, связана ли геометрическое поле с геометрией поиска в соответствии с заданным шаблоном. Этот поиск требует параметра кортежа, (geom, pattern); форма pattern будет зависеть от пространственного бэкенда:

id="mariadb-postgis-and-spatialite">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*'))

Эквивалент SQL для PostGIS:

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

id="oracle">Oracle

Здесь шаблон соотношений состоит как минимум из одной из девяти строк соотношений: TOUCH, OVERLAPBDYDISJOINT, OVERLAPBDYINTERSECT, EQUAL, INSIDE, COVEREDBY, CONTAINS, COVERS, ON, и ANYINTERACT. Несколько строк можно комбинировать с логическим булевым оператором OR, например, 'inside+touch'. [2] Строки соотношений нечувствительны к регистру.

Пример:

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

Эквивалент SQL для Oracle:

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

id="std:fieldlookup-touches">touches

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite

Проверяет, касается ли геометрическое поле геометрии поиска.

Пример:

Zipcode.objects.filter(poly__touches=geom)

id="std:fieldlookup-within">within

Доступность: PostGIS, Oracle, MariaDB, MySQL, SpatiaLite, PGRaster (Взаимно)

Проверяет, находится ли геометрическое поле внутри геометрии поиска.

Пример:

Zipcode.objects.filter(poly__within=geom)

id="std:fieldlookup-left">left

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, находится ли прямоугольник обрамления геометрического поля строго слева от прямоугольника обрамления геометрии поиска.

Пример:

Zipcode.objects.filter(poly__left=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly << geom

id="std:fieldlookup-right">right

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, находится ли прямоугольник обрамления геометрического поля строго справа от прямоугольника обрамления геометрии поиска.

Пример:

Zipcode.objects.filter(poly__right=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly >> geom

id="std:fieldlookup-overlaps_left">overlaps_left

Доступность: PostGIS, PGRaster (Взаимно)

Проверяет, перекрывается ли прямоугольник обрамления геометрического поля или находится слева от прямоугольника обрамления геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_left=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly &< geom

id="std:fieldlookup-overlaps_right">overlaps_right

Доступность: PostGIS, PGRaster (Взаимно)

Проверяет, перекрывается ли прямоугольник обрамления геометрического поля или находится справа от прямоугольника обрамления геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_right=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly &> geom

id="std:fieldlookup-overlaps_above">overlaps_above

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, перекрывается ли прямоугольник обрамления геометрического поля или находится сверху от прямоугольника обрамления геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_above=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly |&> geom

id="std:fieldlookup-overlaps_below">overlaps_below

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, перекрывается ли прямоугольник обрамления геометрического поля или находится снизу от прямоугольника обрамления геометрии поиска.

Пример:

Zipcode.objects.filter(poly__overlaps_below=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly &<| geom

id="std:fieldlookup-strictly_above">strictly_above

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, находится ли прямоугольник обрамления геометрического поля строго сверху от прямоугольника обрамления геометрии поиска.

Пример:

Zipcode.objects.filter(poly__strictly_above=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly |>> geom

id="std:fieldlookup-strictly_below">strictly_below

Доступность: PostGIS, PGRaster (Преобразование)

Проверяет, находится ли прямоугольник обрамления геометрического поля строго снизу от прямоугольника обрамления геометрии поиска.

Пример:

Zipcode.objects.filter(poly__strictly_below=geom)

Эквивалент PostGIS:

SELECT ... WHERE poly <<| geom

id="id6">Поиск по расстоянию

Доступность: 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)))

distance_gte

Возвращает модели, где расстояние до геометрического поля от поля поиска больше или равно заданному значению расстояния.

Пример:

Zipcode.objects.filter(poly__distance_gte=(geom, D(m=5)))

distance_lt

Возвращает модели, где расстояние до геометрического поля от поля поиска меньше заданного значения расстояния.

Пример:

Zipcode.objects.filter(poly__distance_lt=(geom, D(m=5)))

distance_lte

Возвращает модели, где расстояние до геометрического поля от поля поиска меньше или равно заданному значению расстояния.

Пример:

Zipcode.objects.filter(poly__distance_lte=(geom, D(m=5)))

dwithin

Возвращает модели, где расстояние до геометрического поля от поля поиска находится в пределах заданного расстояния друг от друга. Обратите внимание, что вы можете предоставить только объекты Distance, если целевые геометрии находятся в проектной системе координат. Для географических геометрий следует использовать единицы измерения поля геометрии (например, градусы для WGS84) .

Пример:

Zipcode.objects.filter(poly__dwithin=(geom, D(m=5)))

Функции агрегации

Django предоставляет некоторые функции агрегации, специфичные для ГИС. Подробную информацию о том, как использовать эти функции агрегации, см. в руководстве по теме агрегации.

Пример:

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

Возвращает пределы всех 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

class Extent3D(geo_field)

Доступность: PostGIS

Возвращает 3D-предела всех 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

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)

Union

class Union(geo_field)

Доступность: PostGIS, Oracle, SpatiaLite

Этот метод возвращает объект GEOSGeometry, представляющий объединение всех геометрий в наборе запросов. Обратите внимание, что использование Union является ресурсоемким и может занимать значительное время на больших наборах запросов.

Пример:

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

Примечания