ZADD

ZADD

ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member
  ...]

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

1.2.0

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

O(log(N)) для каждого добавленного элемента, где N — количество элементов в отсортированном множестве.

Категории ACL:

@write, @sortedset, @fast,

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

Если key не существует, создается новое отсортированное множество с указанными элементами в качестве единственных элементов, как если бы отсортированное множество было пустым. Если ключ существует, но не содержит отсортированное множество, возвращается ошибка.

Значения оценок должны быть строковым представлением числа двойной точности с плавающей запятой. Значения +inf и -inf также являются допустимыми значениями.

Параметры ZADD

ZADD поддерживает список параметров, указанных после имени ключа и перед первым аргументом оценки. Параметры:

• XX: Обновить только существующие элементы. Не добавлять новые элементы.
• NX: Добавить только новые элементы. Не обновлять уже существующие элементы.
• LT: Обновить существующие элементы только в том случае, если новая оценка меньше текущей оценки. Этот флаг не препятствует добавлению новых элементов.
• GT: Обновить существующие элементы только в том случае, если новая оценка больше текущей оценки. Этот флаг не препятствует добавлению новых элементов.
• CH: Изменить возвращаемое значение с количества новых элементов, добавленных в общее количество изменённых элементов (CH — аббревиатура от изменённых). Изменённые элементы — это новые добавленные элементы и элементы, которые уже существовали, для которых оценка была обновлена. Элементы, указанные в командной строке и имеющие ту же оценку, что и ранее, не учитываются. Примечание: обычно возвращаемое значение ZADD учитывает только количество добавленных новых элементов.
• INCR: Когда этот параметр указан, ZADD действует как ZINCRBY. В этом режиме может быть указана только одна пара оценка-элемент.

Примечание: параметры GT, LT и NX являются взаимоисключающими.

Диапазон целых оценок, которые можно точно выразить

Отсортированные множества Redis используют число с плавающей запятой двойной точности 64-битное для представления оценки. Во всех поддерживаемых нами архитектурах это представлено как число с плавающей запятой IEEE 754, которое может точно представлять целые числа между -(2^53) и +(2^53) включительно. Более практично, все целые числа между -9007199254740992 и 9007199254740992 идеально представляются. Большие целые числа или дроби в памяти представлены в экспоненциальной форме, поэтому возможно, что вы получите только приближение десятичного числа или очень большого целого числа, которое вы установили как оценку.

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

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

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

Для знакомства с отсортированными множествами см. страницу типов данных на отсортированных множествах.

Элементы с одинаковой оценкой

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

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

Если пользователь вставляет все элементы в отсортированное множество с одинаковой оценкой (например, 0), все элементы отсортированного множества сортируются лексикографически, и запросы диапазонов на элементы возможны с помощью команды ZRANGEBYLEX (Примечание: также можно запросить отсортированные множества по диапазону оценок, используя ZRANGEBYSCORE).

Возврат

Целочисленный ответ, в частности:

• При использовании без дополнительных аргументов — количество элементов, добавленных в отсортированное множество (без учёта обновлений оценок).
• Если указан параметр CH, количество элементов, которые были изменены (добавлено или обновлено).

Если указан параметр INCR, возвращаемое значение будет Строковым ответом:

• Новая оценка member (число двойной точности с плавающей запятой) представлена в виде строки или nil, если операция была прервана (при вызове с параметром XX или NX).

Примеры

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

История

• Начиная с версии Redis 2.4.0: Принимает несколько элементов.
• Начиная с версии Redis 3.0.2: Добавлены параметры XX, NX, CH и INCR.
• Начиная с версии Redis 6.2.0: Добавлены параметры GT и LT.