GEORADIUS

GEORADIUS (deprecated)

GEORADIUS key longitude latitude radius <M | KM | FT | MI>
  [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count [ANY]] [ASC | DESC]
  [STORE key] [STOREDIST key]

Доступна с версии:

3.2.0

Временная сложность:

O(N+log(M)), где N — количество элементов внутри прямоугольника, ограниченного центром и радиусом, а M — количество элементов в индексе.

Категории ACL:

@write, @geo, @slow,

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

В этом руководстве также рассматриваются варианты GEORADIUS_RO и GEORADIUSBYMEMBER_RO (подробнее см. раздел ниже).

Типичное использование этой команды — получение геопространственных элементов вблизи заданной точки на расстоянии не более заданного значения в метрах (или других единицах). Это позволяет, например, предлагать мобильным пользователям приложения близлежащие места.

Радиус задаётся в следующих единицах:

• м для метров.
• км для километров.
• ми для миль.
• фут для футов.

Команда необязательно возвращает дополнительную информацию, используя следующие параметры:

• WITHDIST: Также вернуть расстояние возвращаемых элементов от заданного центра. Расстояние возвращается в тех же единицах, что и единицы, указанные в качестве аргумента радиуса команды.
• WITHCOORD: Также вернуть координаты долготы и широты соответствующих элементов.
• WITHHASH: Также вернуть сырое значение отсортированного множества, закодированное с помощью geohash, в виде 52-битного беззнакового целого числа. Это полезно только для низкоуровневых хаков или отладки и в остальном малоинтересно для обычного пользователя.

По умолчанию команда возвращает неупорядоченные элементы. Два разных метода сортировки можно вызвать, используя следующие два параметра:

• ASC: Сортировать возвращаемые элементы от ближайшего к самому удалённому относительно центра.
• DESC: Сортировать возвращаемые элементы от самого удалённого к ближайшему относительно центра.

По умолчанию возвращаются все совпадающие элементы. Можно ограничить результаты первыми N совпадающими элементами, используя параметр COUNT <count>. Когда ANY задан, команда вернёт результат, как только найдётся достаточно совпадений, поэтому результаты могут не быть самыми близкими к заданной точке, но при этом затраты сервера значительно ниже. Когда ANY не задан, команда совершит усилия, пропорциональные количеству элементов, соответствующих заданной области, и отсортирует их, поэтому запрос на очень большие области с очень малым значением COUNT может быть медленным, даже если возвращается всего несколько результатов.

По умолчанию команда возвращает элементы клиенту. Возможна запись результатов с одним из этих параметров:

• STORE: Сохранить элементы в упорядоченном множестве с их геопространственной информацией.
• STOREDIST: Сохранить элементы в упорядоченном множестве с расстоянием до центра в виде числа с плавающей точкой в тех же единицах, что и указанные в радиусе.

Возврат

Массивный ответ, а именно:

• Без указания каких-либо WITH параметров команда просто возвращает линейный массив, например, ["Нью-Йорк","Милан","Париж"].
• Если указаны параметры WITHCOORD, WITHDIST или WITHHASH, команда возвращает массив массивов, где каждый подмассив представляет один элемент.

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

1. Расстояние от центра как число с плавающей точкой в тех же единицах, что и указанные в радиусе.
2. Целое число geohash.
3. Координаты как массив из двух элементов x,y (долгота, широта).

Например, команда GEORADIUS Sicily 15 37 200 km WITHCOORD WITHDIST вернёт каждый элемент следующим образом:

["Palermo","190.4424",["13.361389338970184","38.115556395496299"]]

Только чтение

Поскольку у GEORADIUS и GEORADIUSBYMEMBER есть параметры STORE и STOREDIST, они технически помечены как команды записи в таблице команд Redis. По этой причине реплики только для чтения будут отмечать их, а реплики Redis Cluster будут перенаправлять их на главный экземпляр даже если подключение находится в режиме только чтения (см. команду READONLY Redis Cluster).

Рассмотрение нарушения совместимости с прошлым, но отклонено, по крайней мере, для Redis 4.0, поэтому вместо этого были добавлены два варианта команд только для чтения. Они точно такие же, как и оригинальные команды, но отказываются от параметров STORE и STOREDIST. Два варианта называются GEORADIUS_RO и GEORADIUSBYMEMBER_RO и могут безопасно использоваться в репликах.

Примеры

GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
GEORADIUS Sicily 15 37 200 km WITHDIST
GEORADIUS Sicily 15 37 200 km WITHCOORD
GEORADIUS Sicily 15 37 200 km WITHDIST WITHCOORD

История

• Начиная с версии Redis 6.2.0: Добавлен параметр ANY для COUNT.
• Начиная с версии Redis 7.0.0: Добавлена поддержка имён единиц в верхнем регистре.