Операции с геопространственными индексами

В Managed Valkey все управление геопространственными индексами выполняется командами Valkey. С полным списком команд Valkey вы можете ознакомиться в официальной документации Valkey.

Обратите внимание, что в Managed Valkey некоторые команды Valkey недоступны.

Чтобы получить координаты объектов, используйте команду GEOPOS.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

3. Узнайте имя ключа с помощью итеративного обхода.

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение zset.

5. Узнайте имена объектов.

6. Выполните команду:

   1
   GEOPOS <имя ключа> <объект 1> [<объект 2> ...]

   Команда вернет список координат в порядке перечисления объектов. Для каждого объекта сначала вернется долгота, затем широта. Для отсутствующего объекта вернется nil. Если ключ не существует, nil вернется для каждого запрошенного объекта.

   Координаты могут минимально отличаться от переданных при добавлении из-за точности внутреннего представления. Данные индекса сохранятся.

Чтобы получить расстояние между двумя объектами, используйте команду GEODIST.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

3. Узнайте имя ключа с помощью итеративного обхода.

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение zset.

5. Узнайте имена объектов.

6. Выполните команду:

   1
   GEODIST <имя ключа> <объект 1> <объект 2> [m | km | ft | mi]

   В команде единица измерения — m для метров, km для километров, ft для футов или mi для миль. По умолчанию будут использованы метры.

   Команда вернет расстояние в выбранных единицах. Если хотя бы один объект или ключ не существует, вернется nil.

   Расстояние будет вычислено по координатам в приближении сферической Земли. Оно не будет длиной автомобильного или пешеходного маршрута.

Чтобы получить строковые геохеши объектов, используйте команду GEOHASH.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

3. Узнайте имя ключа с помощью итеративного обхода.

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение zset.

5. Узнайте имена объектов.

6. Выполните команду:

   1
   GEOHASH <имя ключа> <объект 1> [<объект 2> ...]

   Команда вернет список строк Geohash длиной 11 символов в порядке перечисления объектов. Строка будет представлять местоположение соответствующего объекта. Для отсутствующего объекта вернется nil. Если ключ не существует, nil вернется для каждого запрошенного объекта.

   Результат будет строковым геохешем, а не числовым весом участника сортированного множества. Данные индекса сохранятся.

Чтобы найти объекты внутри заданной области, используйте команду GEOSEARCH.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

3. Узнайте имя ключа с помощью итеративного обхода.

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение zset.

5. Узнайте имя объекта.

6. Выполните нужную команду:

   • В радиусе
   • В прямоугольнике
   • В многоугольнике

   1
   GEOSEARCH <имя ключа> FROMLONLAT <долгота> <широта> BYRADIUS <радиус> <единица> [ASC | DESC] [COUNT <количество> [ANY]] [WITHCOORD] [WITHDIST]

   Вместо FROMLONLAT <долгота> <широта> можно указать FROMMEMBER <объект>.

   1
   GEOSEARCH <имя ключа> FROMLONLAT <долгота> <широта> BYBOX <ширина> <высота> <единица> [ASC | DESC] [COUNT <количество> [ANY]] [WITHCOORD] [WITHDIST]

   Вместо FROMLONLAT <долгота> <широта> можно указать FROMMEMBER <объект>.

   1
   GEOSEARCH <имя ключа> BYPOLYGON <число вершин> <долгота 1> <широта 1> <долгота 2> <широта 2> <долгота 3> <широта 3> [<долгота 4> <широта 4> ...] [COUNT <количество> [ANY]] [WITHCOORD]

   Укажите не менее трех вершин по порядку обхода границы. Число вершин должно совпадать с числом пар координат. FROMLONLAT и FROMMEMBER для этого варианта не используются.

   В командах:

   • <единица> — m, km, ft или mi для метров, километров, футов или миль.
   • ASC и DESC — порядок от ближайших и от дальних объектов.
   • COUNT — положительное ограничение количества результатов. ANY ускорит поиск, но ближайшие объекты не будут гарантированы.
   • WITHCOORD — добавить координаты.
   • WITHDIST — добавить расстояния до центра.
   • <долгота> — число от -180 до 180 градусов.
   • <широта> — число от -85.05112878 до 85.05112878 градусов.
   • <объект> — уникальное имя объекта внутри индекса.

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

   Команда вернет найденные объекты. Без дополнительных полей в ответе будут только имена. Если совпадений нет, вернется пустой список. Для получения ближайших объектов задайте ASC COUNT <количество> без ANY. Поиск по координатам при отсутствующем ключе вернет пустой список. Если объект для FROMMEMBER не найден, вернется ошибка. Данные индекса сохранятся.

