SETRANGE(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

💖 SETRANGE — the valkey command manual, but make it make sense 💖

okay bestie, welcome to valkey(3valkey) lore. today's episode: SETRANGE. buckle up 🎀

✨ NAME ✨

setrange — overwrites a part of a string value with another by an offset. creates the key if it doesn't exist. it's giving "surgical strike but make it cute" 💅

🌸 SYNOPSIS 🌸

SETRANGE key offset value

🦋 DESCRIPTION 🦋

so basically, it overwrites part of the string stored at key, starting at the specified offset, for the entire length of value. that's it. that's the whole vibe.

but here's the part that's lowkey important: if offset is larger than the current length of the string at key, the string gets padded with zero-bytes to make offset fit. yes, zero-bytes. yes, invisible little \x00 girlies. they're just living there now. 🫶

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. it will not ghost you — it builds the whole runway first. ✈️✨

okay important: the maximum offset you can set is 2^29 -1 (536870911), because Valkey Strings are limited to 512 megabytes. if you need to grow beyond this size, you can use multiple keys. that's the workaround, that's the tea. 🍵
⚠️ WARNING, and I mean this with my whole chest: 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, Valkey needs to allocate all intermediate memory which can block the server for some time. no cap, this one's real. here are the receipts from 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 - setting bit number 8388608 (8MB allocation) takes ~8ms 💀 and note that once this first allocation is done, subsequent calls to SETRANGE for the same key will not have the allocation overhead. so it's a one-time entrance fee, basically. main character tax. 👑

🌈 Patterns

thanks to SETRANGE and the analogous GETRANGE commands, you can use Valkey strings as a linear array with O(1) random access. iconic behaviour honestly. this is a very fast and efficient storage in many real world use cases. not me being obsessed with a string command 😭

💌 REPLY 💌

valkey-protocol(7) Integer reply: the length of the string after it was modified by the command. so you get the glow-up receipt. 🧾✨

⭐ 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. so like, normally instant, but big value = big M = you're waiting. physics. 🙈

👑 ACL CATEGORIES 👑

  • @slow
  • @string
  • @write

🎀 HISTORY 🎀

  • Available since: 2.2.0

she's been here since 2.2.0, a true veteran. respect the elders. 🫡💜

🔥 EXAMPLES 🔥

Basic usage:

127.0.0.1:6379> SET key1 "Hello World"
OK
127.0.0.1:6379> SETRANGE key1 6 "Valkey"
(integer) 12
127.0.0.1:6379> GET key1
"Hello Valkey"

look at that. "Hello World" walked in, "Hello Valkey" walked out. ate and left no crumbs. 💅✨

Example of zero padding:

127.0.0.1:6379> SETRANGE key2 6 "Valkey"
(integer) 12
127.0.0.1:6379> GET key2
"\x00\x00\x00\x00\x00\x00Valkey"

six little zero-bytes just holding space for the word. besties supporting besties. 🫶🦋

🌟 SEE ALSO 🌟

append(3valkey), decr(3valkey), decrby(3valkey), delifeq(3valkey), get(3valkey), getdel(3valkey), getex(3valkey), getrange(3valkey), getset(3valkey), incr(3valkey), incrby(3valkey), incrbyfloat(3valkey), lcs(3valkey), mget(3valkey), mset(3valkey), msetnx(3valkey), psetex(3valkey), set(3valkey), setex(3valkey), setnx(3valkey), strlen(3valkey), substr(3valkey)

okay that's the whole page bestie, you're officially a SETRANGE girlie now 💖✨

this was 9.0.0, dated 2025-10-21, from your friendly neighbourhood SETRANGE(3valkey) manual page. mwah. 😘🎀

📦 where this page comes from