EVAL(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ EVAL — the valkey manual, bestie edition ✨

okay so you're here for EVAL(3valkey)?? the command that runs your Lua scripts server-side?? say less, I got you 💖 this is from the Valkey Command Manual and it's literally one of the most iconic scripting commands ever, no cap.

🌸 NAME 🌸

eval — executes a server-side Lua script.

🎀 SYNOPSIS 🎀

EVAL script numkeys key [key...]  arg [arg...]

💅 DESCRIPTION 💅

So what you're doing here is invoking the execution of a server-side Lua script. simple as that. 👑

The first argument is the script's source code. Scripts are written in Lua and executed by the embedded valkey-lua-api(7) Lua 5.1 interpreter in Valkey. yes bestie, Lua 5.1, don't come at me with 5.4, that's not the vibe here.

The second argument is the number of input key name arguments, followed by all the keys accessed by the script. These names of input keys are available to the script as the valkey-lua-api(7) KEYS global runtime variable. Any additional input arguments should not represent names of keys. 🫶

Important: to ensure the correct execution of scripts, both in standalone and clustered deployments, all names of keys that a script accesses must be explicitly provided as input key arguments. The script should only access keys whose names are given as input arguments. Scripts should never access keys with programmatically-generated names or based on the contents of data structures stored in the database. like... this is not a suggestion, this is THE RULE, please don't break cluster mode 🙈
Note: in some cases, users will abuse Lua EVAL by embedding values in the script instead of providing them as argument, and thus generating a different script on each call to EVAL. These are added to the Lua interpreter and cached to valkey-server, consuming a large amount of memory over time. Starting from Valkey 8.0, scripts loaded with EVAL or valkey-eval_ro(7) EVAL_RO will be deleted from Valkey after a certain number (least recently used order). The number of evicted scripts can be viewed through the evicted_scripts field in the stats section of the valkey-info(7) INFO command. so if your memory is looking kinda wild, check that field fr fr 💀

Please refer to the valkey-programmability(7) and valkey-eval-intro(7) Introduction to Eval Scripts for more information about Lua scripts. go read those, they're giving textbook but make it cute 📚✨

🌈 REPLY 🌈

The return value depends on the script that was executed. yeah. it's giving "whatever you asked for" energy. 🦋

⭐ COMPLEXITY ⭐

Depends on the script that is executed. your script, your problem, bestie 😭

👑 ACL CATEGORIES 👑

  • @scripting
  • @slow

🧚 HISTORY 🧚

  • Available since: 2.6.0

🍓 EXAMPLES 🍓

The following example will run a script that returns the first argument that it gets. iconic behavior honestly.

> EVAL "return ARGV[1]" 0 hello
"hello"

look at her go 💖

💜 SEE ALSO 💜

okay that's the whole page, you ate that 🫶 this version is 9.0.0, dated 2025-10-21 — go forth and script responsibly, bestie, and remember: list your keys explicitly or the cluster will simply not forgive you 💅✨

📦 where this page comes from