Операции с сортированными множествами

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

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

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

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

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

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

4. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

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

   • Получить участников по индексам
   • Получить участников по весу

   1
   ZRANGE <имя ключа> <начало> <конец> [REV] [WITHSCORES]

   Индексация начинается с 0, -1 означает последнего участника. Обе границы будут включены. Диапазон 0 -1 охватит всех участников. По умолчанию порядок будет соответствовать возрастанию веса, с REV — убыванию.

   1
   ZRANGE <имя ключа> <минимальный вес> <максимальный вес> BYSCORE [WITHSCORES]

   Обе границы будут включены. Для исключения границы поставьте перед числом (, например (10. Значения -inf и +inf обозначают отсутствие нижнего и верхнего ограничения.

   Параметр WITHSCORES добавит в ответ веса участников. Команда вернет участников диапазона, данные сохранятся. Если ключ не существует или диапазон пуст, вернется пустой список. При одинаковых весах участники будут упорядочены лексикографически по байтам, а с REV — в обратном порядке.

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

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

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

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

4. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

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

   1
   ZCARD <имя ключа>

   Команда вернет количество участников сортированного множества. Если ключ не существует, команда вернет 0.

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

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

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

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

4. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

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

   1
   ZADD <имя ключа> [NX | XX] [CH] <вес 1> <участник 1> [<вес 2> <участник 2> ...]

   В команде:

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

   Без NX или XX команда добавит новых участников и обновит вес существующих. Если ключ не существует, команда создаст сортированное множество, кроме случая с XX. При изменении веса положение участника будет пересчитано. Участники с одинаковым весом будут упорядочены лексикографически по байтам их значений.

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

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

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

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

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

4. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

5. Узнайте имя участника.

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

   1
   ZSCORE <имя ключа> <участник>

   Команда вернет вес участника. Если ключ или участник не существует, команда вернет nil.

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

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

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

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

4. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

5. Узнайте имя участника.

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

   1
   ZINCRBY <имя ключа> <шаг> <участник>

   В команде <шаг> — число, на которое нужно изменить вес. Для уменьшения укажите отрицательный шаг. Для дробного числа используйте точку, например 0.5.

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

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

• ZRANK — получить позицию при упорядочивании по возрастанию веса;
• ZREVRANK — получить позицию при упорядочивании по убыванию веса.

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

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

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

4. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

5. Узнайте имена участников.

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

   • ZRANK
   • ZREVRANK

   1
   ZRANK <имя ключа> <участник>

   Команда вернет ранг участника, начиная с 0. Для ZRANK ранг 0 получит первый участник с минимальным весом.

   1
   ZREVRANK <имя ключа> <участник>

   Команда вернет ранг участника, начиная с 0. Для ZREVRANK ранг 0 получит первый участник с максимальным весом.

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

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

• ZINTERSTORE — сохранить участников, которые есть во всех исходных множествах;
• ZUNIONSTORE — сохранить участников, которые есть хотя бы в одном исходном множестве.

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

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

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

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

5. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

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

   • ZINTERSTORE
   • ZUNIONSTORE

   1
   ZINTERSTORE <имя целевого ключа> <количество ключей> <имя ключа 1> [<имя ключа 2> ...] [WEIGHTS <коэффициент 1> [<коэффициент 2> ...]] [AGGREGATE <способ>]

   1
   ZUNIONSTORE <имя целевого ключа> <количество ключей> <имя ключа 1> [<имя ключа 2> ...] [WEIGHTS <коэффициент 1> [<коэффициент 2> ...]] [AGGREGATE <способ>]

   В командах:

   • Значение <количество ключей> — положительное целое число исходных ключей, которое должно совпадать с числом перечисленных имен.
   • WEIGHTS — коэффициенты умножения весов: по одному для каждого исходного ключа в том же порядке. Если параметр не указан, все коэффициенты будут равны 1.
   • AGGREGATE SUM — сложить веса участника после умножения на коэффициенты. Этот способ будет использован по умолчанию.
   • AGGREGATE MIN или AGGREGATE MAX — выбрать минимальный или максимальный вес участника после умножения на коэффициенты.

   Несуществующие исходные ключи будут учтены как пустые множества. При объединении вес участника будет рассчитан только по тем множествам, в которых он есть.

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

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

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

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

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

4. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

5. Начните обход с курсора 0:

   1
   ZSCAN <имя ключа> 0 [MATCH <шаблон>] [COUNT <количество>]

   В команде MATCH <шаблон> — отобрать участников по шаблону, а COUNT <количество> — задать положительное целое число как ориентир объема работы за вызов. Количество результатов может отличаться от указанного.

   Команда вернет следующий курсор и пары участников и весов.

6. Подставляйте полученный курсор в следующий вызов. Используйте тот же ключ и условия отбора:

   1
   ZSCAN <имя ключа> <курсор> [MATCH <шаблон>] [COUNT <количество>]

   Обход завершится, когда команда вернет курсор 0. Если ключ не существует, сразу вернутся курсор 0 и пустой список. Порядок участников по весу не будет гарантирован.

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

• BZPOPMIN — извлечь участника с минимальным весом;
• BZPOPMAX — извлечь участника с максимальным весом.

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

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

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

4. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

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

   • BZPOPMIN
   • BZPOPMAX

   1
   BZPOPMIN <имя ключа 1> [<имя ключа 2> ...] <таймаут>

   1
   BZPOPMAX <имя ключа 1> [<имя ключа 2> ...] <таймаут>

   В командах <таймаут> — неотрицательное время ожидания в секундах. Значение 0 задаст ожидание без ограничения времени со стороны команды.

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

   Если все множества отсутствуют, соединение будет ожидать, пока участник добавится другим клиентом. При истечении таймаута без появления участника вернется nil. Ожидание заблокирует текущее соединение, но другие клиенты смогут выполнять команды. После извлечения последнего участника ключ сортированного множества будет удален.

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

• ZREMRANGEBYRANK — удалить участников по рангам;
• ZREMRANGEBYSCORE — удалить участников по весу.

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

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

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

4. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

5. Проверьте участников диапазона. Состав множества мог измениться между чтением и удалением.

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

   • ZREMRANGEBYRANK
   • ZREMRANGEBYSCORE

   1
   ZREMRANGEBYRANK <имя ключа> <начало> <конец>

   Ранги отсчитываются от 0 по возрастанию веса. Отрицательные значения задают позиции от конца, например -1 — последнюю позицию. Обе границы будут включены.

   1
   ZREMRANGEBYSCORE <имя ключа> <минимальный вес> <максимальный вес>

   Обе границы будут включены. Для исключения границы поставьте перед числом (, например (10. Значения -inf и +inf обозначают отсутствие нижнего и верхнего ограничения.

   Команда вернет количество удаленных участников. Если ключ не существует или диапазон не содержит участников, команда вернет 0. После удаления всех участников ключ сортированного множества будет удален.

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

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

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

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

4. Убедитесь, что значение ключа — сортированное множество. Должно вернуться значение zset.

5. Узнайте имена участников.

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

   1
   ZREM <имя ключа> <участник 1> [<участник 2> ...]

   Команда удалит указанных участников и вернет количество удаленных участников. Несуществующие участники будут пропущены. Если ключ не существует, команда вернет 0. После удаления последнего участника ключ сортированного множества будет удален.