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

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

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

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

Запросы с растрами

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

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

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

Приведённые ниже примеры демонстрируют SQL-эквиваленты запросов в разных типах поддержки растров. Та же схема применяется ко всем пространственным запросам.

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

bbcontains

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

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

Пример:

Zipcode.objects.filter(poly__bbcontains=geom)

bboverlaps

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

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

Пример:

Zipcode.objects.filter(poly__bboverlaps=geom)

contained

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

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

Пример:

Zipcode.objects.filter(poly__contained=geom)

contains

Доступность: PostGIS, Oracle, 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 (Взаимосторонняя)

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

Пример:

Zipcode.objects.filter(poly__coveredby=geom)

covers

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

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

Пример:

Zipcode.objects.filter(poly__covers=geom)

crosses

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

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

Пример:

Zipcode.objects.filter(poly__crosses=geom)

disjoint

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

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

Пример:

Zipcode.objects.filter(poly__disjoint=geom)

equals

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

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

Пример:

Zipcode.objects.filter(poly__equals=geom)

exact, same_as

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

Проверяет, “равны” ли геометрическое поле и искомая геометрия. В Oracle и SpatiaLite проверяется пространственная эквивалентность, а в MySQL и PostGIS — эквивалентность ограничивающих прямоугольных областей.

Пример:

Zipcode.objects.filter(poly=geom)

intersects

Доступность: PostGIS, Oracle, 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, 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*'))

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

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

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

touches

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

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

Пример:

Zipcode.objects.filter(poly__touches=geom)

within

Доступность: PostGIS, Oracle, 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, MySQL, SpatiaLite, PGRaster (Native)

Для получения обзора выполнения запросов по расстоянию, обратитесь к введению в запросы по расстоянию.

Поиск по расстоянию имеет следующий вид:

<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 или query expression <ref/models/expressions>).

Во всех поисках по расстоянию, кроме 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

Возвращает линию, построенную из геометрий точек в 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.

Примечания