PFADD - Upstash Documentation

Use PFADD to add elements to a HyperLogLog. A HyperLogLog estimates how many distinct items it has seen while using a small, fixed amount of memory (at most about 12 KB) no matter how many elements pass through it. That is the trade it makes: individual elements are not stored, so they cannot be listed, checked for membership, or removed, and the cardinality that comes back from PFCOUNT is an approximation with a standard error of about 0.81%. The key is created on first use, and the reply is 1 when the internal registers changed as a result of the call, which is a hint that at least one element was new, and 0 when they did not. Calling PFADD with no elements creates an empty HyperLogLog if the key does not exist yet. Use it for counts where the exact number does not matter, such as unique visitors per page or per day, and a set for cases where you must be able to look elements up.

Syntax

PFADD <key> [<element> [<element> ...]]

Arguments

Argument	Required	Repeatable	Description
`<key>`	Yes	No	Redis key targeted by the command.
`<element>`	No	Yes	Element to add to the HyperLogLog.

Response

The reply reports the result of the operation. Error replies have the same shape in RESP2 and RESP3 and are surfaced as exceptions by the SDKs below.

Protocol	Reply
RESP2	Integer: `1` if at least one internal register was altered, `0` otherwise
RESP3	Integer: `1` if at least one internal register was altered, `0` otherwise

Client libraries often decode bulk strings, maps, sets, and numeric strings into language-native values. The table describes the Redis wire reply.

Examples

TCP examples use the TLS REDIS_URL from the Upstash console. REST examples use UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.

Redis CLI

PFADD my-key element

@upstash/redis

import { Redis } from "@upstash/redis";

const redis = Redis.fromEnv();
const result = await redis.pfadd("my-key", "element");
console.log(result);

upstash_redis

from upstash_redis import Redis

redis = Redis.from_env()
result = redis.pfadd("my-key", "member")
print(result)

ioredis

import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL!);
const result = await redis.pfadd("my-key", "element");
console.log(result);

node-redis

import { createClient } from "redis";

const client = await createClient({ url: process.env.REDIS_URL })
  .on("error", console.error)
  .connect();
const result = await client.pfAdd("my-key", "element");
console.log(result);

redis-py

import os
import redis

client = redis.from_url(os.environ["REDIS_URL"])
result = client.pfadd("my-key", "member")
print(result)

go-redis

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/redis/go-redis/v9"
)

func main() {
    opts, err := redis.ParseURL(os.Getenv("REDIS_URL"))
    if err != nil {
        panic(err)
    }
    client := redis.NewClient(opts)
    result, err := client.PFAdd(context.Background(), "my-key").Result()
    if err != nil {
        panic(err)
    }
    fmt.Println(result)
}

jedis

import java.net.URI;

import redis.clients.jedis.Jedis;

try (Jedis jedis = new Jedis(new URI(System.getenv("REDIS_URL")))) {
  Object result = jedis.pfadd("my-key");
  System.out.println(result);
}

redis-rs

use redis::TypedCommands;

fn main() -> redis::RedisResult<()> {
    let url = std::env::var("REDIS_URL").expect("REDIS_URL is not set");
    let client = redis::Client::open(url)?;
    let mut connection = client.get_connection()?;

    let result = connection.pfadd("my-key", &["member"])?;
    println!("{result:?}");
    Ok(())
}

​Syntax

​Arguments

​Response

​Examples

Syntax

Arguments

Response

Examples