SET(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ NAME ✨

okay so bestie, welcome to the Valkey Command Manual 💖 this one is all about set — it sets the string value of a key, and it literally does not care what type that key used to be 👑 if the key doesn't exist yet, boom, it gets created. no cap.

🌸 SYNOPSIS 🌸

SET key value [NX | XX | IFEQ comparison-value] [GET] [EX seconds | PX
milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds |
KEEPTTL]

💅 DESCRIPTION 💅

Set key to hold the string value. If key already holds a value, it gets overwritten, regardless of its type — like, no questions asked, it's giving "new phone who dis" 🫶

And the way that any previous time to live associated with the key is discarded on a successful SET operation… yeah, gone, bestie. vanished. 💀

🎀 OPTIONS 🎀

The SET command supports a set of options that modify its behavior:

  • EX seconds — set the specified expire time, in seconds (a positive integer) ⏳
  • PX milliseconds — set the specified expire time, in milliseconds (a positive integer) ⚡
  • EXAT timestamp-seconds — set the specified Unix time at which the key will expire, in seconds (a positive integer) 🕰️
  • PXAT timestamp-milliseconds — set the specified Unix time at which the key will expire, in milliseconds (a positive integer) 🕰️✨
  • NX — only set the key if it does not already exist 🙅‍♀️
  • XX — only set the key if it already exists ✅
  • IFEQ comparison-value — set the key if the comparison value matches the existing value. An error is returned and SET is aborted if the value stored at key is not a string 🚨
  • KEEPTTL — retain the time to live associated with the key 🫶
  • GET — return the old string stored at key, or nil if key did not exist. An error is returned and SET is aborted if the value stored at key is not a string 👀
📌 Note: since the SET command options can replace SETNX, SETEX, PSETEX, GETSET, it is possible that in future versions of Valkey these commands will be deprecated and finally removed. so like… heads up, iykyk 🫣

🌈 REPLY 🌈

RESP2

If GET not given, any of the following:

If GET given, any of the following:

Note that when using GET together with XX/NX/IFEQ, the reply indirectly indicates whether the key was set:

  • GET and XX given: Non-valkey-protocol(7) Nil reply indicates the key was set. ✨
  • GET and NX given: valkey-protocol(7) Nil reply indicates the key was set. ✨
  • GET and IFEQ given: The key was set if the reply is equal to comparison-value. ✨

RESP3

If GET not given, any of the following:

If GET given, any of the following:

Note that when using GET together with XX/NX/IFEQ, the reply indirectly indicates whether the key was set:

  • GET and XX given: Non-valkey-protocol(7) Null reply indicates the key was set. ✨
  • GET and NX given: valkey-protocol(7) Null reply indicates the key was set. ✨
  • GET and IFEQ given: The key was set if the reply is equal to comparison-value. ✨

⚡ COMPLEXITY ⚡

O(1)

like. constant. we love a low-effort icon 💅

🔐 ACL CATEGORIES 🔐

@slow @string @write

🦋 HISTORY 🦋

  • Available since: 1.0.0 🌱
  • Changed in 2.6.12: Added the EX, PX, NX and XX options.
  • Changed in 6.0.0: Added the KEEPTTL option.
  • Changed in 6.2.0: Added the GET, EXAT and PXAT option.
  • Changed in 7.0.0: Allowed the NX and GET options to be used together.
  • Changed in 8.1.0: Added the IFEQ option.

glow up after glow up fr fr 🌟

🍓 EXAMPLES 🍓

Basic usage

127.0.0.1:6379> SET mykey "Hello"
OK
127.0.0.1:6379> GET mykey
"Hello"

Set a value and an expiry time.

127.0.0.1:6379> SET anotherkey "will expire in a minute" EX 60
OK

Conditionally set a value.

127.0.0.1:6379> SET foo "Initial Value"
OK
127.0.0.1:6379> GET foo
"Initial Value"
127.0.0.1:6379> SET foo "New Value" IFEQ "Initial Value"
OK
127.0.0.1:6379> GET foo
"New Value"

🌸 Patterns 🌸

📌 Note: the following pattern is discouraged in favor of valkey-distlock(7) the Redlock algorithm which is only a bit more complex to implement, but offers better guarantees and is fault tolerant. like yeah it's more work but she's worth it bestie 🫶

The command SET resource-name anystring NX EX max-lock-time is a simple way to implement a locking system with Valkey. 🔒

A client can acquire the lock if the above command returns OK (or retry after some time if the command returns Nil), and remove the lock just using DEL.

The lock will be auto-released after the expire time is reached. ✨

It is possible to make this system more robust modifying the unlock schema as follows:

  • Instead of setting a fixed string, set a non-guessable large random string, called token. 🎲
  • Instead of releasing the lock with DEL, send a script that only removes the key if the value matches. 🧠

This avoids that a client will try to release the lock after the expire time deleting the key created by another client that acquired the lock later. no more chaos, periodt 💅

An example of unlock script would be similar to the following:

if server.call("get",KEYS[1]) == ARGV[1]
then
    return server.call("del",KEYS[1])
else
    return 0
end

The script should be called with EVAL ...script... 1 resource-name token-value

👑 SEE ALSO 👑

  • valkey-delifeq(7) DELIFEQ - Deletes the key if its value matches the given string.

👑 SEE ALSO 👑

and that's the whole page bestie!! 🦋 this was 9.0.0 manual-page energy, dated 2025-10-21, and yes it ate 💖 mwah, go set some keys, you're the main character now 👑✨

📦 where this page comes from