ZRANGE

ZRANGE

ZRANGE key start stop [BYSCORE | BYLEX] [REV] [LIMIT offset count]
  [WITHSCORES]

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

1.2.0

Сложность по времени:

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

Категории ACL:

@read, @sortedset, @slow,

Возвращает указанный диапазон элементов в упорядоченном множестве, хранящемся по адресу <key>.

ZRANGE может выполнять различные типы запросов по диапазону: по индексу (рангу), по баллу или по лексикографическому порядку.

Начиная с Redis 6.2.0, эта команда может заменить следующие команды: ZREVRANGE, ZRANGEBYSCORE, ZREVRANGEBYSCORE, ZRANGEBYLEX и ZREVRANGEBYLEX.

Общее поведение и параметры

Порядок элементов — от самого низкого до самого высокого балла. Элементы с одинаковым баллом упорядочиваются лексикографически.

Необязательный параметр REV меняет порядок, сортируя элементы от самого высокого до самого низкого балла, а при совпадении баллов — по обратному лексикографическому порядку.

Необязательный параметр LIMIT позволяет получить поддиапазон из совпадающих элементов (аналогично SELECT LIMIT offset, count в SQL). Отрицательное значение <count> возвращает все элементы с <offset>. Имейте в виду, что если <offset> велико, упорядоченное множество нужно просмотреть для <offset> элементов, прежде чем получить возвращаемые элементы, что может привести к сложности по времени O(N).

Необязательный параметр WITHSCORES дополняет ответ команды баллами возвращаемых элементов. Возвращаемый список содержит value1,score1,...,valueN,scoreN вместо value1,...,valueN. Библиотеки клиента могут возвращать более подходящий тип данных (предложение: массив с массивами/кортежами (значение, балл)).

Диапазоны индексов

По умолчанию команда выполняет запрос по диапазону индексов. Параметры <start> и <stop> представляют нулевые индексы, где 0 — первый элемент, 1 — следующий и так далее. Эти параметры задают включительно диапазон, поэтому, например, ZRANGE myzset 0 1 вернёт как первый, так и второй элемент упорядоченного множества.

Индексы также могут быть отрицательными числами, обозначающими смещения от конца упорядоченного множества, при этом -1 — последний элемент упорядоченного множества, -2 — предпоследний и так далее.

Индексы вне диапазона не приводят к ошибке.

Если <start> больше, чем конечный индекс упорядоченного множества или <stop>, возвращается пустой список.

Если <stop> больше конечного индекса упорядоченного множества, Redis использует последний элемент множества.

Диапазоны баллов

При использовании параметра BYSCORE команда работает так же, как ZRANGEBYSCORE, и возвращает диапазон элементов из упорядоченного множества, имеющих баллы, равные или находящиеся между <start> и <stop>.

<start> и <stop> могут быть -inf и +inf, обозначающими соответственно отрицательную и положительную бесконечности. Это означает, что вам не нужно знать наибольший или наименьший балл в упорядоченном множестве, чтобы получить все элементы до или начиная с определенного балла.

По умолчанию интервалы баллов, заданные параметрами <start> и <stop> , являются замкнутыми (включительно). Можно задать открытый интервал (исключительно), добавив перед баллом символ (.

Например:

ZRANGE zset (1 5 BYSCORE

Вернёт все элементы с 1 < score <= 5 , а:

ZRANGE zset (5 (10 BYSCORE

Вернёт все элементы с 5 < score < 10 (5 и 10 исключены).

Обратные диапазоны

Использование параметра REV переворачивает упорядоченное множество, при этом индекс 0 соответствует элементу с наибольшим баллом.

По умолчанию, <start> должно быть меньше или равно <stop> для возврата чего-либо. Однако, если выбраны параметры BYSCORE, или BYLEX, то <start> является наибольшим рассматриваемым баллом, а <stop> — наименьшим, поэтому <start> должно быть больше или равно <stop> для возврата чего-либо.

Например:

ZRANGE zset 5 10 REV

Вернёт элементы между индексами 5 и 10 в обратном порядке индексов.

ZRANGE zset 10 5 REV BYSCORE

Вернёт все элементы с баллами меньше 10 и больше 5.

Лексикографические диапазоны

При использовании параметра BYLEX команда работает так же, как ZRANGEBYLEX, и возвращает диапазон элементов из упорядоченного множества между лексикографическими замкнутыми интервалами <start> и <stop>.

Обратите внимание, что лексикографический порядок зависит от того, что все элементы имеют одинаковый балл. Ответ не определен, когда у элементов разные баллы.

Допустимые значения <start> и <stop> должны начинаться с ( или [, чтобы указать, является ли интервал диапазона исключительным или включительно, соответственно.

Специальные значения + или - для <start> и <stop> означают положительные и отрицательные бесконечные строки соответственно, так что, например, команда ZRANGE myzset - + BYLEX гарантированно вернёт все элементы в упорядоченном множестве, при условии, что у всех элементов одинаковый балл.

Параметр REV меняет порядок элементов <start> и <stop>, где <start> должен быть лексикографически больше <stop> для получения непустого результата.

Лексикографическое сравнение строк

Строки сравниваются как бинарный массив байтов. Из-за способа задания набора символов ASCII, это обычно также означает сравнение обычных символов ASCII в очевидном словаре. Однако это неверно, если используются строки не из обычного ASCII (например, utf8 строки).

Однако пользователь может применить преобразование к закодированной строке, чтобы первая часть вставленного элемента в упорядоченное множество сравнивалась так, как необходимо для конкретного приложения. Например, если нужно добавить строки, которые будут сравниваться без учёта регистра, но при запросе необходимо получить исходный регистр, строки можно добавить следующим образом:

ZADD autocomplete 0 foo:Foo 0 bar:BAR 0 zap:zap

Благодаря первой нормализованной части каждого элемента (перед двоеточием), мы принуждаем определённое сравнение. Однако после запроса диапазона с использованием ZRANGE ... BYLEX, приложение может отобразить пользователю вторую часть строки, после двоеточия.

Бинарный характер сравнения позволяет использовать упорядоченные множества в качестве универсального индекса, например, первой частью элемента может быть 64-битное число в формате big-endian. Так как числа big-endian имеют наиболее значимые байты в начальных позициях, бинарное сравнение будет соответствовать числовому сравнению чисел. Это можно использовать для реализации запросов по диапазонам 64-битных значений. Как в примере ниже, после первых 8 байтов, мы можем сохранить значение элемента, который мы индексируем.

Возврат

Массив ответов: список элементов в указанном диапазоне (при необходимости с их баллами, если задан параметр WITHSCORES).

Примеры

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZRANGE myzset 0 -1
ZRANGE myzset 2 3
ZRANGE myzset -2 -1

Следующий пример с использованием WITHSCORES демонстрирует, как команда всегда возвращает массив, но на этот раз заполненный element_1, score_1, element_2, score_2, ..., element_N, score_N.

ZRANGE myzset 0 1 WITHSCORES

Этот пример демонстрирует, как запросить упорядоченное множество по баллам, исключая значение 1 и до бесконечности, возвращая только второй элемент результата:

ZRANGE myzset (1 +inf BYSCORE LIMIT 1 1

История

• Начиная с версии Redis 6.2.0: добавлены параметры REV, BYSCORE, BYLEX и LIMIT.