How Big Should a Redis Key Be?

A hash with 200,000 fields answered HGETALL in 217 ms on a real Upstash Redis database. At 205,000 fields, the same call failed:

ERR max request size exceeded. Limit: 10485760 bytes, Actual: 10548899 bytes.

There are published hard limits on Redis, but none on practical size. Redis's guide says keys hundreds of kilobytes or larger are considered big. Different vendors also place different limits on what is big. So we set out to find what size of key is too big to use.

We scaled up values and hashes on a Pay as You Go database and a free scratch database in AWS us-east-1, from a client with around 1 ms latency, to find what breaks. We use data from the Pay as You Go database unless stated otherwise.

At 1 million fields, a simple HLEN took 566 ms one minute after loading, instead of the usual 1 ms. That same access took 9.4 seconds repeatedly on a free database with a 64 MB memory limit. Clients for other keys still respond in about 1 ms, but any client accessing this key also waits.

How big is too big for a Redis key?

Keep values in the tens of kilobytes and collections under about 10,000 members. A full read of 100,000 fields took 109 ms, and more than 200,000 fields caused the full read to fail. On the other hand, collections with fewer than about 10,000 members and values in tens of kilobytes stayed close to 1 ms in our tests.

The 10 MB limit applies to Free and Pay as You Go, and the largest Fixed plan allows 100 MB. This is also a per-request limit, so you can build up a collection over 10 MB and then one read of the whole thing fails.

Big values cost little until traffic arrives

One client reading one big value barely notices the size:

Big objects mean big bandwidth usage. A thousand reads of a 1 MB value mean sending 1 GB of data. Our support team found a cache with 400 KiB sized values and 12 million reads a day, leading to over 100 TB bandwidth usage a month. At $0.03 per GB on Pay as You Go, 100 TB costs around $3,000.

An alternative is to save a large file in object storage, like Upstash Blob, and only save its path in Redis. Or use compression on the client side if the value needs to be stored in Redis.

Bandwidth is the major cost of large values, but there’s a performance cost too. 1,000 reads of a 1 MB value with 20 parallel clients took 1,542 ms, 27 ms median (p50) read. The same 1,000 reads of a 1 KB value took 79 ms, 1.2 ms median read. (p50 is the median read, p99 is the time that 99% of reads are faster than.)

Reading a whole collection is what grows

Reading a few fields stayed flat as the hash grew. Reading all of them grew with it, then failed:

Lists had the same behavior. LRANGE 0 -1 took 8.5 ms at 10,000 items, and 66 ms at 100,000 items, and failed with a 14.1 MB reply at 300,000 items. Fetching the most recent 100 items remained under 3 ms at all of those sizes.

HSCAN is more surprising. When a hash is large, the advice is usually to page it. This works, but even with paging the cost was affected by the hash's size. At 1 million fields, one page of 100 fields took 276 ms. Paging the hash would take a very long time.

Splitting up the hash works better than paging it.

Streams are the one to watch, because they don't fail. On both databases, XRANGE key - + with no COUNT returned 1,000 entries from a stream of 5,000, and no error. Stock Redis returned all 5,000. So code that reads a whole stream has to pass COUNT and page by the last ID:

XLEN                        5000
XRANGE - +                  1000
XRANGE - + COUNT 3000       3000
5 pages of COUNT 1000       5000

A big hash can stall everyone who touches it

This stall was the most surprising result. We loaded hashes of each size, then ran a plain HLEN six times, 10 seconds apart. HLEN should take about 1 ms at any size. This is the slowest of the six:

Strings up to 9 MB stayed under 5 ms on both. The two databases differed in how often this happened. On Pay as You Go, one read paid the cost and the rest stayed at about 1 ms. Its 1 million field row comes from a separate run, read one minute after loading, and reads of that hash at 2 and 5 minutes took 1.1 ms. A read of another 1 million field hash after 15 minutes idle took 0.7 ms. On the scratch database it kept coming back, as in these six reads of the 1 million field hash, two seconds apart:

1.1 ms, 1.3 ms, 1.3 ms, 1.3 ms, 9396 ms, 9436 ms

The stall on the scratch database was long enough to check who waits, so we ran other clients during one:

Upstash locks per key, so unrelated keys keep working. Every user of the big key waits, though. If that key holds all your sessions, then all your sessions wait with it.

We didn't confirm the cause. It fits how Upstash stores data, where an entry that leaves memory gets read back from disk on the next access. A big key that stays in memory would pay this once, and one that doesn't fit would keep paying it, which matches what we saw on these two databases.

Stock Redis fails differently. It has one main thread, so a big key can make every client wait, whichever key they use:

DEL and UNLINK of a 1 million field hash both returned quickly (0.9 ms) with Upstash. Deleting a big key is a known stall on stock Redis (lazy freeing is still off by default for DEL, so use UNLINK).

Split big keys, and limit what grows

One hash of 1 million fields can become 1,024 hashes of about 1,000 fields each, which puts every read back in the 1,000 field rows of the tables above. A field name always maps to the same hash, so reads and writes still need only one call:

import { Redis } from "@upstash/redis";
 
const redis = Redis.fromEnv();
const SHARDS = 1024;
 
function shardKey(base: string, id: string) {
  let hash = 0;
  for (const char of id) hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
  return `${base}:${hash % SHARDS}`;
}
 
async function setSession(id: string, value: string) {
  await redis.hset(shardKey("sessions", id), { [id]: value });
}
 
async function getSession(id: string) {
  return redis.hget<string>(shardKey("sessions", id), id);
}
 
await setSession("user-42", "active");
console.log(shardKey("sessions", "user-42"), await getSession("user-42"));

sessions:960 active

A list or stream that only grows needs a limit from the first write. Trimming on every push keeps a list at a fixed size, and a stream with MAXLEN ~ 1000 stopped at 1,390 entries after 20,000 writes. The ~ lets Redis trim in larger steps, so it stays close to the limit:

import { Redis } from "@upstash/redis";
 
const redis = Redis.fromEnv();
 
async function addEvent(userId: string, event: string) {
  const key = `events:${userId}`;
  const pipeline = redis.pipeline();
  pipeline.lpush(key, event);
  pipeline.ltrim(key, 0, 99);
  pipeline.expire(key, 86400);
  await pipeline.exec();
}
 
for (let i = 0; i < 150; i++) await addEvent("42", `event-${i}`);
 
console.log(await redis.llen("events:42"));

100

Unacknowledged stream entries count too. A consumer that read 100 entries at a time and never acknowledged them was stopped at the limit of 1,000 pending entries. Calling XACK freed it:

ERR XReadGroup is cancelled. Pending Entries List limit per consumer is about to be reached.
Limit: 1000, Current PEL size: 900, Requested Read: 100

What to use

• To delete large keys on stock Redis use UNLINK.
• Keep values in the tens of kilobytes. Store large files in object storage, and keep the path in Redis.
• Keep collections under about 10,000 members.
• If you have collections over that size, split them up with a hash of the ID.
• Rather than HGETALL, use HMGET.
• Rather than LRANGE 0 -1, use LRANGE with a window.
• Rather than XRANGE - +, use XRANGE with COUNT.
• If you use lists and streams, set a limit from the first write, with LTRIM or MAXLEN ~.
• If you use streams with consumer groups, XACK after every message.