BuildDocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Mzadd
Bun

method

RedisClient.zadd

key: KeyLike,
...args: string | number[]
): Promise<number>;

Add one or more members to a sorted set, or update scores if they already exist

ZADD adds all the specified members with the specified scores to the sorted set stored at key. It is possible to specify multiple score / member pairs. If a specified member is already a member of the sorted set, the score is updated and the element reinserted at the right position to ensure the correct ordering.

If key does not exist, a new sorted set with the specified members as sole members is created. If the key exists but does not hold a sorted set, an error is returned.

The score values should be the string representation of a double precision floating point number. +inf and -inf values are valid values as well.

Options:

  • NX: Only add new elements. Don't update already existing elements.
  • XX: Only update elements that already exist. Never add elements.
  • GT: Only update existing elements if the new score is greater than the current score. This flag doesn't prevent adding new elements.
  • LT: Only update existing elements if the new score is less than the current score. This flag doesn't prevent adding new elements.
  • CH: Modify the return value from the number of new elements added, to the total number of elements changed (CH is an abbreviation of changed).
  • INCR: When this option is specified ZADD acts like ZINCRBY. Only one score-member pair can be specified in this mode.

Note: The GT, LT and NX options are mutually exclusive.

@param key

The sorted set key

@param args

Score-member pairs and optional flags (NX, XX, GT, LT, CH, INCR)

@returns

Promise that resolves with the number of elements added (or changed if CH is used, or new score if INCR is used)

// Add members with scores
await redis.zadd("myzset", "1", "one", "2", "two", "3", "three");

// Add with NX option (only if member doesn't exist)
await redis.zadd("myzset", "NX", "4", "four");

// Add with XX option (only if member exists)
await redis.zadd("myzset", "XX", "2.5", "two");

// Add with CH option (return count of changed elements)
await redis.zadd("myzset", "CH", "5", "five", "2.1", "two");

// Use INCR option (increment score)
await redis.zadd("myzset", "INCR", "1.5", "one");

Referenced types

type KeyLike = string | ArrayBufferView | Blob