Command: NUM.INCR

Overview

The NUM.INCR command increments a numeric value associated with a key. If the key does not exist, it sets the key to the given value (or to 1 by default). This command supports both integer and floating-point numbers.

Command Name

NUM.INCR

Description

NUM.INCR retrieves the value associated with a key, adds the specified increment (default is 1), and stores the result back. If the key does not exist, it initializes the key with the increment value. The command supports numeric data types only (integers and floats).

Use Cases

  • Incrementing counters

  • Tracking numerical metrics (e.g., page visits, scores)

  • Performing atomic add operations in a concurrent environment

Syntax 

  localhost:9219> NUM.INCR <key> [increment]

  • <key> : Required. The key whose value needs to be incremented.

  • [increment] : Optional. The numeric value to increment by. Defaults to 1 if omitted.

Permissions

  • Write access to the specified key.

  • Internal shard resolution and write-ahead log access are required.

Input Examples

Basic increment 
  localhost:9219> NUM.SET myNumber 42
Ok

localhost:9219> NUM.INCR myNumber
Ok 43
Increment by specific value 
  localhost:9219> NUM.INCR myNumber 10
Ok 53
Floating-point operations 
  localhost:9219> NUM.SET myNumber 11.5
Ok

localhost:9219> NUM.INCR myNumber
Ok 12.5

localhost:9219> NUM.INCR myNumber 0.5
Ok 13

Output Examples

Example1 
  localhost:9219> NUM.SET myNumber 42
Ok
Example2 
  localhost:9219> NUM.INCR myNumber
Ok 43
Example3 
  localhost:9219> NUM.INCR myNumber 10
Ok 53
Example4 
  localhost:9219> NUM.SET myNumber 11.5
Ok
Example4 
  localhost:9219> NUM.INCR myNumber
Ok 12.5
Example5 
  localhost:9219> NUM.INCR myNumber 0.5
Ok 13

Behavior on Error

The command may fail in the following scenarios:

Error Type Description
InvalidKeyError If the key is missing or not a valid key format
InvalidArgsError If more than 2 arguments are passed
InvalidValueError If the existing key is not numeric or the increment value is not a valid number