EVAL

Use EVAL to run a Lua script on the server.

<numkeys> says how many of the arguments that follow are key names. The script receives those in the KEYS table and every remaining argument in ARGV. Passing key names as keys rather than hardcoding them in the script body matters, because Redis uses that list for routing and access checks. Inside the script, redis.call runs Redis commands and its return value is converted to a Lua value.

The script runs as a single atomic step, which makes it the standard way to do read, decide, and write logic, such as a rate limiter or a compare-and-set update, in one round trip and without a transaction. Keep scripts short, since a script that holds the database blocks everything else, and keep them deterministic by deriving values from KEYS, ARGV, or data read inside the script rather than from clock or random sources.

Upstash isolates a script with a lock. By default that is the global lock, because the engine cannot know in advance which keys the script will touch, so no other command runs while the script does. Adding the allow-key-locking flag to the script's shebang line makes it lock the hash tag of each key passed in KEYS instead, so calls that work on disjoint hash tags run in parallel:

#!lua flags=allow-key-lockingredis.call('INCR', KEYS[1])return 1

With the flag set, every key the script touches must appear in KEYS or share a valid hash tag with an already locked key. Commands that need database-wide access, such as FLUSHDB, are rejected. See Key-Based Locking for the full rules.

Sending a script also caches it under its SHA1 digest, so later calls can use EVALSHA and avoid resending the body. Use EVAL_RO for scripts that only read.

Syntax#

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

Arguments#

Important points#

• numkeys must equal the number of key arguments that immediately follow it; remaining arguments are available to the script or function as ordinary arguments.
• The script takes the global lock unless its shebang sets the allow-key-locking flag, in which case it locks the hash tag of each key passed in KEYS and any matching Search indexes. See Key-Based Locking.
• A script queued inside a MULTI/EXEC transaction always runs under the global lock, even when it sets allow-key-locking. Call it directly if you want per-key locking.
• Pass every key the script touches through KEYS when possible. With allow-key-locking, a dynamic key is accepted only when its hash tag is already locked, and a cold dynamic key is loaded with that lock held. See Dynamic Keys and Latency.

Reply conversion#

Replies from redis.call and redis.pcall reach the script as Lua values, converted with RESP2 rules by default whatever protocol the client connection itself negotiated. redis.setresp(3) switches the script to RESP3 conversions for every call that follows, and redis.setresp(2) switches back. The setting lasts for the rest of the script's execution and does not change how the script's own return value is sent to the client.

RESP3 conversions keep information that RESP2 flattens away: a double stays a number instead of becoming a formatted string, a map keeps its keys, and a null is distinguishable from false.

redis.call('ZADD', KEYS[1], '1.5', 'member')redis.setresp(3)local score = redis.call('ZSCORE', KEYS[1], 'member')return score['double']  -- 1.5 as a number, not the string "1.5"

The same tables are accepted on the way out: returning { double = 1.5 } from a script sends a double reply to a RESP3 client, and { map = { ... } } sends a map.

Response#

The reply reports the result of the operation. Error replies have the same shape in RESP2 and RESP3 and are surfaced as exceptions by the SDKs below.

Examples#

TCP examples use the TLS REDIS_URL from the Upstash console. REST examples use UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.

EVAL "return ARGV[1]" 0 hello

import { Redis } from "@upstash/redis";const redis = Redis.fromEnv();const script = `    return ARGV[1]`const result = await redis.eval(script, [], ["hello"]);console.log(result) // "hello"

from upstash_redis import Redisredis = Redis.from_env()result = redis.eval("return ARGV[1]", args=["value"])print(result)

import Redis from "ioredis";const redis = new Redis(process.env.REDIS_URL!);const result = await redis.eval("return ARGV[1]", "0", "value");console.log(result);

import { createClient } from "redis";const client = await createClient({ url: process.env.REDIS_URL })  .on("error", console.error)  .connect();const result = await client.eval("return ARGV[1]", { arguments: ["value"] });console.log(result);

import osimport redisclient = redis.from_url(os.environ["REDIS_URL"])result = client.eval("return ARGV[1]", 0, "value")print(result)

package mainimport (    "context"    "fmt"    "os"    "github.com/redis/go-redis/v9")func main() {    opts, err := redis.ParseURL(os.Getenv("REDIS_URL"))    if err != nil {        panic(err)    }    client := redis.NewClient(opts)    result, err := client.Eval(context.Background(), "return ARGV[1]", nil, "value").Result()    if err != nil {        panic(err)    }    fmt.Println(result)}

import java.net.URI;import redis.clients.jedis.Jedis;try (Jedis jedis = new Jedis(new URI(System.getenv("REDIS_URL")))) {  Object result = jedis.eval("return ARGV[1]", java.util.List.of(), java.util.List.of("value"));  System.out.println(result);}

fn main() -> redis::RedisResult<()> {    let url = std::env::var("REDIS_URL").expect("REDIS_URL is not set");    let client = redis::Client::open(url)?;    let mut connection = client.get_connection()?;    let mut command = redis::cmd("EVAL");    command.arg("return ARGV[1]");    command.arg("1");    let result: redis::Value = command.query(&mut connection)?;    println!("{result:?}");    Ok(())}