JSON.NUMINCRBY

Increment a number in a JSON document

Increments the numeric value at the specified path by a given amount. Supports both integers and floating-point numbers.

Usage

const newValue = await redis.json.numincrby("user:123", "$.score", 10);

Arguments

key · string · required

The key containing the JSON document

path · string · required

JSONPath expression pointing to the numeric value to increment

value · number · required

The increment value. Can be positive (to increase) or negative (to decrease). Supports both integers and floating-point numbers.

Response

result · (number | null)[]

An array of numbers representing the new value at each matching path after the increment. Returns null for paths that don’t exist or aren’t numeric values.

Examples

Increment an integer

// Initial: { "score": 100 }
const newScore = await redis.json.numincrby("user:123", "$.score", 50);
console.log(newScore); // [150]

// Result: { "score": 150 }

Decrement by using negative value

// Initial: { "balance": 1000 }
const newBalance = await redis.json.numincrby("account:456", "$.balance", -250);
console.log(newBalance); // [750]

// Result: { "balance": 750 }

Increment a floating-point number

// Initial: { "price": 19.99 }
const newPrice = await redis.json.numincrby("product:789", "$.price", 5.50);
console.log(newPrice); // [25.49]

// Result: { "price": 25.49 }

Increment nested numeric value

interface UserStats {
  profile: {
    name: string;
    stats: {
      points: number;
      level: number;
    };
  };
}

const newPoints = await redis.json.numincrby(
  "user:123",
  "$.profile.stats.points",
  100
);
console.log(newPoints); // [1100]

Increment multiple values (wildcard path)

// Initial: {
//   "products": [
//     { "id": 1, "stock": 10 },
//     { "id": 2, "stock": 5 }
//   ]
// }

const newStocks = await redis.json.numincrby(
  "inventory:1",
  "$.products[*].stock",
  -1
);
console.log(newStocks); // [9, 4]

// Result: All product stocks decreased by 1

Increment with decimal precision

// Useful for currency calculations
const newTotal = await redis.json.numincrby(
  "order:123",
  "$.total",
  0.01
);
console.log(newTotal); // [99.99]

Track counter

// Increment page view counter
const views = await redis.json.numincrby(
  "analytics:homepage",
  "$.views",
  1
);
console.log(`Total views: ${views[0]}`);

Handle non-existent paths

const result = await redis.json.numincrby(
  "user:123",
  "$.nonexistent",
  10
);
console.log(result); // [null]

Handle non-numeric values

// Initial: { "name": "Alice" }
const result = await redis.json.numincrby(
  "user:123",
  "$.name",
  10
);
console.log(result); // [null] - cannot increment a string

JSONPath Syntax

• $.number - Increment a top-level number
• $.nested.number - Increment a nested number
• $.object.count - Increment a number within an object
• $..count - Increment all matching numbers recursively
• $.items[*].quantity - Increment numbers within each item

Notes

• The operation is atomic - the increment happens as a single operation
• Both integers and floating-point numbers are supported
• Negative values can be used to decrement
• Returns null if the path doesn’t exist or doesn’t point to a numeric value
• When using wildcard paths, the operation is performed on all matching numeric values
• Floating-point arithmetic follows standard IEEE 754 rules

See Also

• JSON.SET - Set JSON values
• JSON.GET - Get JSON values
• Redis JSON.NUMINCRBY documentation