EVAL

Execute a Lua script on the Redis server

Usage

await redis.eval(script, keys, args);

Executes a Lua script on the Redis server. The script can access keys and arguments passed to it.

Parameters

script · string · required

The Lua script to execute.

keys · string[] · required

Array of key names that the script will access. These are available in the script as KEYS[1], KEYS[2], etc.

args · unknown[]

Array of arguments to pass to the script. These are available in the script as ARGV[1], ARGV[2], etc.

Response

result · unknown

The value returned by the Lua script. The type depends on what the script returns.

Examples

Basic Script Execution

const result = await redis.eval(
  "return ARGV[1]",
  [],
  ["Hello World"]
);
console.log(result); // "Hello World"

Incrementing a Counter

const script = `
  local current = redis.call('GET', KEYS[1])
  if current == false then
    current = 0
  end
  local next = current + tonumber(ARGV[1])
  redis.call('SET', KEYS[1], next)
  return next
`;

const newValue = await redis.eval(
  script,
  ["counter"],
  ["5"]
);
console.log(newValue); // 5 (or current value + 5)

Conditional Set

const script = `
  local current = redis.call('GET', KEYS[1])
  if current == ARGV[1] then
    redis.call('SET', KEYS[1], ARGV[2])
    return 1
  else
    return 0
  end
`;

const updated = await redis.eval(
  script,
  ["mykey"],
  ["oldvalue", "newvalue"]
);
console.log(updated); // 1 if updated, 0 if not

Working with Multiple Keys

const script = `
  local val1 = redis.call('GET', KEYS[1])
  local val2 = redis.call('GET', KEYS[2])
  return {val1, val2}
`;

const values = await redis.eval(
  script,
  ["key1", "key2"],
  []
);
console.log(values); // [value1, value2]

EVAL vs EVAL_RO

EVAL

The eval command can execute scripts that modify data:

const script = `
  redis.call('SET', KEYS[1], ARGV[1])
  return 'OK'
`;

const result = await redis.eval(
  script,
  ["mykey"],
  ["myvalue"]
);

EVAL_RO (Read-Only)

Use evalRo for read-only scripts that don’t modify data. This is more efficient for read replicas:

const script = `
  return redis.call('GET', KEYS[1])
`;

const result = await redis.evalRo(
  script,
  ["mykey"],
  []
);

Read-only scripts:

• Can be executed on read replicas
• Are optimized for read-heavy workloads
• Will error if they attempt to modify data

Using the Script Class

For better performance with frequently used scripts, use the Script class which automatically handles SHA-1 caching:

const script = redis.createScript<number>(`
  local current = redis.call('GET', KEYS[1]) or 0
  local next = current + tonumber(ARGV[1])
  redis.call('SET', KEYS[1], next)
  return next
`);

// First call uses EVAL, subsequent calls use EVALSHA
const result1 = await script.exec(["counter"], ["1"]);
const result2 = await script.exec(["counter"], ["1"]);

The Script class provides three methods:

• eval(keys, args) - Always uses EVAL
• evalsha(keys, args) - Always uses EVALSHA (requires script to be loaded)
• exec(keys, args) - Optimistically tries EVALSHA, falls back to EVAL if needed

For read-only scripts, use createScript with the readOnly option:

const script = redis.createScript<string>(
  "return redis.call('GET', KEYS[1])",
  { readOnly: true }
);

const result = await script.exec(["mykey"], []);

See Also

• EVALSHA - Execute a cached script by SHA-1 hash
• SCRIPT LOAD - Load a script into the server cache
• FCALL - Call a Redis function