#sidebar StringCommandsSidebar

SETRANGE _key_ _offset_ _value_ (Redis >

2.1.8) = Time complexity: O(1) not counting the time taken to copy the new string in place, as usually this string is small so the amoritzed time is O(1). Otheriwse O(M) with M being the length of the value argument

Overwrites part of a string at key starting at the specified offset,for all the length of value.If the offset is over the old length of the string, the string is paddedwith zero bytes until needed. Non existing keys are considered likealready containing an empty string.

Examples

First example, basic usage setting a range.

redis> set foo "Hello World"
OK
redis> setrange foo 6 "Redis"
(integer) 11
redis> get foo
"Hello Redis"

Example of the zero padding behavior.

redis> del foo
(integer) 1
redis> setrange foo 10 bar
(integer) 13
redis> get foo
"\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00bar"

Note that the maximum offset that you can set is 536870911 as Redis Strings are limited to 512 megabytes. You can still create longer arrays of values using 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. On a 2010 Macbook Pro, setting byte number 536870911 (512MB allocation) takes ~300ms, setting byte number 134217728 (128MB allocation) takes ~80ms, setting bit number 33554432 (32MB allocation) takes ~30ms and setting bit number 8388608 (8MB allocation) takes ~8ms. Note that once this first allocation is done, subsequent calls to SETRANGE for the same key will not have the allocation overhead.

Patterns

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

Return value

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