JSON.NUMINCRBY

JSON.NUMINCRBY — это команда базы данных Redis, входящая в модуль RedisJSON, предназначенная для атомарного увеличения числового значения, хранящегося в JSON-документе, на заданную величину. Команда относится к категории операций модификации данных и позволяет изменять числовые поля внутри JSON-структур без необходимости извлекать, изменять и записывать весь документ целиком, что обеспечивает высокую производительность и потокобезопасность.

Синтаксис и параметры

Команда JSON.NUMINCRBY имеет следующий синтаксис:

`` JSON.NUMINCRBY <key> <path> <number> ``

• key — ключ Redis, в котором хранится JSON-документ.
• path — путь к числовому полю внутри JSON-документа в формате JSONPath (например, $.price, $.items[0].count). Путь должен указывать на существующее числовое значение.
• number — число (целое или с плавающей точкой), на которое будет увеличено текущее значение. Может быть отрицательным для уменьшения.

Команда возвращает новое значение поля после выполнения операции.

Поведение

JSON.NUMINCRBY выполняет атомарное увеличение числового значения, хранящегося по указанному пути. Если путь указывает на несуществующее поле, команда возвращает ошибку. Если значение по указанному пути не является числом (например, строка, массив или объект), также возвращается ошибка.

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

Примеры использования

Увеличение целого числа

Предположим, в Redis по ключу product:1 хранится следующий JSON-документ:

``json { "name": "Ноутбук", "price": 50000, "stock": 10 } ``

Команда:

`` JSON.NUMINCRBY product:1 $.stock 5 ``

Увеличит значение поля stock на 5, и документ станет:

``json { "name": "Ноутбук", "price": 50000, "stock": 15 } ``

Увеличение числа с плавающей точкой

Если поле price содержит значение 50000, то команда:

`` JSON.NUMINCRBY product:1 $.price 2500.50 ``

Вернёт новое значение 52500.5.

Уменьшение числа

Для уменьшения значения используется отрицательное число:

`` JSON.NUMINCRBY product:1 $.stock -3 ``

Вернёт 12, если исходное значение было 15.

Применение

Команда JSON.NUMINCRBY широко используется в сценариях, где требуется атомарное изменение числовых данных в JSON-документах, хранящихся в Redis. Основные области применения:

• Электронная коммерция: обновление количества товаров на складе, цен, скидок и баллов лояльности.
• Игровая индустрия: изменение очков, уровней, здоровья персонажей или игровой валюты.
• Финансовые системы: обновление балансов счетов, курсов валют, процентных ставок.
• Аналитика и мониторинг: инкрементирование счётчиков событий, времени выполнения, количества запросов.

Атомарность операции гарантирует, что при одновременном выполнении нескольких команд JSON.NUMINCRBY для одного и того же поля не возникнет состояния гонки, и все изменения будут применены последовательно.

Ограничения и особенности

• Команда поддерживает только числовые значения (целые и с плавающей точкой). Попытка применить её к строке, массиву, объекту или логическому значению приводит к ошибке.
• Путь должен указывать на существующее поле. Если поле отсутствует, команда не создаёт его автоматически, в отличие от некоторых других команд RedisJSON (например, JSON.SET).
• При использовании отрицательного числа команда фактически выполняет вычитание, но синтаксически это остаётся операцией увеличения.
• Команда работает с JSON-документами, хранящимися в Redis с использованием модуля RedisJSON. Без установленного модуля команда недоступна.

Сравнение с другими командами

• JSON.NUMINCRBY отличается от JSON.INCRBY (устаревшая команда) тем, что использует синтаксис JSONPath, а не простой путь с точками. В современных версиях RedisJSON рекомендуется использовать JSON.NUMINCRBY с JSONPath.
• В отличие от JSON.SET, которая полностью перезаписывает значение по указанному пути, JSON.NUMINCRBY выполняет инкрементальное изменение, что более эффективно для частых обновлений числовых полей.
• Для атомарного увеличения числовых значений в простых строках Redis (не JSON) используется команда INCRBY.

Производительность

Команда JSON.NUMINCRBY выполняется за O(1) по времени, так как Redis обрабатывает JSON-документы в памяти и модифицирует только указанное поле, не затрагивая остальную структуру. Это делает её одной из самых быстрых операций для изменения числовых данных в JSON-документах.

Безопасность

Команда не требует специальных разрешений, кроме стандартных прав доступа к Redis. Как и все команды Redis, JSON.NUMINCRBY может быть выполнена только авторизованными клиентами. Рекомендуется использовать аутентификацию и шифрование соединений (TLS) в производственных средах.

Источники

• Документация RedisJSON: https://redis.io/docs/latest/commands/json.numincrby/
• RedisJSON GitHub: https://github.com/RedisJSON/RedisJSON
• Redis Commands Reference: https://redis.io/commands/