Справочник API GIS QuerySet

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

Пространственные запросы в этом разделе доступны для 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)

isempty

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

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

Пример:

Zipcode.objects.filter(poly__isempty=True)

isvalid

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

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

Пример:

Zipcode.objects.filter(poly__isvalid=True)

overlaps

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

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

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. Несколько строк могут быть объединены логическим булевым оператором OR, например, '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)

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, filter=None) [source]

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

Возвращает объект геометрии GEOMETRYCOLLECTION или MULTI из столбца геометрии. Это аналогично упрощенной версии агрегата Union, за исключением того, что он может быть на несколько порядков быстрее при выполнении объединения, так как он группирует геометрии в коллекцию или многообъектный объект, не заботясь о растворении границ.

Extent

class Extent(geo_field, filter=None) [source]

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

Возвращает область всех geo_field в QuerySet в виде 4-кортежа, состоящего из координаты нижнего левого угла и координаты верхнего правого угла.

Пример:

>>> 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, filter=None) [source]

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

Возвращает 3D область всех geo_field в QuerySet в виде 6-кортежа, содержащего координаты нижнего левого угла и верхнего правого угла (каждая с координатами 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, filter=None) [source]

Доступность: 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, filter=None) [source]

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

Примечания