SETRANGE

Syntax text Syntax diagram API methods

SETRANGE key offset value

Client:

setrange(
    name: KeyT,
    offset: int,
    value: EncodableT
) → ResponseT

SETRANGE(
    key: RedisArgument,
    offset: number,
    value: RedisArgument
) → Any

setrange(
    key: byte[],
    offset: long,
    value: byte[]
) → long

setrange(
    key: String,
    offset: long,
    value: String
) → long

setrange(
    key: K,  // the key.
    offset: long,  // the offset type: long.
    value: V  // the value.
) → Long  // Long integer-reply the length of the string after it was modified by the command.

setrange(
    key: K,  // the key.
    offset: long,  // the offset type: long.
    value: V  // the value.
) → RedisFuture<Long>  // Long integer-reply the length of the string after it was modified by the command.

setrange(
    key: K,  // the key.
    offset: long,  // the offset type: long.
    value: V  // the value.
) → Mono<Long>  // Long integer-reply the length of the string after it was modified by the command.

SetRange(
    ctx: context.Context,
    key: string,
    offset: int64,
    value: string
) → *IntCmd

StringSetRange(
    key: RedisKey,  // The key of the string.
    offset: long,  // The offset in the string to overwrite.
    value: RedisValue,  // The value to overwrite with.
    flags: CommandFlags  // The flags to use for this operation.
) → RedisValue  // The length of the string after it was modified by the command.

StringSetRange(
    key: RedisKey,  // The key of the string.
    offset: long,  // The offset in the string to overwrite.
    value: RedisValue,  // The value to overwrite with.
    flags: CommandFlags  // The flags to use for this operation.
) → RedisValue  // The length of the string after it was modified by the command.

StringSetRange(
    key: RedisKey,  // The key of the string.
    offset: long,  // The offset in the string to overwrite.
    value: RedisValue,  // The value to overwrite with.
    flags: CommandFlags  // The flags to use for this operation.
) → RedisValue  // The length of the string after it was modified by the command.

StringSetRange(
    key: RedisKey,  // The key of the string.
    offset: long,  // The offset in the string to overwrite.
    value: RedisValue,  // The value to overwrite with.
    flags: CommandFlags  // The flags to use for this operation.
) → RedisValue  // The length of the string after it was modified by the command.

setrange(
    $key: string,
    $offset: Any,
    $value: Any
) → int

setrange(
    key: K,
    offset: isize,
    value: V
) → (usize)

setrange(
    key: K,
    offset: isize,
    value: V
) → (usize)

Available since:: Redis Open Source 2.2.0
Time complexity:: O(1), not counting the time taken to copy the new string in place. Usually, this string is very small so the amortized complexity is O(1). Otherwise, complexity is O(M) with M being the length of the value argument.
ACL categories:: @write, @string, @slow,
Compatibility:: Redis Software and Redis Cloud compatibility

Overwrites part of the string stored at key, starting at the specified offset, for the entire length of value. If the offset is larger than the current length of the string at key, the string is padded with zero-bytes to make offset fit. Non-existing keys are considered as empty strings, so this command will make sure it holds a string large enough to be able to set value at offset.

Note that the maximum offset that you can set is 2^29 -1 (536870911), as Redis strings are limited to 512 megabytes. If you need to grow beyond this size, you can use multiple keys.

Warning: When setting the last possible byte and the string value stored at key does not yet hold a string value, or holds a small string value, Redis needs to allocate all intermediate memory which can block the server for some time.

Note that once the first allocation is done, subsequent calls to SETRANGE for the same key will not have the allocation overhead.

Required arguments

key

The name of the key.

offset

The zero-based offset at which to start overwriting. The string is zero-padded if the offset is beyond the current length.

value

The string to write at the offset.

Examples

Basic usage:

Example of zero padding:

Details

Patterns

Thanks to SETRANGE and the analogous GETRANGE commands, you can use Redis strings as a linear array with O(1) random access. This is a very fast and efficient storage in many real world use cases.

Redis Software and Redis Cloud compatibility

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

Return information

RESP2 RESP3

Integer reply: the length of the string after it was modified by the command.