> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ZADD

> Add a member to a sorted set, or update its score if it already exists.

## Arguments

<ParamField body="key" type="str" required>
  The key of the sorted set.
</ParamField>

<ParamField body="scores" type="Dict[str, float]" required>
  A dictionary of elements and their scores.
</ParamField>

<ParamField body="xx" type="bool">
  Only update elements that already exist. Never add elements.
</ParamField>

<ParamField body="nx" type="bool">
  Only add new elements. Never update elements.
</ParamField>

<ParamField body="gt" type="bool">
  Update scores if the new score is greater than the old score.
</ParamField>

<ParamField body="lt" type="bool">
  Update scores if the new score is less than the old score.
</ParamField>

<ParamField body="ch" type="bool">
  Return the number of elements changed instead.
</ParamField>

<ParamField body="incr" type="bool">
  When this option is specified `ZADD` acts like `ZINCRBY`. Only one score-element pair can be specified in this mode.
</ParamField>

## Response

<ResponseField type="int" required>
  The number of elements added to the sorted sets, not including elements already existing for which the score was updated.

  If `ch` was specified, the number of elements that were updated.

  If `incr` was specified, the new score of `member`.
</ResponseField>

<RequestExample>
  ```py Simple theme={"system"}
  # Add three elements
  assert redis.zadd("myset", {
      "one": 1,
      "two": 2,
      "three": 3
  }) == 3

  # No element is added since "one" and "two" already exist
  assert redis.zadd("myset", {
      "one": 1,
      "two": 2
  }, nx=True) == 0

  # New element is not added since it does not exist
  assert redis.zadd("myset", {
      "new-element": 1
  }, xx=True) == 0

  # Only "three" is updated since new score was greater
  assert redis.zadd("myset", {
      "three": 10, "two": 0
  }, gt=True) == 1

  # Only "three" is updated since new score was greater
  assert redis.zadd("myset", {
      "three": 10,
      "two": 0
  }, gt=True) == 1
  ```
</RequestExample>