XRANGE

XRANGE

XRANGE key start end [COUNT count]

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

5.0.0

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

O(N), где N — количество возвращаемых элементов. Если N является константой (например, всегда запрашиваются первые 10 элементов с помощью COUNT), можно считать её O(1).

Категории ACL:

@read, @stream, @slow,

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

Команда XRANGE имеет ряд применений:

• Возвращение элементов в определенном временном диапазоне. Это возможно, поскольку идентификаторы потока связаны со временем.
• Итерация по потоку инкрементально, возвращая всего несколько элементов на каждой итерации. Однако она семантически гораздо более надежна, чем семейство функций SCAN.
• Получение одной записи из потока, предоставив идентификатор записи дважды: в качестве начала и конца интервала запроса.

Команда также имеет обратную команду, возвращающую элементы в обратном порядке, под названием XREVRANGE, которая в остальном идентична.

- и + специальные идентификаторы

Специальные идентификаторы - и + означают соответственно минимальный возможный идентификатор и максимальный возможный идентификатор внутри потока, поэтому следующая команда вернёт все записи в потоке:

> XRANGE somestream - +
1) 1) 1526985054069-0
   2) 1) "duration"
      2) "72"
      3) "event-id"
      4) "9"
      5) "user-id"
      6) "839248"
2) 1) 1526985069902-0
   2) 1) "duration"
      2) "415"
      3) "event-id"
      4) "2"
      5) "user-id"
      6) "772213"
... other entries here ...

Специальные идентификаторы - и + означают соответственно минимальный и максимальный идентификаторы диапазона, но они удобнее для ввода.

Неполные идентификаторы

Идентификаторы потока состоят из двух частей: метки времени в миллисекундах Unix и порядкового номера для записей, вставленных в ту же миллисекунду. Можно использовать XRANGE, указывая только первую часть идентификатора, метку времени в миллисекундах, как в следующем примере:

> XRANGE somestream 1526985054069 1526985055069

В этом случае XRANGE автоматически дополнит начальный интервал значением -0 и конечный интервал значением -18446744073709551615, чтобы вернуть все записи, которые были сгенерированы между заданной миллисекундой и концом другой заданной миллисекунды. Это также означает, что при повторении одной и той же миллисекунды дважды мы получим все записи в течение этой миллисекунды, поскольку диапазон порядковых номеров будет от нуля до максимального.

Используемый таким образом XRANGE работает как команда запроса диапазона для получения записей в заданное время. Это очень удобно для доступа к истории прошлых событий в потоке.

Исключающие диапазоны

Диапазон по умолчанию закрыт (включает), что означает, что ответ может включать записи с идентификаторами, соответствующими начальному и конечному интервалам запроса. Можно указать открытый интервал (исключающий) путём добавления символа ( перед идентификатором. Это полезно для итерации по потоку, как описано ниже.

Возвращение максимального количества записей

Используя опцию COUNT, можно уменьшить количество возвращаемых записей. Это очень важная функция, хотя она может показаться незначительной, поскольку позволяет, например, моделировать операции, такие как дать мне запись, большую или равную следующей:

> XRANGE somestream 1526985054069-0 + COUNT 1
1) 1) 1526985054069-0
   2) 1) "duration"
      2) "72"
      3) "event-id"
      4) "9"
      5) "user-id"
      6) "839248"

В приведенном выше случае запись 1526985054069-0 существует, в противном случае сервер отправил бы нам следующую.

Использование COUNT также является основой для использования XRANGE в качестве итератора.

Итерация по потоку

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

> XRANGE writers - + COUNT 2
1) 1) 1526985676425-0
   2) 1) "name"
      2) "Virginia"
      3) "surname"
      4) "Woolf"
2) 1) 1526985685298-0
   2) 1) "name"
      2) "Jane"
      3) "surname"
      4) "Austen"

Затем вместо повторного начала итерации с -, в качестве начала диапазона используется идентификатор записи последней записи, возвращенной предыдущим вызовом XRANGE в качестве исключающего интервала.

Идентификатор последней записи — 1526985685298-0, поэтому мы просто добавляем к нему '(' и продолжаем итерацию:

> XRANGE writers (1526985685298-0 + COUNT 2
1) 1) 1526985691746-0
   2) 1) "name"
      2) "Toni"
      3) "surname"
      4) "Morrison"
2) 1) 1526985712947-0
   2) 1) "name"
      2) "Agatha"
      3) "surname"
      4) "Christie"

И так далее. В конечном итоге это позволит посетить все записи в потоке. Очевидно, мы можем начать итерацию с любого идентификатора или даже со специфического времени, указав начальный неполный идентификатор. Более того, мы можем ограничить итерацию заданным идентификатором или временем, указав конечный идентификатор или неполный идентификатор вместо +.

Команда XREAD также может итерировать по потоку. Команда XREVRANGE может итерировать по потоку в обратном порядке, от более высоких идентификаторов (или времен) к более низким идентификаторам (или временам).

Итерация с более ранними версиями Redis

Хотя исключающие диапазоны доступны только с Redis 6.2, всё ещё возможно использовать аналогичный шаблон итерации по потоку с более ранними версиями. Вы начинаете получение из потока так же, как описано выше, чтобы получить первые записи.

Для последующих вызовов вам необходимо программно продвигать последний возвращенный идентификатор записи. Большинство клиентов Redis должны абстрагировать этот деталь, но реализация также может быть в приложении, если это необходимо. В примере выше это означает увеличение последовательности 1526985685298-0 на единицу, с 0 до 1. Второй вызов, следовательно, будет:

> XRANGE writers 1526985685298-1 + COUNT 2
1) 1) 1526985691746-0
   2) 1) "name"
      2) "Toni"
...

Также обратите внимание, что как только последовательная часть последнего идентификатора достигнет 18446744073709551615, вам нужно будет увеличить метку времени и сбросить последовательную часть до 0. Например, увеличение идентификатора 1526985685298-18446744073709551615 должно привести к 1526985685299-0.

Симметричный шаблон применяется к итерации по потоку с помощью XREVRANGE. Единственное различие заключается в том, что клиенту необходимо уменьшить идентификатор для последующих вызовов. При уменьшении идентификатора с последовательной частью 0 метка времени должна быть уменьшена на 1, а последовательность установлена на 18446744073709551615.

Получение отдельных элементов

Если вы ищете команду XGET, вас разочарует, так как XRANGE фактически является тем, что нужно для получения одной записи из потока. Всё, что вам нужно сделать, это указать идентификатор дважды в аргументах XRANGE:

> XRANGE mystream 1526984818136-0 1526984818136-0
1) 1) 1526984818136-0
   2) 1) "duration"
      2) "1532"
      3) "event-id"
      4) "5"
      5) "user-id"
      6) "7782813"

Дополнительная информация о потоках

Для получения дополнительной информации о потоках Redis ознакомьтесь с нашим документом по введению в потоки Redis.

Возврат

Ответ в формате массива, а именно:

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

Примеры

XADD writers * name Virginia surname Woolf
XADD writers * name Jane surname Austen
XADD writers * name Toni surname Morrison
XADD writers * name Agatha surname Christie
XADD writers * name Ngozi surname Adichie
XLEN writers
XRANGE writers - + COUNT 2

История

• Начиная с версии Redis 6.2.0: добавлены исключающие диапазоны.