Справочник 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)

intersects

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

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

Пример:

Zipcode.objects.filter(poly__intersects=geom)

isvalid

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

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

Пример:

Zipcode.objects.filter(poly__isvalid=True)

overlaps

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

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

relate

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

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

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

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

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

Oracle

Здесь шаблон отношения состоит как минимум из одной из девяти строк отношений: 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)

within

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

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

Пример:

Zipcode.objects.filter(poly__within=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

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

Передаваемое значение в поиск по расстоянию — кортеж; первые два значения обязательны и представляют собой геометрию, для которой вычисляются расстояния, и значение расстояния (число в единицах поля, объект 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.

Примечания