Справочник 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. Несколько строк могут быть объединены с помощью логического булевого оператора ИЛИ, например, '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, или выражение запроса). Для передачи индекса полосы используйте кортеж из трёх элементов, где вторым элементом является индекс полосы.

Во всех запросах по расстоянию, кроме 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 предоставляет некоторые специализированные функции агрегирования GIS. Подробнее о том, как использовать эти функции агрегирования, см. в руководстве по агрегированию.

Пример:

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

Примечания