Чтобы добавить объекты в геопространственный индекс или изменить их координаты, используйте команду GEOADD.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

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

4. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение zset.

5. Узнайте имена объектов.

6. Выполните команду:

   1
   GEOADD <имя ключа> [NX | XX] [CH] <долгота 1> <широта 1> <объект 1> [<долгота 2> <широта 2> <объект 2> ...]

   В команде:

   • <долгота> — число от -180 до 180 градусов.
   • <широта> — число от -85.05112878 до 85.05112878 градусов.
   • <объект> — уникальное имя объекта внутри индекса.
   • NX — добавлять только новые объекты, не изменяя существующие.
   • XX — изменять только существующие объекты.
   • CH — включить в ответ не только добавленные объекты, но и объекты с измененным сохраненным местоположением.

   Указывайте долготу перед широтой, отделяйте дробную часть точкой. NX и XX взаимоисключающие.

   Команда добавит объекты или обновит их координаты. Если ключ не существует, будет создан индекс, кроме случая с XX. По умолчанию вернется количество добавленных объектов; с CH — суммарное количество добавленных и измененных. Если изменений не произойдет, вернется 0. Координаты вне допустимых диапазонов приведут к ошибке.

Чтобы сохранить найденные объекты в отдельный ключ, используйте команду GEOSEARCHSTORE.

1. Подключитесь к кластеру.

2. Переключитесь на нужную базу данных.

3. Для работы с существующими ключами узнайте их имена с помощью итеративного обхода.

4. Выберите отдельное имя целевого ключа. Проверьте, существует ли он. Прежнее значение будет заменено результатом.

5. Проверьте тип значения ключа. Для существующего ключа должно вернуться значение zset.

6. Задайте область поиска по инструкции GEOSEARCH. Ниже показан поиск в радиусе от заданных координат.

7. Выполните нужную команду:

   • Сохранить координаты
   • Сохранить расстояния

   1
   GEOSEARCHSTORE <имя целевого ключа> <имя исходного ключа> FROMLONLAT <долгота> <широта> BYRADIUS <радиус> <единица> [ASC | DESC] [COUNT <количество> [ANY]]

   Будет сохранен геопространственный индекс найденных объектов. Их координаты можно будет прочитать.

   1
   GEOSEARCHSTORE <имя целевого ключа> <имя исходного ключа> FROMLONLAT <долгота> <широта> BYRADIUS <радиус> <единица> [ASC | DESC] [COUNT <количество> [ANY]] STOREDIST

   Будет сохранено обычное сортированное множество: весом объекта станет расстояние до центра в выбранных единицах. Для чтения объектов и расстояний используйте ZRANGE с WITHSCORES. Такой результат не будет геопространственным индексом для последующих GEO-команд.

   В командах:

   • <единица> — m, km, ft или mi для метров, километров, футов или миль.
   • ASC и DESC — порядок от ближайших и от дальних объектов.
   • COUNT — положительное ограничение количества результатов. ANY ускорит поиск, но ближайшие объекты не будут гарантированы.
   • STOREDIST — сохранить расстояние.
   • <долгота> — число от -180 до 180 градусов.
   • <широта> — число от -85.05112878 до 85.05112878 градусов.
   • <объект> — уникальное имя объекта внутри индекса.

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

   Можно использовать FROMMEMBER, BYBOX или BYPOLYGON по тем же правилам, что и в GEOSEARCH. Параметры вывода WITHCOORD, WITHDIST и WITHHASH здесь не применяются.

   Команда вернет количество сохраненных объектов. Существующий целевой ключ будет перезаписан независимо от типа значения. Если результат пуст, целевой ключ будет удален. При разных именах исходный индекс сохранится.