BITCOUNT

Syntax text Syntax diagram API methods

BITCOUNT key [start end [BYTE | BIT]]

Client:

bitcount(
    key: KeyT,
    start: Optional[int] = None,
    end: Optional[int] = None,
    mode: Optional[str] = None
) → ResponseT

BITCOUNT(
    key: RedisArgument,
    range?: BitCountRange
) → Any

bitcount(
    key: byte[]
) → long  // OK

bitcount(
    key: byte[],
    start: long,
    end: long
) → long  // OK

bitcount(
    key: byte[],
    start: long,
    end: long,
    option: BitCountOption
) → long  // OK

bitcount(
    key: String
) → long  // OK

bitcount(
    key: String,
    start: long,
    end: long
) → long  // OK

bitcount(
    key: K  // the key.
) → Long  // Long integer-reply The number of bits set to 1.

bitcount(
    key: K,  // the key.
    start: long,  // the start.
    end: long  // the end.
) → Long  // Long integer-reply The number of bits set to 1.

bitcount(
    key: K  // the key.
) → RedisFuture<Long>  // Long integer-reply The number of bits set to 1.

bitcount(
    key: K,  // the key.
    start: long,  // the start.
    end: long  // the end.
) → RedisFuture<Long>  // Long integer-reply The number of bits set to 1.

bitcount(
    key: K  // the key.
) → Mono<Long>  // Long integer-reply The number of bits set to 1.

bitcount(
    key: K,  // the key.
    start: long,  // the start.
    end: long  // the end.
) → Mono<Long>  // Long integer-reply The number of bits set to 1.

BitCount(
    ctx: context.Context,
    key: string,
    bitCount: *BitCount
) → *IntCmd

StringBitCount(
    key: RedisKey,  // The key of the string.
    start: long,  // The start byte to count at.
    end: long,  // The end byte to count at.
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The number of bits set to 1.

StringBitCount(
    key: RedisKey,  // The key of the string.
    start: long,  // The start byte to count at.
    end: long,  // The end byte to count at.
    indexType: StringIndexType,  // In Redis 7+, we can choose if start and end specify a bit index or byte index (defaults to Byte).
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The number of bits set to 1.

StringBitCountAsync(
    key: RedisKey,
    start: long,
    end: long,
    flags: CommandFlags
) → Task<long>

StringBitCountAsync(
    key: RedisKey,
    start: long,
    end: long,
    indexType: StringIndexType,
    flags: CommandFlags
) → Task<long>

StringBitCount(
    key: RedisKey,  // The key of the string.
    start: long,  // The start byte to count at.
    end: long,  // The end byte to count at.
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The number of bits set to 1.

StringBitCountAsync(
    key: RedisKey,
    start: long,
    end: long,
    flags: CommandFlags
) → Task<long>

StringBitCountAsync(
    key: RedisKey,
    start: long,
    end: long,
    indexType: StringIndexType,
    flags: CommandFlags
) → Task<long>

StringBitCount(
    key: RedisKey,  // The key of the string.
    start: long,  // The start byte to count at.
    end: long,  // The end byte to count at.
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The number of bits set to 1.

StringBitCount(
    key: RedisKey,  // The key of the string.
    start: long,  // The start byte to count at.
    end: long,  // The end byte to count at.
    indexType: StringIndexType,  // In Redis 7+, we can choose if start and end specify a bit index or byte index (defaults to Byte).
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The number of bits set to 1.

StringBitCount(
    key: RedisKey,  // The key of the string.
    start: long,  // The start byte to count at.
    end: long,  // The end byte to count at.
    flags: CommandFlags  // The flags to use for this operation.
) → long  // The number of bits set to 1.

bitcount(
    $key: string,
    $start = null: Any,
    $end = null: Any,
    string $index = 'byte': Any
) → int

bitcount(
    key: K
) → (usize)

bitcount_range(
    key: K,
    start: usize,
    end: usize
) → (usize)

bitcount(
    key: K
) → (usize)

bitcount_range(
    key: K,
    start: usize,
    end: usize
) → (usize)

Available since:: Redis Open Source 2.6.0
Time complexity:: O(N)
ACL categories:: @read, @bitmap, @slow,
Compatibility:: Redis Software and Redis Cloud compatibility

Count the number of set bits (population counting) in a string.

By default all the bytes contained in the string are examined. It is possible to specify the counting operation only in an interval passing the additional arguments start and end.

Like for the GETRANGE command start and end can contain negative values in order to index bytes starting from the end of the string, where -1 is the last byte, -2 is the penultimate, and so forth.

Non-existent keys are treated as empty strings, so the command will return zero.

By default, the additional arguments start and end specify a byte index. We can use an additional argument BIT to specify a bit index. So 0 is the first bit, 1 is the second bit, and so forth. For negative values, -1 is the last bit, -2 is the penultimate, and so forth.

Examples

Pattern: real-time metrics using bitmaps

Bitmaps are a very space-efficient representation of certain kinds of information. One example is a Web application that needs the history of user visits, so that for instance it is possible to determine what users are good targets of beta features.

Using the SETBIT command this is trivial to accomplish, identifying every day with a small progressive integer. For instance day 0 is the first day the application was put online, day 1 the next day, and so forth.

Every time a user performs a page view, the application can register that in the current day the user visited the web site using the SETBIT command setting the bit corresponding to the current day.

Later it will be trivial to know the number of single days the user visited the web site simply calling the BITCOUNT command against the bitmap.

A similar pattern where user IDs are used instead of days is described in the article called "Fast easy realtime metrics using Redis bitmaps".

Performance considerations

In the above example of counting days, even after 10 years the application is online we still have just 365*10 bits of data per user, that is just 456 bytes per user. With this amount of data BITCOUNT is still as fast as any other O(1) Redis command like GET or INCR.

When the bitmap is big, there are two alternatives:

Taking a separated key that is incremented every time the bitmap is modified. This can be very efficient and atomic using a small Redis Lua script.
Running the bitmap incrementally using the BITCOUNT start and end optional parameters, accumulating the results client-side, and optionally caching the result into a key.

Redis Software and Redis Cloud compatibility

Redis Software	Redis Cloud	Notes
✅ Standard ✅ Active-Active	✅ Standard ✅ Active-Active

Return information

RESP2 RESP3

Integer reply: the number of bits set to 1.

History

Starting with Redis version 7.0.0: Added the BYTE|BIT option.

Products

Tools

Get Redis

Connect

Learn

Latest

See how it works