Справочник 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 будет зависеть от пространственного бэкенда:

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

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

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

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

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.

Примечания