XADD

XADD

XADD key [NOMKSTREAM] [<MAXLEN | MINID> [= | ~] threshold
  [LIMIT count]] <* | id> field value [field value ...]

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

5.0.0

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

O(1) при добавлении новой записи, O(N) при обрезке, где N — количество удаленных записей.

Категории ACL:

@write, @stream, @fast,

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

Запись состоит из списка пар «поле-значение». Пари «поле-значение» хранятся в том же порядке, в котором они были заданы пользователем. Команды, которые считывают поток, такие как XRANGE или XREAD, гарантированно возвращают поля и значения в том же порядке, в котором они были добавлены с помощью XADD.

XADD — единственная команда Redis, которая может добавлять данные в поток, но существуют и другие команды, такие как XDEL и XTRIM, которые могут удалять данные из потока.

Указание идентификатора потока в качестве аргумента

Идентификатор записи потока идентифицирует данную запись внутри потока.

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

Идентификаторы задаются двумя числами, разделенными символом -:

1526919030474-55

Оба значения являются 64-разрядными числами. Когда идентификатор генерируется автоматически, первая часть — это время Unix в миллисекундах экземпляра Redis, генерирующего идентификатор. Вторая часть — это просто порядковый номер, используемый для различения идентификаторов, сгенерированных в одну и ту же миллисекунду.

Вы также можете указать неполный идентификатор, состоящий только из части миллисекунд, которая интерпретируется как нулевое значение для части последовательности. Чтобы автоматически сгенерировать только часть последовательности, укажите часть миллисекунд, за которой следует разделитель - и символ *.

> XADD mystream 1526919030474-55 message "Hello,"
"1526919030474-55"
> XADD mystream 1526919030474-* message " World!"
"1526919030474-56"

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

Когда пользователь указывает явный идентификатор команде XADD, минимальный допустимый идентификатор — 0-1, и пользователь *должен* указать идентификатор, который больше, чем любой другой идентификатор в настоящее время в потоке, в противном случае команда завершится ошибкой. Обычно обращение к конкретным идентификаторам полезно только если у вас есть другая система, генерирующая уникальные идентификаторы (например, таблица SQL), и вы действительно хотите, чтобы идентификаторы потока Redis совпадали с идентификаторами этой другой системы.

Потоки с ограничением

XADD использует те же семантику, что и команда XTRIM — обратитесь к странице документации для получения дополнительной информации. Это позволяет добавлять новые записи и контролировать размер потока одним вызовом XADD, эффективно ограничивая поток произвольным порогом. Хотя точная обрезка возможна и является значением по умолчанию, из-за внутренней структуры потоков более эффективно добавить запись и обрезать поток с помощью XADD используя почти точную обрезку (аргумент ~).

Например, вызов XADD в следующем формате:

XADD mystream MAXLEN ~ 1000 * ... entry fields here ...

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

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

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

Возврат

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

Команда возвращает идентификатор добавленной записи. Идентификатор — это автоматически сгенерированный идентификатор, если * передан в качестве аргумента идентификатора, в противном случае команда просто возвращает тот же идентификатор, который был задан пользователем при вставке.

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

Примеры

XADD mystream * name Sara surname OConnor
XADD mystream * field1 value1 field2 value2 field3 value3
XLEN mystream
XRANGE mystream - +

История

• Начиная с версии Redis 6.2.0: добавлен параметр NOMKSTREAM, стратегия обрезки MINID и параметр LIMIT.
• Начиная с версии Redis 7.0.0: добавлена поддержка явного формата идентификатора <ms>-*.